Re: Class documentation templates (in autogsdoc)

[Stefan Urbanek]

On 2002-11-14 18:17:44 +0100 Richard Frith-Macdonald <richard@brainstorm.co.uk> 
wrote:
> On Wednesday, November 13, 2002, at 08:06  pm, Stefan Urbanek wrote:
>
> > Hi,
> >
> > I do not like the current layout of generated class html files. I would like to:
> > - add some css
> > - remove the author from the top - it is not necessary to have it there, better 
> > thing wuold be to have one 'credits' file or to have all authors in the top 
> > documentation file
> > - put the copyright to the bottom
> > - remove the 'Contents' section from class documentation
> >
> > How can I specify a template for a class.html file? Or is there some other way 
> > how I can do that?
> >
> > Moreover, how can I get rid of parenthesis around protocol names in the 
> > protocol index?
>
> By all means add template support to the AGSHtml class (shouldn't be too hard 
> ... I did spend some
> time thinking abut how it might be done), but please leave the default layout 
> largely as it is,
> as it's designed (meaning I thought about it) for GNUstep.

That would be great to have.

> We have author information in each file, because the GNUstep libraries have 
> lots of authors and
> they should be given credit for their individual pieces of work.  I've seen 
> that stated as quite a
> definite fsf policy, and I agree with it.

Well, I forgot to specify that I was not talking about GNUstep documentation, 
but about documentation of my project.
A do not say that the autor does not have to be mentioned, but... Why user 
wants to read the documentation? Usualy, because he/she wants to get 
information about the library/interface/... so the software documentation 
should be at first place. It is just layout issue, but I think that the author 
and copyright is taking too much place at the top and still is some kind of 
obstacle before user gets to the information he wants.  I would like to put 
authors at the bottom or as mentioned before to separate credits file in the 
form like one used in books for photographs... Author Name:list of pages ... or 
here as ... Author name: list of classes. Class documentation is like one page 
from a book...
Users do not care about authors unles they want to give suggestion, 
corrections, comments, blame...

Similar for copyright, it is better to put it at the bottom of the page, so 
user will get immediately to the point. It is about readability of 
documentation.

> We have copyright at the top simply because that's conventional in most GNU 
> documentation
> I've seen ... however, I don't think there is an actual gnu policy on this, so 
> it could be changed.

Well, as I have mentioned ... its not about conventions, but about usability.

> We have a contents section in classes because the GNUstep libraries have a lot 
> of categories
> (though it would make sense to omit it in the case where a file contains 
> nothing but the class
> documentation).

Hm, is there a way how to specify name for group of methods as in apple's cocoa 
class docs?

Stefan