Re: To XML or not to XML?

[Peter Simons]

Bastiaan Niels Veelo writes:

 > I am not that well informed about XML. How well can you
 > automatically check the syntax of an XML submission? What
 > is the difference between checking <LICENSE>GPL</LICENSE>
 > and checking "@lincense GPL"? I am probably missing
 > something.

The main difference is that in order to check the latter
syntax, a parser has to be written. Whereas a parser for the
former syntax does exist: the XML parser. Writing a DTD that
describes a complexly structured data type takes 10 minutes,
writing a parser yourself takes _much_ longer.

Just take a look at:

  http://www.gnu.org/software/ac-archive/dtd/acmacro1-xml.dtd

This is all the information which is necessary to describe
an Autoconf macro -- _including_ pretty much all of XHTML.
The XML parser will not only tell you whether the macro is
correct, it will also tell you whether your HTML inside the
documentation is correct! That is damn convenient.

Plus, manipulating XML files in software is very simple.


 >> [Guido's need] is packaging and using tools to
 >> automatically distribute new versions of macros to
 >> different hosts and to update the various projects using
 >> one of the extra ac-macros. And that's easier with a
 >> pristine format that can be parsed by autoconf directly
 >> as well as tools that test for text diffs.

 > How can we address that?

I am all for improving the release archives that we
distribute. I'd also like to be able to say "make install"
or to have an RPM file, a BSD port, or a Gentoo ebuild.
Which is, what I suspect, Guido is worried about above.
Well, it just has to be done. It's not that having all that
wouldn't be possible, it's just that someone has to do it.
;-)


 > CVS keywords should be banned. My macro in the GNU
 > archive has one version, in the SourceForge archive it
 > has an other (higher, though it is actually older), and
 > in my three repositories it has yet three different
 > version numbers.

The archives on SourceForge.net and gnu.org run on the same
CVS repository of macros, hence they should _always_ both
have the same version numbers. That doesn't mean I am a fan
of CVS keywords, I just wanted to point out that your macro
does unfortunately break that rule because, well, here both
archives are _not_ using the same version. If that were
remedied, there would be no inherent problem with using CVS
keywords.


 > I am concerned about the separation between the macro
 > code and its documentation, which the XML format has as a
 > consequence as it is now.

That separation would exist only _internally_ in the
archive. The software can generate pretty much anything we'd
like it to from the XML file. We can output man pages, plain
text, m4 sources with the documentation in a comment header,
etc. I never intended to distribute XML files to users of
the archive.


 > For my own needs as a macro author, I want to be able to
 > test my macro before uploading (so if this is in XML, I
 > need to be able to quickly convert it to m4) and I want
 > to be able to apply patches against my source.

That shouldn't be a problem. You don't have to embed the
macro itself into the XML file. It's perfectly alright to
have a bnv_have_qt.m4 and a bnv_have_qt.xml file. The latter
would then contain the line

  <m4source href="bnv_have_qt.m4">

and all would be well.


 > What if we start to (ab)use Doxygen?

I wouldn't mind using Doxygen to generate the archive. I
know the tool is incredibly powerful and comes with all kind
of features that we could use nicely.

I have never used Doxygen myself, though. I have no idea
whether it can be customized to suit the needs of the Macro
Archive. And if it can, how much work doing that would be.

Have you ever done something like that with Doxygen?


 > These are pristine sources, Autoconf can process them
 > right away.

Just to make sure this point is very clear: In the XML
variant the m4 sources themselves would be (or could be)
"pristine", too. The only difference is that the
documentation (and classification, license, category,
version, etc.) would be in a different file -- not in the m4
file itself, like it used to be.

That does, however, _not_ mean that the archive couldn't
generate m4 versions of the macros which contain the
documentation in some plain text layout. (Our markup is
basically HTML; we could probably re-use an existing
converter.)


 > Submitters will be able to generate the HTML themselves,
 > and /they/ will be able to make sure things are OK before
 > submitting.

If they do have Doxygen, and I believe that's a massive
package these days. (I may be wrong, though.)


 > Whould not this satisfy the needs of both archive
 > maintainers, authors and users alike?

The problem is that we will never know until someone has
built a prototype with Doxygen. :-) Judging from what I know
about the package, I think it is possible, but I wouldn't
know how to do it.

Peter