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

[Julian Scheid]

address@hidden wrote:
> Julian Scheid <address@hidden> writes:
>   
>
> > > 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? 
>
>
> I mean that the essential part of a javadoc tool (the part that is not
> done by anything else) is converting a java source file into a
> collection of comments, ie this:

Yes it is, but that's not a task so trivial that it could be done by
XSLT. This is what Gjdoc is for, and I don't see why and how we should
replace that.
Note that Gjdoc doesn't do merely text conversion. One of its main
tasks is resolving class names, i.e. understanding that a reference to
"Date" in java/sql/Connection.java is supposed to mean "java.sql.Date",
unless there is an explicit import statement "import java.util.Date".
Perhaps this sounds trivial but it isn't. At least it isn't easily
accomplished using XSLT or a similar language.

> I don't think you understand what I'm suggesting, which is that we
> think of the different processes that go on in creating documentation
> as a pipeline of format processors:
>
>   source file -> documentation (xml) -> xhtml
>                                      -> tex(ml)info -> texinfo -> info
>                                                                -> TEX
>                                      -> info
>
> I think I'm suporting what you're saying about getting rid of
> TexinfoDoclet. It would be better to produce only XML and then
> transform that.

OK, I got you wrong. This is exactly the way I see it.

> IMHO one of the transforms should be to texinfo which we would then
> process with makeinfo to produce info.
>
> You seem to prefer creating info directly, that's fine but I'm nervous
> about not using the defined GNU documentation format (which is
> texinfo, not info).

Agree, we should add that too in the long run. We can think about
supporting TexInfo before supporting Info for "political reasons",
but WRT usability what I personally need is Info docs, not TexInfo
docs even if TexInfo is the official GNU doc format. (I don't see
why I should use printed documentation when I can have on-screen
documentation which I can access much more quickly, can paste stuff
from etc.... Printed docs would be nice, but in my eyes are no
priority.)
IMO we should create a specialized Info generator for producing
on-screen docs, and later a generator which produces general-purpose
TexInfo.

Julian