From mboxrd@z Thu Jan 1 00:00:00 1970 From: "Alan W. Irwin" 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 Message-ID: References: X-SW-Source: 2000-q4/msg00056.html Message-ID: <20001205225000.ojq9fw4w3JFx-s_0ZIASJl9HbSYQ00CgS7tHoG24pMk@z> 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 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/ > > > >