Re: Base programming manual updates

[Quentin Mathé]

Le 17 mai 04, à 17:10, Adrian Robert a écrit :

> Hi all,
>
> I've been working on improving the GNUstep documentation, primarily  
> that for the Base library so far.  One thing that I did was to add a  
> "frames" mode to the autogsdoc HTML docs generator to make the API  
> docs easier to navigate.  This is in CVS already.

Nice improvement.

> Not yet in CVS, I also added a very minimal HTML "front page" to help  
> get around the hierarchy that goes in System/Library/Documentation.

Well this front page is nice, it makes the things look clearer.
The header just need to have background pattern which matches the  
GNUstep title/picture; also this GNUstep title/picture needs to be left  
aligned.

> As well, I've done some work on improving the "Programming Manual".   
> This covers Objective-C, provides an overview of GNUstep, and  
> introduces the Base (Foundation) library.  While it is true that much  
> of this information can be found in the Apple docs, GNUstep needs to  
> stand on its own.  If someone has just installed GNUstep on their  
> machine, they should be able to read how to use it without going out  
> and scrounging for Apple's docs - which leave some things to be  
> desired anyway.  Also there are a lot of GNUstep differences (mostly  
> improvements ;) that need to be described.
>
> I invite you to take a look at
>
> http://kamares.ucsd.edu/~arobert/GNUstep/Documentation/
>
> and especially
>
> http://kamares.ucsd.edu/~arobert/GNUstep/Documentation/Developer/Base/ 
> ProgrammingManual/manual_toc.html
>
> There was some reorganization from the previous incarnation of the  
> manual, and a lot of filling in.  The main chapter on the Base library  
> APIs has yet to be done, but is not planned to be very detailed -- it  
> will mainly quickly point out the main facilities of the library, on  
> the basis that some people will prefer this type of 20,000 foot view  
> to poking around through the classes to find if some capability is  
> there or not.  (I'm particularly interested in getting Java developers  
> familiar with the JDK APIs quickly up to speed on the Foundation.)

The programming manual looks now very complete and detailed, it has in  
my opinion a good 'detailed explanations/ simple introductions' ratio.  
Otherwise I would like to see a PDF version.

> If anyone has time I would be very interested in feedback on the  
> following points (in priority order):
>
> 1) Is there anything said that is wrong?

Not I have seen, but my reading has been really fast.

> 2) Are there any important details missing under the topics that are  
> covered?

May be a class cluster implementation example would be welcome.

> 3) Are there any important sections or topics that are NOT covered and  
> should be?

Hmm. Well, there are other topics like metaclasses (related to the  
runtime implementation), and -base specific stuff like KVC and  
eventually also archiving.

> I know there are issues with texinfo formatting/references, coding  
> standards in the examples, etc., this will be fixed in a later pass..   
> Stylistic comments are welcome as well, however I might ignore them.  
> ;-) (Seriously, the first priority is to get complete coverage; it can  
> always be improved later on.)

On the stylistic point of view, some colors could be welcome and would  
eliminate the need of the frames with a large border which aren't the  
nicest thing ever :-).

Quentin.

--
Quentin Mathé
address@hidden