1 |
Ühel kenal päeval, P, 26.08.2018 kell 05:19, kirjutas Andrew Savchenko: |
2 |
> On Fri, 24 Aug 2018 23:06:46 +0300 Mart Raudsepp wrote: |
3 |
> > USE=doc has a very overloaded meaning. |
4 |
> > Meson doesn't ship pre-generated gtk-docs like autotools did, thus |
5 |
> > developers writing GLib/GTK+ apps may want to keep them around, as |
6 |
> > libraries move from autotools to meson. gtk-doc is integrated into |
7 |
> > various IDEs and standalone devhelp viewer, giving a concrete case |
8 |
> > when |
9 |
> > one might want to globally enable this (if using those IDEs until |
10 |
> > they |
11 |
> > don't have online gtk-doc support that's still in the works, |
12 |
> > offline |
13 |
> > developer docs, or matching system versions docs on purpose). |
14 |
> > Per-package USE=doc is rather inconvenient to manage. |
15 |
> > |
16 |
> > Suggested description for global gtk-doc USE: |
17 |
> > Build and install gtk-doc based developer documentation |
18 |
> > |
19 |
> > Longer version idea: |
20 |
> > Build and install gtk-doc based developer documentation for dev- |
21 |
> > util/devhelp, IDE and offline use |
22 |
> > |
23 |
> > |
24 |
> > As the "Build" in the description suggests, this is only for when a |
25 |
> > generation is needed. In practice this means that it shouldn't be |
26 |
> > used |
27 |
> > for autotools based builds from tarballs, where the gtk-doc is |
28 |
> > already |
29 |
> > shipped - for those you just want a dev-util/gtk-doc-am build dep, |
30 |
> > which will make gtkdoc-rebase available that the standard gtk-doc |
31 |
> > autotools rules call to make the pre-generated docs pretty much |
32 |
> > equal |
33 |
> > to what you'd get from regenerating (mainly local offline links). |
34 |
> > In |
35 |
> > those aforementioned autotools cases, it's often questionable to |
36 |
> > have a |
37 |
> > USE flag (doc) at all for this when using proper tarballs. |
38 |
> > |
39 |
> > Most GNOME libraries have converted to using meson, thus building |
40 |
> > them |
41 |
> > is necessary to keep local developer docs available and thus keep |
42 |
> > IDE |
43 |
> > integration useful. Just always building gtk-doc would be |
44 |
> > distasteful |
45 |
> > to some, hence this global USE flag proposal. There will be dozens |
46 |
> > of |
47 |
> > consumers as I bump libraries for GNOME 3.26 and even more so 3.28 |
48 |
> > and |
49 |
> > 3.30 soon enough afterwards. Some are already there (including some |
50 |
> > not |
51 |
> > from GNOME), which currently use USE=doc for this. |
52 |
> > Instead of supporting disted tarballs with meson, they plan to do |
53 |
> > aforementioned online docs support for the API docs integrations, |
54 |
> > but |
55 |
> > I haven't heard about any progress on that, plus offline use use |
56 |
> > case |
57 |
> > will remain anyways. |
58 |
> |
59 |
> Looks like we have a larger issue here. USE=doc covers all types of |
60 |
> documentation outside of man, info pages and maybe some small text |
61 |
> files. Such additional documentation often includes API reference |
62 |
> manual and people may want to have it if they are using it during |
63 |
> development or may want to disable it, but keep user-level |
64 |
> documentation, because API docs often take quite some time to |
65 |
> build. Such cases cover html docs, doxygen docs, gtk-doc and so on. |
66 |
> |
67 |
> So what about some new flag for API reference and other huge |
68 |
> development documentation? E.g. USE="apidoc"? |
69 |
|
70 |
According to global description examples (API, Javadoc, etc), that's |
71 |
already sort of the case, but is used more broadly. So sure, it can be |
72 |
an option to more clearly and easily differentiate programmer docs from |
73 |
other docs, but that doesn't cover the use case I'm after. |
74 |
These other USE="apidoc" won't be usable by gtk-doc and still the |
75 |
inability to easily enable only gtk-docs - which will be usable in my |
76 |
IDE, unlike the rest. |
77 |
|
78 |
Basically I'm after a concrete purpose flag here, like e.g. |
79 |
USE=handbook is, so it's not that there isn't already prior art of |
80 |
differing from USE=doc and having a separate flag. |
81 |
|
82 |
|
83 |
Mart |