269 lines
10 KiB
HTML
269 lines
10 KiB
HTML
<!-- MHonArc v2.5.0b2 -->
|
|
<!--X-Subject: RE: Requiring use of DocBook; LinuxDoc -->
|
|
<!--X-From-R13: Uertbel Zroynap <UZroynapNph-cbegynaq.rqh> -->
|
|
<!--X-Date: Sat, 24 Jun 2000 03:53:06 -0400 (EDT) -->
|
|
<!--X-Message-Id: A5F46F4ED18FD211ABEE00105AC6CF0701093825@email.cu-portland.edu -->
|
|
<!--X-Content-Type: text/plain -->
|
|
<!--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:GLeblanc@cu-portland.edu">
|
|
</head>
|
|
<body>
|
|
<!--X-Body-Begin-->
|
|
<!--X-User-Header-->
|
|
<!--X-User-Header-End-->
|
|
<!--X-TopPNI-->
|
|
<hr>
|
|
[<a href="msg02991.html">Date Prev</a>][<a href="msg02993.html">Date Next</a>][<a href="msg02995.html">Thread Prev</a>][<a href="msg02999.html">Thread Next</a>][<a href="maillist.html#02992">Date Index</a>][<a href="threads.html#02992">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>: "'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>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>
|
|
<!--X-Head-of-Message-End-->
|
|
<!--X-Head-Body-Sep-Begin-->
|
|
<hr>
|
|
<!--X-Head-Body-Sep-End-->
|
|
<!--X-Body-of-Message-->
|
|
<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>
|
|
|
|
<!--X-Body-of-Message-End-->
|
|
<!--X-MsgBody-End-->
|
|
<!--X-Follow-Ups-->
|
|
<hr>
|
|
<ul><li><strong>Follow-Ups</strong>:
|
|
<ul>
|
|
<li><strong><a name="02999" href="msg02999.html">Re: Requiring use of DocBook; LinuxDoc</a></strong>
|
|
<ul><li><em>From:</em> Gary Preckshot <garrell@inreach.com></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="msg02991.html">Re: Requiring use of DocBook; LinuxDoc</a></strong>
|
|
</li>
|
|
<li>Next by Date:
|
|
<strong><a href="msg02993.html">Re: Requiring use of DocBook; LinuxDoc</a></strong>
|
|
</li>
|
|
<li>Previous by thread:
|
|
<strong><a href="msg02995.html">Re: Requiring use of DocBook; LinuxDoc</a></strong>
|
|
</li>
|
|
<li>Next by thread:
|
|
<strong><a href="msg02999.html">Re: Requiring use of DocBook; LinuxDoc</a></strong>
|
|
</li>
|
|
<li>Index(es):
|
|
<ul>
|
|
<li><a href="maillist.html#02992"><strong>Date</strong></a></li>
|
|
<li><a href="threads.html#02992"><strong>Thread</strong></a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<!--X-BotPNI-End-->
|
|
<!--X-User-Footer-->
|
|
<!--X-User-Footer-End-->
|
|
</body>
|
|
</html>
|