discuss-gnustep
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Class documentation templates (in autogsdoc)


From: Stefan Urbanek
Subject: Re: Class documentation templates (in autogsdoc)
Date: Thu, 14 Nov 2002 22:27:15 +0100

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






reply via email to

[Prev in Thread] Current Thread [Next in Thread]