Re: To XML or not to XML?

[Bastiaan Niels Veelo]

Thanks for taking up this thread again, Peter.

Peter Simons wrote:
<snip>

> So when I chose to go towards XML, my hope was that
> automated syntax checking and the wide availability of XML
> editing tools (Emacs' PSGML rocks, for instance) would cut
> down the time I need to spend on fixing the submissions!
>
>  

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.

<snip>

> Or do you have entirely different suggestions how to
> proceed? Guido, what do you think?
>
> Peter
>  

Let's view it from a user's perspective. What is important?

1) A single archive. Maybe mirrors, but not independent archives that 
carry equally named macros in different versions and with different 
version numbers yet.

2) The ability to quickly find out whether a new version has come out.

3) The ability to quickly download and use the new macro.

4) Have good documentation off-line.


About 1):

If we are going to have a single archive, we need to support the needs 
of both maintainers, Guido and Peter.

I hope Guido is fine with me quoting him:
>My own need is _not_ in presentation, my own 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. That's 
pretty much
>all about it.

How can we address that?


About 2):
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. Plain, manually edited version numbers are 
the only thing that will work.


About 4):
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. 
If you don't have instant access to the Internet, then only a link to 
the relevant HTML page in the archive is not going to help much.

For programming resources, a man page is nice to have. If I install the 
archive through apt-get for example, it would be nice to be able to 
simply say "man bnv_have_qt" in stead of having to search if it possibly 
is in /usr/share/doc some place.

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. I think it is an advantage if the documentation is in the 
pristine source file. XML is not an ideal fit for me, because I am 
working with the m4 source, and submitting in XML. I can convert from 
XML to the m4 (although I don't know how) but not the other way around. 
OK, cut-n-paste works, but it is clumsy.


Here is a thought. What if we start to (ab)use Doxygen? A filter will 
make it able to read m4 comments. It will generate HTML, man pages, 
Postscrip, PDF, RTF and whatnot. A style sheet will give the archive a 
common look. The source of the documentation always stays with the code, 
is human readable, and allows extended possibilities for markup. These 
are pristine sources, Autoconf can process them right away. Submitters 
will be able to generate the HTML themselves, and /they/ will be able to 
make sure things are OK before submitting. This will reduce the need for 
syntax checking and quality assurance. Still it is easy to automatically 
check for the existence of "\subsection Licence" for example. If a macro 
is deprecated, it can be marked with "\deprecated". This leaves a clear 
note in the documentation, and it can be scanned for so that the macro 
can automatically be moved to a page with deprecated macros, for 
example. If there is any metadata that can not be picked up from the 
documentation (like "\subsedtion" or "\deprecated" above) or from the 
source itself (like "AC_REQUIRE"), we can still have a section of "dnl 
@metadata" that is not parsed by Doxygen. Maybe it would even be 
possible to let Doxygen generate the main page including list of 
contents, and macros may be cross-referenced, and it may even happen 
automatically. There is much potential.

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

Bastiaan.