cp-tools-discuss
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

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


From: nferrier
Subject: Re: [Cp-tools-discuss] [Fwd: Texinfo Doclet Replacement]
Date: 09 May 2002 12:21:10 +0100

Julian Scheid <address@hidden> writes:

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

ClasspathX does not have an XSLT engine. Dave and myself would like to
have one but we just don't have the time to write one.

Personally, I'm happy to depend on the GNOME libxslt.


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

I think the goal of producing texinfo is a good one. It is the GNU
documentation format which means it would be very easy to combine
javadoc produced texinfo with other manuals (for example the GNU GCJ
manual).

In addition texinfo is easy to author so I anticipate that there will
be other GNU manuals for java written with texinfo.

Lastly, texinfo is easy to make into printed documentation, unlike
many other formats.


Here's a short step back to take an overview:

Javadoc comments seem to me to be pretty simple doc system. One
uses a few simple macros to represent information about your source
code. The javadoc processor collates these together, builds some
indexes and formats the whole with some styling convention.

In practice it gets complicated by the styling language to be used,
the result of that is that the javadoc has to be written to cope with
one styling language or another (eg: embedded HTML or texinfo or
docbook or whatever).


What I would like to get to is a place where the javadoc process is
agnostic about the output styling language and we can simply plug in
the right output layer.


In practice that means that we have to have a number of pluggable
transformations:

- have HTML embedded in your document but want texinfo output? 
  you need an HTML->texinfo style sheet.

- have texinfo javadoc but want docbook output?
  you need a texinfo -> xml -> docbook style sheet pipeline.

This would be achievable with tools that were quite simple, the job
of a javadoc processor *could* be achieved by a very simple styling
tool (probably even by XSLT). 


Taking this view the doclets themselves are simply be a decleration of
a particular pipeline (maybe eventually we'll write an intelligent
doclet that guesses what it's input format is).

Does this make sense to anyone?


Nic




reply via email to

[Prev in Thread] Current Thread [Next in Thread]