1 |
USE=doc has a very overloaded meaning. |
2 |
Meson doesn't ship pre-generated gtk-docs like autotools did, thus |
3 |
developers writing GLib/GTK+ apps may want to keep them around, as |
4 |
libraries move from autotools to meson. gtk-doc is integrated into |
5 |
various IDEs and standalone devhelp viewer, giving a concrete case when |
6 |
one might want to globally enable this (if using those IDEs until they |
7 |
don't have online gtk-doc support that's still in the works, offline |
8 |
developer docs, or matching system versions docs on purpose). |
9 |
Per-package USE=doc is rather inconvenient to manage. |
10 |
|
11 |
Suggested description for global gtk-doc USE: |
12 |
Build and install gtk-doc based developer documentation |
13 |
|
14 |
Longer version idea: |
15 |
Build and install gtk-doc based developer documentation for dev- |
16 |
util/devhelp, IDE and offline use |
17 |
|
18 |
|
19 |
As the "Build" in the description suggests, this is only for when a |
20 |
generation is needed. In practice this means that it shouldn't be used |
21 |
for autotools based builds from tarballs, where the gtk-doc is already |
22 |
shipped - for those you just want a dev-util/gtk-doc-am build dep, |
23 |
which will make gtkdoc-rebase available that the standard gtk-doc |
24 |
autotools rules call to make the pre-generated docs pretty much equal |
25 |
to what you'd get from regenerating (mainly local offline links). In |
26 |
those aforementioned autotools cases, it's often questionable to have a |
27 |
USE flag (doc) at all for this when using proper tarballs. |
28 |
|
29 |
Most GNOME libraries have converted to using meson, thus building them |
30 |
is necessary to keep local developer docs available and thus keep IDE |
31 |
integration useful. Just always building gtk-doc would be distasteful |
32 |
to some, hence this global USE flag proposal. There will be dozens of |
33 |
consumers as I bump libraries for GNOME 3.26 and even more so 3.28 and |
34 |
3.30 soon enough afterwards. Some are already there (including some not |
35 |
from GNOME), which currently use USE=doc for this. |
36 |
Instead of supporting disted tarballs with meson, they plan to do |
37 |
aforementioned online docs support for the API docs integrations, but |
38 |
I haven't heard about any progress on that, plus offline use use case |
39 |
will remain anyways. |
40 |
|
41 |
|
42 |
Mart |