Bug#169399: handling of additional documentation with doc-base
Hi,
>>"Josip" == Josip Rodin <joy@gkvk.hr> writes:
Josip> Surprisingly enough, we have yet to put any mention of
Josip> doc-base into the Policy. A lot of the packages that need it
Josip> use it by now[1], so it appears to be working properly. It
Josip> would be useful if it was "legalized" by the Policy Manual so
Josip> that new maintainers can't miss it for example, and that
Josip> existing maintainers can't ignore it saying "it's not in
Josip> Policy, so what if it's a good idea!".
By a lot, if you mean about 5-10% of the programs, well, yes.
Josip> So, I propose an addition like this into the section
Josip> 13.3 "Additional documentation":
Josip> All additional documentation should be registered via
Josip> doc-base so that is made available in generic documentation
Josip> viewers (such as dhelp, dwww or doc-central). Please refer
Josip> to the doc-base manual in the doc-base package for all the
Josip> information on the exact technical implementation.
That change makes over 90% of the packages on my machine
instantly buggy, for not following a should directive.
Josip> That makes not having doc-base files a normal or minor bug, which seems
Josip> reasonable to me.
Policy should not suddenly make 90% of the packages buggy, so
no, this is not reasonable.
Josip> (Linking within the paragraph is left as an exercise to the
Josip> policy editor, e.g., myself. :)
======================================================================
<heading>Additional documentation</heading>
<p>
Any additional documentation that comes with the package may
be installed at the discretion of the package maintainer.
Text documentation should be installed in the directory
<file>/usr/share/doc/<var>package</var></file>, where
<var>package</var> is the name of the package, and
compressed with <tt>gzip -9</tt> unless it is small. It is
strongly recommended that such documentation be registered
via <package>doc-base</package> so that it is easily
accessible (by being visible in generic documentation
viewers in the project). Please refer to the documentation
of the package <package>doc-base</package> for details.
</p>
======================================================================
Josip> [1] For reference, on my machine:
Josip> % dpkg -S /usr/share/doc-base/* | cut -d: -f1 | sort -u | wc -l
Josip> 58
Josip> % dpkg -l | grep ^.i -c
Josip> 688
__> dpkg -S /usr/share/doc-base/* | cut -d: -f1 | sort -u | wc -l
97
__> dpkg -l | grep ^.i -c
1538
On another machine:
__> dpkg -S /usr/share/doc-base/* | cut -d: -f1 | sort -u | wc -l
158
__> dpkg -l | grep ^.i -c
2021
manoj
--
Important letters which contain no errors will develop errors in the
mail. Corresponding errors will show up in the duplicate while the
Boss is reading it. Vital papers will demonstrate their vitality by
spontaneously moving from where you left them to where you can't find
them.
Manoj Srivastava <srivasta@debian.org> <http://www.debian.org/%7Esrivasta/>
1024R/C7261095 print CB D9 F4 12 68 07 E4 05 CC 2D 27 12 1D F5 E8 6E
1024D/BF24424C print 4966 F272 D093 B493 410B 924B 21BA DABB BF24 424C
Reply to: