[gentoo-dev] [RFC] New global USE flag: gtk-doc

[gentoo-dev] [RFC] New global USE flag: gtk-doc

[Mart Raudsepp]

[-- Attachment #1: Type: text/plain, Size: 2157 bytes --]

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.


Mart

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 981 bytes --]

Re: [gentoo-dev] [RFC] New global USE flag: gtk-doc

[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?

-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

Re: [gentoo-dev] [RFC] New global USE flag: gtk-doc

[Mart Raudsepp]

[-- Attachment #1: Type: text/plain, Size: 1456 bytes --]

Ü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

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 981 bytes --]

Re: [gentoo-dev] [RFC] New global USE flag: gtk-doc

[Andrew Savchenko]

[-- Attachment #1: Type: text/plain, Size: 2895 bytes --]

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

[-- Attachment #2: Type: application/pgp-signature, Size: 833 bytes --]

Re: [gentoo-dev] [RFC] New global USE flag: gtk-doc

[Mart Raudsepp]

[-- Attachment #1: Type: text/plain, Size: 3746 bytes --]

Ü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

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 981 bytes --]

Re: [gentoo-dev] [RFC] New global USE flag: gtk-doc

[Mart Raudsepp]

[-- Attachment #1: Type: text/plain, Size: 1069 bytes --]

Ü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

[-- Attachment #2: This is a digitally signed message part --]
[-- Type: application/pgp-signature, Size: 981 bytes --]