commit: a4ada1b4f1e37f189a38d4d5bc06a2c3503e77c9 Author: W. Trevor King <wking <AT> tremily <DOT> us> AuthorDate: Sun Sep 14 18:31:38 2014 +0000 Commit: Markos Chandras <hwoarang <AT> gentoo <DOT> org> CommitDate: Sun Sep 14 21:22:55 2014 +0000 URL: http://sources.gentoo.org/gitweb/?p=proj/devmanual.git;a=commit;h=a4ada1b4
ebuild-writing/common-mistakes: Mention the 'doc' USE flag When reminding folks to install the docs, also remind them that they should be using the 'doc' USE flag for serious docs. This USE flag is the standard way to enable/disable doc installation, and we don't want ebuilds blindly pulling in doc depenencies regardless of how it's set. Use some of Ulrich Müller's wording [1]. [1]: https://bugs.gentoo.org/show_bug.cgi?id=522800#c3 Thanks-to: Ulrich Müller <ulm <AT> gentoo.org> --- ebuild-writing/common-mistakes/text.xml | 12 ++++++++++-- 1 file changed, 10 insertions(+), 2 deletions(-) diff --git a/ebuild-writing/common-mistakes/text.xml b/ebuild-writing/common-mistakes/text.xml index db851a2..ff906fd 100644 --- a/ebuild-writing/common-mistakes/text.xml +++ b/ebuild-writing/common-mistakes/text.xml @@ -391,11 +391,19 @@ implied already, you should only add it if it is something other than <body> <p> -If your package has documentation, make sure you install it using <c>dodoc</c> -or in <path>/usr/share/doc/${PF}</path>. Remember to check for errors when +If your package has documentation, make sure you install it using <c>dodoc</c> +or in <path>/usr/share/doc/${PF}</path>. Remember to check for errors when running <c>dodoc</c>/<c>doins</c>. </p> +<p> +If the package documentation is large or requires additional +dependencies to build, you should make it optional with the <c>doc</c> +USE flag. If the documentation is small and does not require +additional dependencies (e.g. <c>README</c> files), install it +unconditionally. +</p> + </body> </subsection>
