Bug#169399: handling of additional documentation with doc-base
On Sat, Nov 16, 2002 at 06:42:37PM -0600, Manoj Srivastava wrote:
> 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.
Not many more have additional documentation to be included in doc-base
files.
> 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.
No, it wouldn't. This part of policy wouldn't apply to packages that have
nothing to do with it.
Packages that would deserve a bug are those that which have additional docs
but have registered it only with dhelp or such (ew!) or that have it but
haven't registered it.
The "policy is not a beating stick" argument doesn't apply to changes that
document best current practice, and expose already existing bugs (lack of
docs integration in this case -- I'm sure we can all agree that the state of
our documentation overall is far from optimal and that it cannot be ignored
as "wishlist" forever).
--
2. That which causes joy or happiness.
Reply to: