[Date Prev][Date Next] [Thread Prev][Thread Next] [Date Index] [Thread Index]

Bug#367697: clarify 12.3 Additional documentation



On 17 May 2006, Peter Eisentraut told this:

> I would like to see some clarifications for section 12.3 "Additional
> documentation", in particular this:
>
> 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
> /usr/share/doc/package, where package is the name of the package,
> and compressed with gzip -9 unless it is small.
>
> I was wondering what "text documentation" means.  Does it mean
> plain-text formatted or anything that contains text (e.g., HTML)?

        HTML is not something that is readily readable using a pager.
 I would suggest that you take it to mean 

> I also notice that nothing here tells where to put non-text
> documentation, such as images or interactive tutorials.  (I know
> it's clear, but the wording might be unnecessarily specific.)
> Perhaps it would clearer this way:

        "at the discretion of the package maintainer".

> Any additional documentation that comes with the package may be
> installed at the discretion of the package maintainer. Documentation
> files should be installed in the directory /usr/share/doc/package,
> where package is the name of the package.  Plain-text files should
> be compressed with gzip -9 unless they are small.

        Umm, no. This outlaws subdirectories like html/ pdf/ etc. Not
 what the intent is.

> Or perhaps:
>
> Any additional documentation that comes with the package may be
> installed at the discretion of the package maintainer. Documentation
> files should be installed in the directory /usr/share/doc/package,
> where package is the name of the package.  All such files should be
> compressed with gzip -9 unless they are small.

        Nope. Policy does not say HTML files must be compressed,
 making them less useful.

        I'll consider adding "Plain" as an adjective for text
 documentation, but we should not over regulate.

        manoj
-- 
"Gods are fragile things; they may be killed by a whiff of science or
a dose of common sense."  -Chapman Cohen
Manoj Srivastava   <srivasta@acm.org>  <http://www.datasync.com/%7Esrivasta/>
1024D/BF24424C print 4966 F272 D093 B493 410B  924B 21BA DABB BF24 424C



Reply to: