Re: To XML or not to XML?

[Bastiaan Niels Veelo]

Peter Simons wrote:

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

The inherent problem is that when John Doe has downloaded a macro whos 
version is defined with a CVS keyword, incorporated it into his project, 
committed it to his repository, that version number changes to something 
like "1.0, doe". Then, 6 months later, he encounters a problem with the 
macro. He goes back to check the archive. But, having forgotten what the 
version number was like when he downloaded (probably never looked at it) 
the version mentioned in the archive has no meaning. Downloading and 
diffing is the only thing he can do.

That is bad enough. But if there are more than one archive and they are 
not in sync, and John is unsure where he got it from (maybe he got there 
through Google, and now Google presents a different one at the top of 
the list) he may actually diff his macro against a version that is 
older, and downgrade while thinking that he is upgrading!

This is not far-fetched: one of my users got his macro through Google, 
and I myself had to assess the differences between my macro's in the two 
archives to determine which one was the newest.

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

Well, that is something to put on the todo list then. 
http://www.gnu.org/software/ac-archive/m4source/bnv_have_qt.m4 is not 
documented :-(

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

OK, that is good news. That would at least bring the SourceForge macro 
up to date, albeit undocumented.

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

Not exactly like that, but I have used it in several occasions. For an 
idea of its layout capabilities, see for example 
http://svn.dsource.org/svn/projects/dcouple/trunk/managed/doc/index.html. 
Never mind the warning there, or the links at the top, we would not use 
the capabilities for source code documentation.

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

Good. This needs to be exploited.

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

I don't know, is under 4MB (installed) massive?
http://packages.debian.org/testing/devel/doxygen

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

Not right now, but I may be able to check this out in more detail at 
some point. But I need exact specifications of requirements of both you 
and Guido.

But there are clearly possibilities of the XML approach that I was not 
aware of. If you can generate m4 code with a comment block at the top, 
much like the old format, and arrange with Guido that he mirrors the 
right files, that would solve the sync problem between the archives. 
This is my main concern, and I hope you guys can fix it.

If XML is to be the submission format, we the submitters need to be 
explained how to work with it. And we are stupid ;-) We want to be able 
to preview the HTML that will appear on the site. Maintenance must also 
be easy --- I am still sceptical about users using a different format 
than authors. I have received several patches from users, which I have 
to process by hand.


Cheers,
Bastiaan.