From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from lists.gentoo.org (pigeon.gentoo.org [208.92.234.80]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by finch.gentoo.org (Postfix) with ESMTPS id E35AE138334 for ; Sun, 26 Aug 2018 09:08:53 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 7F5FFE089C; Sun, 26 Aug 2018 09:08:50 +0000 (UTC) Received: from smtp.gentoo.org (smtp.gentoo.org [140.211.166.183]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) by pigeon.gentoo.org (Postfix) with ESMTPS id 1C594E087F for ; Sun, 26 Aug 2018 09:08:49 +0000 (UTC) Received: from [192.168.2.51] (62.65.228.137.cable.starman.ee [62.65.228.137]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) (Authenticated sender: leio) by smtp.gentoo.org (Postfix) with ESMTPSA id 546B9335C42 for ; Sun, 26 Aug 2018 09:08:48 +0000 (UTC) Message-ID: <1535274521.4490.4.camel@gentoo.org> Subject: Re: [gentoo-dev] [RFC] New global USE flag: gtk-doc From: Mart Raudsepp To: gentoo-dev@lists.gentoo.org Date: Sun, 26 Aug 2018 12:08:41 +0300 In-Reply-To: <20180826051910.a042ddb5433737e35c35cbf1@gentoo.org> References: <1535141206.6451.19.camel@gentoo.org> <20180826051910.a042ddb5433737e35c35cbf1@gentoo.org> Content-Type: multipart/signed; micalg="pgp-sha512"; protocol="application/pgp-signature"; boundary="=-vtgUHO9+eP0o77okwipW" X-Mailer: Evolution 3.24.6 Precedence: bulk List-Post: List-Help: List-Unsubscribe: List-Subscribe: List-Id: Gentoo Linux mail X-BeenThere: gentoo-dev@lists.gentoo.org Reply-to: gentoo-dev@lists.gentoo.org Mime-Version: 1.0 X-Archives-Salt: c3efc772-f958-4662-8934-4111dc718fe7 X-Archives-Hash: 16e5e53a48b57a84efc5dd6f46b37ce6 --=-vtgUHO9+eP0o77okwipW Content-Type: text/plain; charset="UTF-8" Content-Transfer-Encoding: quoted-printable =C3=9Chel kenal p=C3=A4eval, P, 26.08.2018 kell 05:19, kirjutas Andrew Savc= henko: > On Fri, 24 Aug 2018 23:06:46 +0300 Mart Raudsepp wrote: > > USE=3Ddoc 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=3Ddoc is rather inconvenient to manage. > >=20 > > Suggested description for global gtk-doc USE: > > Build and install gtk-doc based developer documentation > >=20 > > Longer version idea: > > Build and install gtk-doc based developer documentation for dev- > > util/devhelp, IDE and offline use > >=20 > >=20 > > 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. > >=20 > > 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=3Ddoc 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. >=20 > Looks like we have a larger issue here. USE=3Ddoc 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. >=20 > So what about some new flag for API reference and other huge > development documentation? E.g. USE=3D"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=3D"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=3Dhandbook is, so it's not that there isn't already prior art of differing from USE=3Ddoc and having a separate flag. Mart --=-vtgUHO9+eP0o77okwipW Content-Type: application/pgp-signature; name="signature.asc" Content-Description: This is a digitally signed message part Content-Transfer-Encoding: 7bit -----BEGIN PGP SIGNATURE----- Version: GnuPG v2 iQKTBAABCgB9FiEEUdZn9pOq0mlNjRvdEKbJ+k9JlgYFAluCbhlfFIAAAAAALgAo aXNzdWVyLWZwckBub3RhdGlvbnMub3BlbnBncC5maWZ0aGhvcnNlbWFuLm5ldDUx RDY2N0Y2OTNBQUQyNjk0RDhEMUJERDEwQTZDOUZBNEY0OTk2MDYACgkQEKbJ+k9J lgYl9g//bWKSXc+x4skZS2N+LcmL4HQo14nMV22PPoFyJkjqSEzoEEGY12kRgwD5 NKblRKIxEHwW+Y2eZouhhc9+AgCIJaRZ1JLu/5CdAHdm8TZtfYsSuTYW9bpCt6Ls 58i1adSzWNWfgKUwHMAFPLP9ugRaQcRqknmQ5lD7zyL2s+dDyT/xA0gV4lKqjNFR zZ5UVgO2b1oFPdV6+RrK8d/krZtHBOipkBLDK/Wbte9rUdbm6U2+bQiV9GyAWwiv 6L2cJpZksaCyl7UhpOhUmWTMo5mAsbq4m+OpesAac5KKgvxyw1Xav2F/o6NdWGtP nUVzloEWMxPCcjh8H6D4+WvEbr9FpNAn2PE1h/al3n4nk0Nrz2L55/vAB8X6GT2i RWnsboCoeSZAf4ZS5d1Ka9q0Tr0OrwVDdO5nruIeKVjNFGAlSMNH5Em0a6BWHVrO eQSbLbTsUq1MIZ2Ix4qjUaasjBdFrQe/3CnK60ZDrTa/NfkRHAVEQyYTsypjmFNO pm4OF/h+IngTqM800ZVw0bjzUVkWtjsldttGBzJ1XgTIFO6UAtHWdeWAPNATnHMw T1V0fg7E5ASXOp1vq02CK1EoA2IjikXApyWb6T5K6ptBBeuBy1yWpw55yaTDjy17 6tsJwXvG1H0yFm/seJMRA+aUGzqHJEImqvfkPEZkvxX8yVJndXs= =8lhP -----END PGP SIGNATURE----- --=-vtgUHO9+eP0o77okwipW--