[Top][All Lists]

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: macro doc inconsistencies

From: John W. Eaton
Subject: Re: macro doc inconsistencies
Date: Mon, 23 Apr 2001 12:24:15 -0500

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 
| : 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


Finally, there is another script script that processes the .txi files,
replacing the @DOCSTRING(fcn_name) lines with the docstrings from the

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


--        | Unfortunately we were hoplessly optimistic in 1954 | about the problems of debugging FORTRAN programs.
                      |                                       -- J. Backus

reply via email to

[Prev in Thread] Current Thread [Next in Thread]