207 lines
9.1 KiB
HTML
207 lines
9.1 KiB
HTML
<!-- MHonArc v2.5.0b2 -->
|
|
<!--X-Subject: Requiring use of DocBook; LinuxDoc -->
|
|
<!--X-From-R13: Rnivq Znjlre <qnirNynsa.bet> -->
|
|
<!--X-Date: Sat, 24 Jun 2000 03:52:32 -0400 (EDT) -->
|
|
<!--X-Message-Id: 20000622173003.A559@localhost -->
|
|
<!--X-Content-Type: text/plain -->
|
|
<!--X-Reference: 20000622115851.A231@localhost -->
|
|
<!--X-Reference: 39526568.EFE6A70E@cgipc.com -->
|
|
<!--X-Head-End-->
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML//EN">
|
|
<html>
|
|
<head>
|
|
<title>Requiring use of DocBook; LinuxDoc</title>
|
|
<link rev="made" href="mailto:dave@lafn.org">
|
|
</head>
|
|
<body>
|
|
<!--X-Body-Begin-->
|
|
<!--X-User-Header-->
|
|
<!--X-User-Header-End-->
|
|
<!--X-TopPNI-->
|
|
<hr>
|
|
[<a href="msg02989.html">Date Prev</a>][<a href="msg02991.html">Date Next</a>][<a href="msg02989.html">Thread Prev</a>][<a href="msg02993.html">Thread Next</a>][<a href="maillist.html#02990">Date Index</a>][<a href="threads.html#02990">Thread Index</a>]
|
|
<!--X-TopPNI-End-->
|
|
<!--X-MsgBody-->
|
|
<!--X-Subject-Header-Begin-->
|
|
<h1>Requiring use of DocBook; LinuxDoc</h1>
|
|
<hr>
|
|
<!--X-Subject-Header-End-->
|
|
<!--X-Head-of-Message-->
|
|
<ul>
|
|
<li><em>To</em>: <A HREF="mailto:ldp-discuss@lists.linuxdoc.org">ldp-discuss@lists.linuxdoc.org</A></li>
|
|
<li><em>Subject</em>: Requiring use of DocBook; LinuxDoc</li>
|
|
<li><em>From</em>: David Lawyer <<A HREF="mailto:dave@lafn.org">dave@lafn.org</A>></li>
|
|
<li><em>Date</em>: Sat, 24 Jun 2000 00:00:59 -0700</li>
|
|
<li><em>In-reply-to</em>: <39526568.EFE6A70E@cgipc.com></li>
|
|
<li><em>Mail-followup-to</em>: ldp-discuss@lists.linuxdoc.org</li>
|
|
<li><em>References</em>: <20000622115851.A231@localhost> <39526568.EFE6A70E@cgipc.com></li>
|
|
<li><em>Resent-date</em>: Sat, 24 Jun 2000 03:52:32 -0400 (EDT)</li>
|
|
<li><em>Resent-from</em>: <A HREF="mailto:ldp-discuss@lists.debian.org">ldp-discuss@lists.debian.org</A></li>
|
|
<li><em>Resent-message-id</em>: <oFs7LC.A.3d.QjGV5@murphy></li>
|
|
<li><em>Resent-sender</em>: <A HREF="mailto:ldp-discuss-request@lists.debian.org">ldp-discuss-request@lists.debian.org</A></li>
|
|
<li><em>User-agent</em>: Mutt/1.0pre3i</li>
|
|
<li><em>User-agent</em>: Mutt/1.0pre3i</li>
|
|
</ul>
|
|
<!--X-Head-of-Message-End-->
|
|
<!--X-Head-Body-Sep-Begin-->
|
|
<hr>
|
|
<!--X-Head-Body-Sep-End-->
|
|
<!--X-Body-of-Message-->
|
|
<pre>
|
|
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
|
|
|
|
</pre>
|
|
|
|
<!--X-Body-of-Message-End-->
|
|
<!--X-MsgBody-End-->
|
|
<!--X-Follow-Ups-->
|
|
<hr>
|
|
<ul><li><strong>Follow-Ups</strong>:
|
|
<ul>
|
|
<li><strong><a name="02993" href="msg02993.html">Re: Requiring use of DocBook; LinuxDoc</a></strong>
|
|
<ul><li><em>From:</em> Poet/Joshua Drake <poet@linuxports.com></li></ul></li>
|
|
<li><strong><a name="02994" href="msg02994.html">Re: Requiring use of DocBook; LinuxDoc</a></strong>
|
|
<ul><li><em>From:</em> Gary Lawrence Murphy <garym@canada.com></li></ul></li>
|
|
<li><strong><a name="02995" href="msg02995.html">Re: Requiring use of DocBook; LinuxDoc</a></strong>
|
|
<ul><li><em>From:</em> David Lawyer <dave@lafn.org></li></ul></li>
|
|
</ul></li></ul>
|
|
<!--X-Follow-Ups-End-->
|
|
<!--X-References-->
|
|
<!--X-References-End-->
|
|
<!--X-BotPNI-->
|
|
<ul>
|
|
<li>Prev by Date:
|
|
<strong><a href="msg02989.html">Cico Routers & XTACACSD</a></strong>
|
|
</li>
|
|
<li>Next by Date:
|
|
<strong><a href="msg02991.html">Re: Requiring use of DocBook; LinuxDoc</a></strong>
|
|
</li>
|
|
<li>Previous by thread:
|
|
<strong><a href="msg02989.html">Cico Routers & XTACACSD</a></strong>
|
|
</li>
|
|
<li>Next by thread:
|
|
<strong><a href="msg02993.html">Re: Requiring use of DocBook; LinuxDoc</a></strong>
|
|
</li>
|
|
<li>Index(es):
|
|
<ul>
|
|
<li><a href="maillist.html#02990"><strong>Date</strong></a></li>
|
|
<li><a href="threads.html#02990"><strong>Thread</strong></a></li>
|
|
</ul>
|
|
</li>
|
|
</ul>
|
|
|
|
<!--X-BotPNI-End-->
|
|
<!--X-User-Footer-->
|
|
<!--X-User-Footer-End-->
|
|
</body>
|
|
</html>
|