Re: Improving documentation & I18N

Hi all,

I am very excited about the momentum that we are getting!
I agree with Victor's plan, and we should go ahead with it.
I would say that you guys try to document all those functions that you 
understand, and leave to me others that you don't.
I can take care of those, once you have finished your part.

Regarding plans with gtkextra, I think it's fair to say that the code is 
pretty stable and almost ready for a release.
I still want to fix a couple of (minor) bugs with gtkitementry.c and 
gtkiconlist.c. If I find the time, I would also like to improve the 
algorithms for density and contour plots.
But I think I won't be touching the API, so you guys can feel 
comfortable with the current files.

Regarding autogen.sh, that is one of the items that I need to work on 
before a release. It kinda works, but it complains a lot, as you have seen.
I believe that at certain point some changes in automake broke a couple 
of things, and we simply have to figure out what the new proper way to 
make those calls.
I would look at some other gtk project, and look at their autogen file 
to see if I can get a clue.

Thank you again, guys, I very much appreciate you contribution!
Saludos,
<ADRIAN>

Dan Gruhn wrote:

>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=/
>_______________________________________________
>Scigraphica-gtkextra mailing list
>[email protected]
>https://lists.sourceforge.net/lists/listinfo/scigraphica-gtkextra
>
>  
>


-------------------------------------------------------------------------
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=/