[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Proposed announcement etc, 2.nd revision
Gregory Leblanc wrote:
>
> > -----Original Message-----
> > From: Stein Gjoen [mailto:sgjoen@mail.nyx.net]
> > Sent: Monday, February 07, 2000 11:39 AM
> > To: ldp-discuss@lists.linuxdoc.org
> > Subject: Proposed announcement etc, 2.nd revision
> >
> > I got some feedback on the proposed texts I posted 1.st february on
> > - announcement text
> > - intro.ldp manpage source
> > - intro.txt the above formatted
> >
> > Additionally I am here submitting a proposal to the
> > stub manpage for my own Multi Disk HOWTO, a manpage
> > that I hope can make man -k <keyword> also find the
> > HOWTO collection.
> >
> > So, once again: please give me feedback!
> >
> > (Straight off I just noticed the stub manpage didn't format well
> > but I am not good at manpage authoring.)
And 10 minutes later I discovered what the previous poster
also dicovered. It was late...
> > I feel the announcement should be sent by the main
> > contact address for the LDP, otherwise I am likely to
> > receive a lot of incorrectly adressed email.
> >
> > ==(Announcement)===
> >
> >
> > After some restructuring of the Linux Documentation Project (LDP)
> > we feel ready to serve the Linux community from the new home:
> > http://www.linuxdoc.org/
>
> To me this implies some major change has happened to the linuxdoc.org site
> recently, something along the lines of the new site that the OSWG just put
> up. I don't think that this is really what we should be advertising,
> although I don't have any better ideas.
I feel there HAVE been many changes, the most important
is that we have a momentum going, things happening and
that the LDP now provides better service. As far as I
know the LinuxDoc site was never advertised, at least
I never saw it.
The OSWG is not mentioned here and I feel it would be a
good idea if they announced their site too. I just don't
want to cause confusion on the relationship between LDP
and OSWG.
> > The LDP has collected and produced numerous documents such as
> > - guides
> > - HOWTOs and mini-HOWTOs
> > - FAQs
> > - man pages
> > and more.
> >
> > All in all the LDP endeavors to produce and provide a
> > one-stop source of
> > information relating to the various aspects of Linux. There
> > is now also
>
> I think I'd remove the word "also", it seems unnecessary here.
Fair enough. I wanted to give an impression of continuous
action of the part of the LDP but strictly speaking it is
not necessary.
> > a search engine on the front page to help you quickly and efficiently
> > locate the documents you need. If you have a question, chances are you
> > will find what you need here.
> > These documents are produced for you, the end users. That
> > means if there
> > is anything in the documents you find unclear, ambiguous or incorrect
> > you should not hesitate in contacting the author. While the
> > workload of
> > the authors in general may be high and cannot be expected to
> > answer specific
> > problems you may have on your machine, generally authors are
> > only happy to
> > receive feedback on the documents.
>
> Sounds good.
> > Likewise, if you feel you have something to contribute or you
> > wish to try
> > your hands as an LDP author you are welcome to contact the
> > LDP coordinator
> > with your inputs (see the HOWTO-HOWTO). Remember that new
> > documents are
> > produced all the time so it is important to contact the LDP before you
> > start writing in order to eliminate the possibility of duplicate work.
> I haven't gotten a copy of the work that Jorge is working on, but if it's
> ready for prime-time before this announcement goes out, perhaps it should be
> included here as well.
I am not sure what work you are referring to here.
> > Remember that you do not have to be on-line to read the
> > HOWTOs, in many
> > cases these documents are installed with your Linux
> > distribution and can
> > be found at
> > file:///usr/doc/HOWTO /usr/doc/HOWTO/
> >
> > Regards,
> > Stein Gjoen
> >
>
> [opaque man format yanked]
>
> > ===(intro.txt)===
> >
> >
> > LDP Introduction(ldp) LDP Introduction(ldp)
> >
> >
> > NAME
> > LDP - Intro to the Linux Documentation Project, with help,
> > guides and documents
> >
> > SYNOPSIS
> > The Linux Documentation Project, or LDP for short, pro-
> > vides free documentation, guides, FAQs, HOWTOs and mini-
> > HOWTOs and man-pages to the Linux community.
> I hate making comments like this, becuase I'm never confident that my
> English is better than anybody else's, but I'd re-phrase the above as:
> The Linux Documentation Project, or LDP for short, provides a variety of
> free documentation, including Guides, FAQs, HOWTOs and mini-HOWTOs, and
> man-pages for the Linux Community.
>
> Actually, looking at that, it's not any better, just a little different.
> Maybe a couple more people can tell me why my phrasing is bad.
English is not my first language either and past midnight I
only gargle fluent double Dutch...
> > MAILING LISTS
> > LDP has a number of mailing lists, mostly of use for
> > authors:
>
> This implies to me that the mailing lists are mostly for authors. While I
> don't write documentation specific to Linux, I'm on several of the lists.
Well yes, it was my impression that is was mostly for authors
but the word 'mostly' does not exclude anyone.
> > <ldp-announce@lists.linuxdoc.org>
> > Announcements from the LDP project
> >
> > <ldp-discuss@lists.linuxdoc.org>
> > General discussion on the LDP project
>
> Perhaps this section should contain the "request" addresses for these lists,
> with brief subscription instructions (I.E. the command line issue to
> subscribe). I think that it should also tell how to get the info message
> for these lists as a sort of "for more information on this list, send a
> message with a body of info to ldp-discuss-request@lists.linuxdoc.org or
> issue the command 'mail...' (sorry, I don't know how to use mail)".
Sounds like a good idea. Hmmm, yes it is
"subscribe" to ldp-discuss-request@lists.linuxdoc.org
> > FILES
> > Most distributions include the HOWTOs and mini-HOWTOs in
> > the installation
> > /usr/doc/ (most documentation is here)
> > /usr/doc/HOWTO/ (HOWTO files)
> > /usr/doc/HOWTO/mini/ (mini-HOWTO files)
> > SEE ALSO
> > man(1)
> >
> > info pages as read with Emacs
>
> Are we going to create info pages as well?
Not that I know. This is just a reference to the large number
of info pages that exists since the FSF has a lot of outdated
manpages and chose to maintain their info pages instead. To
avoid controversy I wasn't planning on putting the reasons in
the announcement.
> [incomprehensible nroff whacked]
>
> >
> > ===(disk.txt)===
> >
> > Stub man page for the StubimanspageWforlthe Multi Disk HOWTO(ldp)
The above needs trimming. Badly.
> > NAME
> > Multi Disk HOWTO - Multi disk design, partitioning, for-
> > matting, tuning and maintenence
Should be extractable. Tags for this could be used to add
useful <META> tags to the resulting HTML pages.
> > ABSTRACT
> > This document describes how best to use multiple disks and
> > partitions for a Linux system. Although some of this text
> > is Linux specific the general approach outlined here can
> > be applied to many other multi tasking operating systems.
>
> Is this taken from the abstract in your HOWTO? I tend to think that this
> would be the easiest way to do things, if we're going to make a man page
> available for all of the HOWTOs.
Yes, this is from the abstract. Some time ago I outlined how
I felt the process should work; ideally it should be generated
automaticaly from the SGML source.
Now that it looks like we can get the tools developed I
might pester this list with my ruminations on this issue.
> > FILES
> > Most distributions include the HOWTOs and mini-HOWTOs in
> > the installation
> > /dev/ (device files)
> > /etc/fstab (mount list)
> > /etc/mdtab (old style RAID table)
> > /etc/raidtab (new style RAID table)
I'd like to add that the <file> tag could be used to generate
this list and that I'd prefer the HTML code to render these as
<tt><a href="file:///dev/>/dev/</a></tt>
or something similar so the tag becomes more useful.
> > RELATED HOWTOS
> > Tips, Partition, Partition Rescue, Large-Disk, LILO, Soft-
> > ware-RAID, Upgrade
Inter HOWTO linking is a long standing problem, if we can solve
these also this list should be automatically generated.
> > SEE ALSO
> > fdisk(8), mount(8), mkfs(1), umount(8)
Likewise the <cmd> tag (of whatever it is) should
make also this list automatically generated,
complete with man page chapter reference.
> > ==========
>
> No where in this man page do you tell where to get the full text of your
> Multi-disk HOWTO. I think that this NEEDS to be part of the man page, or
> there isn't any point in having the man page. <flame> The idea is to get
> the user some return on reading TFM, not to taunt them with the idea that
> there's more information someplace, and not tell them where it is. </flame>
That was the embarassing error I referred to near the top.
Of course theer should be a pointer. Currently with distributions
using the File System Standard (FSSTND) the path is
/usr/doc/HOWTO/
which brings up a few uglies:
First of all we do not know what format the distributions
use, it can be
o .txt
o .txt.gz
o .HTML
o something else
As long as the LDP does not take over this job we have no way of
knowing.
Secondly the mini-HOWTOs reside at /usr/doc/HOWTO/mini/
and you also have the /usr/doc/HOWTO/unmaintained
and all these splits causes extra complexity while
making use of grep harder. Why not put it all under
/usr/doc/HOWTO/ ?
Finally, and this is a harder one, the File Hierarchy Standard
(FHS) is set to supercede the FSSTND, and it looks like Debian
will be the first to implement this new standard. In that case
the docs end up at
/usr/share/doc/HOWTO/
I would like the pointer to point straight to
/usr/doc/HOWTO/Disk-HOWTO.txt
but I see no way of doing that.
Ideas, anyone?
> Sorry Stein. Thanks,
> Greg
Regards,
Stein Gjoen
--
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org