Re: The /usr/doc Hierarchie
>>>>> "Ian" == Ian Jackson <iwj10@cus.cam.ac.uk> writes:
Ian> In general, documentation source should be in the source
Ian> package. The /usr/doc directory can contain PostScript, DVI,
Ian> ASCII, ASCII with overprint highlighting, &c.
We have to ask who is it, who wants to use the /usr/doc -- I like the
idea, it's the online user, who wants to view helpful documents quickly.
Therefore I think, there should be a priority list: ASCII comes first,
since you are able to search for strings; then ASCII with highlighting;
then DVI (displaying DVI normally is quicker than PS).
Ian> I don't think TeX source is appropriate; it is definitely
Ian> inappropriate if no formatted version is provided.
Agreed.
>> /usr/doc/base /usr/doc/admin /usr/doc/mail
Ian> I disagree, strongly. It is important to be able to find
Ian> things in /usr/doc, even if one is a naive user. Having to use
Ian> (for example) `find' is unacceptable.
Generally, I do not think "a naive user" is stupid. If `ls' displays
more than one screen, she should know something about ``How to pipe
output to a pager''... If `find' is unacceptable, someone will offer a
script, that hides `find'. Right now /usr/doc is an ugly mixture; I
hate to see directories containing files and subdirs--of course, I
hate my $HOME ;-)
To provide examples is a good idea--but why hide these examples in
doc/examples (e.g., doc/examples/linuxdoc-sgml/example.sgml vs
doc/linuxdoc-sgml)? Next time I will offer psgml-1a8-1.deb which has
usr/doc/copyright/psgml
usr/doc/examples/psgml-1a8/
usr/doc/examples/psgml-1a8/dot.emacs
usr/doc/examples/psgml-1a8/catalog.sgml
usr/doc/examples/psgml-1a8/style.el
usr/doc/psgml-1a8/README.gz
But I would prefere
usr/doc/copyright/psgml
usr/doc/sgml/psgml-1a8/
usr/doc/sgml/psgml-1a8/dot.emacs
usr/doc/sgml/psgml-1a8/catalog.sgml
usr/doc/sgml/psgml-1a8/style.el
usr/doc/sgml/psgml-1a8/README.gz
and I would like to see the linuxdoc stuff there as well:
usr/doc/copyright/linuxdoc-sgml
usr/doc/sgml/linuxdoc-sgml/README
usr/doc/sgml/linuxdoc-sgml/examples/example.sgml
usr/doc/sgml/linuxdoc-sgml/guide/{guide.ps.gz,guide.sgml,...}
usr/doc/sgml/linuxdoc-sgml/html/{guide.html,guide.sgml-2.html,...}
Ian> One should not need to know how a package was installed when
Ian> looking up its documentation - remember that the user is not
Ian> always the sysadmin.
Yes, but since the Debian dist. offers funny names, there should be no
problem (`mail', `editors', etc.; the BOGUS dist. in contrast, has
`doc/bin', `doc/usr.bin', `doc/usr.bin.X11').
Karl.
Reply to: