From mboxrd@z Thu Jan 1 00:00:00 1970 From: Michael Smith 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 Message-ID: References: X-SW-Source: 2000-q4/msg00055.html Message-ID: <20001205212700.v_phW32FUWzfOj8bH4PlIjzi9szFHbzlzfkW7Kwg5WA@z> 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/