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 |