Re: GNUStep Documentation– General Improvements

[Riccardo Mottola]

Hi
> > 1. The first of which is that in order to find the pages containing the
> > information generated by autogsdoc one has to scoure the site, even though
> > reference documentation should be easy to find.  A link to the reference
> > documentation shouuld appear on the main page instead of a link on a page
> > form the sidebar at the bottom on the wiki page.
> >      
> I agree that better links would be good from the website/wiki ... but bear in 
> mind that you are talking about developer api documentation here ... the reader 
> is normally expected to have this documentation locally on their own machine.
>
>    
Two clicks from the main page is not *that* bad for a developer 
reference. I end up bookmarking it anyway...

> > 2. GNUStep uses it's own proprietary documentation genrator
> >      
> Actually, it's a non-proprietory, open format and *free* tool usable by anyone, 
> but it was designed for ObjC/GNustep.
>
>    
exactly. it is open as other generators too, it just didn't spread as 
others because it is geared to obj-c and our own needs.

I do use it to document several (obj-c) projects easily. Definitively 
not closed.
> > when perfectly
> > good Objective-C document generators such as Doxygene are available,
> >      
> But they weren't when the original markup language was designed (1997).  I 
> think the gnustep documentation markup language pre-dates Doxygen, and while I 
> agree that Doxygen's presentation is now much better, the autogsdoc stuff still 
> has advantages (not least of which is the fact that you can install gnustep and 
> generate the documentation without needing an external package).
>
>    
Not a small disadvantage.
> > and
> > also produce less bland more readably, clean and easily navigatable
> > documentation.  These doccument generators also have multiple output
> > formats.
> >      
> autogsdoc is designed that way too (a big part of the reason the original 
> markup language was done as xml was to facilitate the use of technologies like 
> xslt to produce different output formats) ... but nobody's bothered to 
> implement concrete formats.
> It would be good to improve this (or adopt some format like Doxygen, if someone 
> would volunteer to change all the source/headers/makefiles and add any missing 
> features to Doxygen).
>
>    
I like its current frame-based HTML output quite a bit. it is easily 
browseable. Writing a TEX backend would be nice, to eventually create a 
printable (and/or PDF) reference to the APIs, but our descriptions are 
anyway not yet that good to make it interesting
> > 3.  Required delegate methods should be indicated by differently colored
> > headers and anchor links.
> >      
> I'm not sure about that (generally I dislike a proliferation of different link 
> colors), but it might be worth doing something to identify delegate methods.
>
>    
Well, they could be marked / grouped... put in italic style or be 
referenced at the top in a list... just throwing in some ideas.

Riccardo