Slashdot Mirror

BartlebyScrivener writes "I am a author, screenwriter, law prof, and a hobbyist programmer. I love MacVim and write almost everything in it: Exams, novels, even screenplays now that Fountain is available. I use LaTeX and WordPress and so on, but several years ago I discovered Markdown and the wonderful Pandoc. I searched Slashdot expecting to find lively discussions of both Markdown and Pandoc, but found nothing. Do Slashdotters look down their noses at these tools and do their work in HTML and LaTeX? I can't imagine computer geeks using Word instead of their favorite text editors. If not Markdown and Pandoc, what tools do Slashdotters use when they create documents that probably need to be distributed in more than one format: HTML, PDF, EPUB or perhaps even docx?" And then there's DocBook, LyX, and a host of other markup languages. What do you use, in what context?

belmolis asks: "For many years I've done almost all of my writing in TeX. This has increasingly caused problems with publishing in journals. For a long time, many journals reset what you sent them, so they didn't care what program you used. More and more, I find, they do, and in most cases, what they want is MS Word. Is there any good way to convert TeX to Word?" "I've seen some advertised. Some only work with LaTeX, which doesn't help. One claims to use a full-scale TeX interpreter, but my queries as to whether it can handle home-brew Metafont fonts, PIC graphics etc. have gone unanswered. These products also all seem to be plugins for MS Word. I don't use MS Windows or any other MS products, and hate WYSIWYG word processors (I hated Bravo before it was reincarnated as Word) so a Word plugin is not a great solution, even if it works.

Furthermore, I wonder what exactly these programs do. If they interpret the TeX and then generate very low level Word, that may result in a document that looks similar, but a journal editor probably won't be able to edit it the way he wants to. In some cases the editor can be persuaded to accept a camera-ready PDF, since it turns out that the publishers often want PDF and the reason the editor wants Word is so he can edit the text, but when the editor can't or won't budge, is there any alternative to reformatting the document entirely in Word or a clone?

The larger question this raises is, where are we going? Even if formats are open, translation is difficult if they are only commensurable at a very low level. Is the solution to write in something very abstract like DocBook? And if so, will the market go this way?"

Saqib Ali asks: "Office 2003 Pro as been out for quite some time now. I was wondering how many large corporations have been to able use it as a XML authoring / modelling application? I have been involved in evaluation of several XML authoring / modelling applications and am planning to evaluate Office 2003 for it's XML authoring capabilities. The scope of my evaluation is limited to capabilities required for authoring technical documentation, preferably in DocBook XML. Is there anything I should keep in mind before starting the evaluation? One feature that I like about Office 2003 is its support for WebDAV. Our homebrewed CMS (Content Management Systems) supports WebDAV, which makes publishing the content a breeze. Except for OpenOffice, I haven't seen any other XML authoring application that has support for WebDAV. Any suggestions?"

Saqib Ali asks: "A DTD (Documentation Type Definition) defines the document structure with a list of legal elements. DocBook DTD is being widely used in creating Linux related documentation. However I am looking for a XML DTD that is more suited to internal IT documentation, and easy to learn and use. Preferably I would like to use a DTD that can be used with OpenOffice. What DTDs are other Slashdot readers using for for internal IT documentation? I have created documentation using DocBook DTD and hosted them on a Apache Cocoon . Cocoon lets me transform the XML to HTML or PDF. I would like to keep the same backend infrastructure (i.e. Cocoon) but try out other DTDs that are suited for IT related documentation. Any ideas?"

Saqib Ali asks: "This week I saw a demo of the Tagless Editor by i4i. The editor is a plugin to Microsoft Word, which can be used to create XML based content. The plugin can handle various custom DTDs. However it can not properly handle the DocBook DTD. I was wondering if there is any WYSIWYG XML editor that can be used to edit DocBook DTD based content? Any ideas?"

Jim Mock writes in to "announce the hardcopy release of the FreeBSD Handbook. Written by the FreeBSD Documentation Project, the FreeBSD Handbook is a comprehensive guide to installing and running FreeBSD, and covers the installation and day-to-day use of FreeBSD, the ports collection, kernel configuration, the X Window System, printing, FreeBSD's Linux binary compatibility support, upgrading your system from source by using the ``make world'' command, and much more." Read on for more details.

Integrity demands that I point out that in another window I'm the FreeBSD Documentation project manager -- that doesn't mean I get to see any of the money this raises though, so the black-helicopter gang needn't worry. Jim continues: "If you are interested in purchasing a copy of the handbook, you can do so online from the FreeBSDMall or Walnut Creek CDROM."

If you're involved in other open source documentation efforts you might be interested to know that the Handbook is marked up in (a slightly extended version of) the DocBook DTD (and more details about the extensions are available at the Doc. Project Primer). The "source" for the Handbook is (naturally) available in CVS, as are the tools and infrastructure used to build it.

Cactvs142 asks: "Have to make a choice for writing my science report in chemistry. I want to use XML and end up with PDF, so Word (etc.) and LaTex fail. It comes down to this choice: DocBook or TEI. DocBook is used by O'Reilly, but TEI already supports MathML. Which one is the better choice?"

Last week we got a bunch of questions for Deb Richardson, leader of the Open Source Writers Group. These are her answers. Please don't forget as you read: OSWG needs volunteers, and this is a great way to participate in Open Source development if you're handier at writing and editing words than code.

One thing to consider
by Duke of URL

When we tell new people to RTFM sometimes they get overwhelmed. They often don't want all the extra stuff a man page has. The newbies may just want to get a step-by-step direction sheet of how to do things, which is fine. They learn fast that way - but eventually they're going to need to learn the details.

So how do we write docs which help newbies and still give the 'learned' the details they need?

Deb:

Currently there is no way to create documentation that changes dynamically according to the level and needs of the user. I think we have the technology to begin working towards these sorts of systems, but it will be a while before they're a realistic option.

Writing documentation that is targeted towards a specific audience is very important, of course. As you said, new users have different needs than experienced users. At the moment, the only really effective way to address both these types of user is simply to create both types of documentation.

Trying to address all possible audiences within the scope of a single document is simply a recipe for disaster. You will end up with either a gargantuan piece of work that takes too long to create and maintain, or you will end up with a document that tries to serve the "average user" that won't meet anyone's needs at all. Either way, you end up with ineffective docs.

Short answer: Different docs for different audiences.

How to make sure that the documentation is updated
by cribeiro

One of the hard parts of the documentation process is keeping the docs in sync with the software. People tend to fix bugs and forget to update the docs. Telling developers to maintain it does not work for several reasons. The same problem applies for tutorials and things like that. What do you think could be made to make sure that all documents are kept updated?

Deb:

Having dedicated documentation people within your project is definitely a step in the right direction. The GNOME project, for example, has the GNOME Documentation Project. Also, having your documentation people tightly integrated with the rest of the development team is very important. If your documentation people find out about changes, updates, and additions at the same time the developers do, then chances are much better that these changes will be reflected in your documentation in a timely manner.

It's also important to keep in mind that it takes time to produce good documentation. It has to be written, edited, verified on a technical level, re-edited, proofread, and so on. If you want to ensure that your documentation is in sync with your software releases then you might have to hold off on releasing the software until you know that your documentation is complete.

Documentation should be viewed as an important part of the whole product. If the documentation isn't done, then the product isn't done. If a product isn't done, then it isn't released. So, if you look at it from that perspective, it's not so much "holding back on a release" as "not releasing until the product is complete".

Will the open source community adopt this sort of attitude towards documentation? Hopefully. This doesn't go against the "release early, release often" philosophy either. "Publish early, publish often" is a perfectly reasonable way to treat documentation releases, as well.

So, I guess my answer is: get at least one or two dedicated documentation people for your project. Make sure that these people are kept completely up to date on the development process. And give these people the time they need to get the documentation "in sync" before doing your next release. Don't make your documentation people constantly play "catch up" -- this is extremely frustrating, and is a pretty quick way to discourage your volunteers. Treat them as an important and integral part of your team. The more tightly integrated they are, the easier it is to maintain up-to-date documentation.

a gender thing?
by Jerom

Open source documentation has always been a bit of an outsider within the open-source movement. It's also quite rare to see women in charge of an open source project.

Do you think these two facts are somehow related?

How do you think a larger part of the female population could be involved in open-source projects?

Deb:

Do I think these facts are related? No. There are lots of open-source documentation projects out there that were founded and are maintained by men.

I think a larger part of the female population could get involved with open source projects if, ta dah, they just got involved. Yes, there are probably reasons why there aren't more women involved in open source, ranging from fundamental societal factors concerning our educational systems to the random locker-room chatter that plagues so many online forums. What are the actual reasons? I have no idea. I'm really not the right person to ask, because, well, I am involved in open source. :)

Sorry I can't help.

Translation and Localization?
by Noryungi

As a professional translator and localization specialist, I think I have a fair idea of the challenges involved in producing good technical documents.

My questions are the following: do you think most Open Source Technical Writers or Open Source Programmers produce documents that are easy to translate or do you think this side of documentation could use some improvement?

Deb:

Answer to this bit:

I've never actually done any translation, so I'm hardly an authority on the subject. I suspect that yes, this side of the documentation could use some improvement -- I've been criticized for using various colloquialisms and such in my documentation that really don't translate well, or that are hard to understand if you speak English as a second language. I've also been warned that using puns is a "no no", and that spelling counts. A translator may not recognize an incorrectly spelled word, making it remarkably difficult to translate.

A lot of the free documentation that is currently available breaks one or more of these rules, so it's pretty obvious that they could use some improvement towards simplifying translation tasks.

What are the general rules you apply when considering a new documentation? Possible number of users? Importance of the project? For instance: GNOME may have more users but a program such as SendMail may well be even more important in terms of use.

Deb:

Personally? I pick my volunteer projects the same way most open source coders pick their projects:

1. Does it scratch a personal itch? I am more likely to write documentation for something if I have a really hard time figuring out how to use it and/or I think the existing documentation is weak. Writing documentation for a piece of software is a very effective way to learn how to use it. I also like to think that I'm saving someone else from having to go through the same problems later on.

2. Is it interesting? I'm unlikely to volunteer for something I don't enjoy. That's just a little nuts. If it bores me, I'm not going to spend a bunch of my free time working on it.

3. Is it needed? Writing docs that aren't needed is a waste of time. On the other hand, writing a document that fills a fairly significant gap and that helps a lot of people is an incredibly satisfying accomplishment.

4. Is it fun? For me "fun" and "interesting" tend to be more or less interchangeable, but sometimes boring stuff can be fun too, particularly if it means you get to work with a bunch of neat people. There are lots of uninteresting tasks that can still be fun if you've got the right people to work with.

Generally, if I can answer "yes" to at least two of these four questions, I'd probably work on the project. Or at least consider working on the project. There are a number of projects (Mozilla!) that I would really like to work on. Unfortunately, I just can't take on any more work at the moment.

I suppose you consider translation important to Open Source projects... but do you have a lot of translators that volunteer for that thankless task? And what would you advise me to do in order to have enough time to have a regular job and do my part to bring Open Source to as many people as possible?

Deb:

Translation is absolutely important to Open Source projects. In my opinion, documentation that is only available in English is incomplete. The open source user base is, obviously, multinational, and if we're only providing for one part of that user base, then we're only doing part of the job.

Certainly the "translators" are the smallest group of volunteers we have at the OSWG, and we could always use more. So, no, we don't currently have "a lot" of volunteer translators, unfortunately :)

What should you do in order to do open source work while also holding down a regular job? That's a hard question. I think that the best thing for you to do is to find an open source project about which you are really passionate. Working on open source stuff requires a lot of time, dedication, and hard work. Trust me, after running two projects for over a year, I know. But, if you're really passionate about what you're working on, it doesn't matter how hard or time consuming it is -- you will somehow find the time. (Sadly, "giving up sleep" is often the first result :)

I'm sure that there are a lot of people who would love to contribute to Open Source but who really just can't make time. That's okay. There are ways that people can help without having to invest a huge amount of time -- send bug reports, become a Free Software advocate, donate to some of the Open Source projects that are working on stuff you really like, etc.

If nothing else, take the time to occassionally send an appreciative note to someone who has done something you think is really good -- there's nothing quite as satisfying as getting an email from a total stranger who just says "thanks, I think you're doing a good job". Really. It might seem silly, but there are some days where I have received so much flame mail, or something has gone so stunningly wrong in my project, that I've just wanted to throw in the towel and give it up completely. But getting random notes of appreciation does _a lot_ to offset that. Knowing that there are at least a few people out there who care about what you're doing can really make a difference on those darker days.

From the desk of a real tech supporter
by Signal 11

I've been working tech support for going on three years. I've written my share of documentation, and I've read quite a bit more of it. The problem with linux documentation I think is three-fold:

1) Diverse environment. It's very difficult to write short, concise, documentation when you need to do a writeup for over a dozen possible environments. Take setting up an internet connection on RH6. You could do it in any of the following fashions: pppd, linuxconf (ifup/ifdown), kppp, gnome's modem, etc. Each program does the same thing but has a substantially different interface.

2) Limited experience. Let's face it, most people hacking code haven't done tech support long enough to aquire good writing skills. Their code is beautiful, but their explanations are severely lacking. Learning how to take the knowledge you have and lay it out to someone who knows nothing about it is very, very difficult in any technical profession.

3) Different userbase. Until now, the linux community consisted mainly of highly-trained network and systems people, programmers, and well-learned geeks. Now that the balance is shifting to people who are relatively inexperienced, a huge gaping chasm for documentation has opened up.

Sorry for the length, but it was necessary to get to the question. My question is this: What can be done through an online forum to teach [experienced] people on how to convey their knowledge in a format useful to a new linux user?

Deb:

Well, I don't know right now, but we're about to find out. The Open Source Writers Group is in the process of planning a series of "writer's workshops" that will be held via IRC and mailing lists. If you're interested, we're currently discussing the idea on the oswg-discuss mailing list...you can get information about subscribing here: http://www.oswg.org:8080/oswg/list_info

Perhaps the obvious question, but one to be asked.
by Mercury

I'm a programmer, do several different languages, but I've been in the game too long, I can't view from the prospective of a user anymore, and as such can't write user interfaces nor documentation worth beans..

So my question is this, how would you suggest I learn how to write documentation which users can actually understand?

Deb:

Well...the short answer is "this is why tech writers exist in the first place". Writing good user documentation is challenging for this very reason. That's not really a great answer tho' :)

How can you learn how to do write docs? There are a lot of books out there about technical writing -- do a search for "technical writing" on fatbrain.com, and it returns 203 titles (I have no idea how many of these are actually about tech writing, but the first page of results contained a large number of relevant titles). Go poke around the bookstore and see what you can find.

There's also the "practice makes perfect" school of thought. Write some docs, give them to some people to test and get their comments back. Do some rewriting and editing in light of these comments, then do it again. And again. This can be a pretty time consuming process, of course, but it is a basic form of "usability testing". Usability testing should be done on docs as well as software, and usability flaws should be treated like bugs.

After a few iterations of this, you will probably have some pretty solid docs to release. Make them available to the community ("publish early, publish often") with a note encouraging reader comments and suggestions so you can continue to get more feedback for future revisions and improvements.

Just remember that writing good documentation is actually really hard. Don't get too frustrated if your first few attempts are pretty sucky. Mine were, but that certainly hasn't stopped me yet ;)

How are you going to motivate Open Source writers?
by georgeha

Let me qualify the following statement with my experience, I am a published writer on Open Source material. I cowrote a book on Samba for a few reasons.

1) Kicks, just to see if I could write a book.

2) Money

3) Fame, feedback, geek cred

4) To gain knowledge on Samba and networking.

Writing the book took a lot of my free time for a third of a year. The money was nice, but not especially lucrative. I've had little feedback on this book. I do understand Samba fairly well at this point.

If I understand the Open Source philosophy for programmers, you write code because you need something done. Once it's done, you share the code since it costs little to share it, gain a reputation as a good coder, and possibly parlay that into stock options or a career as a programmer.

The way I understand the Open Source philosophy for writers, you write something about something you know, you spend many hours cleaning it up to make it easy to understand, then you share it. I get little feedback, and I might get a job offer as a technical writer for far less than I'm making in my day job as a technical support person.

To me, it seems that if you want to make it in Open Source, be a programmer, not a writer.

How are you planning to give more cachet to Open Source writers, how are you planning to make it more desirable to make people spend countless hours writing Open Source?

Deb:

Hm. Well, this is a really good question. I don't know. I've been thinking about how to make writing free docs as "sexy" as writing free code for quite a while now, and I haven't come up with anything yet. As I keep saying, writing docs is hard work. If anyone has any ideas about how we could get more people working on docs, I'd love to hear them.

Right now, writing free docs is a labour of love. Unfortunately, there aren't nearly enough of us who love this stuff. We really need more and better free documentation.

Man pages
by Ed Avis

What is your opinion on man pages? Are they an obsolete distraction, or are they still essential for any well-documented program?

Do you think it's reasonable to use man pages for learning, or should they be written only as a reference manual?

Deb:

I think man pages, or some man-page-like facility, is extremely valuable. Having an instant reference available is always a good thing.

Are man pages a good learning tool? Not really. For example, do a `man tar' right now. Go ahead, I'll wait. [pause] As you can see, the current tar man page is awful. If I were a new Linux user and got that when I was trying to learn how to use tar, I'd have no idea where to begin. All I need to do is `tar -xvzf filename.tar.gz', but trying to figure that out from the current man page isn't exactly easy.

Apparently the `info' pages are better learning tools in that they're more geared towards new users (I've not spent a lot of time looking at the info pages, so this is a second-hand opinion). On the other hand, the interface for info pages (do an `info tar') isn't the most user-friendly thing in the world.

What I would like to see (and what I keep getting on soapboxes about after I've had a pint or two at the pub) is a fully cross-platform, xml-aware, user-friendly, Mozilla-based help browser. Yes, there are a lot of buzzwords in that description, but I still think that it would be a phenomenally useful tool. Providing a usable interface for online help is at least as important as having usable content to display within that interface.

After building the help browser, the next step would be to build an easy-to-use integrated authoring system. That's a bit more challenging, of course, but not unrealistically so. The easier it is for people to write documentation, the more documentation is likely to get written.

If these tools existed, then it's likely that the Open Source community would begin generating more and better content -- `reference' stuff like man pages, `learning tools' like info pages and HOWTOs, and more. In my opinion, being able to create and automatically cross-reference all this stuff and have it all display nicely in a clean interface would go a long long way towards making Linux easier to learn and use.

If anyone's interested in helping me design and build this stuff, let me know :)

Who is the target audience?
by Seth Scali

Okay, this seems like a basic question, but it's really kinda thorny, isn't it?

On one hand, there's me:

If I want to install FooWidget 2.6, I know that I can do the following:

% ftp ftp.foowidget.org
get foowidget-2.6.tar.gz quit
% tar -zxf foowidget-2.6.tar.gz
% cd foowidget
% ./configure (or make config, etc.)
% make
% make install

So a doc that says: "FTP the file from ftp.foowidget.org, untar it, run configure, run make and make install" doesn't do me a whole bloody lot of good. If I'm looking at the doc, it's usually because there's a problem (i.e., it won't compile or run right).

So for me, the ideal doc is actually kinda technical-- maybe a troubleshooting guide, or a list of known bugs and workarounds.

But then there's my mother:

"What the hell is FooWidget, and why the fuck do you want me to install it?" (Yes, that would likely be her-- she's been known to make sailors blush).

For her, the step-by-step instructions are all she needs (she already knows how to troubleshoot -- she picks up the phone and calls me at work). So the ideal docs for her are the ones that will hold your hand.

So for whom do we write our docs? My mom (in which case, I will feel insulted that you think I need to be taught how to su root) or me (in which case my mother tells me that this Linux bullshit is too hard, and she wants me to re-install Windows)? Is there a compromise between the two (like with the LyX documentation, perhaps)?

Deb:

One of the most important things to do before starting to write documentation is to define your audience. Who are you writing for? Kernel hackers? New users? Advanced users?

You cannot write documentation that will be useful for everyone. That's just reality. As I said earlier, you're either going to end up with a huge mess of a document that won't be of much use to anyone, or you'll end up with a really "generalized" document that won't be of much use to anyone.

So, to answer "is there a compromise between the two?": No. Not really. You have to figure out who you're trying to address in your document, and just focus on that one particular audience.

Embedded Documentation/Extracting Docs from code
by dlc

As a Perl programmer, I am very impressed by the POD (plain old documentation) system that is almost universal to Perl modules and scripts -- embedding documentation into the code, with a corresponding tool to extract it. I also think that Javadoc is pretty cool -- it actually pulls out function and variable declarations and creates hyperlinked documentation based on that. Given that software documentation tends to lag behind the software itself, do you that there is a future in software that generates documentation from source code, in a more general way? Something like a set of scripts written in Perl (for example, due to it's excellent pattern matching) that would read your C/Lisp/C++/Java/Perl/Python/Pascal/whatever and generate documentation (perhaps XML in a standard format that can then be run through a 2man or 2info or 2pod).

Deb:

Okay, if I understand the question correctly, you're asking: do I think that we will eventually generate documentation from source code?

Well, it depends what sort of documentation you're talking about. If you're talking about documenting the code itself, maybe/yes. But if you're talking about user documentation, no. User documentation should be task-based, telling the users how to do the various things they want to do. Documentation generated from code is more likely to be feature-based, talking about what the various functions and features of the software are, etc.

Task-based and feature-based documentation are very very different things.

All that said, I want to make an amendment: where I said "no", I really meant "not yet". There are some really interesting technologies out there, and some really smart people thinking about some of this stuff. It might very well be possible that we could eventually create a system that allows us to auto-generate a lot of documentation from code. Right now, however, I cannot see it becoming a reality in the near future (feel free to start hacking to prove me wrong ;)

Also keep in mind that this question ranges a little bit away from my area of expertise. My official answer really is "I don't know", so if I'm completely wrong on this one, feel free to correct me.

More importantly, perhaps, do you think there is any reason to develop a XML dialect specifically for documentation?

Deb:

Well, there is one: DocBook.

Ok Deb, tell me...
by Xiphia

Firstly Deb, I have nothing but respect for your technical ability and your work with the OSWG. What I want to know is, how does a savvy professional and self-titled feminist like yourself justify your work on LinuxChix? Let me explain...

When I first discovered the LinuxChix site I was very excited... here was an opportunity to meet some of the other ladies in the industry, compare stories, and talk tech. I was sorely disappointed though... after a few weeks of monitoring the lists, I saw little technical discussion that wasn't already covered by mainstream FAQs and discussion groups, a lot of talk about boyfriends, and a fair amount of male-bashing radical talk about the need for things like women-only seminars and distributions.

Now I'm a woman in the industry, and I strongly feel that the day I can't hold my own with the big boys I should turn in my engineering ring. What's the deal? Do women need these special services because we can't handle the REAL distributions and seminars? I think not, and if a man said that (and I don't know any who would - in my experience most are EAGER to let the ladies play too) you'd smack him so hard his head would spin!

Now I believe I understand (and support) your original intent in founding the group, but on reflection I am wondering if perhaps in creating a ladies-only (or at least ladies-primarily) environment you have done the ladies a disservice. Why encourage women to cut out the majority of the knowledge base by submitting questions to LinuxChix instead of either finding their own answers online or querying the more mainstream lists?

Does LinuxChix as it exists today meet its original goals or your original vision in founding it? If so, how can you prevent it from becoming a crutch for those ladies unwilling (or unable) to deal with the real world? I hope you don't feel this is a slam... as I said, I respect you both personally and professionally, but this question has been bugging me for some time, and I had to get it off my chest. I look forward to your response.

Deb:

Sorry Robin, this one is far too political and way too off topic.

- deb

chromatic has reviewed O'Reilly's DocBook. Written by Norman Walsh and Leonard Muellner the book is: "A hefty reference of DocBook Elements and Entities, with an emphasis on customization and configuration -- if you know what that means, you'll find this book useful." DocBook: The Definitive Guide author Norman Walsh & Leonard Muellner pages 652 publisher O'Reilly & Associates, 10/1999 rating 8.5/10 reviewer chromatic ISBN 1565925807 summary A hefty reference of DocBook Elements and Entities, with an emphasis on customization and configuration -- if you know what that means, you'll find this book useful.

DocBook, a SGML DTD for technical writing and documentation, has been widely adopted by a number of organizations and authors. Many commercial and free tools support it, and the specification is under active development. DocBook: The Definitive Guide is the official documentation.

Content The first section of the Guide discusses SGML and XML concepts, as well as the specifics of DocBook. Be warned that this is not a particularly gentle introduction -- familiarity with well-formed HTML will help, but the Guide is a reference, not a tutorial.

With that in mind, the introduction walks through creating, parsing, and publishing valid DocBook documents. As the specification is cross-platform and not tied to any particular editor, the discussion focuses on the logical divisions and elements and practices of editing a document, rather than the particulars and mechanics of using a particular tool. The Parsing chapter gives solutions for some of the more common validation errors ("DTD not found", "misspelled tag", et cetera). The Publishing chapter zeroes in on stylesheets, focusing on DSSSL and the Jade utility. The authors demonstrate a stylesheet based configuration which will simplify the customization and publishing processes for different output formats.

The bulk of this book is a reference section which lists DocBook elements alphabetically. Each element has a content model lifted straight from the DTD, a list of applicable attributes, a list of parameter entities in which the element occurs, a description of what is is and where it might be used, processing expectations, and examples of its use mentioning any gotchas. Some elements are very simple, while elements higher in the hierarchy have much more complex requirements and nuances. Deprecated elements are marked with the appropriate version of the specification, with valid replacements suggested.

Each parameter entity has a synopsis and a description, listing all of the elements in which it occurs. Finally, each character entity is listed along with its Unicode number, a glyph, and the ISO decription. Characters are listed by character set, in alphabetical order.

The final section wraps up odds and ends in Appendices. This includes a section on installing the DocBook DTD, a discussion of the past and future versions of DocBook, and a useful list of additional resources (including pointers to SGML and XML tutorials). Another appendix is devoted to the differences between standard DocBook and XML. The included CD-ROM contains the complete SGML and HTML versions of the Guide itself, various DocBook DTDs, stylesheets, and applications mentioned in the book.

Pros and Cons The Creating section includes an enumeration of the categories of DocBook elements. This includes sets, lists, and components. It would be nice to have a comprehensive list arranged hierarchically, in addition to the alphabetical reference. (Occasionally an author might want to search for the correct element in a specific context. Why not?)

Including a troubleshooting section, so to speak, in the Parsing chapter was an excellent idea. One might almost conclude that the best way to think of DocBook is as a code library instead of a huge tree of entities and options. (The Customization chapter bears this out.) The authors also present various ways to accomplish specific goals, always with an eye out for the best and most flexible option.

As mentioned before, however, the tutorial value of the Guide is low, unless you're already comfortable with SGML or XML. DocBook's probably not the place to start out anyway, but someone who needs a quick introduction to DocBook for whatever reason ought to look elsewhere first.

Summary You may never use all of the information found here -- but if you're developing a customization layer, building stylesheets, or just using DocBook to mark up your writings, you'll find this book invaluable. (If you're the kind of person who can read the DTD and absorb the meaning there, you might not need it.) For anything more than casual use of the DTD, this is the first and last place you'll look.

Table of Contents

1. Introduction
2. 1. Getting Started with SGML/XML
   2. Creating DocBook Documents
   3. Parsing DocBook Documents
   4. Publishing DocBook Documents
   5. Customizing DocBook
3. Reference
4. 1. DocBook Element Reference
   2. DocBook Parameter Entity Reference
   3. DocBook Character Entity Reference
5. Appendixes
6. 1. Installation
   2. DocBook and XML
   3. DocBook Versions
   4. Resources
   5. What's on the CD-ROM?
   6. Interchanging DocBook Documents
   7. DocBook V3.1 Quick Reference

Read this book online at Docbook.org.