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 3095D138334 for ; Sun, 26 Aug 2018 02:19:26 +0000 (UTC) Received: from pigeon.gentoo.org (localhost [127.0.0.1]) by pigeon.gentoo.org (Postfix) with SMTP id 88291E081A; Sun, 26 Aug 2018 02:19:22 +0000 (UTC) Received: from smtp.gentoo.org (dev.gentoo.org [IPv6:2001:470:ea4a:1:5054:ff:fec7:86e4]) (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 1553FE07D3 for ; Sun, 26 Aug 2018 02:19:21 +0000 (UTC) Received: from localhost (unknown [213.87.136.235]) (using TLSv1.2 with cipher ECDHE-RSA-AES128-GCM-SHA256 (128/128 bits)) (No client certificate requested) (Authenticated sender: bircoph) by smtp.gentoo.org (Postfix) with ESMTPSA id 83422335CFF for ; Sun, 26 Aug 2018 02:19:17 +0000 (UTC) Date: Sun, 26 Aug 2018 05:19:10 +0300 From: Andrew Savchenko To: gentoo-dev@lists.gentoo.org Subject: Re: [gentoo-dev] [RFC] New global USE flag: gtk-doc Message-Id: <20180826051910.a042ddb5433737e35c35cbf1@gentoo.org> In-Reply-To: <1535141206.6451.19.camel@gentoo.org> References: <1535141206.6451.19.camel@gentoo.org> X-Mailer: Sylpheed 3.7.0 (GTK+ 2.24.30; i686-pc-linux-gnu) 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 Content-Type: multipart/signed; protocol="application/pgp-signature"; micalg="PGP-SHA512"; boundary="Signature=_Sun__26_Aug_2018_05_19_11_+0300_7mtJoS=3F7yeSw4Y" X-Archives-Salt: dddbab4b-8b0e-4d4e-adfe-befad21183e4 X-Archives-Hash: 05278dfef701cefa70f5b3096d9d1abd --Signature=_Sun__26_Aug_2018_05_19_11_+0300_7mtJoS=3F7yeSw4Y Content-Type: text/plain; charset=US-ASCII Content-Disposition: inline Content-Transfer-Encoding: quoted-printable 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. 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. So what about some new flag for API reference and other huge development documentation? E.g. USE=3D"apidoc"? Best regards, Andrew Savchenko --Signature=_Sun__26_Aug_2018_05_19_11_+0300_7mtJoS=3F7yeSw4Y Content-Type: application/pgp-signature -----BEGIN PGP SIGNATURE----- iQIzBAEBCgAdFiEE63ZIHsdeM+1XgNer9lNaM7oe5I0FAluCDh8ACgkQ9lNaM7oe 5I3OHg//buBTNw+7cEjj3B10oDiBko3NrH3vufW2wQ+lrn7OcFSlNXmiLuQVDEvI V9qAjXq3M1dwsyPvpd8o9NPL7IMNN817sV/V06JHkK9Lo2De08iMTjJhPZdpdZ4W X0iZLO9Tw7rhA7lMIWV+1YHFBR7rFzRBBkEXEqpiXXr9agI9ng5T5jXTDxyOoFXI 71xWC/LTiOhStoig1RiIhhMwEo9Kmpvbhr7ajILZ7+0RULXP4fN61Ws6V1q4wrgg MHNkOeIGa6Fr/XlcOb97OjMSQH1YcVbkfMA7bm6ZPbqYDHAixKvTwnkOiSX+rKVF XMcWE0Ks/Wq1HQpQA5FPlty0nrhKf5gntZUQWEiDnO1565N7nR0r3svipYDUbMaz gk2FmA3I8Ac49TBg8rVT/NSoJVutQgHk8A5DO3MWJ8VlznJ0WdGNPOmc4BSMIxwn DU71LDhIhPfJ+tRJ0ga3WMBZL8wQKF0jF6ujHBqK5kKiDM+XyfoRDDH1rLsNBpj/ IXniWlPqiScw0P65rDzwVKqpRv8zzL7tlpgaLH3dhXe+bWJ5LEifhaRzvWz3rNhX PAB9o4qcgzVdmsv0+KMyEu68omXH49kABy/yW46BaCvLr2fCj9/Fth3Qmu+kUGX0 bu0H5P19vzTHdvDoL9g3b781qQfG/PQ6EUpKFcFRG2snOMQ0s1A= =RHTQ -----END PGP SIGNATURE----- --Signature=_Sun__26_Aug_2018_05_19_11_+0300_7mtJoS=3F7yeSw4Y--