707 lines
29 KiB
HTML
707 lines
29 KiB
HTML
<!-- MHonArc v2.5.0b2 -->
|
|
<!--X-Subject: Re: Requiring use of DocBook; LinuxDoc -->
|
|
<!--X-From-R13: Rnivq Znjlre <qnirNynsa.bet> -->
|
|
<!--X-Date: Sat, 24 Jun 2000 12:12:34 -0400 (EDT) -->
|
|
<!--X-Message-Id: 20000624090608.A633@localhost -->
|
|
<!--X-Content-Type: multipart/mixed -->
|
|
<!--X-Head-End-->
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML//EN">
|
|
<html>
|
|
<head>
|
|
<title>Re: Requiring use of DocBook; LinuxDoc</title>
|
|
<link rev="made" href="mailto:dave@lafn.org">
|
|
</head>
|
|
<body>
|
|
<!--X-Body-Begin-->
|
|
<!--X-User-Header-->
|
|
<!--X-User-Header-End-->
|
|
<!--X-TopPNI-->
|
|
<hr>
|
|
[<a href="msg02995.html">Date Prev</a>][<a href="msg02997.html">Date Next</a>][<a href="msg03039.html">Thread Prev</a>][<a href="msg02997.html">Thread Next</a>][<a href="maillist.html#02996">Date Index</a>][<a href="threads.html#02996">Thread Index</a>]
|
|
<!--X-TopPNI-End-->
|
|
<!--X-MsgBody-->
|
|
<!--X-Subject-Header-Begin-->
|
|
<h1>Re: Requiring use of DocBook; LinuxDoc</h1>
|
|
<hr>
|
|
<!--X-Subject-Header-End-->
|
|
<!--X-Head-of-Message-->
|
|
<ul>
|
|
<li><em>To</em>: <A HREF="mailto:ldp-discuss@lists.linuxdoc.org">ldp-discuss@lists.linuxdoc.org</A></li>
|
|
<li><em>Subject</em>: Re: Requiring use of DocBook; LinuxDoc</li>
|
|
<li><em>From</em>: David Lawyer <<A HREF="mailto:dave@lafn.org">dave@lafn.org</A>></li>
|
|
<li><em>Date</em>: Sat, 24 Jun 2000 09:06:09 -0700</li>
|
|
<li><em>Mail-followup-to</em>: ldp-discuss@lists.linuxdoc.org</li>
|
|
<li><em>Resent-date</em>: Sat, 24 Jun 2000 12:12:34 -0400 (EDT)</li>
|
|
<li><em>Resent-from</em>: <A HREF="mailto:ldp-discuss@lists.debian.org">ldp-discuss@lists.debian.org</A></li>
|
|
<li><em>Resent-message-id</em>: <VUuRfC.A.fsG.L1NV5@murphy></li>
|
|
<li><em>Resent-sender</em>: <A HREF="mailto:ldp-discuss-request@lists.debian.org">ldp-discuss-request@lists.debian.org</A></li>
|
|
<li><em>User-agent</em>: Mutt/1.0pre3i</li>
|
|
</ul>
|
|
<!--X-Head-of-Message-End-->
|
|
<!--X-Head-Body-Sep-Begin-->
|
|
<hr>
|
|
<!--X-Head-Body-Sep-End-->
|
|
<!--X-Body-of-Message-->
|
|
<pre>
|
|
Attached find the thread on this topic. It's from a "quasi-private"
|
|
email discussion. The posts (as attachments) are:
|
|
|
|
0. David Lawyer: start of thread (not attached since already sent)
|
|
1. (Message you are now reading)
|
|
2. Poet Joshua/Drake: rebuttal to 0 above.
|
|
3. David Lawyer: rejoinder to 2 above.
|
|
4. Gregory Leblanc: rebuttal to 0 and 3 above.
|
|
5. David Lawyer: rejoinder to 4 above.
|
|
|
|
David Lawyer
|
|
</pre>
|
|
<blockquote><small>--- <i>Begin Message</i> ---</small>
|
|
<ul>
|
|
<li><em>To</em>: David Lawyer <<A HREF="mailto:dave@lafn.org">dave@lafn.org</A>></li>
|
|
<li><em>Subject</em>: Re: Requiring use of DocBook; LinuxDoc</li>
|
|
<li><em>From</em>: Poet/Joshua Drake <<A HREF="mailto:poet@linuxports.com">poet@linuxports.com</A>></li>
|
|
<li><em>Date</em>: Fri, 23 Jun 2000 06:06:33 -0700 (PDT)</li>
|
|
<li><em>Cc</em>: Mark Komarinski <<A HREF="mailto:markk@cgipc.com">markk@cgipc.com</A>>, Guylhem Aznar <<A HREF="mailto:guylhemj@metalab.unc.edu">guylhemj@metalab.unc.edu</A>>, Greg Ferguson <<A HREF="mailto:gferg@hoop.timonium.sgi.com">gferg@hoop.timonium.sgi.com</A>>, Gregory Leblanc <<A HREF="mailto:GLeblanc@cu-portland.edu">GLeblanc@cu-portland.edu</A>>, Poet/Joshua Drake <<A HREF="mailto:poet@linuxports.com">poet@linuxports.com</A>>, Taketoshi Sano <<A HREF="mailto:kgh12351@nifty.ne.jp">kgh12351@nifty.ne.jp</A>></li>
|
|
<li><em>Envelope-to</em>: root@localhost</li>
|
|
<li><em>In-reply-to</em>: <<a href="msg02990.html">20000622173003.A559@localhost</a>></li>
|
|
<li><em>Resent-date</em>: Sat, 24 Jun 2000 00:55:36 -0700</li>
|
|
<li><em>Resent-from</em>: <A HREF="mailto:dave@lafn.org">dave@lafn.org</A></li>
|
|
<li><em>Resent-message-id</em>: <E135kmu-00005n-00@davespc></li>
|
|
<li><em>Resent-sender</em>: <A HREF="mailto:ldp-discuss-request@lists.debian.org">ldp-discuss-request@lists.debian.org</A></li>
|
|
<li><em>Resent-to</em>: <A HREF="mailto:ldp-discuss@lists.linuxdoc.org">ldp-discuss@lists.linuxdoc.org</A></li>
|
|
</ul>
|
|
<pre>
|
|
<CITE>If the above by Mark K is correct, I think it needs to be changed back
|
|
<CITE>to allowing LinuxDoc for new authors. We want to make it easy for new
|
|
<CITE>authors to get started and maintain their documents. One of our major
|
|
<CITE>tasks is to get new authors to create new HOWTOs and update outdated
|
|
<CITE>ones. To do this we need to make things as simple as possible. In my
|
|
<CITE>case, I almost decided not to write a HOWTO due to the requirement of
|
|
<CITE>having to use LinuxDoc. But if I were required to use DocBook I might
|
|
<CITE>have refused, even if someone was willing to covert my first
|
|
<CITE>submission to DocBook.
|
|
|
|
|
|
I disagree completely, we should not change the LinuxDoc rule. DocBook is
|
|
not difficult in any way if you use it like LinuxDoc. What I mean is, yes
|
|
DocBook can be a total bear if you try and do a much of nifty crap with it
|
|
but if you keep it simple it is no more difficult than LinuxDoc. In fact
|
|
it is no harder than HTML.
|
|
|
|
We can not continue to change every item on the opinions of 1
|
|
individual. I appreciate the gentlemens frustration but I believe it is
|
|
imperative that we continue pushing DocBook, aggressively. All the other
|
|
major Documentation (outside of Debian) have switched to DocBook.
|
|
|
|
Joshua Drake
|
|
|
|
|
|
|
|
|
|
|
|
--
|
|
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
|
|
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
|
|
|
|
|
|
</pre>
|
|
<small>--- <i>End Message</i> ---</small></blockquote>
|
|
<blockquote><small>--- <i>Begin Message</i> ---</small>
|
|
<ul>
|
|
<li><em>To</em>: Poet/Joshua Drake <<A HREF="mailto:poet@linuxports.com">poet@linuxports.com</A>></li>
|
|
<li><em>Subject</em>: Re: Requiring use of DocBook; LinuxDoc</li>
|
|
<li><em>From</em>: David Lawyer <dave></li>
|
|
<li><em>Date</em>: Fri, 23 Jun 2000 14:40:54 -0700</li>
|
|
<li><em>Cc</em>: David Lawyer <<A HREF="mailto:dave@lafn.org">dave@lafn.org</A>>, Mark Komarinski <<A HREF="mailto:markk@cgipc.com">markk@cgipc.com</A>>,Guylhem Aznar <<A HREF="mailto:guylhem@metalab.unc.edu">guylhem@metalab.unc.edu</A>>,Greg Ferguson <<A HREF="mailto:gferg@hoop.timonium.sgi.com">gferg@hoop.timonium.sgi.com</A>>,Gregory Leblanc <<A HREF="mailto:GLeblanc@cu-portland.edu">GLeblanc@cu-portland.edu</A>>,Taketoshi Sano <<A HREF="mailto:kgh12351@nifty.ne.jp">kgh12351@nifty.ne.jp</A>>,Stein Gjoen <<A HREF="mailto:sgjoen@mail.nyx.net">sgjoen@mail.nyx.net</A>></li>
|
|
<li><em>In-reply-to</em>: <<a href="msg02993.html">Pine.LNX.4.21.0006230601470.15451-100000@crazypenguins.commandprompt.com</a>></li>
|
|
<li><em>References</em>: <<a href="msg02990.html">20000622173003.A559@localhost</a>> <<a href="msg02993.html">Pine.LNX.4.21.0006230601470.15451-100000@crazypenguins.commandprompt.com</a>></li>
|
|
<li><em>User-agent</em>: Mutt/1.0pre3i</li>
|
|
</ul>
|
|
<pre>
|
|
[ Regarding David Lawyer's proposal to continue to allow use of LinuxDoc
|
|
for new authors]
|
|
On Fri, Jun 23, 2000 at 06:06:33AM -0700, Poet/Joshua Drake wrote:
|
|
>
|
|
> I disagree completely, we should not change the LinuxDoc rule.
|
|
|
|
I never saw any "rule" posted that we would no longer accept LinuxDoc
|
|
from new authors.
|
|
|
|
> DocBook is not difficult in any way if you use it like LinuxDoc.
|
|
> What I mean is, yes DocBook can be a total bear if you try and do a
|
|
> much of nifty crap with it but if you keep it simple it is no more
|
|
> difficult than LinuxDoc.
|
|
|
|
Not so. See my examples at the end of this message.
|
|
|
|
> In fact it is no harder than HTML.
|
|
|
|
Possilbly true but HTML is significantly more difficult than LinuxDoc.
|
|
|
|
> [snip] but I believe it is imperative that we continue pushing
|
|
> DocBook, aggressively. All the other major Documentation (outside of
|
|
> Debian) have switched to DocBook.
|
|
|
|
We have special needs in that we recruit rank amateurs who want the
|
|
writing format to be as simple as possible. Anyway, I'm not objecting
|
|
to people using DocBook that want to do so (including "rank
|
|
amateurs"). Thus while we too have already accepted DocBook I think
|
|
we should continue to accept LinuxDoc from anyone.
|
|
|
|
David Lawyer
|
|
#########################################################################
|
|
|
|
Comparison of DocBook to LinuxDoc (short).
|
|
by David Lawyer, June 23, 2000
|
|
|
|
Using DocBook instead of LinuxDoc requires many more tags and the tags
|
|
tend to be longer. The tag clutter makes DocBook harder to read.
|
|
Thus DocBook is not nearly as easy to do by hand (with an editor that
|
|
doesn't support it) as LinuxDoc.
|
|
|
|
LinuxDoc is quoted with LD; DocBook with DB.
|
|
-------------2---3--------- => DocBook has: 2 times as many tags;
|
|
3 times as many tag characters.
|
|
|
|
|
|
Example 1-------------------1.5---2------------------------------------
|
|
|
|
DB <sect>
|
|
DB <title>Introduction</title>
|
|
|
|
LD <sect>Introduction
|
|
LD <p>
|
|
|
|
Example 2--------------------2---3------------------------------------
|
|
|
|
DB <indexterm>
|
|
DB <primary>disk!introduction</primary>
|
|
DB </indexterm>
|
|
|
|
LD <nidx>disk!introduction</nidx>
|
|
|
|
Example 3--------------------infinite-------------------------------------
|
|
|
|
DB <para>
|
|
DB This is the text of a paragraph. LinuxDoc needs no tags for it.
|
|
DB </para>
|
|
|
|
LD This is the text of a paragraph. LinuxDoc needs no tags for it.
|
|
|
|
Example 4-------------1+--4-----In docB "release" must be typed twice------
|
|
|
|
DB <emphasis>release</emphasis> release.
|
|
|
|
LD <em>release</em>.
|
|
|
|
Example 5--------------3---3----You can't easily read the docB list---------
|
|
|
|
DB <ItemizedList>
|
|
DB <ListItem>
|
|
DB
|
|
DB <Para>
|
|
DB Use the "isapnp" program
|
|
DB </Para>
|
|
DB </ListItem>
|
|
DB <ListItem>
|
|
DB
|
|
DB <Para>
|
|
DB Have a PnP BIOS do the configuring
|
|
DB </Para>
|
|
DB </ListItem>
|
|
DB <ListItem>
|
|
DB
|
|
DB <Para>
|
|
DB Patch the kernel to create a PnP Linux (not currently available)
|
|
DB </Para>
|
|
DB </ListItem>
|
|
DB
|
|
DB </ItemizedList>
|
|
|
|
LD <itemize>
|
|
LD <item> Use the "isapnp" program
|
|
LD <item> Have a PnP BIOS do the configuring
|
|
LD <item> Patch the kernel to create a PnP Linux (not currently available)
|
|
LD </itemize>
|
|
</pre>
|
|
<small>--- <i>End Message</i> ---</small></blockquote>
|
|
<blockquote><small>--- <i>Begin Message</i> ---</small>
|
|
<ul>
|
|
<li><em>To</em>: "'David Lawyer'" <<A HREF="mailto:dave@lafn.org">dave@lafn.org</A>>, Poet/Joshua Drake <<A HREF="mailto:poet@linuxports.com">poet@linuxports.com</A>></li>
|
|
<li><em>Subject</em>: RE: Requiring use of DocBook; LinuxDoc</li>
|
|
<li><em>From</em>: Gregory Leblanc <<A HREF="mailto:GLeblanc@cu-portland.edu">GLeblanc@cu-portland.edu</A>></li>
|
|
<li><em>Date</em>: Fri, 23 Jun 2000 17:15:20 -0700</li>
|
|
<li><em>Cc</em>: Mark Komarinski <<A HREF="mailto:markk@cgipc.com">markk@cgipc.com</A>>, Guylhem Aznar <<A HREF="mailto:guylhem@metalab.unc.edu">guylhem@metalab.unc.edu</A>>, Greg Ferguson <<A HREF="mailto:gferg@hoop.timonium.sgi.com">gferg@hoop.timonium.sgi.com</A>>, Taketoshi Sano <<A HREF="mailto:kgh12351@nifty.ne.jp">kgh12351@nifty.ne.jp</A>>, Stein Gjoen <<A HREF="mailto:sgjoen@mail.nyx.net">sgjoen@mail.nyx.net</A>></li>
|
|
<li><em>Envelope-to</em>: root@localhost</li>
|
|
<li><em>Resent-date</em>: Sat, 24 Jun 2000 00:25:06 -0700</li>
|
|
<li><em>Resent-from</em>: <A HREF="mailto:dave@lafn.org">dave@lafn.org</A></li>
|
|
<li><em>Resent-message-id</em>: <E135kJO-00004a-00@davespc></li>
|
|
<li><em>Resent-sender</em>: <A HREF="mailto:ldp-discuss-request@lists.debian.org">ldp-discuss-request@lists.debian.org</A></li>
|
|
<li><em>Resent-to</em>: <A HREF="mailto:ldp-discuss@lists.linuxdoc.org">ldp-discuss@lists.linuxdoc.org</A></li>
|
|
</ul>
|
|
<pre>
|
|
> -----Original Message-----
|
|
> From: David Lawyer [<A HREF="mailto:dave@lafn.org">mailto:dave@lafn.org</A>]
|
|
> Sent: Friday, June 23, 2000 2:41 PM
|
|
> To: Poet/Joshua Drake
|
|
> Cc: David Lawyer; Mark Komarinski; Guylhem Aznar; Greg
|
|
> Ferguson; Gregory
|
|
> Leblanc; Taketoshi Sano; Stein Gjoen
|
|
> Subject: Re: Requiring use of DocBook; LinuxDoc
|
|
>
|
|
> [ Regarding David Lawyer's proposal to continue to allow use
|
|
> of LinuxDoc
|
|
> for new authors]
|
|
> On Fri, Jun 23, 2000 at 06:06:33AM -0700, Poet/Joshua Drake wrote:
|
|
> >
|
|
> > I disagree completely, we should not change the LinuxDoc rule.
|
|
> > DocBook is not difficult in any way if you use it like LinuxDoc.
|
|
> > What I mean is, yes DocBook can be a total bear if you try and do a
|
|
> > much of nifty crap with it but if you keep it simple it is no more
|
|
> > difficult than LinuxDoc.
|
|
>
|
|
> Not so. See my examples at the end of this message.
|
|
|
|
I disagree. There are more tags required, but that does not make it
|
|
dificult.
|
|
|
|
> > In fact it is no harder than HTML.
|
|
>
|
|
> Possilbly true but HTML is significantly more difficult than LinuxDoc.
|
|
|
|
Hogwash. I'd say that once you know what a markup language is, none of them
|
|
are any more dificult than any other.
|
|
|
|
> > [snip] but I believe it is imperative that we continue pushing
|
|
> > DocBook, aggressively. All the other major Documentation (outside of
|
|
> > Debian) have switched to DocBook.
|
|
>
|
|
> We have special needs in that we recruit rank amateurs who want the
|
|
> writing format to be as simple as possible. Anyway, I'm not objecting
|
|
> to people using DocBook that want to do so (including "rank
|
|
> amateurs"). Thus while we too have already accepted DocBook I think
|
|
> we should continue to accept LinuxDoc from anyone.
|
|
|
|
I don't. Linuxdoc is NOT easier to work with, and it's also being phased
|
|
out just about every doc project in favor of DocBook. The DocBook tools are
|
|
under much more significant development than the Linuxdoc tools (no offense,
|
|
Sano), and DocBook itself is still being developed and maintained by
|
|
professionals in the field of technical documentation.
|
|
|
|
> David Lawyer
|
|
> ##############################################################
|
|
> ###########
|
|
>
|
|
> Comparison of DocBook to LinuxDoc (short).
|
|
> by David Lawyer, June 23, 2000
|
|
>
|
|
> Using DocBook instead of LinuxDoc requires many more tags and the tags
|
|
> tend to be longer. The tag clutter makes DocBook harder to read.
|
|
> Thus DocBook is not nearly as easy to do by hand (with an editor that
|
|
> doesn't support it) as LinuxDoc.
|
|
>
|
|
> LinuxDoc is quoted with LD; DocBook with DB.
|
|
> -------------2---3--------- => DocBook has: 2 times as many tags;
|
|
> 3 times as many tag characters.
|
|
>
|
|
>
|
|
> Example
|
|
> 1-------------------1.5---2------------------------------------
|
|
>
|
|
> DB <sect>
|
|
> DB <title>Introduction</title>
|
|
>
|
|
> LD <sect>Introduction
|
|
> LD <p>
|
|
|
|
Looks good to me, I can put in a title rather than just sticking out there,
|
|
and having no idea that that's a title rather than something else.
|
|
|
|
> Example 2--------------------2---3------------------------------------
|
|
>
|
|
> DB <indexterm>
|
|
> DB <primary>disk!introduction</primary>
|
|
> DB </indexterm>
|
|
>
|
|
> LD <nidx>disk!introduction</nidx>
|
|
|
|
What on EARTH does "nidx" mean? At least the DocBook tags are meaningful
|
|
here.
|
|
|
|
> Example
|
|
> 3--------------------infinite-------------------------------------
|
|
>
|
|
> DB <para>
|
|
> DB This is the text of a paragraph. LinuxDoc needs no tags for it.
|
|
> DB </para>
|
|
>
|
|
> LD This is the text of a paragraph. LinuxDoc needs no tags for it.
|
|
|
|
But then how does it know when it needs a new paragraph? Does it keep
|
|
formatting the way that you have it in the source document?
|
|
|
|
> Example 4-------------1+--4-----In docB "release" must be
|
|
> typed twice------
|
|
>
|
|
> DB <emphasis>release</emphasis> release.
|
|
>
|
|
> LD <em>release</em>.
|
|
|
|
So, write a tiny macro to expand <em> and </em> to <emphasis> and
|
|
</emphasis>, respectively. Sounds like very little effort to get to a much
|
|
more complete markup language to me.
|
|
|
|
> Example 5--------------3---3----You can't easily read the
|
|
> docB list---------
|
|
>
|
|
> DB <ItemizedList>
|
|
> DB <ListItem>
|
|
> DB
|
|
> DB <Para>
|
|
> DB Use the "isapnp" program
|
|
> DB </Para>
|
|
> DB </ListItem>
|
|
> DB <ListItem>
|
|
> DB
|
|
> DB <Para>
|
|
> DB Have a PnP BIOS do the configuring
|
|
> DB </Para>
|
|
> DB </ListItem>
|
|
> DB <ListItem>
|
|
> DB
|
|
> DB <Para>
|
|
> DB Patch the kernel to create a PnP Linux (not currently available)
|
|
> DB </Para>
|
|
> DB </ListItem>
|
|
> DB
|
|
> DB </ItemizedList>
|
|
>
|
|
> LD <itemize>
|
|
> LD <item> Use the "isapnp" program
|
|
> LD <item> Have a PnP BIOS do the configuring
|
|
> LD <item> Patch the kernel to create a PnP Linux (not
|
|
> currently available)
|
|
> LD </itemize>
|
|
|
|
80% of this is your formatting. Try:
|
|
|
|
|
|
<itemizedlist>
|
|
|
|
<listitem>
|
|
<para>Use the "isapnp" program</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Have a PnP BIOS do the configuring</para>
|
|
</listitem>
|
|
|
|
<listitem>
|
|
<para>Patch the kernel to create a PnP Linux (not currently
|
|
available)</para>
|
|
</lisitem>
|
|
|
|
</itemizedlist>
|
|
|
|
Actually, if Ferg took a look and formatted it, that would look even better.
|
|
There is a bit more typing, but you can turn off requiring end-tags in the
|
|
DTD, and shorten that a bunch. If you do that, I think that you (err, we?)
|
|
can get a tool that adds all of those end tags and jazz. Once again, I
|
|
really don't think that we need to accept LinuxDoc. I also don't think that
|
|
there will be a shortage of volunteers to markup documents until DocBook
|
|
becomes obsolete, which doesn't seem likely any time soon, since MAJOR
|
|
vendors are using it. (the Solaris man pages are in SGML, and they've hired
|
|
Norm Walsh). Since some people still think that we ought to accept
|
|
LinuxDoc, this discussion should not be limited to the select few here, but
|
|
really should be had on the discussion list, since that's what it's there
|
|
for.
|
|
Greg
|
|
|
|
|
|
--
|
|
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
|
|
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
|
|
|
|
|
|
</pre>
|
|
<small>--- <i>End Message</i> ---</small></blockquote>
|
|
<blockquote><small>--- <i>Begin Message</i> ---</small>
|
|
<ul>
|
|
<li><em>To</em>: Gregory Leblanc <<A HREF="mailto:GLeblanc@cu-portland.edu">GLeblanc@cu-portland.edu</A>></li>
|
|
<li><em>Subject</em>: Re: Requiring use of DocBook; LinuxDoc</li>
|
|
<li><em>From</em>: David Lawyer <dave></li>
|
|
<li><em>Date</em>: Sat, 24 Jun 2000 00:17:57 -0700</li>
|
|
<li><em>Cc</em>: 'David Lawyer' <<A HREF="mailto:dave@lafn.org">dave@lafn.org</A>>, Poet/Joshua Drake <<A HREF="mailto:poet@linuxports.com">poet@linuxports.com</A>>,Mark Komarinski <<A HREF="mailto:markk@cgipc.com">markk@cgipc.com</A>>,Guylhem Aznar <<A HREF="mailto:guylhem@metalab.unc.edu">guylhem@metalab.unc.edu</A>>,Greg Ferguson <<A HREF="mailto:gferg@hoop.timonium.sgi.com">gferg@hoop.timonium.sgi.com</A>>,Taketoshi Sano <<A HREF="mailto:kgh12351@nifty.ne.jp">kgh12351@nifty.ne.jp</A>>,Stein Gjoen <<A HREF="mailto:sgjoen@mail.nyx.net">sgjoen@mail.nyx.net</A>></li>
|
|
<li><em>In-reply-to</em>: <<a href="msg02992.html">A5F46F4ED18FD211ABEE00105AC6CF0701093825@email.cu-portland.edu</a>></li>
|
|
<li><em>References</em>: <<a href="msg02992.html">A5F46F4ED18FD211ABEE00105AC6CF0701093825@email.cu-portland.edu</a>></li>
|
|
<li><em>User-agent</em>: Mutt/1.0pre3i</li>
|
|
</ul>
|
|
<pre>
|
|
On Fri, Jun 23, 2000 at 05:15:20PM -0700, Gregory Leblanc wrote:
|
|
> > -----Original Message-----
|
|
> > From: David Lawyer [<A HREF="mailto:dave@lafn.org">mailto:dave@lafn.org</A>]
|
|
> > Sent: Friday, June 23, 2000 2:41 PM
|
|
> > To: Poet/Joshua Drake
|
|
> > Cc: David Lawyer; Mark Komarinski; Guylhem Aznar; Greg
|
|
> > Ferguson; Gregory
|
|
> > Leblanc; Taketoshi Sano; Stein Gjoen
|
|
> > Subject: Re: Requiring use of DocBook; LinuxDoc
|
|
> >
|
|
> > [ Regarding David Lawyer's proposal to continue to allow use
|
|
> > of LinuxDoc
|
|
> > for new authors]
|
|
> > On Fri, Jun 23, 2000 at 06:06:33AM -0700, Poet/Joshua Drake wrote:
|
|
> > >
|
|
> > > I disagree completely, we should not change the LinuxDoc rule.
|
|
> > > DocBook is not difficult in any way if you use it like LinuxDoc.
|
|
> > > What I mean is, yes DocBook can be a total bear if you try and do a
|
|
> > > much of nifty crap with it but if you keep it simple it is no more
|
|
> > > difficult than LinuxDoc.
|
|
> >
|
|
> > Not so. See my examples at the end of this message.
|
|
>
|
|
> I disagree. There are more tags required, but that does not make it
|
|
> difficult.
|
|
|
|
The poet said "no more difficult than LinuxDoc". Doesn't more tags
|
|
required make it more difficult if you're doing it manually?
|
|
|
|
>
|
|
> > > In fact it is no harder than HTML.
|
|
> >
|
|
> > Possibly true but HTML is significantly more difficult than LinuxDoc.
|
|
>
|
|
> Hogwash. I'd say that once you know what a markup language is, none of them
|
|
> are any more difficult than any other.
|
|
|
|
If a markup language has a small number of short tags it's both easier
|
|
to learn and to type since there are less keystrokes to type.
|
|
|
|
>
|
|
> > > [snip] but I believe it is imperative that we continue pushing
|
|
> > > DocBook, aggressively. All the other major Documentation (outside of
|
|
> > > Debian) have switched to DocBook.
|
|
> >
|
|
> > We have special needs in that we recruit rank amateurs who want the
|
|
> > writing format to be as simple as possible. Anyway, I'm not objecting
|
|
> > to people using DocBook that want to do so (including "rank
|
|
> > amateurs"). Thus while we too have already accepted DocBook I think
|
|
> > we should continue to accept LinuxDoc from anyone.
|
|
>
|
|
> I don't. Linuxdoc is NOT easier to work with,
|
|
|
|
Why?
|
|
> and it's also being phased
|
|
> out just about every doc project in favor of DocBook. The DocBook tools are
|
|
> under much more significant development than the Linuxdoc tools (no offense,
|
|
> Sano), and DocBook itself is still being developed and maintained by
|
|
> professionals in the field of technical documentation.
|
|
|
|
Good. People that want to use DocBook for LDP are free to do so.
|
|
|
|
>
|
|
> > David Lawyer
|
|
> > ##############################################################
|
|
> > ###########
|
|
> >
|
|
> > Comparison of DocBook to LinuxDoc (short).
|
|
> > by David Lawyer, June 23, 2000
|
|
> >
|
|
> > Using DocBook instead of LinuxDoc requires many more tags and the tags
|
|
> > tend to be longer. The tag clutter makes DocBook harder to read.
|
|
> > Thus DocBook is not nearly as easy to do by hand (with an editor that
|
|
> > doesn't support it) as LinuxDoc.
|
|
> >
|
|
> > LinuxDoc is quoted with LD; DocBook with DB.
|
|
> > -------------2---3--------- => DocBook has: 2 times as many tags;
|
|
> > 3 times as many tag characters.
|
|
> >
|
|
> >
|
|
> > Example
|
|
> > 1-------------------1.5---2------------------------------------
|
|
> >
|
|
> > DB <sect>
|
|
> > DB <title>Introduction</title>
|
|
> >
|
|
> > LD <sect>Introduction
|
|
> > LD <p>
|
|
>
|
|
> Looks good to me, I can put in a title rather than just sticking out there,
|
|
> and having no idea that that's a title rather than something else.
|
|
|
|
But it's less to type with LinuxDoc.
|
|
|
|
>
|
|
> > Example 2--------------------2---3------------------------------------
|
|
> >
|
|
> > DB <indexterm>
|
|
> > DB <primary>disk!introduction</primary>
|
|
> > DB </indexterm>
|
|
> >
|
|
> > LD <nidx>disk!introduction</nidx>
|
|
>
|
|
> What on EARTH does "nidx" mean? At least the DocBook tags are meaningful
|
|
> here.
|
|
Good point. But I've never used this tag (yet?).
|
|
>
|
|
> > Example
|
|
> > 3--------------------infinite-------------------------------------
|
|
> >
|
|
> > DB <para>
|
|
> > DB This is the text of a paragraph. LinuxDoc needs no tags for it.
|
|
> > DB </para>
|
|
> >
|
|
> > LD This is the text of a paragraph. LinuxDoc needs no tags for it.
|
|
>
|
|
> But then how does it know when it needs a new paragraph? Does it keep
|
|
> formatting the way that you have it in the source document?
|
|
|
|
I think it's based on a blank line between paragraphs.
|
|
|
|
>
|
|
> > Example 4-------------1+--4-----In docB "release" must be
|
|
> > typed twice------
|
|
> >
|
|
> > DB <emphasis>release</emphasis> release.
|
|
> >
|
|
> > LD <em>release</em>.
|
|
>
|
|
> So, write a tiny macro to expand <em> and </em> to <emphasis> and
|
|
> </emphasis>, respectively. Sounds like very little effort to get to a much
|
|
> more complete markup language to me.
|
|
|
|
Writing a macro is extra effort and some editors don't have macros.
|
|
|
|
>
|
|
> > Example 5--------------3---3----You can't easily read the
|
|
> > docB list---------
|
|
> >
|
|
> > DB <ItemizedList>
|
|
> > DB <ListItem>
|
|
> > DB
|
|
> > DB <Para>
|
|
> > DB Use the "isapnp" program
|
|
> > DB </Para>
|
|
> > DB </ListItem>
|
|
> > DB <ListItem>
|
|
> > DB
|
|
> > DB <Para>
|
|
> > DB Have a PnP BIOS do the configuring
|
|
> > DB </Para>
|
|
> > DB </ListItem>
|
|
> > DB <ListItem>
|
|
> > DB
|
|
> > DB <Para>
|
|
> > DB Patch the kernel to create a PnP Linux (not currently available)
|
|
> > DB </Para>
|
|
> > DB </ListItem>
|
|
> > DB
|
|
> > DB </ItemizedList>
|
|
> >
|
|
> > LD <itemize>
|
|
> > LD <item> Use the "isapnp" program
|
|
> > LD <item> Have a PnP BIOS do the configuring
|
|
> > LD <item> Patch the kernel to create a PnP Linux (not
|
|
> > currently available)
|
|
> > LD </itemize>
|
|
>
|
|
> 80% of this is your formatting. Try:
|
|
|
|
I didn't write this. It's from the conversion made by LDP of my
|
|
HOWTO.
|
|
>
|
|
>
|
|
> <itemizedlist>
|
|
>
|
|
> <listitem>
|
|
> <para>Use the "isapnp" program</para>
|
|
> </listitem>
|
|
>
|
|
> <listitem>
|
|
> <para>Have a PnP BIOS do the configuring</para>
|
|
> </listitem>
|
|
>
|
|
> <listitem>
|
|
> <para>Patch the kernel to create a PnP Linux (not currently
|
|
> available)</para>
|
|
> </listitem>
|
|
>
|
|
> </itemizedlist>
|
|
>
|
|
> Actually, if Ferg took a look and formatted it, that would look even better.
|
|
> There is a bit more typing,
|
|
|
|
A lot more!
|
|
|
|
> but you can turn off requiring end-tags in the > DTD, and shorten that
|
|
> a bunch.
|
|
|
|
But it seems that most everyone (including you) has been saying that
|
|
we don't want "minimum tags".
|
|
|
|
> If you do that, I think that you (err, we?) can get a tool that adds
|
|
> all of those end tags and jazz. Once again, I really don't think
|
|
> that we need to accept LinuxDoc.
|
|
|
|
Let's keep accepting LinuxDoc until such tools (and more) are in
|
|
place.
|
|
|
|
> I also don't think that there will be a shortage of volunteers to
|
|
> markup documents until DocBook becomes obsolete, which doesn't seem
|
|
> likely any time soon, since MAJOR vendors are using it.
|
|
|
|
I'm not so sure about volunteers.
|
|
|
|
(the Solaris man pages are in SGML, and they've hired Norm Walsh).
|
|
|
|
> Since some people still think that we ought to accept LinuxDoc, this
|
|
> discussion should not be limited to the select few here, but really
|
|
> should be had on the discussion list, since that's what it's there
|
|
> for. Greg
|
|
>
|
|
Good. I'll forward this and the previous thread to the list.
|
|
|
|
David Lawyer
|
|
</pre>
|
|
<small>--- <i>End Message</i> ---</small></blockquote>
|
|
|
|
<!--X-Body-of-Message-End-->
|
|
<!--X-MsgBody-End-->
|
|
<!--X-Follow-Ups-->
|
|
<hr>
|
|
<ul><li><strong>Follow-Ups</strong>:
|
|
<ul>
|
|
<li><strong><a name="02997" href="msg02997.html">Re: Requiring use of DocBook; LinuxDoc</a></strong>
|
|
<ul><li><em>From:</em> Chuck Dale <bug@aphid.net></li></ul></li>
|
|
</ul></li></ul>
|
|
<!--X-Follow-Ups-End-->
|
|
<!--X-References-->
|
|
<!--X-References-End-->
|
|
<!--X-BotPNI-->
|
|
<ul>
|
|
<li>Prev by Date:
|
|
<strong><a href="msg02995.html">Re: Requiring use of DocBook; LinuxDoc</a></strong>
|
|
</li>
|
|
<li>Next by Date:
|
|
<strong><a href="msg02997.html">Re: Requiring use of DocBook; LinuxDoc</a></strong>
|
|
</li>
|
|
<li>Previous by thread:
|
|
<strong><a href="msg03039.html">Re: Requiring use of DocBook; LinuxDoc</a></strong>
|
|
</li>
|
|
<li>Next by thread:
|
|
<strong><a href="msg02997.html">Re: Requiring use of DocBook; LinuxDoc</a></strong>
|
|
</li>
|
|
<li>Index(es):
|
|
<ul>
|
|
<li><a href="maillist.html#02996"><strong>Date</strong></a></li>
|
|
<li><a href="threads.html#02996"><strong>Thread</strong></a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<!--X-BotPNI-End-->
|
|
<!--X-User-Footer-->
|
|
<!--X-User-Footer-End-->
|
|
</body>
|
|
</html>
|