[Cp-tools-discuss] [Fwd: Texinfo Doclet Replacement]

[Julian Scheid]

Hi folks,

we've put a lot of efforts into TexiDoclet, but there
are reasons why a complete rewrite, or better to say:
replacement would make sense. Yes I know it hurts.

Take the following layout for TexiDoclet II, which
is a misleading name in this new context BTW.


    Java Source
         |
         V
      [Gjdoc]
         |
         V
     Doclet API
         |
         V
     [XmlDoclet]
         |
         V
     .xml files
         |
         V
     [xsltproc]
         |
         V
   .xmlinfo files
         |
         V
[gnu.tools.XmlInfo]
         |
         V
    .info files


That is: Gjdoc extracts structure and comments from the
Java sources and delivers via the Doclet API. XmlDoclet takes
this information and produces a couple of XML files. These are
transformed by xsltproc to produce an alternative XML format
which  I call ".xmlinfo". Finally, a special-purpose tool
called "XmlInfo" generates .info files from .xmlinfo files,
just like makeinfo generates .info files from .texinfo files.

Sounds complicated, but in fact all this is already contained
in cp-tools except
1) an XSLT sheet producing .xmlinfo and
2) the XmlInfo tool

If these two were given, the resulting solution would be
much cleaner than the current, mainly because XmlDoclet and
the XSLT processor can do much of the work currently done
by TexiDoclet: parsing and translating HTML, and operating
on the information in a database-like way (think queries).

In order to prove this point I wrote a prototype of the
XmlInfo tool. It is only 600 lines long but it can already
generate .info files from .xmlinfo files of arbitrary
length without performance loss or increased memory usage
because it uses the SAX interface. It already supports
nodes, menus, and links and produces valid Info output.
It currently doesn't support tables and bullet lists
however.

These are 600 lines of source code, let them grow to a
thousand or 1500 when tables etc. have been added, but this
is and will remain a simple tool.

All other work will be done by the XSLT sheet, which is in
many aspects very similar to the sheet we already use to
generate HTML docs. In fact, some templates can be moved
from gjdocxml2html.xslt to some gjdocinclude.xslt to be
included in both sheets, for example the code to generate
the inheritance tree.

The sheet for generating HTML is not very complex, and the
sheet for generating .xmlinfo will be even simpler.

Therefore I'm unsure about how much sense it makes to put
additional efforts into the current incarnation of
TexiDoclet. After a few hours of work, I already have a
prototype working (XmlInfo tool and a simple XSLT sheet
for generating .xmlinfo files), and I guess another day
or two until the Info docs have a similar quality compared
to the HTML docs.

Some nice side effects:
- we do no longer depend on makeinfo (though we now do
depend on an XSLT processor. But I wonder how classpathx'
javax.xml.transform package can prove useful here. Nic,
what about performance compared to xsltproc?)
- we can run gjdoc/xmldoclet once and produce both HTML
and Info from its output.

I think we could reduce the quiet complex component
TexiDoclet to a much more trivial XSLT sheet and would
only have to add one trivial application, XmlInfo, in
order to achieve this.
This would allow us to concentrate on Gjdoc and the
XSLT sheets, as XmlDoclet is a quiet simple piece too.

Feedback is welcome.

Julian