[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
Re: Requiring use of DocBook; LinuxDoc
Attached find the thread on this topic. It's from a "quasi-private"
email discussion. The posts (as attachments) are:
0. David Lawyer: start of thread (not attached since already sent)
1. (Message you are now reading)
2. Poet Joshua/Drake: rebuttal to 0 above.
3. David Lawyer: rejoinder to 2 above.
4. Gregory Leblanc: rebuttal to 0 and 3 above.
5. David Lawyer: rejoinder to 4 above.
David Lawyer
--- Begin Message ---
<CITE>If the above by Mark K is correct, I think it needs to be changed back
<CITE>to allowing LinuxDoc for new authors. We want to make it easy for new
<CITE>authors to get started and maintain their documents. One of our major
<CITE>tasks is to get new authors to create new HOWTOs and update outdated
<CITE>ones. To do this we need to make things as simple as possible. In my
<CITE>case, I almost decided not to write a HOWTO due to the requirement of
<CITE>having to use LinuxDoc. But if I were required to use DocBook I might
<CITE>have refused, even if someone was willing to covert my first
<CITE>submission to DocBook.
I disagree completely, we should not change the LinuxDoc rule. 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. In fact
it is no harder than HTML.
We can not continue to change every item on the opinions of 1
individual. I appreciate the gentlemens frustration but I believe it is
imperative that we continue pushing DocBook, aggressively. All the other
major Documentation (outside of Debian) have switched to DocBook.
Joshua Drake
--
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
--- End Message ---
--- Begin Message ---
[ 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>
--- End Message ---
--- Begin Message ---
> -----Original Message-----
> From: David Lawyer [mailto:dave@lafn.org]
> Sent: Friday, June 23, 2000 2:41 PM
> To: Poet/Joshua Drake
> Cc: David Lawyer; Mark Komarinski; Guylhem Aznar; Greg
> Ferguson; Gregory
> Leblanc; Taketoshi Sano; Stein Gjoen
> Subject: Re: Requiring use of DocBook; LinuxDoc
>
> [ 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.
> > 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.
I disagree. There are more tags required, but that does not make it
dificult.
> > In fact it is no harder than HTML.
>
> Possilbly true but HTML is significantly more difficult than LinuxDoc.
Hogwash. I'd say that once you know what a markup language is, none of them
are any more dificult than any other.
> > [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.
I don't. Linuxdoc is NOT easier to work with, and it's also being phased
out just about every doc project in favor of DocBook. The DocBook tools are
under much more significant development than the Linuxdoc tools (no offense,
Sano), and DocBook itself is still being developed and maintained by
professionals in the field of technical documentation.
> 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>
Looks good to me, I can put in a title rather than just sticking out there,
and having no idea that that's a title rather than something else.
> Example 2--------------------2---3------------------------------------
>
> DB <indexterm>
> DB <primary>disk!introduction</primary>
> DB </indexterm>
>
> LD <nidx>disk!introduction</nidx>
What on EARTH does "nidx" mean? At least the DocBook tags are meaningful
here.
> 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.
But then how does it know when it needs a new paragraph? Does it keep
formatting the way that you have it in the source document?
> Example 4-------------1+--4-----In docB "release" must be
> typed twice------
>
> DB <emphasis>release</emphasis> release.
>
> LD <em>release</em>.
So, write a tiny macro to expand <em> and </em> to <emphasis> and
</emphasis>, respectively. Sounds like very little effort to get to a much
more complete markup language to me.
> 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>
80% of this is your formatting. Try:
<itemizedlist>
<listitem>
<para>Use the "isapnp" program</para>
</listitem>
<listitem>
<para>Have a PnP BIOS do the configuring</para>
</listitem>
<listitem>
<para>Patch the kernel to create a PnP Linux (not currently
available)</para>
</lisitem>
</itemizedlist>
Actually, if Ferg took a look and formatted it, that would look even better.
There is a bit more typing, but you can turn off requiring end-tags in the
DTD, and shorten that a bunch. If you do that, I think that you (err, we?)
can get a tool that adds all of those end tags and jazz. Once again, I
really don't think that we need to accept LinuxDoc. I also don't think that
there will be a shortage of volunteers to markup documents until DocBook
becomes obsolete, which doesn't seem likely any time soon, since MAJOR
vendors are using it. (the Solaris man pages are in SGML, and they've hired
Norm Walsh). Since some people still think that we ought to accept
LinuxDoc, this discussion should not be limited to the select few here, but
really should be had on the discussion list, since that's what it's there
for.
Greg
--
To UNSUBSCRIBE, email to ldp-discuss-request@lists.debian.org
with a subject of "unsubscribe". Trouble? Contact listmaster@lists.debian.org
--- End Message ---
--- Begin Message ---
On Fri, Jun 23, 2000 at 05:15:20PM -0700, Gregory Leblanc wrote:
> > -----Original Message-----
> > From: David Lawyer [mailto:dave@lafn.org]
> > Sent: Friday, June 23, 2000 2:41 PM
> > To: Poet/Joshua Drake
> > Cc: David Lawyer; Mark Komarinski; Guylhem Aznar; Greg
> > Ferguson; Gregory
> > Leblanc; Taketoshi Sano; Stein Gjoen
> > Subject: Re: Requiring use of DocBook; LinuxDoc
> >
> > [ 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.
> > > 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.
>
> I disagree. There are more tags required, but that does not make it
> difficult.
The poet said "no more difficult than LinuxDoc". Doesn't more tags
required make it more difficult if you're doing it manually?
>
> > > In fact it is no harder than HTML.
> >
> > Possibly true but HTML is significantly more difficult than LinuxDoc.
>
> Hogwash. I'd say that once you know what a markup language is, none of them
> are any more difficult than any other.
If a markup language has a small number of short tags it's both easier
to learn and to type since there are less keystrokes to type.
>
> > > [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.
>
> I don't. Linuxdoc is NOT easier to work with,
Why?
> and it's also being phased
> out just about every doc project in favor of DocBook. The DocBook tools are
> under much more significant development than the Linuxdoc tools (no offense,
> Sano), and DocBook itself is still being developed and maintained by
> professionals in the field of technical documentation.
Good. People that want to use DocBook for LDP are free to do so.
>
> > 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>
>
> Looks good to me, I can put in a title rather than just sticking out there,
> and having no idea that that's a title rather than something else.
But it's less to type with LinuxDoc.
>
> > Example 2--------------------2---3------------------------------------
> >
> > DB <indexterm>
> > DB <primary>disk!introduction</primary>
> > DB </indexterm>
> >
> > LD <nidx>disk!introduction</nidx>
>
> What on EARTH does "nidx" mean? At least the DocBook tags are meaningful
> here.
Good point. But I've never used this tag (yet?).
>
> > 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.
>
> But then how does it know when it needs a new paragraph? Does it keep
> formatting the way that you have it in the source document?
I think it's based on a blank line between paragraphs.
>
> > Example 4-------------1+--4-----In docB "release" must be
> > typed twice------
> >
> > DB <emphasis>release</emphasis> release.
> >
> > LD <em>release</em>.
>
> So, write a tiny macro to expand <em> and </em> to <emphasis> and
> </emphasis>, respectively. Sounds like very little effort to get to a much
> more complete markup language to me.
Writing a macro is extra effort and some editors don't have macros.
>
> > 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>
>
> 80% of this is your formatting. Try:
I didn't write this. It's from the conversion made by LDP of my
HOWTO.
>
>
> <itemizedlist>
>
> <listitem>
> <para>Use the "isapnp" program</para>
> </listitem>
>
> <listitem>
> <para>Have a PnP BIOS do the configuring</para>
> </listitem>
>
> <listitem>
> <para>Patch the kernel to create a PnP Linux (not currently
> available)</para>
> </listitem>
>
> </itemizedlist>
>
> Actually, if Ferg took a look and formatted it, that would look even better.
> There is a bit more typing,
A lot more!
> but you can turn off requiring end-tags in the > DTD, and shorten that
> a bunch.
But it seems that most everyone (including you) has been saying that
we don't want "minimum tags".
> If you do that, I think that you (err, we?) can get a tool that adds
> all of those end tags and jazz. Once again, I really don't think
> that we need to accept LinuxDoc.
Let's keep accepting LinuxDoc until such tools (and more) are in
place.
> I also don't think that there will be a shortage of volunteers to
> markup documents until DocBook becomes obsolete, which doesn't seem
> likely any time soon, since MAJOR vendors are using it.
I'm not so sure about volunteers.
(the Solaris man pages are in SGML, and they've hired Norm Walsh).
> Since some people still think that we ought to accept LinuxDoc, this
> discussion should not be limited to the select few here, but really
> should be had on the discussion list, since that's what it's there
> for. Greg
>
Good. I'll forward this and the previous thread to the list.
David Lawyer
--- End Message ---