Re: [gentoo-dev] [RFC] New global USE flag: gtk-doc

[Mart Raudsepp]

Ühel kenal päeval, P, 26.08.2018 kell 05:19, kirjutas Andrew Savchenko:
> On Fri, 24 Aug 2018 23:06:46 +0300 Mart Raudsepp wrote:
> > USE=doc has a very overloaded meaning.
> > Meson doesn't ship pre-generated gtk-docs like autotools did, thus
> > developers writing GLib/GTK+ apps may want to keep them around, as
> > libraries move from autotools to meson. gtk-doc is integrated into
> > various IDEs and standalone devhelp viewer, giving a concrete case
> > when
> > one might want to globally enable this (if using those IDEs until
> > they
> > don't have online gtk-doc support that's still in the works,
> > offline
> > developer docs, or matching system versions docs on purpose).
> > Per-package USE=doc is rather inconvenient to manage.
> >
> > Suggested description for global gtk-doc USE:
> > Build and install gtk-doc based developer documentation
> >
> > Longer version idea:
> > Build and install gtk-doc based developer documentation for dev-
> > util/devhelp, IDE and offline use
> >
> >
> > As the "Build" in the description suggests, this is only for when a
> > generation is needed. In practice this means that it shouldn't be
> > used
> > for autotools based builds from tarballs, where the gtk-doc is
> > already
> > shipped - for those you just want a dev-util/gtk-doc-am build dep,
> > which will make gtkdoc-rebase available that the standard gtk-doc
> > autotools rules call to make the pre-generated docs pretty much
> > equal
> > to what you'd get from regenerating (mainly local offline links).
> > In
> > those aforementioned autotools cases, it's often questionable to
> > have a
> > USE flag (doc) at all for this when using proper tarballs.
> >
> > Most GNOME libraries have converted to using meson, thus building
> > them
> > is necessary to keep local developer docs available and thus keep
> > IDE
> > integration useful. Just always building gtk-doc would be
> > distasteful
> > to some, hence this global USE flag proposal. There will be dozens
> > of
> > consumers as I bump libraries for GNOME 3.26 and even more so 3.28
> > and
> > 3.30 soon enough afterwards. Some are already there (including some
> > not
> > from GNOME), which currently use USE=doc for this.
> > Instead of supporting disted tarballs with meson, they plan to do
> > aforementioned online docs support for the API docs integrations,
> > but
> > I haven't heard about any progress on that, plus offline use use
> > case
> > will remain anyways.
>
> Looks like we have a larger issue here. USE=doc covers all types of
> documentation outside of man, info pages and maybe some small text
> files. Such additional documentation often includes API reference
> manual and people may want to have it if they are using it during
> development or may want to disable it, but keep user-level
> documentation, because API docs often take quite some time to
> build. Such cases cover html docs, doxygen docs, gtk-doc and so on.
>
> So what about some new flag for API reference and other huge
> development documentation? E.g. USE="apidoc"?

According to global description examples (API, Javadoc, etc), that's
already sort of the case, but is used more broadly. So sure, it can be
an option to more clearly and easily differentiate programmer docs from
other docs, but that doesn't cover the use case I'm after.
These other USE="apidoc" won't be usable by gtk-doc and still the
inability to easily enable only gtk-docs - which will be usable in my
IDE, unlike the rest.

Basically I'm after a concrete purpose flag here, like e.g.
USE=handbook is, so it's not that there isn't already prior art of
differing from USE=doc and having a separate flag.


Mart