Re: Macro Archive Relaunch

[Peter Simons]

Alexandre Duret-Lutz writes:

 > My impression is that the macro submitter now has to maintain two files:
 >   - the m4 file, that should be readable by autoconf, and that
 >     he/she is using in his project
 >   - and a separate XML file, that duplicates the code

The XML file can reference the actual code. I'm currently writing a
new "how to contribute" document, that should shed some light onto the
different possibilities you have. To give you an overview:

 (1) The authoritative file for your macros is the XML file, which
     _contains_ the macro. Since you cannot use that for Autoconf
     itself, you would have to extract the m4 content as part of your
     build process. This can be achieved by a very simple shell
     script, which I can provide.

     Also, the capability to read the XML file could be added to
     "aclocal" or "autoconf" itself as well, but that is something
     that will happen in the future. (If at all ... So far we have no
     idea how popular the new format will be with the submitters.)

 (2) You have a separate m4 file and the XML file for documentation.
     Then you can process the macro with Autoconf and friends as
     usual. Since XML can reference external content, the XML file can
     be processed without changes as well. (For those who know
     XML/SGML: the keywords here or "system entity" or "XInclude".)

 (3) You use the legacy format and ignore the existence of XML
     altogether.

For the archives, XML has some significant benefits. It is easier to
parse, it is easier to process, and I can automatically _validate_ the
submissions. Thus, macro submissions (or updates to submissions) could
happen _instantaneous_ without having to wait for the maintainer to
catch up. It is virtually impossible to break the build.

For the submitter, XML has pros and cons. It certainly _is_ more
complicated to write than just throwing in a few comments at the top
of your m4 file. A web page that allows submitters to generate the XML
file through an interactive process would certainly help here. (Any
volunteers?) What you gain is much more power to format your synopsis
and your documentation. The "peti_*" macros, currently contained in
the archive, use links, block quotes, etc., for example. IMHO this is
a good thing.

In any case I have no intention of discontinuing support of the legacy
format. A parser for that format does exist, so there is no point in
throwing it away. Users of the legacy format might have to wait longer
for their submissions and updates to make it into the archive, though,
because a maintainer has to take a look at the file and test the
generated output, before it can be approved. (In the past, about half
of all submissions had to be edited manually before I could add them.)
 
Also, I have no intention of converting the existing legacy format
macros into XML. I want to keep the macros in the format that the
users chose when submitting it. (Unless some volunteer shows up to
help me with managing the archive. For me alone, the workload of
checking, converting, testing, and committing every single update in a
different format than the submitter used is too much.)

The XML format is an _option_. My prediction from experience is:

 (1) People will claim that it is doomed, bloated, and pointless.

 (2) People will realize that they can add formatting, links, colors,
     images, and tables to their macro documentation.

 (3) They will love it. 

:-)

The code is there, it is up and running, so I will document it and put
it on-line. Then we'll see what happens.

Peter