Gentoo Archives: gentoo-dev

From: Andrew Savchenko <bircoph@g.o>
To: gentoo-dev@l.g.o
Subject: Re: [gentoo-dev] [RFC] New global USE flag: gtk-doc
Date: Sun, 26 Aug 2018 02:19:26
Message-Id: 20180826051910.a042ddb5433737e35c35cbf1@gentoo.org
In Reply to: [gentoo-dev] [RFC] New global USE flag: gtk-doc by Mart Raudsepp
1 On Fri, 24 Aug 2018 23:06:46 +0300 Mart Raudsepp wrote:
2 > USE=doc has a very overloaded meaning.
3 > Meson doesn't ship pre-generated gtk-docs like autotools did, thus
4 > developers writing GLib/GTK+ apps may want to keep them around, as
5 > libraries move from autotools to meson. gtk-doc is integrated into
6 > various IDEs and standalone devhelp viewer, giving a concrete case when
7 > one might want to globally enable this (if using those IDEs until they
8 > don't have online gtk-doc support that's still in the works, offline
9 > developer docs, or matching system versions docs on purpose).
10 > Per-package USE=doc is rather inconvenient to manage.
11 >
12 > Suggested description for global gtk-doc USE:
13 > Build and install gtk-doc based developer documentation
14 >
15 > Longer version idea:
16 > Build and install gtk-doc based developer documentation for dev-
17 > util/devhelp, IDE and offline use
18 >
19 >
20 > As the "Build" in the description suggests, this is only for when a
21 > generation is needed. In practice this means that it shouldn't be used
22 > for autotools based builds from tarballs, where the gtk-doc is already
23 > shipped - for those you just want a dev-util/gtk-doc-am build dep,
24 > which will make gtkdoc-rebase available that the standard gtk-doc
25 > autotools rules call to make the pre-generated docs pretty much equal
26 > to what you'd get from regenerating (mainly local offline links). In
27 > those aforementioned autotools cases, it's often questionable to have a
28 > USE flag (doc) at all for this when using proper tarballs.
29 >
30 > Most GNOME libraries have converted to using meson, thus building them
31 > is necessary to keep local developer docs available and thus keep IDE
32 > integration useful. Just always building gtk-doc would be distasteful
33 > to some, hence this global USE flag proposal. There will be dozens of
34 > consumers as I bump libraries for GNOME 3.26 and even more so 3.28 and
35 > 3.30 soon enough afterwards. Some are already there (including some not
36 > from GNOME), which currently use USE=doc for this.
37 > Instead of supporting disted tarballs with meson, they plan to do
38 > aforementioned online docs support for the API docs integrations, but
39 > I haven't heard about any progress on that, plus offline use use case
40 > will remain anyways.
41
42 Looks like we have a larger issue here. USE=doc covers all types of
43 documentation outside of man, info pages and maybe some small text
44 files. Such additional documentation often includes API reference
45 manual and people may want to have it if they are using it during
46 development or may want to disable it, but keep user-level
47 documentation, because API docs often take quite some time to
48 build. Such cases cover html docs, doxygen docs, gtk-doc and so on.
49
50 So what about some new flag for API reference and other huge
51 development documentation? E.g. USE="apidoc"?
52
53 Best regards,
54 Andrew Savchenko

Replies

Subject Author
Re: [gentoo-dev] [RFC] New global USE flag: gtk-doc Mart Raudsepp <leio@g.o>