Why and how to work with the LDP (was Re: Notes for DDP writers)
On Sun, 14 Feb 1999 02:50:23 -0600 (CST), Havoc Pennington <hp@Mcs.Net> said:
> I am saddened to hear that people are upset about it. I did contact
> the LDP when I started on the tutorial, exchanged some mail with the
> author of the LDP User's Guide, etc. I've also talked to RMS about
> it. Basically made every effort to work with non-Debian people.
Yes, I'm sure you did. I know your intentions are there. I don't
think the fault is yours. What I'd like to do is build up momentum
and pistol-whip the right people at the LDP.
When I suggest we work at the LDP, I don't mean to cast a blind eye to
their faults. In short, here's a brief catalog of them:
* no standard, free license (a biggie!)
* cathedral'ish and uncoordinate development efforts
(they need a centralized CVS server)
* no standard documentation format (they tend to use TeX; ew!)
* x86-centricity (a problem we share)
> I would have no objection to adding #ifdef type things to the manual
> with Red Hat specifics, or some other approach. But no one is
> volunteering to do the work. (Perhaps that's why they're sulking,
> rather than contacting me.)
We need to cultivate a broader audience of potential contributors. We
need the backing of the FSF, and the free software community at large.
We need all of the above fixed and announcements made to c.o.l.a when
we're ready to start.
So long as we're Debian specific, none of that can happen.
> (More would change in a non-Debian tutorial than you might think;
> many of the examples would break and be impossible to do "portably";
> all the political stuff at the beginning, which I consider
> important, would have to go; config files are in totally different
> places; package management is totally different. It really is a
> _Debian_ Tutorial, it is not a Linux or Unix tutorial that
> gratuitously says Debian on it. And I think the Debian specificity
> is a significant value add for the newbie anyway, though the rest of
> us could just as well read a generic Unix book from several years
> ago.)
I would alternatively suggest a thin layer of Debian specific, with
rich cross-referencing into the manuals. Alternatively, separate
Debian advocacy into a separate document, and have a way to
conditionalize the manuals so that they can show/mask or else
represent distribution-specific items in a clear way.
> Anyway, it would be fine to move the tutorial to the LDP server too,
> if they want, for symbolic reasons. But again: someone has to do the
> work.
Oh yeah, I know. But, Havoc, I don't want you to do all the work!
I'm just hoping to utilize proven free software methodologies and to
enable wider community participation in these documentation problems.
> The one niggling misgiving I have is that IIRC the "official" LDP
> license is non-free and in my view totally unacceptable for Debian;
> fortunately none of the docs seem to actually use it. If the User's
> Guide had, for example, I would have been forced to start from
> scratch rather than use it.
Absolutely; this is an absolute pre-requisite.
> Adam, I would appreciate you forwarding this message or conveying
> the gist of my comments to any of the people who have expressed
> displeasure with the Tutorial's existence, and I would encourage
> them to contact this list or me personally to talk about ways to get
> the advantages I've mentioned of distribution-specificity while also
> working together on the generic parts.
Havoc, no one's ever singled you out. The System Administrator's
Manual was singled out by Lars, the SAG maintainer.
Lars has talked to me in depth about his disappointment in this group,
and also about how he want's to re-invigorate the LDP. I think, if we
can bring the olive branch to Lars, we can position ourselves uniquely
to help implement solutions to all of the LDP problems above. We can
not only garner the wider attention and potential of the LDP, but also
make ourselves crucial to it, and put our stamp on it.
Let me re-iterate the problem list from above, with solutions
* no standard, free license (a biggie!)
Work out a DFSG standard license; ask all LDP authors to adhere to this.
* cathedral'ish and uncoordinate development efforts
(they need a centralized CVS server)
Help them organize a CVS server; hell, we could even offer
cvs.debian.org or some such for use, perhaps. We have experience in
working with this; I think our DDP CVS area, with it's combination of
SGML and Makefiles, is a robust, proven method to manage large amounts
of documentation.
* no standard documentation format (they tend to use TeX; ew!)
Lars has stated he wants to go with Docbook, to which I heartily
agree. Docbook and the docbook-stylesheets can be easily extended
with new elements, if needed.
* x86-centricity (a problem we share)
I think the techniques I use in the Install Manual need to be
assessed. Is it too complex to use SGML with marked sections? Is
there better facilities already provided by the richer Docbook DTD
which make the use of marked sections irrelevant? Do we want different
flavors of document (i.e., what I do in the Install Manual) per
platform, or just side-notes with platform specific information (i.e.,
one output document).
The same issues are raised by distribution-centric materials.
--
.....Adam Di Carlo....adam@onShore.com.....<URL:http://www.onShore.com/>
Reply to: