Bug#106073: recommend to install <package> documentation into /usr/share/doc/<package>/
Hi,
Russ Allbery wrote:
> * Some reorganization and wording tweaks to hopefully make things clearer.
Alas, there's a lot of this --- enough that I wish this had been
prepared as a multiple-patch series, with for example whitespace-only
changes split out.
Oh, well. Onward. :)
[...]
> --- a/policy.sgml
> +++ b/policy.sgml
> @@ -9702,45 +9702,77 @@ END-INFO-DIR-ENTRY
> </p>
> </sect>
>
> - <sect>
> + <sect id="docs-additional">
>
> <heading>Additional documentation</heading>
>
> <p>
> - Any additional documentation that comes with the package may
> + Any additional documentation that comes with the package may be
The rewrapping could go straight to master.
[...]
> - Plain text documentation should be installed in the directory
> - <file>/usr/share/doc/<var>package</var></file>
> + It is
> + often a good idea to include text information files
Putting the overview information first. Good idea.
[...]
> <p>
> - It is often a good idea to put text information files
> - (<file>README</file>s, changelogs, and so forth) that come with
> - the source package in <file>/usr/share/doc/<var>package</var></file>
> - in the binary package.
> + It is
> + often a good idea to include text information files
> + (<file>README</file>s, <file>TODO</file>s, and so forth) that
> + come with the source package in the binary package.
Before, this included a reminder that including the upstream changelog
is often a good idea[1]. Removing that reminder saves me from being
confused into thinking it is _just_ a good idea rather than a policy
"should" (good), but on the other hand it is removing a reminder.
This adds a mention that including upstream's TODO files is often a
good idea. Maybe it is --- I'm not sure. (FAQs, acknowledgements,
and API changelogs are more obvious examples to me.)
[...]
> <p>
> - If a package comes with large amounts of documentation which
> - many users of the package will not require you should create
> - a separate binary package to contain it, so that it does not
> - take up disk space on the machines of users who do not need
> - or want it installed.</p>
> + If a package comes with large amounts of documentation that many
> + users of the package will not require, you should create a
> + separate binary package to contain it so that it does not take
> + up disk space on the machines of users who do not need or want
> + it installed.
Could go straight to master (rewrapping and trivial wording changes).
> As a special case of this rule, shared library
> + documentation of any appreciable size should always be packaged
> + with the library development package (<ref id="sharedlibs-dev">)
> + or in a separate documentation package
[...]
> + The documentation package for the
> + package <var>package</var> is conventionally
> + named <var>package</var>-doc
> + (or <var>package</var>-doc-<var>language-code</var> if there are
> + separate documentation packages for multiple languages).
> + </p>
Sensible.
> + <p>
> + Additional documentation included in the package must be
> + installed under <file>/usr/share/doc/<var>package</var></file>.
(*)
Strengthening to a "must". Is that intended? I haven't had the
gumption yet, but I'd like to move liblzma-dev's documentation to
/usr/share/doc/liblzma/ (with symlinks from .../doc/liblzma-dev) some
day.
> + If the documentation is packaged separately,
> + as <var>package</var>-doc for example, it may be installed under
> + either that path or into the documentation directory for the
> + separate documentation package
> + (<file>/usr/share/doc/<var>package</var>-doc</file> in this
> + example).
I guess this modifies the "must" above.
> However, installing the documentation into the
> + documentation directory of the main package is preferred since
> + it is independent of the packaging method and will be easier for
> + users to find.
> + </p>
In the case of liblzma-doc, what is the main package?
[...]
> <p>
> Packages must not require the existence of any files in
> <file>/usr/share/doc/</file> in order to function
> <footnote>
> - The system administrator should be able to
> + The system administrator should be able to delete files
Could go straight to master. :)
[...]
> - </footnote>.
> - Any files that are referenced by programs but are also
> - useful as stand alone documentation should be installed under
> - <file>/usr/share/<var>package</var>/</file> with symbolic links from
> - <file>/usr/share/doc/<var>package</var></file>.
> + </footnote>. Any files that are referenced by programs but are
> + also useful as stand alone documentation should be installed
> + elsewhere, normally
> + under <file>/usr/share/<var>package</var>/</file>, and then
> + included via symbolic links
> + in <file>/usr/share/doc/<var>package</var></file>.
Yep, makes sense. Maybe even s/normally/for example/.
[...]
> @@ -9782,16 +9802,16 @@ END-INFO-DIR-ENTRY
> via HTML.</p>
>
> <p>
> If your package comes with extensive documentation in a
> markup format that can be converted to various other formats
> you should if possible ship HTML versions in a binary
> - package, in the directory
> - <file>/usr/share/doc/<var>appropriate-package</var></file> or
> - its subdirectories.
> + package.
> <footnote>...</footnote>
> + The documentation must be installed as specified in
> + <ref id="docs-additional">.
Makes sense.
Thanks for taking care of this, and sorry I have only nitpicks to
offer. The only part that I can imagine having important undesirable
consequences is (*) above.
Jonathan
[1] By the way, including the upstream changelog seems to be a rarer
and rarer thing for packagers to do. Maybe it's worth a bug to make
policy §12.7's advice more helpful in light of packages with large
changelogs, like bash, packages whose changelogs are split into
multiple files, like gcc, and packages whose history is tracked in a
VCS but not described in upstream tarballs, like linux-2.6.
Reply to: