Re: gtk+ documentation wikified

[Stefan Kost <ensonic hora-obscura de>]

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