Re: macro doc inconsistencies

[John W. Eaton]

On 22-Apr-2001, Lars J. Aas <address@hidden> wrote:

| I was thinking of using texinfo markup directly in the doc macro.  HTML
| and other formats should come from the texinfo output.  I don't see this
| part as an obstacle - the problem is more on the management-side - getting
| the doc parts organized correctly.  The macros are organized differently
| in the .m4 files than you would organize them in documentation.  A plain
| alphabetical organization is only suitable for reference lookup and not
| for a manual-type document.
| 
| : Perhaps it would be pragmatic to adapt an existing extraction system 
instead?
| : Or maybe we could agree on a tight specification for the markup, and start 
| : using it, and write the extraction system later...
| 
| The doc is mostly written already in the texinfo doc.  If we start
| moving the documentation blocks into the .m4 files before we have a
| usable extraction setup, we risk getting the m4-file doc outdated when
| someone updates the texinfo file.  To avoid having to sync between two
| documentation sources, the new setup should replace the old when we
| start using it.
| 
| You can of course just freeze the texinfo part and say all updates should
| be done in the m4 files - and then everyone will have to wait for the
| extraction system to start working before they actually get the updated
| documentation.  I don't think that's a good idea though.

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.

Using the @DOCSTRING(fcn_name) macro solves the problem of organizing
and ordering the docstrings for functions manually, which seemed much
simpler than trying to add this meta information to the docstrings
themselves.

jwe

-- 
www.octave.org        | Unfortunately we were hoplessly optimistic in 1954
www.che.wisc.edu/~jwe | about the problems of debugging FORTRAN programs.
                      |                                       -- J. Backus