Re: spring cleaning in gtk-doc for next-next verison (1.21)

On 12/29/2014 01:11 PM, Stefan Sauer wrote:
On 02/01/2014 11:58 AM, Stefan Sauer wrote:

while a gtk-doc 1.20 is brewing with some awesome stuff coming, I like
to remove some legacy features in the cycle afterwards.

1) I'd like to remove 'gtkdoc-scanobj'.
This was used to introspect gtk-objects. The makefile fragments shipped
with gtk-doc aren't calling this for years (since gtkdoc-scanjobj was

2) I'd like to remove 'gtkdoc-mktmpl'.
In the old days, gtk-doc works so that it extracted symbol information
from sources and created files under 'tmpl/'. This is where the code was
documented. Then gtk-doc parsed these files and created the docbook
files. A bit later gtk-doc started to support documentation inside the
sources. When I started to send patches to gtk-doc both ways were
supported. My first patches added support for having the remaining docs
in the sources as well. This makes the tmpl files based workflow
obsolete, but therefore all the docs have to be in the sources. This has
several advantages (keeping things up-to-date, not having generated
files in git, faster etc.).

I did some quick checking in my jhbuild checkout dir:
find . -name "configure.*" -exec grep -Hn "GTK_DOC_CHECK" {} \; | grep
-v "flavour[ =]no-tmpl" | egrep -v ":#" | wc -l
find . -wholename "*/tmpl" | sort | wc -l

I could make a gnome goals style page for this. Does that sound good?
Small update:

find . -name "configure.*" -exec grep -Hn "GTK_DOC_CHECK" {} \; | grep -v "flavour[ =]no-tmpl" | egrep -v 
":#" | wc -l
find . -wholename "*/tmpl" | sort | wc -l

So the no-tmpl  usage went a bit up, but we still have 31 modules with
tmpl files checked in. If anyone has questions on how to migrate, please
ask me (or come to #gtkdoc). As a quick way maintainers of the modules
below can check if they actually *use*
tmpl files:
grep -Hn "^[^<@]" ./atk/docs/tmpl/*.sgml
If that just prints the class names (one line per file). Then switching
to no-tmpl is as easy as changing to
GTK_DOC_CHECK([1.14],[--flavour no-tmpl])
(while using version >=1.14)
Small update. If you don't have the tmpl directory checked in, it is
safe to switch to "--flavour no-tmpl". Example cleanu for udisks:

On an unrelated note. If the doc build of your module prints many xsl
warnings related to annotation acronyms, this is the fix:



find . -wholename "*/tmpl" | sort

desktop-devel-list mailing list
desktop-devel-list gnome org

desktop-devel-list mailing list
desktop-devel-list gnome org

[Date Prev][Date Next]   [Thread Prev][Thread Next]   [Thread Index] [Date Index] [Author Index]