describe: show the same information about functions for 'x and #'x.

[sbcl.git] / contrib / STANDARDS

diff --git a/contrib/STANDARDS b/contrib/STANDARDS
index f344dc5..c66f77b 100644 (file)
--- a/contrib/STANDARDS
+++ b/contrib/STANDARDS
@@ -1,6 +1,6 @@
-Proposed contrib standard, version $Revision$
+Proposed contrib standard, $Revision$
 
-The SBCL contrib mechanism is intended to provide a mechanism to
+The SBCL contrib mechanism provides a mechanism to
 manage code which does not form part of SBCL itself, but which is
 sufficiently closely associated with it that it would not be sensible
 to run it as a completely separate project.  For example, alternative
@@ -21,10 +21,9 @@ to not install stale contrib code: a contrib that fails its test suite
 against a given version of SBCL will not be installed in that release.
 
 Note that despite leaving you the contrib maintainer with the
-responsibility of maintenance, we don't _necessarily_ (although we
-quite possibly would) offer you CVS access to the SBCL tree.  This is
-because we can't do that without letting you write to the rest of the
-tree as well (at least as far as I know, at sourceforge).  
+responsibility of maintenance, it doesn't follow that we'd
+_necessarily_ offer you CVS access to the SBCL tree: each application
+is considered individually.  We often do, though.
 
 ** Release cycle
 
@@ -50,17 +49,18 @@ A contrib package must contain a Makefile.  This is to have three targets
 
 all:     # do whatever compilation is necessary
 test:    # run the package tests
-install: # copy all necessary files into $(INSTALL_DIR)
+install: # copy all necessary files into $(BUILD_ROOT)$(INSTALL_DIR)
 
 If the contrib package involves more than one file, you are encouraged
 to use ASDF to build it and load it.  A version of asdf is bundled as
 an SBCL contrib, which knows to look in $SBCL_HOME/systems/ for asd
 files - your install target should create an appropriate symlink there
-to the installed location of the system file.  Look in sb-bsd-sockets/Makefile
-for an example of an asdf-using contrib
+to the installed location of the system file.  Look in
+sb-bsd-sockets/Makefile for an example of an asdf-using contrib.
 
-$(INSTALL_DIR) will have been created by the system before your
-install target is called.  You do not need to make it yourself.
+$(BUILD_ROOT)$(INSTALL_DIR) will have been created by the system
+before your install target is called.  You do not need to make it
+yourself.
 
 * Tests
 
@@ -71,11 +71,23 @@ good place to test that they still exist, etc.
 
 * Documentation
 
-[ Would be at least nice.  My tendency is to say plain text or HTML,
-and optionally your choice of source format which can generate either
-of the preceding.  Document formats not available on typical
-well-endowed-with-free-stuff Unix systems are discouraged.  DocBook
-is fine, as the SBCL manual is DocBook anyway ]
+Each package should provide documentation in Texinfo format.  For the
+documentation to be included in the sbcl manual, the following must
+hold:
+
+- Each Texinfo file must have the extension `.texinfo' so the
+  automatic manual builder will find it.
+
+- It must contain one @node - @section pair at the top and only
+  @subsection (or lower) sectioning commands within, e.g.
+
+@node Sample Contrib
+@section Sample Contrib
+...
+
+  so that the contrib menu can be created automatically.
+
+Take care to choose unique node names.
 
 [ make install should copy the documentation somewhere that the user
 can find it ]
@@ -93,5 +105,5 @@ SBCL that provide clean documented APIs which reasonably can be
 preserved.  If in doubt, seek consensus on the sbcl-devel list
 
 A contrib must load into its own Lisp package(s) instead of polluting
-CL-USER or one of the system packages.  The Lisp package name should
+CL-USER or one of the system packages.  The Lisp package names should
 begin with "SB-".  Ask the sbcl-devel list for a suitable name.