Bug 522800 – devmanual should mention 'doc' USE flag when pushing folks to install docs

• Product: Documentation
• Status: RESOLVED FIXED

[Description W. Trevor King 2014-09-14 18:47:14 UTC]

When reminding folks to install the docs, also remind them that they
should be using the 'doc' USE flag. This USE flag is the standard way
to enable/disable doc installation, and we don't want ebuilds blindly
installing docs regardless of how it's set.

Patch in https://github.com/gentoo/devmanual.gentoo.org/pull/23

Reproducible: Always

[Comment 1 Mike Gilbert 2014-09-14 18:52:54 UTC]

To be more specific, from use.desc:

doc - Add extra documentation (API, Javadoc, etc). It is recommended to enable per package instead of globally


I usually take that to mean developer docs, rather than end-user docs.

[Comment 2 W. Trevor King 2014-09-14 19:03:56 UTC]

(In reply to Mike Gilbert from comment #1)
> doc - Add extra documentation (API, Javadoc, etc). It is recommended
> to enable per package instead of globally
>
> I usually take that to mean developer docs, rather than end-user docs.

Ah, so end-user docs always, and developer docs depending on 'doc'?
How good are projects about distinguishing between user-facing and
developer-facing docs?  I expect any source that comes with in-tarball
docs (which seems to be what these notes are aiming at with “If your
package has documentation”) is going to have developer-facing docs in
the mix, and I don't know how easy it will be to toggle the developer
docs in the build system.

Personally, I see no need to make a developer/end-user distinction.
End users are probably going to mind a few extra API docs less than
embedded folks are going to mind enforced user docs ;).  If we do want
to make that distinction, we should echo it in this package.

[Comment 3 Ulrich Müller 2014-09-14 20:00:24 UTC]

Any small size documentation should be installed unconditionally. USE="doc" is for anything that is a) large or b) requires additional dependencies to build.

[Comment 4 W. Trevor King 2014-09-14 21:28:34 UTC]

(In reply to Ulrich Müller from comment #3)
> Any small size documentation should be installed unconditionally. USE="doc"
> is for anything that is a) large or b) requires additional dependencies to
> build.

That's a distinction that makes more sense to me.  I've updated my patch accordingly.

[Comment 5 W. Trevor King 2014-10-18 17:46:18 UTC]

(In reply to W. Trevor King from comment #0)
> Patch in https://github.com/gentoo/devmanual.gentoo.org/pull/23

This pull request was just merged.