Re: Requiring use of DocBook; LinuxDoc

[David Lawyer <dave@lafn.org>]

> > The Poet wrote: 
> > > 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.
> > 
> David Lawyer wrote:
> > Not so.  See my examples at the end of this message.
> 
On Sun, Jun 25, 2000 at 10:10:12AM -0200, Anthony E. Greene wrote:

> I looked at the examples. I never learned LinuxDoc, but I know HTML and
> have started using DocBook. LinuxDoc is not easier. Manually inserting
> tags may be faster because fewer are required and they're typically
> shorter, but that only applies after you've learned the shortcuts.

No!  You don't spend any time learning shortcuts in LinuxDoc because
the example.sgml template from which you learn has all the "shortcuts"
in it.  You never learn "verbose LinuxDoc" but only "shortcut
LinuxDoc".  In fact, since often double the number of tags is required
to do the same thing in DocBook, the "shortcuts" are an inherent part
of LinuxDoc.  Likewise for the short spelling of some tags in LinuxDoc.

> As a new author, I found DocBook very easy to understand and use. The
> tags are easy to understand and having to always close them makes visual
> parsing easier. The "implied closing" and "implied tags" available in
> LinuxDoc only make it harder to learn. 

They make it much easier to read LinuxDoc and no harder to learn.  You
learn the shortcuts if it were the only way to do it.  I don't argue
that DocBook is all that difficult, but I think that it will take a
few times as long to type in the tags.

> If you decide to use verbose tagging to simplify things, then you
> may as well use DocBook.

Not necessarily since there will be fewer tags in verbose LinuxDoc
(but the template doesn't teach verbose LinuxDoc).

> > > In fact it is no harder than HTML.
> > 
> > Possibly true but HTML is significantly more difficult than LinuxDoc.
> 
> That depends on your style. When maintained using a text editor, HTML is
> best written using verbose tagging and intelligent use of whitespace.
> It's just easier to maintain than minimizing tags and taking shortcuts.
> If you write HTML by hand using these techniques, then DocBook is very
> easy to learn. Basic DocBook may be easier to learn than HTML precisely
> because DocBook's tags are more descriptive. I was able to use DocBook
> almost immediately after looking at an example and the list of tags.
> Using the shortcuts available in LinuxDoc would have taken much longer.
> Without those shortcuts, LinuxDoc is not significantly harder than
> DocBook.

The above implies that a person who already knows HTML and doesn't use
shortcuts may prefer using DocBook because they are used to using end
tags and verbose methods.  Since the example.sgml is so simple (and
I'm planning to help improve on it), I think most people with HTML
experience will find it easier than DocBook.  From example.sgml there
are only several "abbreviated" tags and they are all for "fonts"
(oversimplified) except that <p> (or blank line) is for paragraph.
Examples of "fonts": <it> italics, <em> emphasis.  

But, many will prefer to use DocBook even if it takes longer.  So I
say let them choose what path to take and not force DocBook on them.
Let them use LinuxDoc if they want to.  Most of what they learn will
be useful in DocBook.

			David Lawyer


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