Re: Requiring use of DocBook; LinuxDoc

[David Lawyer <dave@lafn.org>]

[ 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>


--  
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org