Re: macro doc inconsistencies

[Gary V . Vaughan]

On Sunday 22 April 2001 12:55 pm, Lars J. Aas wrote:
> On Fri, Apr 20, 2001 at 09:02:15PM +0100, Gary V . Vaughan wrote:
> : On Sunday 15 April 2001  4:00 pm, Lars J. Aas wrote:
> : > If we could merge the macro reference documentation with the m4 files
> : > and get it extracted automatically, it would be a breeze to keep the
> : > doc consistent with the implementation, and since the doc would be
> : > located with the macro it would be more tempting to update the
> : > documentation when we're working on a macro.  Creating an "autodoc"
> : > system for this wouldn't be trivial though, as you need to consider
> : > macro ordering for the texi document, etc.
> :
> : I almost dare to mention that I have a gawk script that will already more
> : or less do this -- it ships with snprintfv, available from my homepages. 
> : But then I thought better of it and decided not to since I'd probably be
> : flamed... even if I volunteered to tweak it as necessary to make it work
> : with m4 input files.
>
> I was thinking m4 would be the most suitable language to implement this in.

Only if the documentation was inside a macro, most document extraction 
systems (javadoc, gnome-doc, doc++ etc) parse stylised comments, so I took 
the gnome-doc markup and threw together a quick awk script.

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.

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

Cheers,
        Gary.
-- 
  ___              _   ___   __              _         mailto: address@hidden
 / __|__ _ _ ___ _| | / / | / /_ _ _  _ __ _| |_  __ _ ___       address@hidden
| (_ / _` | '_|// / |/ /| |/ / _` | || / _` | ' \/ _` | _ \
 \___\__,_|_|\_, /|___(_)___/\__,_|\_,_\__, |_||_\__,_|//_/
home page:  /___/                      /___/                  gpg public key:
http://www.oranda.demon.co.uk           http://www.oranda.demon.co.uk/key.asc