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

[Julian Scheid]

address@hidden wrote:
> Julian Scheid <address@hidden> writes:
> > 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.

All true, but while there are tools to convert TexInfo to both
Info and Postscript, it's not easy to generate one TexInfo source
from the Java docs that can produce both high-quality printed output
and high-quality Info code. This is because of some nifty formatting
issues.

I think we go better if we have
1) a tool to create Info docs for viewing in Emacs
2) a tool to create some sort of printable documentation, perhaps
via TexInfo.

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

I don't understand what you mean by that, can you explain it?

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

I've expressed my point of view on this issue a number of time,
but once more: using XSLT it's easy to make much anything from
well-formed HTML. XSLT is not suited for processing TexInfo.
Besides, HTML is the standard for Javadoc comments. I don't
think we should extend our suite to cope with Javadoc comments
in a format other than HTML. The current situation - having
HTML comments - is fine, we can create everything from it using
XSLT.

Julian