Re: gtk+ documentation wikified

[Eugene Gorodinsky <e gorodinsky gmail com>]

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 <ensonic hora-obscura de>:
> hi,
>
> Maciej Piechotka schrieb:
>> Eugene Gorodinsky <e gorodinsky 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
>