Re: autogsdoc questions and suggestions

[Richard Frith-Macdonald]

On Tuesday, July 22, 2003, at 12:25 AM, Stefan Urbanek wrote:

> hi,
>
> I have a few questions concerning autogsdoc. First of all, I think it  
> is a nice tool. Besides that, I was not able to find some readable and  
> clean examples about how to use that tool.
>
> QUESTIONS
>
> 1. How can I use CSS with HTML files generated by autogsdoc?
> 2. I have several frameworks:
>    /SourceRoot
>        /Documentation
>        /Frameworks
>            /Framework1
>            /Framework2
>            ....
> How can I make top level documentation .html file containing  
> references to all frameworks, and how can put it into GNUmakefile?  
> Somtehing like 'suite contents'.

Ideally, you should be able to use a .gsdoc file together with the  
-Projects flag for autogsdoc to tell it how to find the projects you  
want to link to.  However, the prjref element needed to refer to an  
external project as a whole is not implemented, so you would have to  
link to individual classes (or use a global scope index).

> 3. If I do not specify authors, I still can see Authors header in  
> generated .html file, how can i remove that?
Should be fixed in cvs.

> 4. How can I tell autogsdoc to move authors and date to the bottom of  
> the page?
> 5. Where should I put templates for such directory layout if they are  
> common for all frameworks, except names?
> 6. How can I specify a template for class documentation? I do not want  
> Contents, Authors and 'Software documentation for ...' title. The  
> title is not necessary, because I already know that i am looking at  
> class documentation. What i want is only a class name, description,  
> declared in/conforms to, method index and method descriptions.
>
> Maybe more questions comming soon.

I think there is pretty much a single answer to most of the above  
really ... autogsdoc does not have any customisability built in ... it  
was written primarily to generate gnustep-base documentation, and while  
it's still a good tool for documenting any other ObjC code, you get the  
same presentation that the base library gets.

That being said, you have two options ...

a. Change autogsdoc to do what you want ... eg. provide a new version  
of the AGSHtml.m source, rewrittten to use some form of templates.  Any  
nicely designed, generic approach which produces something like the  
current output as default would probably be welcome.

b. Post-process the outupt ... since the output is currently xhtml, you  
can use an xslt tool to transform it any way you want,
though you could of course use other text manipulation tools.  This  
might need a minor tweak to AGSHtml.m to get it to output the  
appropriate <?xml version...> and <!DOCTYPE ...> header/wrapper info  
for stricter xslt tools.


> SUGGESTIONS
>
> I think that autogsdoc should strictly differentiate between pure  
> class documentation and some generic documentation (like text in  
> chapters).
I'm not sure what you mean by that.  The base library documentation has  
generic documentation in
Documentation/Base.gsdoc.  Are you saying there should be generic  
documentation and class documentation in the same file?

> What do you think about using code from DevelopmentKit in Autogsdoc?   
> http://savannah.nongnu.org/projects/develkit/ (see examples in Testing  
> directory)
>
> http://savannah.nongnu.org/cgi-bin/viewcvs/develkit/DevelopmentKit/ 
> Testing/template.txt?rev=1.4&content-type=text/vnd.viewcvs-markup
> or
> http://savannah.nongnu.org/cgi-bin/viewcvs/develkit/DevelopmentKit/ 
> Frameworks/DevelopmentKit/ClassTemplate.m?rev=1.4&content-type=text/ 
> vnd.viewcvs-markup

I'm very much against using external software (however good) ... I  
don't want to need to link against
anything that might not be installed.   I wanted it to be possible to  
build gnustep-base completely
in one go.

I mean, you download it and run 'make install' and everything is done,  
rather than -
download base, build and install library
download another library, build and install,
build and install autogsdoc and documentation

I know it's only a small thing, but I'd like it to be as easy as  
possible for a new user to get everything
they need installed.