On 01/01/2008, Douglas A. Tutty <[EMAIL PROTECTED]> wrote:
> On Mon, Dec 31, 2007 at 01:49:25PM -0800, Daniel Burrows wrote:
> > On Mon, Dec 31, 2007 at 01:15:48PM -0600, Manoj Srivastava <[EMAIL
> > PROTECTED]> was heard to say:
> Perhaps it should be policy that if the documentation isn't in the usual
> /usr/share/doc/[package-name] that there be a note there with a pointer
> (i.e. The documentation for this package is in the foo-doc package since
> it is so big.) or (The documentation for this package is under a license
> that does not meet the debian free software guidelines. You can find
> the documentation {in the non-free package foo-doc | at the following
> URL}, preferably the non-free package option.
>
> Also, perhaps it should be policy that the man page for each command
> list the package from which it comes and therefore where the further
> docs are.
>
> The dpkg -S trick should be in the debian installation manual under how
> to find documentation, which should also point to the debian-reference,
> and the other sources of documentation we've discussed in this thread.
>
>
> > A secondary issue is that there's no consistency in file formats
> > between different documentation packages. To read documentation, you
> > need to be able to handle:
> >
> > * Plain text
> > * HTML
> > * PDF
> > * PostScript
> > * DVI
> > * Manpages
> > * Info documents
> > * Whatever help file format Gnome and KDE are using nowadays
> >
There is also texinfo as another source of documentation and anyone
using perl has to know about perldoc.
>
> > This wouldn't be as much of an issue if there was a way for a user to
> > easily access all the documentation related to a command; PDF viewers
> > are fairly easy to deal with, for instance (although a lot of packages
> > compress their PDF documentation, which means you have to manually
> > uncompress it somewhere).
> >
>
> I think that pdf is the biggest issue. I don't normally put a pdf
> reader on all my boxes and I often don't have X. I usually have mc and
> lynx. If I need info, I'll use pinfo although I don't like the info
> format.
>
> I also dislike huge long man pages. To me, man pages should be for a
> bit more help than foo --help; a summary. The main doc should be in
> plain html for viewing with lynx or something.
>
>
I quite like man pages - I guess you must dislike the iptables and
bash ones immensely.
I use less as my pager and can search the man page to find things I
want plus move around the document reasonably well. The format of the
man pages is that the syntax is at the top of the file with the
options all discussed afterwards so I only have to go back up to the
top using 1G to refresh my view of what I am seeing. Esc-U usually
clears selected text resulting from a search.
I would however prefer to see a consistent approach to documentation.
It is very confusing for a newbie.
I am not entirely fond of the info system even though it is useful
with the emacs speedbar. Yet there are short man pages which say see
the info page for the complete documentation and that caused me the
worry of working out if I had info installed.
Lynx is useful for viewing HTML on non-X systems.
It is also important to have the documentation for the particular
version of the package installed
and not the latest available on the upstream website - many newbies
might well seek that website rather than think to look for
documentation on their system.
There is a massive amount of documentation out there. Some indexing
of debian documentation occurs on http://www.uk.debian.org/doc/ but I
think package documentation should always appear in
/usr/share/doc/<packagename>.
Some of the howtos are important to read especially the apt-get howto
but I find I worry how applicable some howtos actually are now.
Regards
Lesley
--
To UNSUBSCRIBE, email to [EMAIL PROTECTED]
with a subject of "unsubscribe". Trouble? Contact [EMAIL PROTECTED]
