Re: macro doc inconsistencies

[Lars J. Aas]

On Mon, Apr 23, 2001 at 12:24:15PM -0500, John W. Eaton wrote:
: You might take a look at what is currently used in the Octave sources
: (current CVS and recent bleeding-edge (2.1.x) releases).  The doc
: strings for individual functions are written using Texinfo, and they
: are included in the source files.  There are some relatively simple
: scripts/programs for extracting the docstrings from the source as part
: of the build process.  All the docstrings are put in two files (could
: be one, but there are two for historical reasons) called DOCSTRINGS.
: The descriptive part of the manual is in .txi files.  In places where
: docstrings for functions should appear, you write
: 
:   @DOCSTRING(fcn_name)
: 
: Finally, there is another script script that processes the .txi files,
: replacing the @DOCSTRING(fcn_name) lines with the docstrings from the
: DOCSTRINGS files.

That's an option I've considered too, and it's probably the best system
without having to create an elaborate organization system.  You might end
up forgetting to add references to various macros from the main doc though,
but then again you can document internal macros the same way and choose
not to include them in the documentation until they become "public" macros.

Doing it this way would probably be easier without using m4 though, just
add an m4 macro for the doc macro that does nothing (or have everything in
commented lines), and then use another scanner to extract the doc-parts -
let the macro name be an argument to the macro, and place them above the
macro definitions instead of inside (which would be easier if you do the
processing with m4, I think).

  Lars J
-- 
Innovation is one percent inspiration and ninetynine percent perspiration,
and in my case; twice that...  -- Norville Barnes, `The Hudsucker Proxy'