3.4: I've just finished writing a new program (or library or whatever).What documentation should I include?
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:
My Books
