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. -- To UNSUBSCRIBE, email to debian-bugs-dist-requ...@lists.debian.org with a subject of "unsubscribe". Trouble? Contact listmas...@lists.debian.org
