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.
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.
> Instead, why not going toward something like perlpod? Autoconf
> itself could extract some of its documentation from its sources
> files if such a tool existed.
I have been on a quest of trying to generate documentation from the
sources automatically for years now, and all solutions I tried gave me
poor output quality, be it perlpod, doxygon, or whatever. Furthermore,
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.
-peter
