[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
RE: Requiring use of DocBook; LinuxDoc
> -----Original Message-----
> From: David Lawyer [mailto:dave@lafn.org]
> 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