Re: Improving documentation & I18N

> Hi Victor,
> 
> I am putting you in touch with Dan Gruhn, adding him to the loop. 
> He's contacted me volunteering to work on the documentation, too. 

This is wonderful news to have more people working on docs updates. Docs 
needs a urgent facelift.

> Maybe we should agree on a way to proceed, the three of us. I 
> support the idea of using gtk-doc and I can't wait to see some i18n support.
> Maybe Victor can give us a sort of status update on how things were 
> left, and we can figure out how to proceed from there.
> 

GTKEXTRA DOCUMENTATION STATUS:

- Initially my primary interest was (and still is) GtkSheet, so the docs for 
it is 100% complete.
 GtkSheet has also a nice tutorial with pics and stuff.

For the rest is like this:
- GtkBorderCombo : 100%
- GtkCharSel : 100%
- GtkCheckItem : 100%
- GtkComboBox : 100%
- GtkFileList : 100%
- GtkFontCombo : 100%
- GtkIconFileSelection : 100%
- GtkIconList : 100%
- GtkPlot : 50-60%
- GtkPlot3D : 30%
- GtkPlotBar : 100%
- GtkPlotBox  : 100%
- GtkPlotCsurface: 0% (just function definitions , no explications)
- GtkPlotCanvas : 60%
- GtkPlotData : 0% (just function definitions , no explications)
- GtkPlotdt : 0% (just function definitions , no explications)
- GtkPlotflux 0% (just function definitions , no explications)
- GtkPlotPC : 0% (just function definitions , no explications)
- GtkPlotPixmap : 100%
- GtkPlotPolar : 0% (just function definitions , no explications)
- GtkPlotPrint : 0% (just function definitions , no explications)
- GtkPlotPS : 0% (just function definitions , no explications)
- GtkPlotSurface : 0% (just function definitions , no explications)
- GtkPSFont : 80%
- GtkToggleCombo : 100%

The percentage represents the number of explained functions. This situation 
is relevant for GtkExtra 0.99.17.
The docs are now in HTML format . I wrote them like this because at that time 
i was against mixing code with docs
(and still am) , but it seems that most of developers found it more easy to 
maintain docs in code and don't 
want to mess with a (commercial) HTML editor.

So i propose using Gtk-Doc because it's a tool used to extract API 
documentation from C-code like Doxygen,
but handles documentation of GObject (including signals and properties) that 
makes it very suitable for
GTK+ apps and libraries. It uses docbook for intermediate files and can 
produce html by default and 
pdf/man-pages with some extra work.
At the moment i'm getting familiar with Gtk-DOc myself , so there could be 
some rough edges in the beginning.

I'm proposing dividing the .c source files like this :
- the Gtk* classes specified above with percentage ~100% - Victor's part - 
because I already know what these 
functions are all about - wrote their explications in the first place.
- the Gtk* clasess with  < 50% - Dan's part because i have only a slight 
ideea what GtkPlot and friends are really
all about.(never used it)
- Dan and I should take care of implementing I18N _("") for our parts and 
generating .po files for various languages
for which there are available translators
- Automake/autoconf scripts - maybe Adrian can help us a little bit here if 
we can't get it right.
As far as i'm concerned autoconf is a complex brain-dead system and i try to 
stay away from it as much as possible ;-D


Thses are some relevant links for docs:
- http://library.gnome.org/devel/gdp-style-guide/stable/fundamentals.html.en
- http://library.gnome.org/devel/gdp-style-guide/stable/wordlist.html.en
- http://library.gnome.org/devel/gdp-style-guide/stable/screenshots.html.en
- http://live.gnome.org/TranslationProject/LocalisationGuide



> Victor, I don't remember, but do you have CVS access? In case you 
> don't, do you have a SF account to add you  to the team? Thank you 
> to both of you for you offers to contribute to the project.

Yes , i have CVS write access. My user name is kornos.
We thank you for this very nice library, at least we can do is write some 
docs.



>[email protected]: 
>  I saw your January 2, 2008 post to Adrian on nabble.com and wondered what 
happened with you.  I, too, would like to see GtkExtra advanced and improved 
and feel that solid documentation is a big step forward.
>I whole heartedly vote for the gtkdocs approach and am getting familiar with 
it now.    I look forward to any status you have on any documentation you 
have done on GtkExtra.
>Best regards,
>Dan

In January i had some spare time and thought about giving some of it to 
GtkExtra.Unfortunately there was no response
and i thought and Gtkextra was going on an indefinite hiatus. I'm glad i was 
wrong.
After that i was tempted by the dark side ( .NET - that is) ;-) and i can 
tell you now for sure that all the GTK,QT 
and other graphical widgets in UNIX world are simply bullshit compared 
to .NET considering efficiency and ergonomicity.
I ported one GTK project wich took a year to write in less than a month. I 
can't wait for Novell to finish MONO and i won't
look back at any other widgets (GTK or whatever). 
But enough with that for now i'll have my focus set on GTKEXTRA docs. ;-)


I wait for your opinions about this email and please don't forget to CC to 
the gtkextra  mailing list also.


Best regards 
Victor




--------------------------------------------------

Flash.ro - Best free webmail service hosted by Idilis
.........................................................
Idilis - Internet Provider :: www.idilis.net
Inchiriem conexiuni radio si in zone neracordate la coloana - Broadband Wireless Idilis -




-------------------------------------------------------------------------
This SF.Net email is sponsored by the Moblin Your Move Developer's challenge
Build the coolest Linux based applications with Moblin SDK & win great prizes
Grand prize is a trip for two to an Open Source event anywhere in the world
http://moblin-contest.org/redirect.php?banner_id=100&url=/