Subject:
Re: LDP Filesystem Hierarchy
From:
Stein Gjoen ####@####.####
Date:
26 Mar 2002 22:57:53 -0000
Message-Id: <3C990F8A.2080603@mail.nyx.net>
Sorry about the massive delay; these days I have a rather long
turnaround time for replies. I had hoped someone else would do
this for me but I realise we are short on volunteers.
David Merrill wrote:
> Thanks for doing this.
>
> Meta-question: Is this how you propose we organize our cvs collection
> as well? Your proposal mingles production and reader viewpoints.
This LFH is intended for how files are organised on the disks
at the readers. I am not proposing a massive rearrangement of
how it is organised at the LDP sites since I don't even know
the details on how it is done today.
> On Sun, Feb 10, 2002 at 07:21:13PM +0100, Stein Gjoen wrote:
>
>>LDP Filesystem Hierarchy
>>Version 0.01 2001-0210
This has been ramped up a few notches already and another one
is due soon.
>>Abstract:
>> This document defines the various directories that make up
>> the hierarchy of an integrated LDP documentation tree. It
>> is designed to function under the FHS, FSSTND as well as
>> standalone setups.
>>
>>
>>Background:
>>The Linux Documentation Project has accumulated a huge number
>>of documents of various kinds, formats and in numerous
>>languages. Up to now integration by inter document linking has
>>not been possible due to lack of standard layout. As new tools
>>are about to come into use this deficiency is becoming more
>>pronounced. This document shall define file locations making
>>it possible to integrate the LDP documents.
>>
>>Applications:
>>
>>Interlinking:
>>making it possible to link from one document
>>to another, certain it will work in all installations. This
>>also makes it possible to collect and link document by topics.
>>
>
> Yes, this is crucial.
Somewhat belatedly I realise such interlinking might very well
have serious implications on how it is stored at the LDP sites
(and mirrors) in order to work, at least without massive cgi
scripting behind the scenes.
> A more difficult problem is... what if the linked document isn't
> included in the collection? We can't count on all distributions
> containing a complete copy.
True, and that will be a problem, on the same level as the
existing and numerous external links we use. My own Multi Disk
HOWTO has 200 external links alone.
> And what about when those documents are being read not through the
> filesystem, but through a help browser that uses ScrollKeeper?
Again I don't know enough details to know.
I would suggest to keep the file structure and some minimum
files ( 00-INDEX and index.html) to tell the users what should
have been there and how to get them at the LDP. Optionally
and more useful if the person generating a collection chose not
to include, say, RFCs, a note of that should be in the RFC
directory. End user functionality is my main concern here.
> And then there's XLink, the XML way of doing interdocument linking. We
> will probably start seeing it show up as we move into XML. It
> certainly offers some great advantages we should take advantage of
> once we have the more basic infrastructure issues resolved.
Another tool I don't know enough about; I will need inputs
and suggestions from those knowledgable on these topics.
>>Distributions:
>>currently distributions often use out-of-date
>>LDP collections. By defining a hierarchy it will be possible
>>to make a tool that collects the LDP works, making a snapshot
>>that is guaranteed to work. The same tool will also make it
>>more attractive for, say, magazines to bundle an LDP snapshot
>>on their bundled CD ROM.
>>
>
> Yep. We should be giving out Linux Business Cards with the LDP
> collection on them at trade shows. That's something worth using LDP
> funds for I think.
And LDP business card would probably be excellent profiling
of the LDP.
>>Customising:
>>this makes it possible (using the above tool)
>>to extract documents in a specific language or format that
>>suits the audience.
>
> Can you go into more detail? I need to understand at a low level to
> tell what all the effects will be.
I am planning to make a mock-up HTML-page to demonstrate.
possibly with some JavaScript, what I have in mind. We have
to make life simple for end user but equally important make
life simple for those generating a collection, be it for a
magazine CD ROM or someone working on a distribution.
A CD ROM published in, say, Japan, will not need documents
in, say, Italian, and so on. A tool to select what is needed
will be a bonus that lowers the threshold for inclusion on
various CDs.
>>Navigation:
>>each directory will have indexing files such
>>as 00-INDEX and index.html that aids navigation through the
>>tree of extensive document collection.
>
> Definitely with you on this one.
We need some serious manpower here, not just to write but
also translate and review.
>>Specifics:
>>
>>In the documentation directory
>>FHS: /usr/share/doc/
>>FSSTND: /usr/doc/
>>
>>FAQ Usenet News FAQs
>>HOWTO HOWTO directory
>>LDP the root of the LDP collection
>>RFC collection of internet RFCs
>>TR collection of WWW consortium documents
>>
>
> The LDP has a directory in both the FHS and the FSSTND?
The LDP is not mentioned explicitly but we would belong
in the documentation directory which is specified. If
you want a different position in the big hierarchy you
would need very good arguments; the FHS group is very
hard to persuade.
>>Some distributions already include FAQ and RFC in which
>>case these are left untouched. Otherwise these are all
>>links to LDP.
>>
>>For legacy reasons as well as recognition the HOWTO directory
>>is a link to a sub directory in LDP. Note that not all HOWTOs
>>are part of LDP, the issue of aggregation must be considered
>>with care.
>>
>>
>>LDP:
>>+ aux Auxilliary non-LDP documents
>>|\
>>|+ FAQ Note: check copyright for all auxilliary
>>|+ RFC documents. Also these may be available as
>>|+ TR plain text as well as HTML.
>>|+ magazines
>>| \
>>| + GNU announcements, news
>>| + LWN Linux Weekly News
>>| + (other magazines)
>>
>
>>| + misc single issue articles etc.
>>|
>>+ HOWTO English language HOWTOs
>>|\
>>|+ HTML
>>|+ PDF
>>|+ PostScript
>>|+ SGML
>>|+ txt
>>|
>>+ de Non English documents with sub directories
>>+ jp as for English language HOWTOs
>>+ no
>>|
>>+ images various logos and images used for web pages
>>+ notes application notes (proposed)
>>+ software misc software used in LDP
>>
>
> On the reader's computer or ours? We shouldn't be placing software
> here, but in a ldp-utils package or as separate packages, on a user's
> machine.
On the readers disk, yes. Software here is only relevant for
standalone disks such as the business card CD. I was thinking
of both browsers and also writers tools (LinuxDoc, DocBook etc).
Of course, a seperate ldp-utils is also a good alternative idea.
> Where are the Guides and Quick References?
Coming up in the next revision.
> FYI, the LinuxChix group has written a set of (I think) four
> Introduction To... documents that are about fundamental concepts in
> backup and restore, security, and a couple of others. They'll be
> coming into the LDP once I talk to Greg about how it will impact him.
>
> So that will make a new category, 'Intro'.
We need all categories enumerated so a simple glance at
the directory structure would tell the reader where to
find the various kinds of documents.
>>+ topics documents that link to collection of HOWTOs
>>
>
> Shouldn't the /LDP directory be a mirror of our website? Then we don't
> need ths "topics" directory, since topical organization is handled via
> html files in /LDP.
It would be an advantage if we could do a simple mirror of
as much of the LDP site as possible. I was thinking of
topical organisation by HTML files (as well as plain text files)
such as broad topics like networking, hardware, setup etc,
with some overlap. Do we really have this today at the LDP
site?
>>+ wiki snapshot of wiki pages
>>
>
> BTW I was planning on putting each mirrored "project" into its own
> directory (e.g., /jargon, /wikipedia).
Sounds good. Perhaps we should add these under
a /project directory?
>>In the software directory there can be software used for
>>creating LDP works but also to read documentation and for
>>updating. Support for multiple OS platforms is useful but
>>should also be selectable.
As noted above this could be offloaded to a separate
package. It is not be entirely FHS compliant to have
executables in the documentation directory and indeed
the noexec mount option might be used here.
>>---------------------------------------
>>
>>OK, that is first draft of what is going to be a long process.
>>Since this will make bundling in packages part of our work we
>>should consider this very carefully. From what I can see making
>>this standard and making the packaging tool is the only way we
>>can guarantee linking between documents will work equally well
>>across all Linux distributions.
>
> Are we equally concerned with linking to documents completely outside
> the LDP? I think we should be, but that's going to take some serious
> work. It's a big problem and afaik nobody's solved it yet.
Link rot is epidemic; any suggestions you have would be welcome.
Advanced use of the Wayback-machine could be an ugly yet somewhat
workable hack.
> ScrollKeeper is a great program with lots of potential, but it
> doesn't help in the case you cite where a reader is browsing docs in
> her directory tree.
The directory tree could be used by a script that fed
ScrollKeeper with input.
> ScrollServer could fill that niche, but it's a long way from
> production ready, and I haven't touched it in a couple of months. I'm
> working on all aspects of the system at once, going back and forth
> among them, and right now I'm working on texi2db.
This LFH is also some way off being production quality but I
hope that by keeping this in mind we could keep all involved
happy.
>>It should be sufficiently self contained that it could be
>> - browsable using a HTML browser
>> - practical to copy across to a documentation directory
>> - usable to read using 'cd', 'ls' and 'more'
>> - self starting under DOS/Win/NT, even Mac
>> - bootable with a tiny free standing Linux distro just to
>> make it possible to give anyone a taste of Linux and LDP.
>>
>>Done right it should also increase our visibility and also
>>usefulness significantly.
>
> It should, yes.
Time and manpower is a weak point but I realise I have
to do quiet a bit myself to get this off the ground. I
hope my next reply will be speedier than it has been
recently.
Regards,
Stein
