Requiring use of DocBook; LinuxDoc

[David Lawyer <dave@lafn.org>]

This was originally sent just to:

	Mark Komarinski <markk@cgipc.com>
	Guylhem Aznar <guylhem@metalab.unc.edu>,
	Greg Ferguson <gferg@hoop.timonium.sgi.com>,
	Gregory Leblanc <GLeblanc@cu-portland.edu>,
	Poet/Joshua Drake <poet@linuxports.com>,
	Taketoshi Sano <kgh12351@nifty.ne.jp>

I'm posting it and the rest of the thread to the list.  Dave L.

> David Lawyer wrote to Mark Komarinski:
> > 
> > I just noticed that in the "For New Authors" you will force them to
> > use DocBook after the first version.  When was this ever decided on?
[snip]
> > But I strongly think we need to keep open the LinuxDoc option for new
> > HOWTOs.  Also, we may run into trouble with a shortage of people
> > willing to translate to DocBook.
> 
On Thu, Jun 22, 2000 at 03:13:44PM -0400, Mark Komarinski wrote:
[snip]
> The understanding I got from the powers-that-be > was:
> 
> 1)  New submissions to LDP in DocBook
> 2)  If an author can't/won't write in DocBook, then they submit
> in readable-format-of-choice and someone will convert it to DB.
> 3)  Once DB has been submitted, authors are expected to submit
> updates in DB format, with assistance from ldp-discuss and ldp-docbook
> as needed.

If the above by Mark K is correct, I think it needs to be changed back
to allowing LinuxDoc for new authors.  We want to make it easy for new
authors to get started and maintain their documents.  One of our major
tasks is to get new authors to create new HOWTOs and update outdated
ones.  To do this we need to make things as simple as possible.  In my
case, I almost decided not to write a HOWTO due to the requirement of
having to use LinuxDoc.  But if I were required to use DocBook I might
have refused, even if someone was willing to covert my first
submission to DocBook.

To use DocBook efficiently with it's tags requires using an
editor/word-processor that supports DocBook.  Putting in the DocBook
tags manually is too much of a burden but it's easy for LinuxDoc
because there are far fewer tags, the tags are shorter, and end tags
are often not needed.  For my HOWTOs putting in the DocBook tags
manually would take about 5 times the effort as for LinuxDoc.  The
DocBook screen display also looks very cluttered with tags and is not
nearly as easy to read as LinuxDoc.

Thus a new author that uses an editor that doesn't support DocBook
will likely want to use LinuxDoc since it's much easier to make
updates (including major rewrites).  We should allow this.

Now the idea of having mark-up people convert any format to DocBook is
an interesting one.  It's good for people who use editors that can
handle DocBook.  But if they don't use such an editor (such as people
who use vim), they are forced to maintain and update their doc in
DocBook and this is far more work than for LinuxDoc.  Unless you
expect them to learn a new editor and this is too much to ask.

I'm worried however that once the DocBook fever wears off, we will
have trouble finding people to do the conversions.  Doing such a
conversion is not as interesting (and doesn't get the recognition)
that authoring a document does.  Thus I think we should encourage new
authors to submit either in LinuxDoc or DocBook.  If they can't do
this then they could submit in some other format and hope that someone
else promptly converts it to one of these two (the author should
specify which one, DocBook or LinuxDoc).

The LDP Author Guide (formerly HOWTO-HOWTO) needs to early on present 
the choices of DocBook vs LinuxDoc in a few paragraphs.  New authors
would then make a tentative decision of which to use.  If they chose
LinuxDoc they would go to a LinuxDoc section (which unfortunately
has been removed) and be advised to start writing immediately using a
template such as example.sgml which Sano has just revised for
linuxdoc-tools 0.5.0.  I'm planning on commenting on it and hopefully
it will be very easy to use.

Another problem may be getting and installing software.  We can't
assume that a potential author even knows how to compile a package
(unless it's menu driven).  Debian has the LinuxDoc tools precompiled
for PCs and I think others do also.  Is this also true for DocBook?

So in conclusion, I don't think we should force DocBook on new
authors.  You may say that DocBook will be easier to search but
LinuxDoc also has keywords that should help.  Searching with grep or
the search engine at LDP websites seems to work pretty well.  For
those who know that HOWTOs exist (many don't) and can use grep, etc.
the major problem is not that one can't find what is in the HOWTOs.
The major problem is that many HOWTOs are out-of-date, didn't cover
the topic adequately when they were new, or no HOWTO may exist on the
topic.  In other words, the main problem is not that the documents are
in LinuxDoc instead of DocBook but that we don't have nearly enough
authors and maintainers.  To get more of what we need the most
(authors/maintainers) we need to make the job easy to do and LinuxDoc
can help with that.

This doesn't rule out that sometime in the future we would require new
authors to use DocBook.  But this needs to be delayed until it's clear
that DocBook will be very easy to learn and use with vim and other
editors (pico ?).  For example, having a macro package for the tags 
for vim would help.  I've created some for LinuxDoc.

			David Lawyer


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