Re: [gentoo-dev] [RFC] New global USE flag: gtk-doc
Ühel kenal päeval, R, 24.08.2018 kell 23:06, kirjutas Mart Raudsepp: > Longer version idea: > Build and install gtk-doc based developer documentation for dev- > util/devhelp, IDE and offline use This has been pushed now with initial consumers (fresh meson based packages or converts from autotools). I have a candidate list of packages that could use a IUSE flag usage change accordingly. It's a short list because I didn't consider autotools packages, as for them it often means to rebuild it for questionable benefits, thus I don't actually want those cases to add unnecessary rebuild time cost with a global USE=gtk-doc - they are already there without current USE=doc and accessible in devhelp and some IDEs. This means autotools builds that don't use a properly disted tarball won't get a bug filed from me right now (but why are they using a bad tarball?). I'll try to get those from my candidate list checked through and converted to bug reports soon for applicable ones. If more than lets say 3, then probably a tracker bug too. Mart signature.asc Description: This is a digitally signed message part
Re: [gentoo-dev] [RFC] New global USE flag: gtk-doc
Ühel kenal päeval, P, 26.08.2018 kell 01:08, kirjutas David Haller: > Hello, > > On Fri, 24 Aug 2018, Mart Raudsepp wrote: > [..] > > Suggested description for global gtk-doc USE: > > Build and install gtk-doc based developer documentation > > Mentioning gtk-doc, what about: > https://bugs.gentoo.org/646850 > > Ready-made patch since 2018-02-07, and then what? This is not relevant to this thread. I was not able to track all bugzilla things at that time, and this looks to be a problem with local usage of gtk-doc, not for out of the box packages without EXTRA_ECONF (I'm not aware of packages using gtkdoc-mkpdf for PDFs - they are all doing just HTML, as the default configure argument for PDF docs is to disable them). I suspect this particular case just could use a gtk-doc package bump for upstream, but that involves an upstream rewrite towards python iirc, and I haven't exactly rushed with bumping that, because the old version works and there are more important bumps to work on (nothing has required the newer gtk-doc). I'm sorry that some bugs fall through the cracks, but I don't mind pings on bugs (especially those that have concrete fixes waiting), or pings on IRC or private mail about them. Not this particular thread though. There are many other bugs to catch up on, but currently my focus has been to bring GNOME 3.26 and 3.28 to our users finally. This thread is a side-product of that. Mart signature.asc Description: This is a digitally signed message part
Re: [gentoo-dev] [RFC] New global USE flag: gtk-doc
Ühel kenal päeval, P, 26.08.2018 kell 05:19, kirjutas Andrew Savchenko: > On Fri, 24 Aug 2018 23:06:46 +0300 Mart Raudsepp wrote: > > USE=doc has a very overloaded meaning. > > Meson doesn't ship pre-generated gtk-docs like autotools did, thus > > developers writing GLib/GTK+ apps may want to keep them around, as > > libraries move from autotools to meson. gtk-doc is integrated into > > various IDEs and standalone devhelp viewer, giving a concrete case > > when > > one might want to globally enable this (if using those IDEs until > > they > > don't have online gtk-doc support that's still in the works, > > offline > > developer docs, or matching system versions docs on purpose). > > Per-package USE=doc is rather inconvenient to manage. > > > > Suggested description for global gtk-doc USE: > > Build and install gtk-doc based developer documentation > > > > Longer version idea: > > Build and install gtk-doc based developer documentation for dev- > > util/devhelp, IDE and offline use > > > > > > As the "Build" in the description suggests, this is only for when a > > generation is needed. In practice this means that it shouldn't be > > used > > for autotools based builds from tarballs, where the gtk-doc is > > already > > shipped - for those you just want a dev-util/gtk-doc-am build dep, > > which will make gtkdoc-rebase available that the standard gtk-doc > > autotools rules call to make the pre-generated docs pretty much > > equal > > to what you'd get from regenerating (mainly local offline links). > > In > > those aforementioned autotools cases, it's often questionable to > > have a > > USE flag (doc) at all for this when using proper tarballs. > > > > Most GNOME libraries have converted to using meson, thus building > > them > > is necessary to keep local developer docs available and thus keep > > IDE > > integration useful. Just always building gtk-doc would be > > distasteful > > to some, hence this global USE flag proposal. There will be dozens > > of > > consumers as I bump libraries for GNOME 3.26 and even more so 3.28 > > and > > 3.30 soon enough afterwards. Some are already there (including some > > not > > from GNOME), which currently use USE=doc for this. > > Instead of supporting disted tarballs with meson, they plan to do > > aforementioned online docs support for the API docs integrations, > > but > > I haven't heard about any progress on that, plus offline use use > > case > > will remain anyways. > > Looks like we have a larger issue here. USE=doc covers all types of > documentation outside of man, info pages and maybe some small text > files. Such additional documentation often includes API reference > manual and people may want to have it if they are using it during > development or may want to disable it, but keep user-level > documentation, because API docs often take quite some time to > build. Such cases cover html docs, doxygen docs, gtk-doc and so on. > > So what about some new flag for API reference and other huge > development documentation? E.g. USE="apidoc"? According to global description examples (API, Javadoc, etc), that's already sort of the case, but is used more broadly. So sure, it can be an option to more clearly and easily differentiate programmer docs from other docs, but that doesn't cover the use case I'm after. These other USE="apidoc" won't be usable by gtk-doc and still the inability to easily enable only gtk-docs - which will be usable in my IDE, unlike the rest. Basically I'm after a concrete purpose flag here, like e.g. USE=handbook is, so it's not that there isn't already prior art of differing from USE=doc and having a separate flag. Mart signature.asc Description: This is a digitally signed message part
Re: [gentoo-dev] [RFC] New global USE flag: gtk-doc
On Fri, 24 Aug 2018 23:06:46 +0300 Mart Raudsepp wrote: > USE=doc has a very overloaded meaning. > Meson doesn't ship pre-generated gtk-docs like autotools did, thus > developers writing GLib/GTK+ apps may want to keep them around, as > libraries move from autotools to meson. gtk-doc is integrated into > various IDEs and standalone devhelp viewer, giving a concrete case when > one might want to globally enable this (if using those IDEs until they > don't have online gtk-doc support that's still in the works, offline > developer docs, or matching system versions docs on purpose). > Per-package USE=doc is rather inconvenient to manage. > > Suggested description for global gtk-doc USE: > Build and install gtk-doc based developer documentation > > Longer version idea: > Build and install gtk-doc based developer documentation for dev- > util/devhelp, IDE and offline use > > > As the "Build" in the description suggests, this is only for when a > generation is needed. In practice this means that it shouldn't be used > for autotools based builds from tarballs, where the gtk-doc is already > shipped - for those you just want a dev-util/gtk-doc-am build dep, > which will make gtkdoc-rebase available that the standard gtk-doc > autotools rules call to make the pre-generated docs pretty much equal > to what you'd get from regenerating (mainly local offline links). In > those aforementioned autotools cases, it's often questionable to have a > USE flag (doc) at all for this when using proper tarballs. > > Most GNOME libraries have converted to using meson, thus building them > is necessary to keep local developer docs available and thus keep IDE > integration useful. Just always building gtk-doc would be distasteful > to some, hence this global USE flag proposal. There will be dozens of > consumers as I bump libraries for GNOME 3.26 and even more so 3.28 and > 3.30 soon enough afterwards. Some are already there (including some not > from GNOME), which currently use USE=doc for this. > Instead of supporting disted tarballs with meson, they plan to do > aforementioned online docs support for the API docs integrations, but > I haven't heard about any progress on that, plus offline use use case > will remain anyways. Looks like we have a larger issue here. USE=doc covers all types of documentation outside of man, info pages and maybe some small text files. Such additional documentation often includes API reference manual and people may want to have it if they are using it during development or may want to disable it, but keep user-level documentation, because API docs often take quite some time to build. Such cases cover html docs, doxygen docs, gtk-doc and so on. So what about some new flag for API reference and other huge development documentation? E.g. USE="apidoc"? Best regards, Andrew Savchenko pgpAPSauwiGKm.pgp Description: PGP signature
Re: [gentoo-dev] [RFC] New global USE flag: gtk-doc
Hello, On Fri, 24 Aug 2018, Mart Raudsepp wrote: [..] >Suggested description for global gtk-doc USE: >Build and install gtk-doc based developer documentation Mentioning gtk-doc, what about: https://bugs.gentoo.org/646850 Ready-made patch since 2018-02-07, and then what? -dnh -- If you don't see why, please stay the fuck away from my code. -- Paul "Rusty" Russel, in /usr/src/linux/Documentation/DocBook/kernel-locking.tmpl
