[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]
Subject: Re: [docbook] First Attempt at Writing a Manual Not Going Well
Thank you, everyone who responded. There is one comment I would like to respond to myself: On Thu, Apr 17, 2003 at 09:26:25AM +0200, Stephane Bortzmeyer wrote: > [...snip...] > Reading your message, it seems you do not have (yet) a clear > understanding about what DocBook is and isn't. > [...snip...] You got that right! I *think* I understand the general idea of DocBook; it is the implementation on my part the boggles me. Boggle #1: When I actually try to sit down and write, I find myself spending vastly more time paging throught the (relatively incomprehensible) manual from O'Reilly that I do actually entering information. I don't even have a recent manual. The online version (www.docbook.org) has wonderful bits like: AuthorBlurb and Affiliation will be removed from the inline content of SectionInfo in DocBook V4.0. A new wrapper element will be created to associate this information with authors, editors, and other contributors. I am using DocBook V4.1, and the most recent online manual is not even V4.0? Am I looking in the right place? Boggle #2: DocBook appears to be something which grew, rather than something which was designed. I know I would not create it this way! There is no uniformity over scale. For example, there could be a <who wrote this> wrapper which could be included in sets, books, chapters, sectn, &c. Instead, there appears to be something slightly different for each. No wrapper at all would work; there is no syntactic informational difference between: <section> <sectioninfo> <author> ...stuff... </author> </sectioninfo> </section> and <section> <author> ...stuff... </author> </section> Either way, the <author> information must be describing the <section>. I must be missing something here. Boggle #3: I would think that the importance of a piece of information would be part of DTD, and not part of the style sheets. Yet the style sheets determine whether a particular bit of info is printed or not. I realize that we have "Separation of Church and State" here, but couldn't the DTD and the style sheets at least communicate? Something like, "Hey, who wrote this is important, don't forget to print it somewhere!" After all, <emphasis> contains no information as to the content of the surrounded text, only that it should be marked up in a special way. We've broken the paradigm already. Why not a <showthiscauseitsimportant> tag? Boggle #4: (Not really DocBook) Where can I learn about ENTITY? Can I use it as a sort of macro system for things I don't want to type fifteen times? Chapter 2 of O'Reilly's DocBook is, again, incomprehensible. All it does is give a link to some useless document at oasis-open.org. In summary, is there something I can go read that will educate me? DocBook for Dummies? Idiots Guide to SGML? Brian -- Brian M. Sutin Instrument Scientist Pasadena, CA The Observatories of the Carnegie Institution of Washington
[Date Prev] | [Thread Prev] | [Thread Next] | [Date Next] -- [Date Index] | [Thread Index] | [List Home]