Re: Milestones document

[zucchi zedzone mmc com au (NotZed)]

> 
> I think its a bit 'difficult' to write documentation - There is no 
> DOCUMENTED way of writing API documentation - Although there is 
> documentation for writing whitepapers.

Yes there is, gnome-libs/devel-docs/api-comment-style.txt ... that
covers the actual api description part.  There's even a tool for
emacs to help you write them.

The gtk-doc module contains the stuff to actually generate documents
from this, it has its own documentation.

> Also - I think people who want to contribute (well, me at least) - get 
> discouraged because I have to learn DocBook (all I know is that I 
> installed these RPMS for documentation). Also, I heard that people author 
> DocBook stuff using emacs in PSGML mode. A) I use vi B) What the hell is 
> PSGML mode? C) see my reference for documentation on writing API 
> documentation (i.e. what are the procedures one should take?)

The api documenter hardly needs to know docbook, unless you want
to expand on the detail.

BTW If you use vi to write sgml, then you're just making things hard
for yourself for no reason; you really need to use tools for it,
and psgml mode is about the most available/decent free one around.

 Michael

> On Mon, 6 Dec 1999, Havoc Pennington wrote:
> 
> > 
> > On Mon, 6 Dec 1999, Derek Simkowiak wrote:
> > > there are far too many undocumented widgets.  If it were up to me, every
> > > widget/API would have complete descriptions, a list of pitfalls and
> > > common problems, along with an illustrative example.
> > > 
> > 
> > Fortunately, it _is_ up to you - anyone can contribute! We are way
> > understaffed here. 
> > 
> > Havoc
> > 
> > 
> > 
> > -- 
> > To unsubscribe: mail gnome-devel-list-request@gnome.org with "unsubscribe"
> > as the Subject.
> > 
> > 
> 
> 
> -- 
> To unsubscribe: mail gnome-devel-list-request@gnome.org with "unsubscribe"
> as the Subject.
> 
>