mirror of https://github.com/GnoConsortium/gno.git
96 lines
3.8 KiB
Plaintext
96 lines
3.8 KiB
Plaintext
$Id: adding.utils,v 1.1 1999/01/09 21:19:58 gdr-ftp Exp $
|
|
|
|
General
|
|
-------
|
|
|
|
You should read this file if you are contemplating adding utilities
|
|
to the base GNO distribution.
|
|
|
|
The first question is whether or not your utility belongs with the
|
|
base distribution. The criteria are loose, but if it is a commonly
|
|
used utility among the majority of GNO users, or if it is required
|
|
for building GNO itself, it may be incorporated into the base
|
|
distribution. If you think your utility matches these criteria,
|
|
contact Devin Reade <gdr@trenco.gno.org>.
|
|
|
|
Source Code
|
|
-----------
|
|
|
|
There is no restriction to which source language you use. If you have
|
|
successfully written a program written in something other than ORCA/C
|
|
or ORCA/M, please share your observations with the GNO development group
|
|
regarding using these other languages.
|
|
|
|
[talk about hierarchy in the src directory]
|
|
|
|
It should be clear from the *source* exactly from where the original code
|
|
came. In the case of GNO base distribution utilities ported from BSD,
|
|
changes should be reviewed by the GNO development team.
|
|
|
|
Mandetory Makefile Targets
|
|
--------------------------
|
|
|
|
|
|
Documentation Requirements
|
|
--------------------------
|
|
|
|
For utilities that become part of the GNO base distribution, there
|
|
are three *required* documentation files:
|
|
|
|
1. A manual page. Ensure that it is using a format understood
|
|
by the GNO version of nroff. BSD manual pages do not
|
|
usually fall into this category. Some utilities have both
|
|
a GNO and a BSD man page. In this case, the BSD man page
|
|
has a suffix of (for example) ".1" while the GNO version
|
|
has a suffix of ".1G". In either case, the suffix of the
|
|
manual page after installation should be ".1". See the
|
|
ftp(1) source for an example.
|
|
2. A describe(1) entry.
|
|
3. A rez source file containing an rVersion entry. This
|
|
will become (part of) the program's resource fork.
|
|
This file may contain other resources as well. Some
|
|
common ones include rComment and rProgInfo entries.
|
|
|
|
The GNO FAQ has information on where samples of these documentation
|
|
files may be found.
|
|
|
|
Other documentation files can be included as necessary. These include
|
|
but are not limited to READMEs, ChangeLogs, and reference manuals.
|
|
|
|
The README or other documentation should contain the following information:
|
|
1. Who wrote or ported the program.
|
|
2. How the maintainer may be contacted.
|
|
3. A list of what features have been tested.
|
|
4. The copying status; is it freeware, public domain, shareware,
|
|
copyleft, or something else?
|
|
|
|
There should be a detailed record of what changes have been made for
|
|
the various versions. Small projects can have this information in the
|
|
README file; large projects should use a separate ChangeLog.
|
|
|
|
|
|
RCS/CVS Identifiers
|
|
-------------------
|
|
|
|
When you're working on your utils please include, in comments near the
|
|
top of each file, the character sequence "[Dollar sign]Id[Dollar sign]"
|
|
(minus the quotes, and with [Dollar sign] repaced by '$'). This is an
|
|
RCS identifer. (RCS is the Revision Control System. CVS, the Concurrent
|
|
Versions System, depends on RCS.) Adding in the RCS identifier will
|
|
cause the version number associated with each file in the repository to
|
|
be displayed (and automatically updated) in each file.
|
|
|
|
You should *not* add a RCS identifier to your describe(1) entry file.
|
|
These files are cat'd together later when creating the database,
|
|
and the RCS identifiers do not belong in the database.
|
|
|
|
Note that some sources (notably some BSD files) already have such a string.
|
|
In these cases, you need not add another. An expanded string looks
|
|
something like this:
|
|
|
|
$Id: adding.utils,v 1.1 1999/01/09 21:19:58 gdr-ftp Exp $
|
|
|
|
When the sources are released, a 'cvs export' will be done which will
|
|
keep the version number intact, even if someone at a remote site decides
|
|
to import it into their own repository.
|