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

[Stefan Sauer <ensonic hora-obscura de>]

On 12/29/2014 01:11 PM, Stefan Sauer wrote:
> On 02/01/2014 11:58 AM, Stefan Sauer wrote:
> > hi,
> >
> > 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
> > introduced).
> >
> > 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
> > 66
> > find . -wholename "*/tmpl" | sort | wc -l
> > 46
> >
> > 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
> 72
> find . -wholename "*/tmpl" | sort | wc -l
> 31
>
> 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 configure.ac 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:
https://bugs.freedesktop.org/attachment.cgi?id=111540

On an unrelated note. If the doc build of your module prints many xsl
warnings related to annotation acronyms, this is the fix:
https://bugs.freedesktop.org/attachment.cgi?id=111541

Stefan
> Stefan
>
> find . -wholename "*/tmpl" | sort
> ./atk/docs/tmpl
> ./at-spi2-core/doc/libatspi/tmpl
> ./cairo-1.12.14/doc/public/tmpl
> ./gconf/doc/gconf/tmpl
> ./gmime-2.6.6/docs/reference/tmpl
> ./gnome-desktop/docs/reference/gnome-desktop3/tmpl
> ./gnutls-3.0.26/doc/reference/tmpl
> ./gtk+-2/docs/reference/gdk/tmpl
> ./gtk+-2/docs/reference/gtk/tmpl
> ./gtk+-2/docs/reference/libgail-util/tmpl
> ./gtkhtml/doc/tmpl
> ./gucharmap/docs/reference/tmpl
> ./ibus-1.5.3/docs/reference/ibus/tmpl
> ./ibus-1.5.5/docs/reference/ibus/tmpl
> ./libcanberra-0.30/gtkdoc/tmpl
> ./libcroco/docs/reference/tmpl
> ./libnice-0.1.3/docs/reference/libnice/tmpl
> ./libnice-0.1.8/docs/reference/libnice/tmpl
> ./libsoup/docs/reference/tmpl
> ./libtasn1-2.2/doc/reference/tmpl
> ./libwnck/doc/tmpl
> ./libxklavier-5.2.1/doc/reference/tmpl
> ./p11-kit-0.13/doc/tmpl
> ./seed/doc/reference/tmpl
> ./udisks/doc/tmpl
> ./webkitgtk-2.2.4/Documentation/webkit2gtk/tmpl
> ./webkitgtk-2.2.4/Documentation/webkitgtk/tmpl
> ./webkitgtk-2.2.5/Documentation/webkit2gtk/tmpl
> ./webkitgtk-2.2.5/Documentation/webkitgtk/tmpl
> ./webkitgtk-2.2.6/Documentation/webkit2gtk/tmpl
> ./webkitgtk-2.2.6/Documentation/webkitgtk/tmpl
>
>
>
> > Stefan
> > _______________________________________________
> > desktop-devel-list mailing list
> > desktop-devel-list gnome org
> > https://mail.gnome.org/mailman/listinfo/desktop-devel-list
>
> _______________________________________________
> desktop-devel-list mailing list
> desktop-devel-list gnome org
> https://mail.gnome.org/mailman/listinfo/desktop-devel-list