Re: Improving documentation & I18N

Victor,

This seems like a pretty good division to me.  I don't have any 
experience with some of the sections I'll be documenting but will study 
the code and try some things out.  If anyone on the list has information 
on ANY of the areas, please post it to the list so that we all can 
benefit by pulling this together in one place.

I have run the autogen.sh/make/make docs process to generate project 
documentation and it works fairly well so we are pretty close there.

Adrian, it would be good if you could tell us what your plans are with 
GtkExtra.  Since we will be modifying the actual code to insert the 
documentation, we need to know what you might be changing.

One other thing, I get complaints from autogen as follows:

    autoheader: WARNING: Using auxiliary files such as `acconfig.h', `config.h.bot'

    autoheader: WARNING: and `config.h.top', to define templates for `config.h.in'

    autoheader: WARNING: is deprecated and discouraged.

    autoheader: 

    autoheader: WARNING: Using the third argument of `AC_DEFINE' and

    autoheader: WARNING: `AC_DEFINE_UNQUOTED' allows one to define a template without

    autoheader: WARNING: `acconfig.h':

    autoheader: 

    autoheader: WARNING:   AC_DEFINE([NEED_FUNC_MAIN], 1,

    autoheader:             [Define if a function `main' is needed.])

    autoheader: 

    autoheader: WARNING: More sophisticated templates can also be produced, see the

    autoheader: WARNING: documentation.

Is this just my environment (autoheader 2.61) or do others see this as 
well?  Is there anything planned to fix this?

Dan

Victor Mierla wrote:
>> 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=/