Re: gtk+ documentation wikified

[Maciej Piechotka <uzytkownik2 gmail com>]

Stefan Kost <ensonic hora-obscura de> writes:

> 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.
>

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