Re: PLEASE: standard package README file/orientation
On 22-Aug-00, 23:12 (CDT), Daniel Barclay <dsb@smart.net> wrote:
> Some packages don't have a documentation directory at all.
Then they are in violation of the Debian policy. Current policy
requires that /usr/doc/<package> exist (possibly as a symlink to
/usr/share/doc/<package>).
> Some others do but their files are so scrambled that you can't
> tell which are current, which are obsolete (because of, e.g.,
> Debian clean-up of how the package works), etc., without
> reading each file.
It is not the maintainer's job to keep a packages upstream documentation
up-to-date. Sorry, but that's the way it is. If the maintainer does
something to the package obsoletes or otherwise breaks the upstream
documentation, then that info *should* be in changelog.Debian.gz, if
nowhere else.
> PLEASE remember what changes, especially for the user installing
> the software, between building and installing from source
> tarballs vs. installing distribution packages:
[snip description of README, etc.]
If that information is provided by the upstream package, then it
should be included in the doc directory, under the same name. Policy
specifically allows for build and installation instructions to be
omitted, but other materials should be included.
That they are not is a bug in the package, not in policy.
> Debian packages don't provide that orientation reliably at all.
ls -l /usr/doc/foo
dpkg -L foo |grep bin
dpkg -L foo |grep man
dpkg -L foo |grep info
works for *every* package. (Yes, I know it would be more efficient
to combine into one dpkg -L command, I left it as an exercise for the
reader.)
> We do have directory /usr/share/doc/<package>/ (well, for some
> packages),
You're looking in the wrong place -- we haven't completed the transition
to /usr/share/doc yet -- the canonical place is /usr/doc.
Look, I share some of your frustrations. But the problem is with
individual packages not included the upstream materials, or the lack of
upstream materials. If a maintainer chooses to augment what's upstream
that's great. Writing a policy requirement for such is not.
Steve
Reply to: