From: Michael Smith <smith@xml-doc.org>
To: docbook-tools-discuss@sources.redhat.com
Subject: Re: Where, what and how - The future of DocBook
Date: Tue, 05 Dec 2000 21:27:00 -0000 [thread overview]
Message-ID: <u7l5eqfwd.fsf@openwave.com> (raw)
Message-ID: <20001205212700.v_phW32FUWzfOj8bH4PlIjzi9szFHbzlzfkW7Kwg5WA@z> (raw)
In-Reply-To: <Pine.LNX.4.21.0012051509320.2919-100000@localhost>
Alan W. Irwin <irwin@beluga.phys.uvic.ca> writes:
> I am a member of a two-man team that converted a largish piece (more
> than 100 pages) of technical documentation from latexinfo to DocBook
> 4.1 XML. [...]
>
> Since the conversion was completed I have been entering lots of
> extra content with an ordinary editor (jed). I understand there is a
> great DocBook interface available with emacs, but I haven't bothered
> with it yet because it is not really needed. From my experience I
> would assert you don't need any special tool to edit and improve
> documentation written in DocBook. The tags that are ordinarily used
> are easy to memorize. Of course, it probably helps that I am a good
> touch typist. If you don't have that skill I guess you need to find
> some tool that gives you WYSIWYG. But it wasn't necessary in my
> case, and I suspect that is true for most documenters.
Yipes -- all due respect, but I think your suspicion may be way off.
The big advantage of an editor like Emacs/psgml is that it takes much
of the guesswork out of document authoring. Validating editors by
design make it hard to produce invalid documents. Using a validating
editor, you really have to go out of your way to make something that
won't validate. Only way you can do it is to type tags in manually --
which you should never need to do with a good XML editing app.
Sure, jed's great (so's Vim -- better syntax highlighting), but if
you've never used a validating editor like Emacs/psgml, you don't know
what you're missing.
I read a thread on the LDP list in which a writer said that one
advantage of LinuxDoc was its short element names. It baffled me why
he would care how long the names were -- until I realized he was
probably typing them by hand using a regular text editor.
Once I realized that, I was baffled as to why -- when Emacs/psgml is
free, great, and so widely used -- why any skilled Linux user would
rely on a regular (non-SGML-validating) editor to work with XML/SGML.
First of all, it ain't quicker -- don't care how fast you can type.
And although it's great to memorize as much of DocBook as you can, I
wonder what kind of agreement you'd get on what tags are "ordinarily
used". I think that depends very much on what you're documenting.
Confronted with DocBook's 375 elements (including 100+ "inline"
elements that can occur in paragraphs) and 100+ attributes, I doubt
that "most documentors" would find a validating editor uneccessary.
Most of the DocBook users I know (and I include myself) are not so
familiar with the DTD that we can always judge with confidence what
elements and attributes are -valid/required- where -- and why bother
when you've got a DTD-aware validating editor to tell you that?
In fact, one of the main concerns I hear from SGML/XML authors --
especially new ones -- is that their editing tools just aren't smart
enough, and don't go far enough in simplifying the editing process.
No, I wouldn't suggest to anyone that they author DocBook docs using
jed or any other non-validating editor -- unless they've got a lot of
extra time on their hands, really enjoy typing, and really like the
process of running documents through a parser, post-authoring, and
fixing them manually to get them to validate.
-- Mike Smith
--
Michael Smith mailto:smith@xml-doc.org
XML-DOC http://www.xml-doc.org/
next prev parent reply other threads:[~2000-12-05 21:27 UTC|newest]
Thread overview: 48+ messages / expand[flat|nested] mbox.gz Atom feed top
2000-12-27 6:36 Peter Toft
2000-12-03 9:23 ` Peter Toft
2000-12-27 6:36 ` Norman Walsh
2000-12-04 6:08 ` Norman Walsh
2000-12-27 6:36 ` Peter Toft
2000-12-05 14:12 ` Peter Toft
2000-12-27 6:36 ` Alan W. Irwin
2000-12-05 15:53 ` Alan W. Irwin
2000-12-27 6:36 ` Michael Smith [this message]
2000-12-05 21:27 ` Michael Smith
2000-12-27 6:36 ` Alan W. Irwin
2000-12-05 22:50 ` Alan W. Irwin
2000-12-27 6:36 ` Gregory Leblanc
2000-12-06 9:39 ` Gregory Leblanc
2000-12-27 6:36 ` Michael Smith
2000-12-06 0:51 ` Michael Smith
2000-12-27 6:36 ` Eric Bischoff
2000-12-06 5:23 ` Eric Bischoff
2000-12-27 6:36 ` Jorge Godoy
2000-12-05 16:58 ` Jorge Godoy
2000-12-27 6:36 ` Eric Bischoff
2000-12-06 5:10 ` Eric Bischoff
2000-12-27 6:36 ` madhu
2000-12-15 9:22 ` madhu
2000-12-27 6:36 ` Michael Smith
2000-12-15 10:40 ` Michael Smith
2000-12-27 6:36 ` Michael Wiedmann
2000-12-06 5:36 ` Michael Wiedmann
2000-12-27 6:36 ` Eric Bischoff
2000-12-06 5:53 ` Eric Bischoff
2000-12-27 6:36 ` Mark Johnson
2000-12-06 8:05 ` Mark Johnson
2000-12-27 6:36 ` Eric Bischoff
2000-12-06 8:15 ` Eric Bischoff
[not found] <200012061914.UAA08546@mailserv.caiw.nl>
2000-12-27 6:36 ` Hugo.van.der.Kooij
2000-12-06 12:31 ` Hugo.van.der.Kooij
[not found] <200012061723.KAA06519@gw.estinc.com>
2000-12-27 6:36 ` Craig Boone
2000-12-06 11:06 ` Craig Boone
2000-12-27 6:36 ` Gregory Leblanc
2000-12-06 11:12 ` Gregory Leblanc
[not found] ` <200012061858.LAA06946@gw.estinc.com>
2000-12-27 6:36 ` Craig Boone
2000-12-06 11:46 ` Craig Boone
-- strict thread matches above, loose matches on Subject: below --
2000-12-27 6:36 Peter Ring
2000-12-05 7:45 ` Peter Ring
2000-12-27 6:36 Pfaffner, Peter
2000-12-05 7:18 ` Pfaffner, Peter
2000-12-27 6:36 Peter Ring
2000-12-07 3:45 ` Peter Ring
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=u7l5eqfwd.fsf@openwave.com \
--to=smith@xml-doc.org \
--cc=docbook-tools-discuss@sources.redhat.com \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for read-only IMAP folder(s) and NNTP newsgroup(s).