RE: Proposed announcement etc, 2.nd revision

[Gregory Leblanc <GLeblanc@cu-portland.edu>]

> -----Original Message-----
> From: Stein Gjoen [mailto:sgjoen@mail.nyx.net]
> Sent: Monday, February 07, 2000 12:46 PM
> To: Gregory Leblanc; ldp-discuss@lists.linuxdoc.org
> Subject: Re: Proposed announcement etc, 2.nd revision
> 
> > > ==(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.

Sounds like good rational to me.  Assuming that we keep things this way,
then we need to announce this on the main LDP site and have a link to the
announcement.

> 
> 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.

I'm not sure how to do that, I was just using the OSWG as an example.  I do
feel that what they do is important, and will be a nice addition to the
things that the LDP is doing.  

> 
> > > 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.

I think that if we make the news on the LDP page more frequent, and get the
HOWTOs updated in a timely manner, then the LDP's main page will become a
site that is frequented by people in the Linux community.

> 
> > > 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.
> 
[snip]
> > > 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.

DocBook stuff.  An "authors guide" is the name that I like for it, becuase
it follows the conventions of the LDP (it will definately be a guide sized
work).  Basically a larger document covering all of the things that are
required or might be necessary for someone to write works to be part of the
LDP.  This isn't really something that's ripe for discussion on this thread,
but I'm sure it will be hashed out more later.

[snip]
> > > 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.

OK, I just like to know that there has been some thought put into things.
:)

[snip]

> > 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.

Ahh, ok this wasn't clear.  These are places to look for other
documentation.  Somehow I didn't pick up on that when I read it the first
time, sorry.

> 
> > > 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.

Yeah, should be easy enough with some perl or some other language if one
prefers.  I don't think I want to work on programming this myself, but
perhaps we can get some volunteers...

> 
> 
> > > 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.

I want to see the LDP moving to being primarily DocBook based within perhaps
a few months.  If we can make the transition before too long, these sorts of
things are easier.  In the meantime, perhaps some pretty simple scripts to
create template man pages from the sgml source will suffice.  They will need
to be hand edited, until/unless we move to a DTD that allows all of this to
be embeded within the main source document.  I don't know LinuxDoc, so I
can't say if it does, but there are fairly clear-cut ways to have this
content in DocBook documents.

> 
> > > 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.

I don't think I follow here.  Are you talking about authors referencing
other HOWTOs, or something else?

> 
> 
> > > 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.

Argh.  Another LinuxDoc markup thing that I can't deal with very well.
Eventually the man page stubs should be automagically generated from the
SGML source, and I'd rather not see a lot of work go into writing tools to
do that for LinuxDoc, if we can avoid it.  Perhaps we should see if we can
find someone(s) to volunteer to do some quickie scripts.  I'm going to have
to contact Jorge Godoy about DocBook things again to make sure that
gets/keeps rolling.  Is Kendall Clark still listening in on these/helping
out with our move to DocBook?

> 
> 
> > > ==========
> > 
> > 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.

Once we've got things settled with tools, it should be easy enough to
generate these from the SGML source.  As long as our tools are available, if
the people mainintaing the distribution should be able to customize these to
fit their needs. 

> 
> 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/ ?

Guy is doing something about this, according to that email I just read.
Thanks.

> 
> 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 have some things here on my system, which is distinctly not debian, but
neither is it RedHat anymore.  The working group for the FHS seems to have
died, and many of the issues with multi-user systems were never addressed.
This could be easily done as long as we're not maintaining the man page
stubs by hand.

> 
> 
> 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?

Yes, but no.  I'll leave this alone for now, perhaps by the end of the week
or beginning of next week we'll have more to discuss on this issue.  Thanks
for the great work,
	Greg


--  
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org