Re: Proposed announcement etc, 2.nd revision

[Stein Gjoen <sgjoen@mail.nyx.net>]

Some big snips ahead...

Gregory Leblanc wrote:
> 
> > -----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)===


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

Hopefully the LDP should be a one stop site to locate
all sorts of Linux information and I hope many will
bookmark the site.

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

There is a number of auxiliary sites that are relevant such
as FAQ archives, various zines and more. The OSWG might look
very similar to the LDP at first glance so I want to make sure
there is no confusion here, especially as they have a number
of very useful HOWTOs.


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

Judging by the news column ther are announcements every
two weeks or so, and I hope this will improve even further
since DNS problems have made the site unavailable from
time to time.


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

Sounds interesting, please keep us informed on this list. I hope
we can get the announcement done within a week or so.


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

It was late at night but I did try my best, without being
too conspiratorical. 8-)

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

Excessive diplomacy on my part I guess. This issue has blown
up a number of times before so I wanted to be cautious.

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

It looks like the SGML tools will be maintained again which
means I will pester this list once again with my ideas on
how to improve things. I do not have the technical knowledge
to do this myself but I try to look at the issues from the
perspective of the end users and see what we can do to
improve.



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

Oh dear. DocBook keeps coming up again and again but proper
docs on how to use it just doesn't seem to be there and
even ESR was unimpressed.

So far DocBook looks like the ideal tool to scare the living
daylight out of prospective HOWTO authors. I would like to
see the unmaintained HOWTOs taken up again and more new HOWTOs
written in which case the learning curve shuld not look like
a spiked brick wall.

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

Yes. This is more difficult when a reference moves from one
HTML page to another so it would seem to me we need a new
mechanism and also all HOWTOs would need to be compiled
together.

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

I hope the system is expandable so we can have our own tags
in case this doesn't exist in the DocBook. LDP is special
purpose and I feel we would be justified in inventing our
own tags if that makes life easier for authors and readers.

> 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

I hope someone could come forward. Failing that I hope my
proposed disk.ldp man page file could be used as a framework
for manual work.

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

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

A kind of postinstall script might do the work but someone has to
make it. Any volunteers?

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

I just saw that message, this should make things a lot easier.

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

The FHS is something of an anomaly, a cathedral aside from the
bazaar, where you get secret URLs to secret documents by sending
email ( I nearly said secret handshakes). To top it off these
are outdated. Oh yes, you are also asked not to copy to public
lists or archives.

And it gets better, the list system is fairly broken, I keep
falling off and have had to resubscribe 4-5 times so far and
noone replies to the reports. Others cannot get off the list
without some rather extreme measures.

There are probably many others on this list who wishes to
follow the list which is why I am posting this to the
whole list. so if the list seems to go dead you will need
to resubscribe.


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

Thanks. I feel we have teh ball rolling now, just a bit more
feedback and I think we can wrap this up.

Regards,
   Stein Gjoen


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