Re: macro archive re-launch

[Tim Van Holder]

On Tue, 2002-01-22 at 08:59, Peter Simons wrote:
> Alexandre Duret-Lutz writes:
> 
>  Peter> Furthermore, I wrote a formatting engine that will parse the SGML file
>  Peter> to (a) extract the macro as raw m4 file
> 
>  > I whish you could do the converse: keep the raw m4 file as the
>  > source and extract whatever you want from this.
> 
> Good point. I see two possible solutions:
> 
>  1. SGML does have an "include" statement, so you can put the
>     documentation into a separate file and include the m4 file into
>     it. In fact, you might even be able to do such tricks as fetching
>     the m4 source on-the-fly via HTTP, etc.

But that still means that macro writers need to maintain two separate
files: the documentation (whether or not it includes the m4 macro), and
the m4 file they actually _use_.

>  2. The parser could continue to parse the comments at the top of the
>     m4 file, only that it doesn't look for the @synopsis comment but
>     for the <synopsis> tag. The downside of this is that you don't
>     have a valid SGML/XML file anymore.

That would be better.  Plus, this is what is normally used (cfr. XML
comments in .NET).

> I want to generate all kinds of formats from the input, like plain
> text, HTML, TeX, and nroff, and no tool I came across could do that.
> SGML, on the other hand, can be converted to _anything_, and it's a
> standard format that is likely to be processable for the next few
> centuries. Also, there's no "principal author" who can abandon the
> project, something that frequently happens to users of other tools.

The same goes for TeXinfo - pretty much every GNU tool, and several
non-GNU ones, use TeXinfo to write their documentation.  So if you have
embedded TeXinfo, that can be extracted, along with info about the
macro, either for standalone use, or to be part of some greater
documentation (this is especially nice for autoconf & automake).

Something like this:

dnl## Macro: xyz_CHECK_FOO
dnl## Author: Foo Bar
dnl##
dnl## Synopsis:
dnl## The @code{xyz_CHECK_FOO} macro checks for the existence of
dnl## @command{foo}, and makes sure it can be used properly.
dnl## This macro does @strong{not} guarantee that the companion
dnl## program @command{bar} will exist though; use
dnl## @ref{xyz_CHECK_FOO_BAR} for that.

(note - just a sample; the markup is probably not quite correct)