| 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 |
Archives