discuss: Docbook, Xml, Jade etc.
Subject:
Re: Docbook, Xml, Jade etc.
From:
David Lawyer ####@####.####
Date:
29 Jul 2003 06:38:49 -0000
Message-Id: <20030729065144.GE2203@lafn.org>
On Mon, Jul 28, 2003 at 04:33:10AM -0700, Tabatha Marshall wrote:
> An author is never obligated to learn the markup. We are more than
> happy to help you with that. Since the work is volunteer-based,
> sometimes it does take time. That is why we're always looking for
> more help.
I think that an author is at least obligated to learn the rudiments of
markup (such as LinuxDoc) for the following reasons. For the case of
LinuxDoc, it's simple to learn and should take less than an hour. The
benefits are that it forces the author to organize the doc into
sections: <sect1>, etc. If you don't require markup, then one can
submit a doc which isn't divided up into sections and subsections.
How does one create a table of contents for such a doc? The use of
<sect> markup results in the automatic creation of a table of contents.
Another reason for using markup is links. Parts of the doc usually
refer to other parts of the same doc (as well as to Internet sites).
Users of HTML want to navigate by just a click. For text readers to do
the same thing within the doc, they may need to use a "find" command to
search for a text string. The markup allows for the creation of such
links. Authors need to select the appropriate names and id-names for
such links. An editor shouldn't have to come up with these names and
id-names. That's something that the author needs to decide on.
There's a problem with links to the internet when reading a text version
of the doc. How does one start a browser from say a pager and follow an
interesting link in a text document? One could use wget but it's not
simple and fast.
Also, markup encourages the creation of itemized list where each <item> is
put on a new line. Also (at least for LinuxDoc) it forces the author to
have a <title>, <author>, and <date>.
So I think that authors need to at least learn a simple markup like
LinuxDoc. I don't mean that they should learn all of the tags but just
several of the most important ones. And they don't need to memorized
them either since they can use a template.
But there's another problem and that's the use of abbreviations (or
macros) used with an editor so that one can type say ;i and get <item>.
For DocBook, instead of just <item> you have to use <ListItem> <Para>
and </Para> </ListItem>. That's 4 times as many tags for the same
function. LinuxDoc seldom requires end tags so just <item> is enough.
I wish I could convince people that we should be suggesting that new
authors use LinuxDoc instead of DocBook. Unless they already know
DocBook and want to use it instead.
David Lawyer
