API Update [long, but read it anyway]

["David C. Mason" <dcm redhat com>]

Hi Everyone,

This is an update to my emotional, angry note last week about the
status of the GNOME API docs. Much has happened in a week. You have
come through with high-flying colors. My enormous thanks to the
following people for getting started on docs:

Bertrand, Steve, Tim G., Lee, Daniel, Augusto, Peter, Elliot, Havoc,
and Jonathan

You are all a credit to the spirit of GNOME. Now... for the rest of
you here is a handy FAQ for the last week of API docs:


Q.  Will you assign me something Dave?

A.  No, you need to get off your butt and read the list of available
    items and select the ones you feel most comfortable documenting. I
    don't want to be in the position of giving you something you don't 
    quite understand.


Q.  Do I just comment the code?

A.  Actually no. gtk-doc, the system we use, scans the code and makes
    template files (in the tmpl directories) which you can fill in
    with all of your vast knowledge. You should read the docs that
    come with the gtk-doc system, there is some good stuff there.


Q.  Am I missing something? When I do a *make* in devel-docs I get many
    errors and no "tmpl" files.

A.  You need to install gtk-doc first. You can get it from the gtk-doc 
    module in CVS or from http://www.gtk.org/rdp/


Q.  I don't know much about SGML and I don't know where to get the
    tools to work with it.  

A.  First, you should read the docs that come with gtk-doc as it helps
    you with the necessary SGML knowledge you will need for this
    project. You really don't need to know much, just write stuff
    between the <para> tags provided for you. You can get the DocBook
    tools from http://sourceware.cygnus.com/docbook-tools/ These are
    rpms right now with some tarballs that don't actually install but
    contain the files needed, but if you ask for help we can probably
    get you up and running without rpm. 

 
Q.  There are items that say they need "re-formatting" can I do those?

A.  Let me get back to you on those. We have to get a little more
    organized and see what needs to be done for these. I will address 
    those later when I bug you all again.


Q.  Hey, I did a lot of writing before you started bugging us. Why
    isn't my name up on the list of completed items.

A.  Because I don't know who wrote what. If you like to see your name
    on a web page let me know which ones you did and I will add it.


Q.  I'd love to help but I don't know much about the GNOME libs.

A.  Why not give it a shot anyway. One guy said he had only written
    three or four apps for GNOME... I had to remind him that he is a 
    veteran in this project. If you know more about GTK give them a
    hand - http://www.gtk.org/rdp/ 


Q.  What about the GTK API, isn't it as important?

A.  It sure is, and they need more help than we do at this
    point. Please, if you know anything about GTK+, give them a
    hand. You can get the skinny at http://www.gtk.org/rdp/


Q.  You would get more help if you didn't suck so much.

A.  We don't need to be flamed, we just need help.



You can always check out the status page to see how we are doing
(http://developer.gnome.org/doc/API/api-status.html) but for those who
can't figure out how to point your browser to the previous address,
here is a list of things left to be documented.

gnome-canvas-image
gnome-canvas-polygon
gnome-canvas-rect-ellipse
gnome-canvas-text
gnome-canvas-util
gnome-canvas-widget
gnome-client
gnome-color-picker
gnome-ice
gnome-icon-entry
gnome-icon-sel
gnome-number-entry
gnome-pixmap
gnome-pixmap-entry
gnome-preferences
gnome-properties
gnome-property-entries
gnome-scores
gnome-stock
gnome-winhints
gnometypes
gtk-ted
gtkcauldron
gtkdial
gtkpixmapmenuitem

Libart-lgpl - ALL!


Until I bug you all again.. toodle-oo.

Dave