public inbox for docbook-tools-discuss@sourceware.org
 help / color / mirror / Atom feed
From: "Alan W. Irwin" <irwin@beluga.phys.uvic.ca>
To: docbook-tools-discuss@sources.redhat.com
Subject: Re: Where, what and how - The future of DocBook
Date: Wed, 27 Dec 2000 06:36:00 -0000	[thread overview]
Message-ID: <Pine.LNX.4.21.0012052201100.2919-100000@localhost> (raw)
In-Reply-To: <u7l5eqfwd.fsf@openwave.com>

Mike, I was reacting against those who implied DocBook was so difficult that
you absolutely required sophisticated tools to deal with it.  Also, you
have, IMO a weak argument about validation since it actually doesn't take
very long to do it on a modern PC independently of the editing process if
you do editing in one window and validation in another. My particular
project had a variety of tags, but the vast majority of them had quite
repetitive patterns so a working example was always nearby in the document.
Thus, I rarely (about 4 times in the whole project) had a validation error.
So things went really fast for the simple method I chose. That is an
important point I hope we can agree on; DocBook ain't difficult and doesn't
absolutely *require* sophisticated tools.

That said, you have been a good advocate for emacs/psgml (and so was my
partner in the project) so I will probably try it next time, but I don't
regret for a moment doing my first DocBook project this simple and
straightforward way. I seem to learn the best if I solve problems with
low-end tools to start, and then move on up to more sophisticated tools
later on.  YMMV, of course.

This has been an interesting discussion about methods and perhaps even
valuable as well, but I sure wish I could get as quick a response on this
list to the practical problem of Cygnus pdfjadetex not working in the
latest release.

Alan

email: irwin@beluga.phys.uvic.ca
phone: 250-727-2902	FAX: 250-721-7715
snail-mail:
Dr. Alan W. Irwin
Department of Physics and Astronomy,
University of Victoria, P.O. Box 3055,
Victoria, British Columbia, Canada, V8W 3P6 
__________________________

Linux-powered astrophysics
__________________________

On 5 Dec 2000, Michael Smith wrote:

> 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/
> 
> 
> 
> 

WARNING: multiple messages have this Message-ID
From: "Alan W. Irwin" <irwin@beluga.phys.uvic.ca>
To: docbook-tools-discuss@sources.redhat.com
Subject: Re: Where, what and how - The future of DocBook
Date: Tue, 05 Dec 2000 22:50:00 -0000	[thread overview]
Message-ID: <Pine.LNX.4.21.0012052201100.2919-100000@localhost> (raw)
Message-ID: <20001205225000.ojq9fw4w3JFx-s_0ZIASJl9HbSYQ00CgS7tHoG24pMk@z> (raw)
In-Reply-To: <u7l5eqfwd.fsf@openwave.com>

Mike, I was reacting against those who implied DocBook was so difficult that
you absolutely required sophisticated tools to deal with it.  Also, you
have, IMO a weak argument about validation since it actually doesn't take
very long to do it on a modern PC independently of the editing process if
you do editing in one window and validation in another. My particular
project had a variety of tags, but the vast majority of them had quite
repetitive patterns so a working example was always nearby in the document.
Thus, I rarely (about 4 times in the whole project) had a validation error.
So things went really fast for the simple method I chose. That is an
important point I hope we can agree on; DocBook ain't difficult and doesn't
absolutely *require* sophisticated tools.

That said, you have been a good advocate for emacs/psgml (and so was my
partner in the project) so I will probably try it next time, but I don't
regret for a moment doing my first DocBook project this simple and
straightforward way. I seem to learn the best if I solve problems with
low-end tools to start, and then move on up to more sophisticated tools
later on.  YMMV, of course.

This has been an interesting discussion about methods and perhaps even
valuable as well, but I sure wish I could get as quick a response on this
list to the practical problem of Cygnus pdfjadetex not working in the
latest release.

Alan

email: irwin@beluga.phys.uvic.ca
phone: 250-727-2902	FAX: 250-721-7715
snail-mail:
Dr. Alan W. Irwin
Department of Physics and Astronomy,
University of Victoria, P.O. Box 3055,
Victoria, British Columbia, Canada, V8W 3P6 
__________________________

Linux-powered astrophysics
__________________________

On 5 Dec 2000, Michael Smith wrote:

> 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/
> 
> 
> 
> 

  parent reply	other threads:[~2000-12-27  6:36 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     ` 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         ` 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
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     ` Alan W. Irwin
2000-12-05 15:53       ` Alan W. Irwin
2000-12-27  6:36       ` Michael Smith
2000-12-05 21:27         ` Michael Smith
2000-12-27  6:36         ` Alan W. Irwin [this message]
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
     [not found] <200012061723.KAA06519@gw.estinc.com>
2000-12-27  6:36 ` Craig Boone
2000-12-06 11:06   ` Craig Boone
     [not found]   ` <200012061858.LAA06946@gw.estinc.com>
2000-12-27  6:36     ` Craig Boone
2000-12-06 11:46       ` Craig Boone
2000-12-27  6:36   ` Gregory Leblanc
2000-12-06 11:12     ` Gregory Leblanc
     [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
2000-12-27  6:36 Pfaffner, Peter
2000-12-05  7:18 ` Pfaffner, Peter
2000-12-27  6:36 Peter Ring
2000-12-05  7:45 ` Peter Ring
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=Pine.LNX.4.21.0012052201100.2919-100000@localhost \
    --to=irwin@beluga.phys.uvic.ca \
    --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).