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

[nferrier]

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:

/** A class.
*/
class X
{
  /** A method.
  */
  public void method();
}

into this:

   Class X: A class.
      method:  A method.
   
Forget the issue of what the javadoc comments contain... the real job
o0f javadoc is to produce a class document for each source file and to
process the macros (@author, @see, @param, etc....) appropriately.



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

It would be if texinfo was converted to XML (which would be easy,
though no ones done it yet).


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

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

The first stage is something like what gjdoc is doing now (in fact I
think it is what gjdoc is doing now). The other stages are either XSLT
transforms or makeinfo transforms.


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.

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

At the end of the day the process above is flexible enough to live
with all our wishes.


Nic