Bug#169399: handling of additional documentation with doc-base

[Josip Rodin <joy@gkvk.hr>]

On Sat, Nov 16, 2002 at 07:16:40PM -0600, Manoj Srivastava wrote:
>  >> That change makes over 90% of the packages on my machine
>  >> instantly buggy, for not following a should directive.
> 
>  Josip> No, it wouldn't. This part of policy wouldn't apply to
>  Josip> packages that have nothing to do with it.
> 
>  Josip> Packages that would deserve a bug are those that which have
>  Josip> additional docs but have registered it only with dhelp or such
>  Josip> (ew!) or that have it but haven't registered it.
> 
> 	Can we have some guestimate on the numbers here?

Hmm, now that you mention it, here's some:

% find doc -name \*.html | perl -pe 's,/[^/]*$,\n,' | sort -u | wc -l
    307
% for i in $(find doc -name \*.html | perl -pe 's,/[^/]*$,\n,' | sort -u); do grep $i doc-base/* -q || echo $i not mentioned; done | wc -l
    240

($PWD=/usr/share)

Hmm, not good. But, if we weed out doc-linux-html's HOWTOs for which the
doc-base entries can only really be extracted from LDP's indices on-the-fly:

% for i in $(find doc -name \*.html | perl -pe 's,/[^/]*$,\n,' | sort -u); do grep $i doc-base/* -q || echo $i not mentioned; done | grep -v doc/HOWTO -c
63

For reference again,

% find doc-base/ -type f | wc -l
     94

This list still includes things like gentoo/html/config/ which has files
that aren't listed explicitely in its doc-base file, but gentoo/html/ is, so
it's de facto linked. Or developers-reference.{fr,ja}.html and
debian-history/{fr,ru} which are erroneously omitted from the already
existing developers-reference and debian-history doc-base files.

Still not too decisive, even if we ignore those false matches. A fair amount
of work to do.

>  Josip> The "policy is not a beating stick" argument doesn't apply to
>  Josip> changes that document best current practice, and expose
>  Josip> already existing bugs (lack of docs integration in this case
>  Josip> -- I'm sure we can all agree that the state of our
>  Josip> documentation overall is far from optimal and that it cannot
>  Josip> be ignored as "wishlist" forever).
> 
> 	Well, if policy is not going to be used as a stick, then it
>  should not matter if we phase it in, starting with recommending it,
>  and then making the directive stronger as we get a handle on how many
>  packages are affected.

In the light of the above numbers, I amend my proposal with s/should/may/.
(Seconded?)

Speaking of bugs... how do we actually specify that a "should" means e.g.
minor, and not normal or important?

-- 
     2. That which causes joy or happiness.