Description

This article is from the Apple II GNO FAQ, by Devin Reade with numerous contributions by others.

3.4: I've just finished writing a new program (or library or whatever).What documentation should I include?

    A#3.4:	Including the following documentation components will not only
help anyone who is maintaining a GNO site, but they will also
make your contribution look more professional.  Remember, if
someone can't tell what your program is supposed to do, they
are less likely to try it out.

You should have:

- A manual page (see also Q#3.5).  Unless your program requires
  a large reference manual ( > 5-10 pages of written text), the
  manual page should be the primary document.

  Ensure the man page is assigned to the correct section.  One
  common mistake is to mix up Section 1 (User Commands) with
  Section 8 (System Administration).

- A describe(1) database entry.  Try to use the ".desc" suffix
  on the file name.  (For example, if you wrote the "foo" program,
  you should have a text file "foo.desc" containing the database
  entry.)  If you have WWW access, please update the online
  describe database maintained by Soenke Behrens -- see Q#4.4.

  The describe entry is very suitable as a brief README file
  when uploading your program to ftp sites, or when posting to
  comp.binaries.apple2.

  Describe entries should only be written for programs, not 
  libraries or individual routines.

- An rVersion resource fork.  If you don't want to write a rez
  source file, then use setvers(1).

  There is a new format out which includes rVersion as a subset.
  It is called rProgramInfo (or rProgInfo), and was formalized
  by Eric Shepherd.  Information on this is available at the
  usual ftp sites in the archive rProgInfo.shk.  See also the
  templates file listed later in this answer.

- "Standard" help and version flags.  If possible, invoking your
  program with the "-V" (capital vee) flag should print the
  version number and exit.  Invoking it with the "-h" flag should
  print a usage (help) message and exit.  Use of the "-?" flag
  is discouraged because it is a meta-character in many shells.

  It may not be practical to support these two flags, such as
  if you are porting a program that already uses them for other
  purposes, or if you are writing a daemon.

To make things easier, templates for manual pages, rVersion
source files, and describe database entries are available at
the usual sites.  Look for an archive with a name similar
to
	templates[version_number].shk
    

 

Continue to:

• prev: 3.3: What are all the numbers in parenthesis following program names?
• Index
• next: 3.5: I'm writing a manual page. What format should I use?

Share and Enjoy

Tags

pc, hardware, Apple II, Apple ][ or Apple //, apple, gno, unix