Re: gtk+ documentation wikified

2009-03-09 Thread Maciej Piechotka 
On Wed, 2009-03-04 at 12:03 +0200, Stefan Kost wrote:
 Maciej Piechotka schrieb:
  On Fri, 2009-02-20 at 10:37 +, Alberto Ruiz wrote:

  2009/2/20 Maciej Piechotka uzytkown...@gmail.com:
  
  Eugene Gorodinsky e.gorodin...@gmail.com writes:
 

  Hi all
 
  Since you guys are discussing the redesign of the gtk+ website, I'd
  like to propose an idea that I have. I've seen quite a lot of comments
  saying gtk+ documentation isn't as good as qt's. What do you think of
  having a wiki that documents all of gtk+ api?
  
  I'm not sure but I guess that it would be possible to integrate it
  somehow with SVN(or, even better, git/bzr/...). The wiki syntax could be
  translated into gtkdoc.

  Gtkdocs are stored in the source code headers,
  
 
  BTW - this idea, which I personally like, is not common. Gtk-doc
  comments are usually placed in source files. The exception is for
  example webkit-gtk (or at least used to be).
 

  that helps developers
  to keep documentation up to date.
  That means that pushing documentation upstream is not possible.
 
  What we could do is to have a queue of contributions/feedback and
  notify the module maintainer about it.
 
  
 
  I never thought about pushing it into trunk directly. Next paragraph of my 
  mail is:
  With svn: The developer/maintainer of wiki could download wiki syntax as
  a patch, apply it and commit.
 
  And the merging usually is quite possible:
  - Find symbol before which there is comment started by /** (or any other
  - Insert the generated doc/update it/...
  - Diff with previous
  In some cases it will need to be handled manually - but I guess that in 99% 
  it will not.
 
  Regards
 

 Hi,
 

Hi. Sorry for delay in responding.

 I put some notes online:
 http://live.gnome.org/DocumentationProject/GtkDocFuture#head-a95d3540bfa9b29299058c0e13b162ce2a772da7
 Should the prototype submit patches to bugzilla?
 
 subtasks that I could need help with:
 1) start a basic cgi for library.gnome.org (if I do it its gonna be
 perl, but I don't care so much)
   * have a hasmap there docmodule-sourcedir
   * implements a fast way to get from symbol to docblob
   * when calling edit.cgi?docmodule=glibsymbol=g_object_new
  * show a textfield with the docs for it
 
 2) write a bugzilla_submit_patch function in for the above cgi (see link
 for how bugbuddy is doing it).
 
 3) build-brigade - anyone reading this? whats the chances of getting a
 doc-builder, where we could also run this cgi?
 
 Stefan

I can help with the first task (although I'm afraid that I'm too
inexperienced to handle it on my own) or I can try to write something
for 2).

Regards


signature.asc
Description: This is a digitally signed message part
___
gtk-devel-list mailing list
gtk-devel-list@gnome.org
http://mail.gnome.org/mailman/listinfo/gtk-devel-list

Re: gtk+ documentation wikified

2009-03-04 Thread Stefan Kost 
Maciej Piechotka schrieb:
 On Fri, 2009-02-20 at 10:37 +, Alberto Ruiz wrote:
   
 2009/2/20 Maciej Piechotka uzytkown...@gmail.com:
 
 Eugene Gorodinsky e.gorodin...@gmail.com writes:

   
 Hi all

 Since you guys are discussing the redesign of the gtk+ website, I'd
 like to propose an idea that I have. I've seen quite a lot of comments
 saying gtk+ documentation isn't as good as qt's. What do you think of
 having a wiki that documents all of gtk+ api?
 
 I'm not sure but I guess that it would be possible to integrate it
 somehow with SVN(or, even better, git/bzr/...). The wiki syntax could be
 translated into gtkdoc.
   
 Gtkdocs are stored in the source code headers,
 

 BTW - this idea, which I personally like, is not common. Gtk-doc
 comments are usually placed in source files. The exception is for
 example webkit-gtk (or at least used to be).

   
 that helps developers
 to keep documentation up to date.
 That means that pushing documentation upstream is not possible.

 What we could do is to have a queue of contributions/feedback and
 notify the module maintainer about it.

 

 I never thought about pushing it into trunk directly. Next paragraph of my 
 mail is:
 With svn: The developer/maintainer of wiki could download wiki syntax as
 a patch, apply it and commit.

 And the merging usually is quite possible:
 - Find symbol before which there is comment started by /** (or any other
 - Insert the generated doc/update it/...
 - Diff with previous
 In some cases it will need to be handled manually - but I guess that in 99% 
 it will not.

 Regards

   
Hi,

I put some notes online:
http://live.gnome.org/DocumentationProject/GtkDocFuture#head-a95d3540bfa9b29299058c0e13b162ce2a772da7
Should the prototype submit patches to bugzilla?

subtasks that I could need help with:
1) start a basic cgi for library.gnome.org (if I do it its gonna be
perl, but I don't care so much)
  * have a hasmap there docmodule-sourcedir
  * implements a fast way to get from symbol to docblob
  * when calling edit.cgi?docmodule=glibsymbol=g_object_new
 * show a textfield with the docs for it

2) write a bugzilla_submit_patch function in for the above cgi (see link
for how bugbuddy is doing it).

3) build-brigade - anyone reading this? whats the chances of getting a
doc-builder, where we could also run this cgi?

Stefan
___
gtk-devel-list mailing list
gtk-devel-list@gnome.org
http://mail.gnome.org/mailman/listinfo/gtk-devel-list

Re: gtk+ documentation wikified

2009-03-04 Thread Frederic Peters 
Stefan Kost wrote:

 subtasks that I could need help with:
 1) start a basic cgi for library.gnome.org (if I do it its gonna be
 perl, but I don't care so much)
   * have a hasmap there docmodule-sourcedir
   * implements a fast way to get from symbol to docblob
   * when calling edit.cgi?docmodule=glibsymbol=g_object_new
  * show a textfield with the docs for it
 
 2) write a bugzilla_submit_patch function in for the above cgi (see link
 for how bugbuddy is doing it).

This could probably be part of the symbols_server,
(see http://bugzilla.gnome.org/show_bug.cgi?id=500378)


 3) build-brigade - anyone reading this? whats the chances of getting a
 doc-builder, where we could also run this cgi?

I had a few offers for build slaves, I'll get back to them.


Frederic
___
gtk-devel-list mailing list
gtk-devel-list@gnome.org
http://mail.gnome.org/mailman/listinfo/gtk-devel-list

Re: gtk+ documentation wikified

2009-03-04 Thread Eugene Gorodinsky 
implements a fast way to get from symbol to docblob
A database seems like good idea here + and tools to sync with the SVN
(is there a way to run a script on the server side when a file has
been submitted?)

2009/3/4 Stefan Kost enso...@hora-obscura.de:
 Maciej Piechotka schrieb:
 On Fri, 2009-02-20 at 10:37 +, Alberto Ruiz wrote:

 2009/2/20 Maciej Piechotka uzytkown...@gmail.com:

 Eugene Gorodinsky e.gorodin...@gmail.com writes:


 Hi all

 Since you guys are discussing the redesign of the gtk+ website, I'd
 like to propose an idea that I have. I've seen quite a lot of comments
 saying gtk+ documentation isn't as good as qt's. What do you think of
 having a wiki that documents all of gtk+ api?

 I'm not sure but I guess that it would be possible to integrate it
 somehow with SVN(or, even better, git/bzr/...). The wiki syntax could be
 translated into gtkdoc.

 Gtkdocs are stored in the source code headers,


 BTW - this idea, which I personally like, is not common. Gtk-doc
 comments are usually placed in source files. The exception is for
 example webkit-gtk (or at least used to be).


 that helps developers
 to keep documentation up to date.
 That means that pushing documentation upstream is not possible.

 What we could do is to have a queue of contributions/feedback and
 notify the module maintainer about it.



 I never thought about pushing it into trunk directly. Next paragraph of my 
 mail is:
 With svn: The developer/maintainer of wiki could download wiki syntax as
 a patch, apply it and commit.

 And the merging usually is quite possible:
 - Find symbol before which there is comment started by /** (or any other
 - Insert the generated doc/update it/...
 - Diff with previous
 In some cases it will need to be handled manually - but I guess that in 99% 
 it will not.

 Regards


 Hi,

 I put some notes online:
 http://live.gnome.org/DocumentationProject/GtkDocFuture#head-a95d3540bfa9b29299058c0e13b162ce2a772da7
 Should the prototype submit patches to bugzilla?

 subtasks that I could need help with:
 1) start a basic cgi for library.gnome.org (if I do it its gonna be
 perl, but I don't care so much)
  * have a hasmap there docmodule-sourcedir
  * implements a fast way to get from symbol to docblob
  * when calling edit.cgi?docmodule=glibsymbol=g_object_new
     * show a textfield with the docs for it

 2) write a bugzilla_submit_patch function in for the above cgi (see link
 for how bugbuddy is doing it).

 3) build-brigade - anyone reading this? whats the chances of getting a
 doc-builder, where we could also run this cgi?

 Stefan
 ___
 gtk-devel-list mailing list
 gtk-devel-list@gnome.org
 http://mail.gnome.org/mailman/listinfo/gtk-devel-list

___
gtk-devel-list mailing list
gtk-devel-list@gnome.org
http://mail.gnome.org/mailman/listinfo/gtk-devel-list

Re: gtk+ documentation wikified

2009-02-27 Thread Maciej Piechotka 
On Fri, 2009-02-20 at 10:37 +, Alberto Ruiz wrote:
 2009/2/20 Maciej Piechotka uzytkown...@gmail.com:
  Eugene Gorodinsky e.gorodin...@gmail.com writes:
 
  Hi all
 
  Since you guys are discussing the redesign of the gtk+ website, I'd
  like to propose an idea that I have. I've seen quite a lot of comments
  saying gtk+ documentation isn't as good as qt's. What do you think of
  having a wiki that documents all of gtk+ api?
 
  I'm not sure but I guess that it would be possible to integrate it
  somehow with SVN(or, even better, git/bzr/...). The wiki syntax could be
  translated into gtkdoc.
 
 Gtkdocs are stored in the source code headers,

BTW - this idea, which I personally like, is not common. Gtk-doc
comments are usually placed in source files. The exception is for
example webkit-gtk (or at least used to be).

 that helps developers
 to keep documentation up to date.
 That means that pushing documentation upstream is not possible.
 
 What we could do is to have a queue of contributions/feedback and
 notify the module maintainer about it.
 

I never thought about pushing it into trunk directly. Next paragraph of my mail 
is:
With svn: The developer/maintainer of wiki could download wiki syntax as
a patch, apply it and commit.

And the merging usually is quite possible:
- Find symbol before which there is comment started by /** (or any other
- Insert the generated doc/update it/...
- Diff with previous
In some cases it will need to be handled manually - but I guess that in 99% it 
will not.

Regards



signature.asc
Description: This is a digitally signed message part
___
gtk-devel-list mailing list
gtk-devel-list@gnome.org
http://mail.gnome.org/mailman/listinfo/gtk-devel-list

Re: gtk+ documentation wikified

2009-02-22 Thread Steve Frécinaux 

Mathias Hasselmann wrote:

Am Donnerstag, den 19.02.2009, 10:33 -0500 schrieb Dominic Lachowicz:

That's hard-ish to do today. GTK+'s documentation is generated in
large part by scanning comments in C code, which a program then turns
into HTML. Any proposal would require a way to keep the Wiki and the C
comments in-sync.


Still that proposed idea has some merits: Currently entry barrier for
fixing GTK+ docs still is quite high.

Guess the most trivial fix would be, to do what the PHP community does
and attach some comment system/forum to library.gnome.org.

More sophisticated would be some application that allows editing of API
docs via web site and provides some way to easily merge them back. Maybe
automatic commits to some separate branch? Maybe just additions to some
patch queue? Don't know. But maybe a nice SoC project?


I remember some old mockups of library.gnome.org including line 
comments, ie comments that were attached to a particular chunk of text, 
rather to being attached to the whole page.

___
gtk-devel-list mailing list
gtk-devel-list@gnome.org
http://mail.gnome.org/mailman/listinfo/gtk-devel-list

Re: gtk+ documentation wikified

2009-02-22 Thread Stefan Kost 
Eugene, Maciej,

I've have some concept for the gtk-doc side of things. For the server side I've
ideas too, if you want to join, there is #gtkdoc on gimpnet irc. Lets discuss
there. Need to talk to the web-site hackers to come up with the easiest/best way
to integrate.

Stefan

Maciej Piechotka schrieb:
 Stefan Kost enso...@hora-obscura.de writes:
 
 hi,

 Maciej Piechotka schrieb:
 Eugene Gorodinsky e.gorodin...@gmail.com writes:

 Hi all

 Since you guys are discussing the redesign of the gtk+ website, I'd
 like to propose an idea that I have. I've seen quite a lot of comments
 saying gtk+ documentation isn't as good as qt's. What do you think of
 having a wiki that documents all of gtk+ api?
 I'm not sure but I guess that it would be possible to integrate it
 somehow with SVN(or, even better, git/bzr/...). The wiki syntax could be
 translated into gtkdoc.

 With svn: The developer/maintainer of wiki could download wiki syntax as
 a patch, apply it and commit.

 With git/bzr/...: It would function more as a separate branch which
 could be merged - along with the edit history.

 Problems: Probably it can have problems with manual merging of docs.
 Imho the actual problem is to locate where to apply the changes. If you want 
 to
 improve the docs of _foo(), you need to gtk-doc comment blob for it, show 
 that
 to the users and let him edit it. Then make a patch and submit or apply.

 
 AFAIU gtk-doc comment is usually just before declaring the symbol. C is
 relativly simple to pass so it is simple to locate. The real problems
 are the conflicts. However, as I think now, the methods are rarly moved
 from file to file, rarly deleted and does not change the meaning. So it
 would be rather rare.
 
 If someone would want to help me to do if for gtk-doc that would rock. 
 Basically
 we need a new output mode, where one specifies the link to the cgi. All the
 extracted docbook would get some annotation for the location of the original
 gtk-doc comment. The xslt would produce edit links for each blob. Klicking 
 that
 link takes you to a form where you can edit the gtk-doc comment.

 Open Questions:
 * should it include all the original comments as hidden fileds (gets big) or 
 can
 the server side script grab the lines from the sources, if vcs-tag, source 
 file
 and line start/end is given?
 
 I guess vcs-tags is better option. There are few stable releases of gtk+ in a
 branch (half year).
 
 * how to submit the change:
   * patch to bugzilla (does anyone know of about how to do that 
 automatically)
   * commit to a specific branch which maintainer regalarily merge

 
 I guess that the specific branch will be ok(but I'm not gtk+
 developer). In future when (if?) gtk+ will be on DCMS it can have even
 featured author (I know it is somehow lame but being in the history of
 the projects is... somehow nice). 
 
 Would thank be enough for a GSoC project? I would mentor it, but I would 
 rather
 juck hack with someone diretly on it? Who joins?

 
 I don't know if I will be helpful (I have virtually no experience of
 gtk-doc internals and I'm rather beginner programmer) but I can at least
 try.
 
 Stefan

 Regards
 
 Regards

___
gtk-devel-list mailing list
gtk-devel-list@gnome.org
http://mail.gnome.org/mailman/listinfo/gtk-devel-list

Re: gtk+ documentation wikified

2009-02-22 Thread Maciej Piechotka 
Stefan Kost enso...@hora-obscura.de writes:

 Eugene, Maciej,

 I've have some concept for the gtk-doc side of things. For the server side 
 I've
 ideas too, if you want to join, there is #gtkdoc on gimpnet irc. Lets discuss
 there. Need to talk to the web-site hackers to come up with the easiest/best 
 way
 to integrate.

 Stefan


Ok. But when? I'm not able to be 24h/day at irc...

Regards

PS.
On irc://irc.gimp.org/#gtkdoc there are currently 2 users (including me)
is channel not-yet-created or misspelled?
-- 
I've probably left my head... somewhere. Please wait untill I find it.
Homepage (pl_PL): http://uzytkownik.jogger.pl/
(GNU/)Linux User: #425935 (see http://counter.li.org/)

___
gtk-devel-list mailing list
gtk-devel-list@gnome.org
http://mail.gnome.org/mailman/listinfo/gtk-devel-list

Re: gtk+ documentation wikified

2009-02-20 Thread Maciej Piechotka 
Eugene Gorodinsky e.gorodin...@gmail.com writes:

 Hi all

 Since you guys are discussing the redesign of the gtk+ website, I'd
 like to propose an idea that I have. I've seen quite a lot of comments
 saying gtk+ documentation isn't as good as qt's. What do you think of
 having a wiki that documents all of gtk+ api?

I'm not sure but I guess that it would be possible to integrate it
somehow with SVN(or, even better, git/bzr/...). The wiki syntax could be
translated into gtkdoc.

With svn: The developer/maintainer of wiki could download wiki syntax as
a patch, apply it and commit.

With git/bzr/...: It would function more as a separate branch which
could be merged - along with the edit history.

Problems: Probably it can have problems with manual merging of docs.

Regards
-- 
I've probably left my head... somewhere. Please wait untill I find it.
Homepage (pl_PL): http://uzytkownik.jogger.pl/
(GNU/)Linux User: #425935 (see http://counter.li.org/)

___
gtk-devel-list mailing list
gtk-devel-list@gnome.org
http://mail.gnome.org/mailman/listinfo/gtk-devel-list

Re: gtk+ documentation wikified

2009-02-20 Thread Stefan Kost 
hi,

Maciej Piechotka schrieb:
 Eugene Gorodinsky e.gorodin...@gmail.com writes:
 
 Hi all

 Since you guys are discussing the redesign of the gtk+ website, I'd
 like to propose an idea that I have. I've seen quite a lot of comments
 saying gtk+ documentation isn't as good as qt's. What do you think of
 having a wiki that documents all of gtk+ api?
 
 I'm not sure but I guess that it would be possible to integrate it
 somehow with SVN(or, even better, git/bzr/...). The wiki syntax could be
 translated into gtkdoc.
 
 With svn: The developer/maintainer of wiki could download wiki syntax as
 a patch, apply it and commit.
 
 With git/bzr/...: It would function more as a separate branch which
 could be merged - along with the edit history.
 
 Problems: Probably it can have problems with manual merging of docs.

Imho the actual problem is to locate where to apply the changes. If you want to
improve the docs of _foo(), you need to gtk-doc comment blob for it, show that
to the users and let him edit it. Then make a patch and submit or apply.

If someone would want to help me to do if for gtk-doc that would rock. Basically
we need a new output mode, where one specifies the link to the cgi. All the
extracted docbook would get some annotation for the location of the original
gtk-doc comment. The xslt would produce edit links for each blob. Klicking that
link takes you to a form where you can edit the gtk-doc comment.

Open Questions:
* should it include all the original comments as hidden fileds (gets big) or can
the server side script grab the lines from the sources, if vcs-tag, source file
and line start/end is given?
* need to try the annotation to embed the location into docbook
* how to submit the change:
  * patch to bugzilla (does anyone know of about how to do that automatically)
  * commit to a specific branch which maintainer regalarily merge

Would thank be enough for a GSoC project? I would mentor it, but I would rather
juck hack with someone diretly on it? Who joins?

Stefan

 
 Regards

___
gtk-devel-list mailing list
gtk-devel-list@gnome.org
http://mail.gnome.org/mailman/listinfo/gtk-devel-list

Re: gtk+ documentation wikified

2009-02-20 Thread Eugene Gorodinsky 
As I understood the way this thing would work is: after the gtk-doc
tool genereates documentation a cgi is executed that would add the new
version of the documentation to the wiki database, and whenever the
documentation in the wiki gets modified, another cgi is executed that
would change the documentation in the source code. I believe this
isn't going to work very well for cases when a function has a lot of
documentation as well as examples on its use etc. For example a
function like glAccum
(http://www.opengl.org/sdk/docs/man/xhtml/glAccum.xml) in OpenGL has
quite a lot of information on it, if all of that were put inside the
source code, it might be a little too much information. Regardles
though, I wouldn't mind helping out.

2009/2/20 Stefan Kost enso...@hora-obscura.de:
 hi,

 Maciej Piechotka schrieb:
 Eugene Gorodinsky e.gorodin...@gmail.com writes:

 Hi all

 Since you guys are discussing the redesign of the gtk+ website, I'd
 like to propose an idea that I have. I've seen quite a lot of comments
 saying gtk+ documentation isn't as good as qt's. What do you think of
 having a wiki that documents all of gtk+ api?

 I'm not sure but I guess that it would be possible to integrate it
 somehow with SVN(or, even better, git/bzr/...). The wiki syntax could be
 translated into gtkdoc.

 With svn: The developer/maintainer of wiki could download wiki syntax as
 a patch, apply it and commit.

 With git/bzr/...: It would function more as a separate branch which
 could be merged - along with the edit history.

 Problems: Probably it can have problems with manual merging of docs.

 Imho the actual problem is to locate where to apply the changes. If you want 
 to
 improve the docs of _foo(), you need to gtk-doc comment blob for it, show that
 to the users and let him edit it. Then make a patch and submit or apply.

 If someone would want to help me to do if for gtk-doc that would rock. 
 Basically
 we need a new output mode, where one specifies the link to the cgi. All the
 extracted docbook would get some annotation for the location of the original
 gtk-doc comment. The xslt would produce edit links for each blob. Klicking 
 that
 link takes you to a form where you can edit the gtk-doc comment.

 Open Questions:
 * should it include all the original comments as hidden fileds (gets big) or 
 can
 the server side script grab the lines from the sources, if vcs-tag, source 
 file
 and line start/end is given?
 * need to try the annotation to embed the location into docbook
 * how to submit the change:
  * patch to bugzilla (does anyone know of about how to do that automatically)
  * commit to a specific branch which maintainer regalarily merge

 Would thank be enough for a GSoC project? I would mentor it, but I would 
 rather
 juck hack with someone diretly on it? Who joins?

 Stefan


 Regards

 ___
 gtk-devel-list mailing list
 gtk-devel-list@gnome.org
 http://mail.gnome.org/mailman/listinfo/gtk-devel-list

___
gtk-devel-list mailing list
gtk-devel-list@gnome.org
http://mail.gnome.org/mailman/listinfo/gtk-devel-list

Re: gtk+ documentation wikified

2009-02-20 Thread Maciej Piechotka 
Stefan Kost enso...@hora-obscura.de writes:

 hi,

 Maciej Piechotka schrieb:
 Eugene Gorodinsky e.gorodin...@gmail.com writes:
 
 Hi all

 Since you guys are discussing the redesign of the gtk+ website, I'd
 like to propose an idea that I have. I've seen quite a lot of comments
 saying gtk+ documentation isn't as good as qt's. What do you think of
 having a wiki that documents all of gtk+ api?
 
 I'm not sure but I guess that it would be possible to integrate it
 somehow with SVN(or, even better, git/bzr/...). The wiki syntax could be
 translated into gtkdoc.
 
 With svn: The developer/maintainer of wiki could download wiki syntax as
 a patch, apply it and commit.
 
 With git/bzr/...: It would function more as a separate branch which
 could be merged - along with the edit history.
 
 Problems: Probably it can have problems with manual merging of docs.

 Imho the actual problem is to locate where to apply the changes. If you want 
 to
 improve the docs of _foo(), you need to gtk-doc comment blob for it, show that
 to the users and let him edit it. Then make a patch and submit or apply.


AFAIU gtk-doc comment is usually just before declaring the symbol. C is
relativly simple to pass so it is simple to locate. The real problems
are the conflicts. However, as I think now, the methods are rarly moved
from file to file, rarly deleted and does not change the meaning. So it
would be rather rare.

 If someone would want to help me to do if for gtk-doc that would rock. 
 Basically
 we need a new output mode, where one specifies the link to the cgi. All the
 extracted docbook would get some annotation for the location of the original
 gtk-doc comment. The xslt would produce edit links for each blob. Klicking 
 that
 link takes you to a form where you can edit the gtk-doc comment.

 Open Questions:
 * should it include all the original comments as hidden fileds (gets big) or 
 can
 the server side script grab the lines from the sources, if vcs-tag, source 
 file
 and line start/end is given?

I guess vcs-tags is better option. There are few stable releases of gtk+ in a
branch (half year).

 * how to submit the change:
   * patch to bugzilla (does anyone know of about how to do that automatically)
   * commit to a specific branch which maintainer regalarily merge


I guess that the specific branch will be ok(but I'm not gtk+
developer). In future when (if?) gtk+ will be on DCMS it can have even
featured author (I know it is somehow lame but being in the history of
the projects is... somehow nice). 

 Would thank be enough for a GSoC project? I would mentor it, but I would 
 rather
 juck hack with someone diretly on it? Who joins?


I don't know if I will be helpful (I have virtually no experience of
gtk-doc internals and I'm rather beginner programmer) but I can at least
try.

 Stefan

 
 Regards

Regards
-- 
I've probably left my head... somewhere. Please wait untill I find it.
Homepage (pl_PL): http://uzytkownik.jogger.pl/
(GNU/)Linux User: #425935 (see http://counter.li.org/)

___
gtk-devel-list mailing list
gtk-devel-list@gnome.org
http://mail.gnome.org/mailman/listinfo/gtk-devel-list

Re: gtk+ documentation wikified

2009-02-20 Thread Vincent Untz 
Le vendredi 20 février 2009, à 14:32 +0200, Stefan Kost a écrit :
 Would thank be enough for a GSoC project? I would mentor it, but I would 
 rather
 juck hack with someone diretly on it? Who joins?

I'd rather have the SoC project be the web interface that makes the doc
editable. Maybe based on Danilo's work.

Vincent

-- 
Les gens heureux ne sont pas pressés.
___
gtk-devel-list mailing list
gtk-devel-list@gnome.org
http://mail.gnome.org/mailman/listinfo/gtk-devel-list

Re: gtk+ documentation wikified

2009-02-19 Thread Dominic Lachowicz 
That's hard-ish to do today. GTK+'s documentation is generated in
large part by scanning comments in C code, which a program then turns
into HTML. Any proposal would require a way to keep the Wiki and the C
comments in-sync.

On Thu, Feb 19, 2009 at 10:28 AM, Eugene Gorodinsky
e.gorodin...@gmail.com wrote:
 Hi all

 Since you guys are discussing the redesign of the gtk+ website, I'd
 like to propose an idea that I have. I've seen quite a lot of comments
 saying gtk+ documentation isn't as good as qt's. What do you think of
 having a wiki that documents all of gtk+ api?
 ___
 gtk-devel-list mailing list
 gtk-devel-list@gnome.org
 http://mail.gnome.org/mailman/listinfo/gtk-devel-list




-- 
Counting bodies like sheep to the rhythm of the war drums.
___
gtk-devel-list mailing list
gtk-devel-list@gnome.org
http://mail.gnome.org/mailman/listinfo/gtk-devel-list

Fwd: gtk+ documentation wikified

2009-02-19 Thread Eugene Gorodinsky 
Have there been cases where documentation for some function was
changed after that function appeared in the stable version?

2009/2/19 Dominic Lachowicz domlachow...@gmail.com:
 That's hard-ish to do today. GTK+'s documentation is generated in
 large part by scanning comments in C code, which a program then turns
 into HTML. Any proposal would require a way to keep the Wiki and the C
 comments in-sync.

 On Thu, Feb 19, 2009 at 10:28 AM, Eugene Gorodinsky
 e.gorodin...@gmail.com wrote:
 Hi all

 Since you guys are discussing the redesign of the gtk+ website, I'd
 like to propose an idea that I have. I've seen quite a lot of comments
 saying gtk+ documentation isn't as good as qt's. What do you think of
 having a wiki that documents all of gtk+ api?
 ___
 gtk-devel-list mailing list
 gtk-devel-list@gnome.org
 http://mail.gnome.org/mailman/listinfo/gtk-devel-list




 --
 Counting bodies like sheep to the rhythm of the war drums.

___
gtk-devel-list mailing list
gtk-devel-list@gnome.org
http://mail.gnome.org/mailman/listinfo/gtk-devel-list

Re: gtk+ documentation wikified

2009-02-19 Thread Dominic Lachowicz 
Yes. The most common example I can think of is when a function is deprecated.

On Thu, Feb 19, 2009 at 10:52 AM, Eugene Gorodinsky
e.gorodin...@gmail.com wrote:
 Have there been cases where documentation for some function was
 changed after that function appeared in the stable version?

 2009/2/19 Dominic Lachowicz domlachow...@gmail.com:
 That's hard-ish to do today. GTK+'s documentation is generated in
 large part by scanning comments in C code, which a program then turns
 into HTML. Any proposal would require a way to keep the Wiki and the C
 comments in-sync.

 On Thu, Feb 19, 2009 at 10:28 AM, Eugene Gorodinsky
 e.gorodin...@gmail.com wrote:
 Hi all

 Since you guys are discussing the redesign of the gtk+ website, I'd
 like to propose an idea that I have. I've seen quite a lot of comments
 saying gtk+ documentation isn't as good as qt's. What do you think of
 having a wiki that documents all of gtk+ api?
 ___
 gtk-devel-list mailing list
 gtk-devel-list@gnome.org
 http://mail.gnome.org/mailman/listinfo/gtk-devel-list




 --
 Counting bodies like sheep to the rhythm of the war drums.





-- 
Counting bodies like sheep to the rhythm of the war drums.
___
gtk-devel-list mailing list
gtk-devel-list@gnome.org
http://mail.gnome.org/mailman/listinfo/gtk-devel-list

Re: gtk+ documentation wikified

2009-02-19 Thread Mathias Hasselmann 
Am Donnerstag, den 19.02.2009, 10:33 -0500 schrieb Dominic Lachowicz:
 That's hard-ish to do today. GTK+'s documentation is generated in
 large part by scanning comments in C code, which a program then turns
 into HTML. Any proposal would require a way to keep the Wiki and the C
 comments in-sync.

Still that proposed idea has some merits: Currently entry barrier for
fixing GTK+ docs still is quite high.

Guess the most trivial fix would be, to do what the PHP community does
and attach some comment system/forum to library.gnome.org.

More sophisticated would be some application that allows editing of API
docs via web site and provides some way to easily merge them back. Maybe
automatic commits to some separate branch? Maybe just additions to some
patch queue? Don't know. But maybe a nice SoC project?

Ciao,
Mathias

 
 On Thu, Feb 19, 2009 at 10:28 AM, Eugene Gorodinsky
 e.gorodin...@gmail.com wrote:
  Hi all
 
  Since you guys are discussing the redesign of the gtk+ website, I'd
  like to propose an idea that I have. I've seen quite a lot of comments
  saying gtk+ documentation isn't as good as qt's. What do you think of
  having a wiki that documents all of gtk+ api?
  ___
  gtk-devel-list mailing list
  gtk-devel-list@gnome.org
  http://mail.gnome.org/mailman/listinfo/gtk-devel-list
 
 
 
 

-- 
Mathias Hasselmann mathias.hasselm...@gmx.de
Personal Blog: http://taschenorakel.de/mathias/
Openismus GmbH: http://www.openismus.com/

___
gtk-devel-list mailing list
gtk-devel-list@gnome.org
http://mail.gnome.org/mailman/listinfo/gtk-devel-list

Re: Fwd: gtk+ documentation wikified

2009-02-19 Thread Mathias Hasselmann 
Am Donnerstag, den 19.02.2009, 17:52 +0200 schrieb Eugene Gorodinsky:
 Have there been cases where documentation for some function was
 changed after that function appeared in the stable version?

Yes, this happens frequently: Spelling errors, explanations of
limitations, code examples, usage scenarios, ...

In the end programmers primary are programmers, not book writers.
Therefore API documentation provided by programmers always can be just a
start. Still API documentation should be close to programmer's finger
tips, 'cause otherwise the documentation will start to bit rot quickly.

Ciao,
Mathias

 
 2009/2/19 Dominic Lachowicz domlachow...@gmail.com:
  That's hard-ish to do today. GTK+'s documentation is generated in
  large part by scanning comments in C code, which a program then turns
  into HTML. Any proposal would require a way to keep the Wiki and -the C
  comments in-sync.
 
  On Thu, Feb 19, 2009 at 10:28 AM, Eugene Gorodinsky
  e.gorodin...@gmail.com wrote:
  Hi all
 
  Since you guys are discussing the redesign of the gtk+ website, I'd
  like to propose an idea that I have. I've seen quite a lot of comments
  saying gtk+ documentation isn't as good as qt's. What do you think of
  having a wiki that documents all of gtk+ api?
  ___
  gtk-devel-list mailing list
  gtk-devel-list@gnome.org
  http://mail.gnome.org/mailman/listinfo/gtk-devel-list
 
 
 
 
  --
  Counting bodies like sheep to the rhythm of the war drums.
 
 ___
 gtk-devel-list mailing list
 gtk-devel-list@gnome.org
 http://mail.gnome.org/mailman/listinfo/gtk-devel-list
 

-- 
Mathias Hasselmann mathias.hasselm...@gmx.de
Personal Blog: http://taschenorakel.de/mathias/
Openismus GmbH: http://www.openismus.com/

___
gtk-devel-list mailing list
gtk-devel-list@gnome.org
http://mail.gnome.org/mailman/listinfo/gtk-devel-list

Fwd: gtk+ documentation wikified

2009-02-19 Thread Eugene Gorodinsky 
A way to overcome that, would be to put a warning on the wiki page
whenever the documentation for a function is updated, so that the
users could see the updated comment in the code and update the
documentation accordingly.


P.S. Sorry for sending the message twice

2009/2/19 Dominic Lachowicz domlachow...@gmail.com:
 Yes. The most common example I can think of is when a function is deprecated.

 On Thu, Feb 19, 2009 at 10:52 AM, Eugene Gorodinsky
 e.gorodin...@gmail.com wrote:
 Have there been cases where documentation for some function was
 changed after that function appeared in the stable version?

 2009/2/19 Dominic Lachowicz domlachow...@gmail.com:
 That's hard-ish to do today. GTK+'s documentation is generated in
 large part by scanning comments in C code, which a program then turns
 into HTML. Any proposal would require a way to keep the Wiki and the C
 comments in-sync.

 On Thu, Feb 19, 2009 at 10:28 AM, Eugene Gorodinsky
 e.gorodin...@gmail.com wrote:
 Hi all

 Since you guys are discussing the redesign of the gtk+ website, I'd
 like to propose an idea that I have. I've seen quite a lot of comments
 saying gtk+ documentation isn't as good as qt's. What do you think of
 having a wiki that documents all of gtk+ api?
 ___
 gtk-devel-list mailing list
 gtk-devel-list@gnome.org
 http://mail.gnome.org/mailman/listinfo/gtk-devel-list




 --
 Counting bodies like sheep to the rhythm of the war drums.





 --
 Counting bodies like sheep to the rhythm of the war drums.

___
gtk-devel-list mailing list
gtk-devel-list@gnome.org
http://mail.gnome.org/mailman/listinfo/gtk-devel-list

Re: gtk+ documentation wikified

2009-02-19 Thread Murray Cumming 
On Thu, 2009-02-19 at 16:56 +0100, Mathias Hasselmann wrote:
 Am Donnerstag, den 19.02.2009, 10:33 -0500 schrieb Dominic Lachowicz:
  That's hard-ish to do today. GTK+'s documentation is generated in
  large part by scanning comments in C code, which a program then turns
  into HTML. Any proposal would require a way to keep the Wiki and the C
  comments in-sync.
 
 Still that proposed idea has some merits: Currently entry barrier for
 fixing GTK+ docs still is quite high.
 
 Guess the most trivial fix would be, to do what the PHP community does
 and attach some comment system/forum to library.gnome.org.

 More sophisticated would be some application that allows editing of API
 docs via web site and provides some way to easily merge them back. Maybe
 automatic commits to some separate branch? Maybe just additions to some
 patch queue? Don't know. But maybe a nice SoC project?

I wish that someone could just finish Danilo's live-document-editing
GSOC project:
http://live.gnome.org/LiveDocumentationEditing

-- 
murr...@murrayc.com
www.murrayc.com
www.openismus.com

___
gtk-devel-list mailing list
gtk-devel-list@gnome.org
http://mail.gnome.org/mailman/listinfo/gtk-devel-list