Re: [tale: Re: Notes for DDP writers]
On Sun, 14 Feb 1999 09:52:45 +0200, Tapio Lehtonen <tale@iki.fi> said:
> On Sun, Feb 14, 1999 at 12:30:46AM -0500, Adam Di Carlo wrote:
>> PostScript is inherently resolution dependant and non-portable. I
>> suggest PDF, which is smaller and more likely to be viewable by
>> all.
> I did not know there was a tool in Debian GNU/Linux to produce
> PDF. I agree PDF is preferable to PS in this case.
debiandoc2latex2e, then pdflatex. Works pretty well; should support
PDF linking but currently doesn't. I'll raise a bug against
debiandoc-sgml about this.
>> Yes, I agree with you, but I would point out that automatic
>> conversion to docbook is a problem of SMGL transformation; there's
>> little a writer could do to make it easier or harder.
> The write should use the same tag for the same purpose consistently,
> then it is possible to automatically convert it to the corresponding
> Docbook or whatever tag. Otherwise a person has to do this
> conversion manually. I'm not claiming that it is possible to do the
> conversion fully automatically, but it helps to have at least some
> parts of it done for you.
That's true. I'd like to point out that we already have a linuxdoc ->
docbook converter, from the Linuxdoc maintainer; this ships with
sgmltools v2.x.
>> I'm sorry, but I'm going to have to *strenuously object* to the
>> mere existance of these manuals.
> I think I misunderstand the above statement. It seems to say, that
> you would like to remove the Debian Documentation Project manuals?
No, not at all. I object to their current scope.
>> For one, 90% of the contents of these manuals are Linux-specific
>> and not Debian specific. As such, to undertake these manuals as
>> *Debian* manuals is contrary to the ideals of the Free Software
>> Movement -- sharing and the greatest benefit to all. I happen to
>> know a *number* of quality Linux documentation folks who have taken
>> issue (quietly) with the existance of these manuals.
>>
>> I really think this is important. Debian manuals should be about
>> Debian. Linux manuals should be worked on by groups which are not
>> just restricted to the Debian group.
> Well, at least the Debian Documentation Project manuals are supposed
> to be Debian manuals. I agree that most of the things in them would
> apply to other Unix systems also, but I do not see any problem in
> this (and if it is a problem, the only way for us to solve it would
> be to start developing Debian on a tangent to the other Unixes, to
> eventually reach a point where anything that works in Debian is sure
> not to work anywhere else. But I digress).
My argument is that the fundamental principle of the Free Software
Movement is to maximize the benefit of software and documentation; to
help eliminate the segmentation and balkanization of software and
documentation which is created by the proprietary software world.
Insofar as we are writing pure Linux documentation, and insofar as
this is a Debian effort, we are not sharing extensively enough. Linux
documentation should be written in the context of the Linux community.
Exclusively Debian documentation will have to be written here.
Don't get me wrong: I'm not saying that we shouldn't be working to
improve Linux documentation. But to achieve this goal, I would like
to see us work to revive the LDP. I think we need to be working with
the Linux community and with the LDP folks rather than working in
isolation.
So to restate, I don't object to us writing Linux documentation; I
object to us writing it in isolation from the greater Linux community.
Furthermore, I think we've bitten off more than we can chew. The
current manuals suffer from the dual problems of being Linux-oriented,
*and* being x86-centric (a serious problem, shared by the LDP stuff).
Let me take an example, Chapter 3 of the Debian Tutorial:
3. Getting started
Debian-specific, fine.
3.1. A multiuser, multitasking operating system
Debian-specific, fine.
3.2. Logging in
GNU/Linux oriented
3.3. Keys
3.4. Command history and editing the command line
GNU/Linux (well, bash) oriented
3.5. Logging in as root
GNU/Linux oriented
3.6. Virtual consoles
3.7. Shutting down
GNU/Linux oriented, x86-centric (talks about Ctrl-Alt-Del).
A little more, overviewing chapters now:
4. The Basics
GNU/Linux oriented
5. Reading documentation and getting help
Somewhat Debian oriented; probably a good example of what needs to be
in a Debian-specific manual. My objection here is that it makes no
mention of the LDP at all.
I really don't wanna pick on Havoc; I think Havoc has voiced that he
agrees in principle that his efforts should be merged with the LDP.
If I read you correctly, Havoc, assuming we did some work to open a
liason with the LDP, and assuming we can work out a bazaar-style
development methodology (i.e., giving you CVS access to the SGML
sources, having an open mailing list), you would gladly split out the
Linux-specific stuff and back-port that to the appropriate LDP
manuals. Which is exactly what I'm asking for.
Just so I'm not singling out Havoc, let's compare Tapio's "Debian
GNU/Linux System Administrator's Manual" (SAM) with Lars Wirzenius'
"Linux System Administrators' Guide" (SAG). Looking at
<URL:http://liw.iki.fi/liw/linux/sag/>, it would seem that the SAG is
actively under development (0.6.1 released on 8 Feb 1999).
Reading the SAM from my CVS copy, the first chapter actually filled in
would seem to be "12 Backup and Restore":
12 Backup and Restore
12.1 Why backup?
12.2 What to backup?
12.3 Backup devices and media
12.4 Backup methods and software
12.5 Types of backup
Compare the SAG at http://metalab.unc.edu/mdw/LDP/sag/node96.html:
On the importance of being backed up
Selecting the backup medium
Selecting the backup tool
Simple backups
Making backups with tar
Restoring files with tar
Multilevel backups
What to back up
Compressed backups
This email is long enough; I'll write another email to this group
discussing more about why now is the time to start LDP integration.
The path will be long and hard, but it's worth it.
> When the Debian manuals start talking specific things and examples,
> they are very Debian centered. If we were to remove from the manuals
> the general parts that apply to a generic Unix system, we would get
> a short and consice manual, but it would probably not be very
> readable or even useful for beginners.
Look, this is the web we're talking about (for the most part). We can
have very rich cross-linking and cross-fertilization. URLs can be
fragile, but that can be solved with the adoption of some sort of URN
scheme (cf www.purl.org).
> In my opinion, the above is an unnecessary vitriolic comment.
Perhaps. If I make polemic statements at times, it is only because I
care so much. I think my commitments to this group, the the
Developer's Reference, and most recently, to the Install Manual (yes,
I'm in communication with the LDP Install Manual maintainer) show that
my committment is real.
--
.....Adam Di Carlo....adam@onShore.com.....<URL:http://www.onShore.com/>
Reply to: