Re: macro doc inconsistencies

[Lars J. Aas]

On Sun, Apr 22, 2001 at 06:27:34PM +0100, Gary V . Vaughan wrote:
: On Sunday 22 April 2001 12:55 pm, Lars J. Aas wrote:
: > I was thinking m4 would be the most suitable language to implement this in.
: 
: Now that you mention it, having a document macro seems like a better idea, 
: though you would still need to do some post processing to insert texinfo 
: markup (or nroff markup to generate manpages, or html for web pages), or else 
: come up with a relatively involved macro markup scheme.  It sounds like a lot 
: of work.

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.

  Lars J