[Top][All Lists]

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

Re: Base programming manual updates

From: Quentin Mathé
Subject: Re: Base programming manual updates
Date: Wed, 2 Jun 2004 18:37:11 +0200

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

and especially 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 Mathé

reply via email to

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