Subject:
Hosting Debian Documentation at LDP
From:
David Lawyer ####@####.####
Date:
3 Apr 2009 09:19:45 +0100
Message-Id: <20090402201214.GC2147@davespc>
There has been a discussion on the staff list about this and Sergiusz
Pawlowicz suggested that I post my suggestions on the discuss list. I
didn't propose this but I think it's a good idea, provided we host the
documentation for all the Debian packages (and possibly for other
distributions). The original proposal by Sergiusz was to host what
Debian has on the web at www.debian.org/doc/. I didn't follow the
thread closely and somehow thought that the proposal might have been to
host the documentation of all the packages which is found in
/usr/share/doc. Here's a transcript of the part of the discussion re
my proposal:
++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++++
-r F- 279/286: David Lawyer Re: [staff] [debian docs?] -- (all)
Date: Mon, 30 Mar 2009 22:41:02 -0700
From ####@####.#### Mon Mar 30 22:48:59 2009
From: David Lawyer ####@####.####
Subject: Re: [staff] [debian docs?]
To: LDP Staff ####@####.####
Mail-Followup-To: LDP Staff ####@####.####
What happened to the LDP staff member Martin Wheeler? He was also
active in Debian and involved in the Debian packages of LDP documents.
But he never suggested that we host Debian documentation.
I think what you have in mind is to host documentation supplied in
various Debian packages and put into a subdirectory of /usr/share/doc.
Example: /usr/share/doc/mutt/ for the mutt email client documentation
files (often several files). This stuff is sometimes not available on
the Internet and thus will not be found in a Google search, especially
if it's Debian specific documentation. I've noticed that some of the
Debian-specific docs contain corrections to the documentation written
by the author of the programs. Useful info.
It would be useful to do this not just for Debian but for all major
Linux distributions. [Later comment by David L: There would be a lot of
duplication of files if this were done, since documentation supplied
by program authors is picked up by the various distributions. What's
desired is the distribution specific files from each distribution (or
portions of files that are distribution specific).] Then a HOWTO
writer could consult this info to see the differences in
configuration, etc. between distributions and mention these
differences in the HOWTO.
Who else will use this info? Someone who has a package installed on
their computer already has the documentation which was included
in the package. But if there are problems, perhaps the distribution
specific info from a different distribution has a fix for the
problems, or explains the situation and options more clearly, etc.
This is why it's important to cover more distributions than just
Debian.
Besides the /usr/share/doc directory, packages often contain default
configuration and initialization files which are automatically
installed in the /etc directory tree and sometimes in library
directories. These are in a sense, part of the documentation. Many
configuration files have comments that help the user modify them.
Such comments are also documentation.
Updated packages of distributions are issued daily and to keep this
documentation up-to-date, a script needs to find updated (or new)
packages every day, extract their documentation, and put it on the LDP
site. Mirrors ?? Probably not, in my opinion. The latest unstable
distribution likely contains better documentation than the stable
version (unless the documentation is not backwards compatible).
David Lawyer
> > On Mon, Mar 30, 2009 at 09:23, jdd for http://tldp.org ####@####.#### wrote:
> >> that's good, but it was not exactly my point.
> >>
> >> Could we discuss with Debian some kind of exchange? do we have the
> >> same mirrors? how is Debian including LDP?
> Sergiusz Pawlowicz a ?crit :
> >
> > Yes, debian is promoting LDP as main source of documentation
> > on their docs page.
> >
> >> AFAIK, the HOWTOs are included in Debian, but I never see news about
> >> that in our lists. May be we could have better result if sharing, for
> >> example with the LDP .deb maintainer
> >>
> >> if you think it's necessary, I can investigate
> >
> > any better relations with debian are appreciated!
On Mon, Mar 30, 2009 at 11:40:39AM +0200, jdd for http://tldp.org wrote:
>
> good :-))
>
> jdd
>
> --
> jdd for the Linux Documentation Project
> http://wiki.tldp.org
> http://www.dodin.net
> http://www.facebook.com/profile.php?id=1412160445
>
> ______________________
> http://lists.tldp.org/
>
>
______________________
http://lists.tldp.org/
- F- 280/286: David Lawyer Re: [staff] [debian docs?] -- (all)
Date: Mon, 30 Mar 2009 22:56:40 -0700
From ####@####.#### Wed Apr 01 22:15:55 2009
From: David Lawyer ####@####.####
Subject: Re: [staff] [debian docs?]
To: LDP Staff ####@####.####
Mail-Followup-To: LDP Staff ####@####.####
On Mon, Mar 30, 2009 at 10:41:02PM -0700, David Lawyer wrote:
>
> I think what you have in mind is to host documentation supplied in
> various Debian packages and put into a subdirectory of /usr/share/doc.
It looks like I was wrong. You are proposing to mirror what Debian
has on their website, which is NOT the documentation contained in
their packages. Well, I think that it would be much better to host
documentation which is not now on the Internet (unless one downloads
the appropriate package) than to just mirror what is already on the
Internet at Debian (and their mirrors?).
David Lawyer
______________________
http://lists.tldp.org/
-N F- 283/286: David Lawyer Re: [staff] [debian docs?] -- (all)
Date: Thu, 2 Apr 2009 00:02:00 -0700
From ####@####.#### Thu Apr 02 00:07:19 2009
From: David Lawyer ####@####.####
Subject: Re: [staff] [debian docs?]
To: LDP Staff ####@####.####
Mail-Followup-To: LDP Staff ####@####.####
> Sergiusz Pawlowicz a ?crit :
>
> > /usr/share/doc content is just an ordinary listing of directories,
> > without any indexes.
>
On Tue, Mar 31, 2009 at 10:27:08PM +0200, jdd for http://tldp.org wrote:
> we already host man pages that makes the most of /usr/share/doc
The documentation in /usr/share/doc/ is often much more detailed,
complete, and clearer than what is in the man pages. For interactive
programs, the man page may only show the options used on the command
line when starting the program. But /usr/share/doc/ may contain a
manual which explains how to interact with the program and explains
its features. Unlike a man page, they may contain sections,
subsections, a table of contents, etc., like a HOWTO doc. The manuals
in /usr/share/doc/ are sometimes called something else like a
Specification (Exim). For each package, there are often several other
files in /usr/share/doc/this-package/ such as tutorials, change-logs,
bugs, Debian specific information, copyright (contains license),
README's, configuration options (including sample configuration
files), various examples, and news about the program. Most all of
these files are plain text but some manuals are html.However, for
many command line programs, the man pages suffice for using the
program.
So one way to organize this is to convert the /usr/share/doc/
directory tree into html. But how to automate this?
David Lawyer
-N L- 511/511: Sergiusz Pawlowicz Re: [staff] [debian docs?] -- (all)
Date: Thu, 2 Apr 2009 20:19:23 +0100
From ####@####.#### Thu Apr 02 11:49:57 2009
From: Sergiusz Pawlowicz ####@####.####
Subject: Re: [staff] [debian docs?]
To: LDP Staff ####@####.####
[snip][re David L's proposal]
yes, IMHO we can discuss it on "discuss" list. maybe you can describe
a problem and call for volunteers? a volunteer has helped me to find a
suitable package for debiandoc-docbook export, so i think there are
good chances to find someone.
cheers -
serge
______________________
http://lists.tldp.org/
===========================================================================
Well, I didn't take the time to rewrite the proposal so above is just
transcripts of what I proposed, etc. But I just don't have time to do
what I'm proposing. David Lawyer
