oXygen XML Editor

Docbook Basics and References

1. What is docbook.
2. Where can I get the Docbook DTD?
3. Namespaces?
4. Quick Reference card
5. What is docbook used for?
6. Docbook Tutorial
7. Docbook tutorial
8. For DocBook beginners
9. Usage stats
10. Docbook processing model
11. Where can I read about Docbook
12. Is there a mailing list
13. List Basics
14. How old is docbook
15. How can I format a Docbook Document for presentation
16. Version tracking, in DTD and Stylesheets
17. Win32 Access to latest docbook material on Sourceforge.
18. SGML and XML setup on Windows
19. XML editors for docbook
20. Modular documents
21. New to docbook on Redhat
22. What's the difference between SGML and XML docbook
23. Is there a simple docbook?
24. Docbook on Mac (OS X)
25. Good docbook tutorial
26. Docbook on Mac OS
27. Docbook presentations
28. Docbook spreads again! More points of contact and feeds
29. Content Management systems
30. Modular docbook XML files writeup
31. Do the stylesheets and DTDs fall under any licenses?
32. HOWTO for docbook
33. A Docbook HowTo
34. Installing and using docbook - Documentation
35. An Introduction to docbook by example
36. German docbook mailing list
37. Czech DocBook site

1.

What is docbook.

Norm Walsh

DocBook provides a system for writing structured documents using SGML or XML. It is particularly well-suited to books and papers about computer hardware and software, though it is by no means limited to them.

In short, DocBook is an easy-to-understand and widely used DTD. Dozens of organizations use DocBook for millions of pages of documentation, in various print and online formats, worldwide.

2.

Where can I get the Docbook DTD?

Norm Walsh

You can get the most up-to-date version and information about DocBook from theDocBook web page.

3.

Namespaces?

Norm Walsh (May 2003)



| Is it possible to add a namespace to my XSLT that identifies 
| docbook elements?

No.

(Stop beating about the bush Norm!)

| (Primary purpose is to make the intellisense
  work, 
|but shouldn't it be more common to use a namespace and prefixes for 
|DocBook elements in XSLT, than not use it?)

Any feature that applies only to elements in an explicit namespace is broken. (IMHO, naturally.)


| If so, is there a common namespace prefix for DocBook 
| (db: for instance) like fo:
| for XSL-FO?

DocBook elements are not in a namespace. If we were starting from scratch today, I'm sure we would put them in a namespace, but DocBook has been around for more than a decade. It long predates namespaces.

Putting DocBook in a namespace today would break every existing tool. That's a huge backwards compatibility problem. We may someday feel that there is a compelling reason to do so, but no one has articulated one yet.

4.

Quick Reference card

The mailing list people

Norm and Lenny have written the definitive guide, but omitted a quick reference guide, so here it is. Three forms. A single sheet for printout, in PDF(thanks to Jeff Beal), and an HTML page, linked through to the definitive guide.

For those not on line, here is the source XML in two forms. One marked up such that you can link it to your own copy of the definitive guide on disk, and another if you need to re-format it or wish to add to the single page format. Hope you find it as useful as we do.

5.

What is docbook used for?

Collated by DaveP

These are some of the answers to that question. Quite extensive, isnt' it!

  1. Books for print/trade publication (or eventual print/trade publication). Processing XML with Java Learning XML (and, I think, other O'Reilly titles). DocBook: The Definitive Guide. An introduction to XSL-FO http://www.dpawson.co.uk/xsl/sect3/bk/index.html

  2. Fairly heavy use within O'Reilly, the publishing house

  3. Maintaining websites

  4. FAQ websites

  5. Computer documentation, including

    xfree86
    GNOME
    KDE
    FreeBSD
    The Linux Documentation Project uses DocBook extensively for its documentation.
    PHP
  6. Producing presentation slides

  7. Producing generated documentation from code comments (GNOME, Linux kernel!)

  8. For training materials. From a single document, I produce presentation slides, sample files, and printed handouts.

  9. I also routinely use it for whitepapers, like system specifications and proposals.

  10. Embedded documentation in code: XSLT Standard Library

  11. Formal specifications. RELAX NG XML schema language official committee specification

  12. Documentation for commercial software and hardware. Sun, Red Hat, SuSE, HP, Cogent Real-Time Systems, Conectiva, Rational, Mandrakesoft, Caldera, Apple (Darwin docs)...

  13. Most everything I've ever written for xmlhack. My Don't Learn XML" article

  14. Theses and disserations

  15. My company (Myrnham Associates) use Docbook as the content store for Instructor-Led-Training material. We have an Authoring application to create modular training using Docbook and a customisation tool that allows you to merge chapters/topics from multiple sources into a customised manual. The output is a Word document. These apps run on Windows.

  16. I wrote a reference guide for Web and publishing using Docbook, This is about 60 pages with TOC and index

    This was then the basis for another document used as reference part to a 300 page book about game creation (to be published). Out of "historical" reasons I use Docbook/SGML, also I have heard that the RTF (very important here) output is the best so far here.

  17. I use it to produce the documentation for an application I manage. From the single documentation file I produce the printed manual, a Windows Help file, and an online html version.

  18. Using single docbook source with various stylesheets to document applications in the following ways:

    Online manuals (PDF, HTML)
    Context-sensitive help (HTML, HTML Help)
    Man pages and formatted text (using non-xsl HTML -> text conversion)
    Filtering conditionalized versions (using profiling)
  19. Here at our group within Mitel Networks, I have used DocBook SGML and XML extensively for:

    User Guide
    HOWTO documents
    Technical papers
    Courseware (internal)
    FAQ pages
    Presentations
  20. The course catalog of the school I'm working in is tagged with a non technical subset of docbook. It is then published both in online and printed form through the use of the DSSSL stylesheets (http://www.insa-tlse.fr/ects).

  21. I work for a company that develops a commercial software product. I maintain documentation for a department of ten to fifteen people. Along with a moderate sized FAQ list, short articles comprise the bulk of it, regarding:

    the product itself
    the automated test tool documentation
    the defect tracking database
    related software (O/S, networking, Apache, SQL, etc.)

    Some of this duplicates already existing documentation, but is tailored for our environment .

    Two years ago, I converted from HTML/CSS to DocBook SGML 3.1, using Norm's DSSSL stylesheets. Last year I converted to DocBook XML 4.0, using Norm's XSL stylesheets. I think the learning curve for XML, XSL, and the associated tool chain is, and will continue to be, smoother than for SGML, DSSSL, etc.

    The majority of the documentation for the product's next release will have DocBook source. A lot of this was converted from FrameMaker.

    I'm happy with DocBook for departmental documentation. However, I write the majority of the content. I'm a little worried that it won't be maintained very well when I leave.

    I think DocBook will be a win for the product documentation. However, the process is still immature.

  22. We are using DocBook for our courses. We are planning a January launch with all of our courses generated from DocBook into HTML.

  23. We (Encorus Technologies) use a (relatively small) docbook extension for generating 3 targets from a single source:

    1. product API specifications (targeted at internal developers),
    2. API reference manual (targeted at our customers),
    3. API validation code (different programming languages).

    Single source is extremely useful here as it makes keeping consistency much easier.

    Plain docbook is used for other specifications and requirements documents.

6.

Docbook Tutorial

Dan York

FYI, the DocBook tutorial I gave at the Ottawa Linux Symposium a week ago is now online at: lodestar2.com

The slides are there, along with source files, stylesheets, etc.

The session went quite well and I received a good number of positive comments about it. It was fun having Daniel V in the audience as well!

P.S. Jirka, the 'profiling' stuff you (and Norm) did is VERY cool! I didn't really know it was in the stylesheets until I was preparing for this presentation.

7.

Docbook tutorial

Ashley J.S Mills

I have written a DocBook 'tutorial' that is ready for scrutiny by the masses. It is located here: Birmingham Uni

The 'tutorial' is quite messy. I could do with cleaning a few things up. However, I have just started my second year at university so I doubt I will have *much* time for this.

There are bound to be errors. I encourage people to use the online forms to submit comments. Hopefully I will get round to fixing any errors and improving the tutorial. I would like to write another one (as a replacement really), that focuses exclusively on XML and is more clear and concise.

8.

For DocBook beginners

Camille Begnis



> I'm a DocBook beginner, trying to write my first "Hello World" document.


> I'm a good LATEX writer and now I'm intending to migrate to DocBook due
> to it most modern approach, extensible design, etc.

> Yesterday I was trying to compile some examples I keep on the web, but
> none of them get working.

> Can you get some tip on "how to create a simple document using DocBook"?

Your entry point: Docbook wiki Hopefully you can find the wiki in proper conditions.

You can have a look at my starter kit: camille.begnis.org

And you also may be interested in an advanced system for your project: mandrake.com

9.

Usage stats

Matt Gruenke

Date Dec 2001

I noticed the download statistics for the Sourceforge DocBook Modular Stylesheets project page. In about the last 2 months, the DSSSL stylesheets have been downloaded about 3,600 times. The XSL ones (disregarding the experimental 1.46 release) have about 2,600. That suggests that as many as 6,000 installations are actively tracking and using just these stylesheet packages!! Furthermore, some projects like the Linux Documentation Project have their own customization and so they may count as only one download, even though they have hundreds (thousands?) of active participants.

Finally, consider that these stylesheets are included with RedHat (at least in 7.x) as an rpm, so none of those users are even counted, here. See for yourself:

Table 1. Docbook downloads

packagereleasedate.tar.gz .zip
dsssl 1.74b2001-11-29 21:00 43 11
  1.732001-09-28 21:002,5661,078
 1.722001-08-05 21:001,300738
dsssl-doc1.742001-11-28 06:276424
 1.732001-09-28 21:001,837660
 1.722001-08-05 21:00830520
xsl1.47-exp2001-11-27 21:009646
 1.46-exp 2001-10-12 21:00500614
 1.452001-09-28 21:00 1,3441,299
  1.442001-08-13 21:001,1851,050
     

Of course, I have no doubt that maybe 30% to 60% of the downloads are individuals merely out to satisfy some casual curiosity about "this DocBook thing". However, on the other end, you have cases like mine, where a dozen people are using infrastructure that I deployed from only one download. I'm assuming that there probably aren't many who downloaded both the DSSSL stylesheets and the XSL ones.

Also, there are those who either use other tools for styling their DocBook, or aren't as proactive about keeping up to date on the latest DSSSL or XSL stylesheets.

Finally, I think it's worth reiterating that there are other ways to get these stylesheets that won't be reflected in the above statistics (such as via RedHat RPMs).

Anyhow, good luck with your evaluation, decision, and justification.

I've got a partially-finished advocacy document and have barely started documenting my industrial-strength deployment strategy. I plan to post these documents, when I finish them, but that may not be for a while.

In my opinion, what you really want to focus on is the benefit of using a DocBook-based documentation infrastructure (e.g. the potential for: revision-control, modular document partitioning, vendor and platform independence, scalability, rich semantics, auditing, repurposing for different media, decoupling of content and presentation, etc.) vs. the cost of deployment & maintenance and potentially augmenting the vocabulary to provide semantics better adapted to your field and customizing the stylesheets for the various media and styling requirements you've got. I think the choice is obvious, for projects of any significant scale. Also, it's worth noting that the bulk of the cost of using DocBook is incurred up front.

Bare in mind, however, that the highly technical bias of myself an my fellow co-workers, who use DocBook. To gain some of the benefits I mentioned, requires a well thought-out deployment by someone with some knowledge of large-scale system administration and experience in buildsystem engineering. Though a UNIX-like environment is by no means necessary, people with such experience, in a UNIX environment, will tend to have a better handle on these sorts of issues and a means of dealing with them. In the end, though, your usage model expectations/requirements are what really dictates the tradeoffs in which of benefits you can enjoy, and should be one of the primary drivers of your deployment strategy/architecture.

10.

Docbook processing model

Nik Clayton

A diagram which maps out the relationships between the various components in the FreeBSD DocBook pulishing toolchain (used to generate high quality PS, PDF, TXT, PDB, RTF, and HTML output).

I thought it might be useful for people who are trying to understand how the various technologies and tools fit together.

>  The diagram, if I am reading it correctly, 
> implies that there is a separate output
> for PDF and PS.

Yes. We've (FreeBSD Doc. Project) found it's worth doing this.

The reason for this is that tex and pdftex have different ideas about what the default graphic filename extension should be. So, when we include graphics in the documents, we omit the extension.

When you run the output through tex it automatically adds a .eps extension, and does the right thing. When you run the output through pdftex it looks for .pdf files first, before falling back to .png files. This ensures that you get high quality images whatever your final output.

There are other options you might want to use (such as the url package) that might only apply to PDF output as well. So splitting them up is quite useful.

See the FreeBSD make(1) infrastructure files at freebsd for the gory details. It's also worth noting that this toolchain produced the published version of the second edition of the FreeBSD Handbook (mall.daemonnews.org, Amazon, etc), so it's certainly good enough for commercial work.

11.

Where can I read about Docbook

Norm Walsh

The online version of DocBook: The Definitive Guide at its own website has been republished under the GNU FDL. Version 2.0.2 is a "work in progress". It purports to document DocBook XML V4.1.2 with the EBNF, HTML Forms, MathML, and SVG modules. As it is being actively updated, it may be inconsistent in some areas.

12.

Is there a mailing list

DaveP

Yes, two in fact. One for markup related questions and answers, and one for the support of applications of docbook, which tends to focus on such things as stylesheet usage.

docbook@lists.oasis-open.org is for general DocBook questions.

See the Oasis page for further information, about the lists, and for subscription and unsubscribing.

Broadly its markup questions on the docbook list, and styling questions on the docbook-apps list.

13.

List Basics

Norm Walsh

This information[1] is posted to the DocBook and DocBook Applications mailing lists (and their digests) at regular intervals under the subject line DocBook list guidelines.

Posting

Only subscribers can post to mailing list, and only from the address they used when they subscribed.

There are two DocBook-related lists: docbook and docbook-apps. The docbook list is for general questions about DocBook. The docbook-apps list is for questions about applications (stylesheets, transformation tools, publishing tools, processing requirements, etc.) that use or work with DocBook.

Specifically:

* Questions about DocBook markup (How do I markup a Widget? What's a FuncSynopsisInfo for?) should be sent to the docbook list.
* Questions about XSL or DSSSL stylesheets, publishing DocBook documents on your platform of choice, support for PostScript, PDF, or other types of output, questions about Windows or Unix applications that can consume or produce DocBook should be sent to the docbook-apps list.

Do not begin your subject line with help or subscribe since the list software will bounce the message because it looks like is an administrative request.

Do not use un-informative subject lines like Urgent, Easy question, or Problem. Instead, use a meaningful subject line that will make sense to the people whose help you are trying to get.

Both subscribers to <docbook@lists.oasis-open.org> and < docbook-digest@lists.oasis-open.org> should post their messages to < docbook@lists.oasis-open.org>. The messages will be received by both subscribers to the list and subscribers to the digest.

Both subscribers to <docbook-apps@lists.oasis-open.org> and < docbook-apps-digest@lists.oasis-open.org> should post their messages to <docbook-apps@lists.oasis-open.org>. The messages will be received by both subscribers to the list and subscribers to the digest.

Do not start a new thread by replying to an unrelated message and just changing the subject line since the header of your message will contain references to the previous message and your new message will appear in the archive as one of the replies to the original message. It is better to start a new message for a new thread.

Before You Post

1. Check that you are posting to the right list.
2. Make sure you are posting from the account that you used to subscribe. If you post from another account, your message will be delayed until it is approved by hand.
3. Check that your question isn't already answered in the mailing list archives at http://lists.oasis-open.org/archives/docbook/ or http://lists.oasis-open.org/archives/docbook-apps/.
4. If you are replying to a post, trim the quoted message to just the parts to which you are replying.

Replies Go to the Author

The DocBook lists don't set the Reply-to: header on messages (see Reply-To Munging Considered Harmful) so replies go to the author by default. If you want to reply to the list, make sure you include the list mailing address in your reply.

Most mail readers make this easy by offering two forms of reply: reply/group-reply or reply/follow-up, for example. If you want to post to the list, make sure you select group-reply or follow-up or whatever your mail reader calls it.

Use Short Quotes of Previous Messages in Replies

Please do not quote entire messages just to add a few lines at the beginning or end. Instead, quote the parts to which you are directly replying or quote enough to establish the context.

Everybody on the list has already received the message that you are quoting, and anyone searching the archive will find your message and the previous message listed under the same thread.

Subscribers to the mailing list will just ignore most of the quoted messages and move to the next post, but subscribers to the mailing list Digest will mostly have to page past the quoted messages to reach the next material in which they are interested in reading.

Do Not Post Attachments

Since mailing lists have in the past been unwittingly used for spreading viruses in e-mail attachments, all e-mail attachments are banned from the DocBook lists.

Most relevant documents (SGML and XML files, stylesheets, documents, etc.) are text files, so this does not affect the majority of posts to the list since you can include the files' text in the body of your message. If you need to refer to a binary file such as a PDF document, you should put the file on a Web site or FTP site and include the file's URL in your post.

Cross-Posting

Cross-posting between the DocBook mailing lists or to other lists is often counter-productive unless everybody who replies to the thread is on both lists. Cross-posts from non-subscribers continuing the thread will bounce, and mailing list subscribers who are not also on the other list will only see half of the thread, as will those on the other list who are not also on the mailing list. Subscribers to both lists will see two copies of the message, annoying them as well.

Digests

Digests--copies of several days mailing list messages, a 100K chunk, sent as one email message--are available. To subscribe to the docbook-digest, send a subscription request to To subscribe to the docbook-apps-digest, send a subscription request to Remember to unsubscribe to the undigested list, unless you want both.

Unsubscribing from Docbook List

To unsubscribe from the DocBook mailing list, send mail to < docbook-request@lists.oasis-open.org> with unsubscribe as the body of your message.

Unsubscribing from Docbook-Apps List

To unsubscribe from the DocBook Applications mailing list, send mail to <> with unsubscribe as the body of your message.

Unsubscribing from the Docbook Digest

To unsubscribe from the DocBook digest list, send mail to < > with unsubscribe as the body of your message.

Unsubscribing from the Docbook-Apps Digest

To unsubscribe from the DocBook Applications digest list, send mail to <> with unsubscribe as the body of your message.

If You Stop Getting Messages

If you stop receiving mailing list message, you may have been removed because mail to you was bouncing. You are not being picked on, and you can just rejoin the list.

Archive

The DocBook mailing list messages are archived at http://lists.oasis-open.org/archives/docbook/.

The DocBook Applications mailing list messages are archived at http://lists.oasis-open.org/archives/docbook-apps/.

Reporting Bugs in Software

Confirmed bugs in software should be reported to its author rather than to the mailing list, but it is appropriate to discuss suspected bugs and workarounds on the docbook-apps list only.

See also: the DocBook Project at SourceForge.

The recommended way to report bugs in software maintined in the DocBook Project at SourceForge is with the project tracker mechanism. Please be sure to attach a test case that demonstrates the bug.

Further Information on DocBook

The DocBook Home Page , DocBook: The Definitive Guide, DocBook DSSSL Stylesheets DocBook XSL Stylesheets

14.

How old is docbook

Norm Walsh

DocBook is almost 10 years old. It began in 1991 as a joint project of HaL Computer Systems and O'Reilly. Its popularity grew, and eventually it spawned its own maintainance organization, the Davenport Group. In mid-1998, it became a Technical Committee (TC) of the Organization for the Advancement of Structured Information Standards (OASIS).

In 1994, the Davenport Group became an officially chartered entity responsible for DocBook's maintenance. DocBook V1.2.2 was published simultaneously. The founding sponsors of this incarnation of Davenport include the following people:

Jon Bosak, Novell
Dale Dougherty, O'Reilly & Associates
Ralph Ferris, Fujitsu OSSI
Dave Hollander, Hewlett-Packard
Eve Maler, Digital Equipment Corporation
Murray Maloney, SCO
Conleth O'Connell, HaL Computer Systems
Nancy Paisner, Hitachi Computer Products
Mike Rogers, SunSoft
Jean Tappan, Unisys

15.

How can I format a Docbook Document for presentation

DaveP

Based on work done by Norm Walsh, and now supported by a growing group of users, stylesheets are available to convert Docbook documents into either web based or paper based formats for presentation. This is one of Docbooks biggest benefits.

For all of them you will need DocBook stylesheets available from Sourceforge

16.

Version tracking, in DTD and Stylesheets

Norm Walsh





> Isn't there a possibility that a patch release will alter the DTD in
> an incompatible fashion, such that a valid XML DocBook x.y.z document
> might not be valid for x.y.(z+n) (for n > 0)?  Or is this explicitly
> prevented, requiring that the issue be addressed in the next major
> revision? 

The latter. The TC does not make backwards incompatible changes in point releases. It's even "worse" than that. If the TC decided tomorrow to make a backwards incompatible change, it would have to be announced in DocBook V5 and could not be implemented until DocBook V6.

> If the latter, then it would seem convenient to treat minor
> revisions as RCS branch revisions, such that it aliases to the latest

There is no direct correlation between the revision numbers (or branch numbers) in CVS and the actual DTD releases. I do, as a matter of course, provide tags for the revisions that form a particular release, but the CVS repository is not the official source for DocBook. The official sources for DocBook are the files that exist on www.oasis-open.org.


> If the above versioning policy is followed, then documents should only
> reference a specific minor revision, while the application is free to
> use the latest compatible patch/superset.  This could be done through
> catalog files.

You can arrange for this behavior using catalogs without changing the versioning policy. Just make your catalog point to the most recent point release for all public identifiers and URIs that are appropriate.

(If we were starting over, I would very likely argue that we should implement a versioning policy along the lines you suggest, but it doesn't seem worth the fuss of changing now)


> I was also wondering whether it's possible that stylesheets (DSSSL or
> XSL) might be dependent on a minimum minor revision (e.g. requiring
> DTD version 4.7 or greater), or should the only dependency they have
> be on the major revision (e.g. requiring version 4 of the DTD)?

I've tried to make the stylesheets support all versions of the DTD. Most of our backwards incompatible changes have, in fact, been fairly minor.

17.

Win32 Access to latest docbook material on Sourceforge.

DaveP and Howard Katz.

If you want access to the very latest docbook material from the Sourceforge site, then you may need CVS to get it in bulk. Norm tells me its a doddle on *nix, but I found it non-obvious on win32. (Why do we stick with M$ ?)

Install a copy of wincsv 1.2 on your machine As of October 2001, I'd recommend not trying the 1.3 beta software on win2K, it bombed on my machine. Obtained from sourceforge, using the x86 version 1.2 (2001-2-21) link near the top of the page.

Note the relationship with tcl,

The compiled WinCvs for Windows 98, Windows NT/2000 (Optionally you may want to install TCL8.1 (or higher) in order to get the macros working, see the TCL home page).

I got tcltk 8.3.2 since the link on the previous page appeared dead. I installed this prior to wincvs.

Once you've got wincvs intalled, go to the 'Admin' menu and select 'Preferences'. On the 'General' tab where it says "Enter the CVSROOT:", enter

:pserver:anonymous@cvs.docbook.sourceforge.net:/cvsroot/docbook

(unless you have a password, in which case replace anonymous with your login name)

Below that, where it asks for 'Authentication:', select

"passwd" file on the cvs server

That's the hard part! That's it for set up.

Now when it comes time to do an actual checkout, you just have to indicate (1) which subproject you're going to download, and (2) what directory it's going to on your machine.

The default drive initially selected for downloads is C:. If you want to change to another directory, it's a bit obtuse but go to "View::Browse location::Change" and point to the D: drive. (You can also leave it pointing at C: and change it in the checkout dialog every time you do a checkout.)

To do the actual checkout, under the "Create" menu, select "Checkout module". Under "Local folder to checkout to:", name the folder you're saving your downloads to. If the directory doesn't exist, you'll be asked if you want to create it.

Under "Enter the module name and path on the server:", put the subproject path.

If I want to grab Bob Stayton's XMetal setup files, for example, I enter contrib/tools/xmetal and hit "OK". That'll do it!

18.

SGML and XML setup on Windows

Markus Hoenicka

SGML for NT is a tutorial that explains how to set up and use free software to edit and process SGML and XML documents on M$ Windows:

See Markus web site.

New in this version:

Now covers basic XML tools. This includes xslide (Emacs mode for XSLT), xsltproc, Xalan, XT, Saxon, FOP, JFOR, and PassiveTeX. The installation of TeX, JadeTeX, and xmltex/PassiveTeX was completely reworked. The Cygwin version now uses the Cygwin TeX binaries and teTeX, the plain Win32 version uses fpTeX instead of MiKTeX. All other tools were updated as appropriate.

Feedback, comments, bug reports are very welcome.

19.

XML editors for docbook

Peter Ring

Markus great setup website "SGML for NT: A brief tutorial how to set up a free SGML editing and publishing system for Windows NT" A very complete guide that by itself constitutes an example of what you try to accomplish. Somewhat biased towards SGML, jade and TeX.

If you lean towards XML and XSLT, supplement the above with: XSLT-process "XSLT-process is a minor mode for GNU Emacs/XEmacs which transforms it into a powerful editor with XSLT processing and debugging capabilities. XSLT-process is not an Emacs major mode for editing XML or XSLT files, for this you should use Lennart Staflin's PSGML, James Clark's sgml-mode.el major mode (distributed with GNU Emacs), or Tony Graham's xslide XSLT mode. "

If you'd rather have everything in a package with all the decisions made on your behalf:

Sebastians setup "Inspired by Kevin Russell's now rather old Ebenezer suite, we have bundled emacs, psgml, and a bunch of other useful stuff together as a single archive for installation on any Windows 32 bit system (30 Mb), or any Unix system (29.5 Mb); This setup was last updated on 20th Sept 2001." Includes TEI and DocBook support. Also for Unix.

XAE "XML Authoring Environment for Emacs" For XML.

If it's not apparent already, I'm somewhat biased towards emacs. Even if you may be able get Arbortext Epic, Softquad XMetaL, or Corel WordPerfect, you'll sometimes need more hands-on control.

There's an introduction to emacs + psgml at Bob Snee's site Be sure to see the PSGML Tricks page: http://www.snee.com/bob/sgmlfree/emcspsgm.html

BTW, emacs 21 has just been released (though not quit yet on WindowsNT). While better support for fonts and images have been available for some time in XEmacs, the release of emacs 21 will probably spur the development of better visual feedback.

If you absolutely can't stand emacs, here's some alternatives:

epcEdit Tcl/Tk-based SGML and XML editor. Does CALS tables. 60-days evaluation

XXE Java-based XML editor, in beta, but useful. Does CALS tables to some extent

Morphon Java-based, XML editor. Does not do tables (when I last checked). 30-days evaluation

XED Python/Tk based, XML editor. Does not do tables

I would like to suggest an xml editor for the "XML editors for docbook" section Name: <oXygen/> XML Editor Url: oxygenxml.com Download: download site Norm rates it. See his blogg.

Iulian Velea

20.

Modular documents

Christopher R. Maden



>My intent was to have a "wrapper" file that included each chapter in as an
>external entity, in the correct order. But I can't do that, as it is made
>clear that external entities cannot have the <xml> declarative tag at the
>very beginning of the document.
>
>(Note: it may be the <DOCTYPE> declaration, and not the <xml> tag, 
> that
>interferes with entity inclusion. I haven't tried in a few months, and I'm
>not sure. But one of them cannot be present in an external entity, and both
>are needed for my XML tools to work properly.)

The XML declaration

<?xml version="1.0" encoding="US-ASCII" standalone="yes"?>

can only occur at the top of a document. However, the text declaration

<?xml version="1.0" encoding="UTF-8"?>

can occur at the top of any external parsed entity. Note that the only difference is the standalone declaration; unless you really need that, just leave it off and you'll be fine.

As for the DOCTYPE: this is an old problem, and more likely the source of your woes. If your editor supports SGML Open catalogs, you can associate a doctype with a root element type, meaning that an un-prolog'd <chapter> automatically gets associated with DocBook. However, this isn't particularly portable. A more robust, but somewhat annoying, approach is to put the content in a naked external parsed entity, and have a chapter-wrapper and a book-wrapper.

chapter1-content.xml
=-=-=-=-=-=-=-=-=-=
<?xml version="1.0"?>
<chapter>
<title>Darkness and Storminess</title>
<!-- ... -->
</chapter>

chapter1.xml
=-=-=-=-=-=
<?xml version="1.0"?>
<!DOCTYPE chapter ... [
<!ENTITY chapter1-content SYSTEM "chapter1-content.xml">
]>
&chapter1-content;

book.xml
=-=-=-=-
<?xml version="1.0"?>
<!DOCTYPE book ... [
<!ENTITY chapter1-content SYSTEM "chapter1-content.xml">
...
]>
<book>
<!-- frontmatter -->
&chapter1-content;
&chapter2-content;
<!-- ... -->
</book>

Not all editors will handle this acceptably, though; when you open chapter1.xml, they'll parse it correctly, but when you save it back out you may find that all of the content is now in the chapter1.xml file. Those editors are broken, but run a test before committing to this approach. It's a bit of a pain as you have to have two files for every chapter, but it works.

21.

New to docbook on Redhat

Tim Waugh


>   since i'm starting from scratch, i have no need to be
>   backward compatible with anything, so is it realistic to
>   start designing in XML rather than SGML?  what is the 
>   state of the XML support?  (i've downloaded the XML
>   4.1.2 rpm and even the alpha 5.0 XML rpm, to play it safe.)

In "out of the box" Red Hat Linux 7.2, there are a few things missing in the support for DocBook XML with XSL. The current Red Hat Rawhide packages are in pretty good shape for XML though (modulo the still-outstanding filesystem hierarchy standard issues).

If you want to play around with DocBook XML to see if it is appropriate for your environment, you can take a look at <http://cyberelk.net/tim/docbook/selfdocbookx/>, which was edited and created using the current rawhide packages.

I also wrote a package called xmlto (http://cyberelk.net/tim/xmlto/) which is a wrapper around the various tools required to convert XML to different formats using XSL. You might (or might not) find that useful. (Probably not though if you are going to be using DSSSL.)

For DocBook XML with DSSSL instead of XSL for the stylesheet language, you'll probably find that you need fewer packages from rawhide to get going.

22.

What's the difference between SGML and XML docbook

Mike Smith



> From my understanding, the DocBook DTD for SGML defines the same set
> of elements and structure as the DocBook DTD for XML; only one is for
> SGML and the other for XML. Is this correct?

It defines the same elements, and mostly the same content models for those elements, with the biggest difference being that the SGML DTD contains SGML exclusions in some content models -- for example, the SGML DTD excludes <footnote> as a descendent of <footnote>, because it doesn't make much practical sense to have footnotes within footnotes.

XML DTDs can't contain exclusions, so if you're authoring using the DocBook XML DTD, it's possible to produce documents containing some valid-but-not-logical markup like footnotes within footnotes.

Appendix B.1 of "DocBook: The Definitive Guide" has details about some other differences.


> Moreover, if I create a DocBook SGML document, how close is it to a
> DocBook XML document? I imagine that, with some
> modifications/limitations to the SGML document, I'll have a DocBook
> XML document (just need to change the DOCTYPE).

For that, take a look at Appendix B.2, "DocBook Instances as XML":

You should be able to run James Clark's "sx" utility on your SGML doc instances to convert them to XML. sx You might also need to run his "sgmlnorm" on them first. sgmlnorm

23.

Is there a simple docbook?

DaveP

A listing of the Simplified DocBook tags is at the docbook site

Unfortunately, that situation creates something of an issue for the new user that the simplified subset was targeted for: DocBook was difficult to browse and understand, because there were so many tags.

Simplified reduces the number of tags to a managable level, focusing on articles rather than books. (The perfect target for tailoring, in my book.)

However, it still isn't possible to browse those tags to find out what they do. That leaves you with consulting the full DocBook manual, and trying to keep track of what to ignore.

Since I'm big fan of Simplified, from what I see so far, I make this observation in an effort to hasten it's adoption.

24.

Docbook on Mac (OS X)

Julien LETESSIER

In order to use docBook XML on OS X with my team, I've packaged everything needed into an OS X package.

In fact's only Xalan and Fop with shell-script wrappers, and is quite straightforward to use.

Once installed (everything goes to /Users/Shared/DocBook, and install adds a few lines to your .tcshrc), you just have to type docbook2pdf my-docbook.xml Or docbook2html my-docbook.xml to get the desired output.

If you want to get it, it's available for now at (6.2MB) this url Check out projectomega.org for Mac OS X developer documentation and updates of this package.

Feedback is, of course, extremely welcome.

25.

Good docbook tutorial

Norm Walsh


| Could someone recommend a good DocBook tutorial that can be used to
| learn the spec. and develop a sample book?

Does this help? tutorial link

Robert McIlvride suggests duke.edu

By the way, his links to our in-house manual are out of date. Here are the current URLs:

DocBook Tools Overview: Emacs/PSGML Tips:

26.

Docbook on Mac OS

Sasha Zucker

For those of you who use Mac OS X to develop technical documentation, the Fink package manager (http://fink.sourceforge.net) now has a several packages available that allow you to set up a docbook authoring environment. The packages I have contributed to the fink project include:

docbook-dtd's (all sgml and xml releases) with working catalog files for the most recent releases

ISO 8879 sgml entities

nwalsh stylesheets and documentation

linuxdoc project stylesheets

The files are available in fink's unstable branch, which you can make available to the fink command by editing the "Trees" field of /sw/etc/fink.conf to look something like this:

Trees: <<<<

local/main local/bootstrap

stable/main stable/crypto

unstable/main unstable/crypto

<<<<

fink's docbook-bundle pacakge conveniently installs everything at once.

$ fink install docbook-bundle

All the files will be downloaded and installed by fink. Of course, you will need openjade, which is also available from fink. After installing the docbook packages with fink, you will have to complete other tasks before everything is running, such as setting SGML_CATALOG_FILES=/sw/share/sgml/catalog:/sw/share/xml/catalog. Refer to http://www.linuxdoc.org/HOWTO/mini/DocBook-Install/ for lots of useful information.

27.

Docbook presentations

Dan York

In November I gave a talk about DocBook XML to the XML Users Group of Ottawa (XUGO - http://www.xugo.org/ ) and finally got around to putting my slides up on the web last weekend. They are at lodestar2.com

On the title page, there are links to the frames and non-frames version and, of course, the DocBook XML source file (using Norm's Slides doctype).

The talk was called "Chasing Documentation's Holy Grail: Toward Single-Source Publishing With DocBook XML" and really focused on introducing DocBook and some of the tools associated with using it. The XUGO evening went well with something like 50 people or so there and lots of questions and interest. If anyone finds any glaring errors or omissions, please do let me know, too, as I may do more like this in the future.

Kevin Conder adds:

I also gave a presentation about DocBook recently. It was to UniForum Chicago in February. Anyway, yet another DocBook presentation is available at: uniforum.chi.il.us

28.

Docbook spreads again! More points of contact and feeds

Norw Walsh, Jesse Proulx and Tim Waugh

New irc channel

Its #docbook on irc.openprojects.net, and the only rule so far is just to be polite.

(May 2002)

Also new, online at docbook.org

A WikiWikiWeb is a collaborative hypertext environment, with an emphasis on easy access to and modification of information.

Create pages for your favorite DocBook things! Become your own moderator! Share and enjoy!

Selfdocbook (XML edition) at cyberelk.net

(Since Tim doesn't explain on the website <grin/> I'll try to.

Java has this thing where comments in the source code are extracted to provide HTML documentation. It does this using doclets, a java program that maps document comments to HTML markup.

If I'm right, Tim has written a doclet which outputs docbook instead of HTML!

So, write your java code, insert special comments starting /** and all the comments will be extracted to an integrated suite of documentation in XML docbook markup!

In a second comment he adds:

you use the doclet on the java source code using the javadoc command with -doclet parameter. The output is then a DocBook file and not the standard html files.

Example:

    javadoc -docletpath dbdoclet.jar \
        -doclet com.mf.doclet.doobook.DocBookDoclet \
        -overview docs/overview.html \
        -protected \
        -properties dbdoclet.properties \
        java.lang

29.

Content Management systems

Bill Hall

Australia probably leads the world in developing content management technology, and our products have achieved some significant export successes into the US up against some of the products already listed despite limited marketing.

My company is a significant user of the technology, and we are currently exploring more options in relationship to the deployment of an overall corporate knowledge management strategy.

Following is my annotated list. Australian products listed first, then another one I am aware of to fill out the picture. I provide some details on the Australian products, since they lead the world in technology but not in self-marketing. The $A exchange rate may also make the Aussie products more competitive in the USA.

RMIT's Structured Information Manager (SIM) / TeraText (teratext.com)

SIM (simdb.com) is developed by the Multimedia Database Systems unit at RMIT University in Melbourne (rmit.edu). MDS has recently spun off a private company known as InQuirion (inquirion.com) and formed a relationship with the US company SAIC (saic.com) to market the product in North America and Europe under the name TeraText.

We have implemented an earlier version to manage maintenance procedures for the Australian and New Zealand fleet of frigates as described in my May, 2001 Technical Communication article (pdf paper).

I believe that TeraText is to documented knowledge, what Oracle is to transactional and tabular data. The repository is a native XML database, which happily works with many different structural formats (SGML, HTML, RTF (i.e., word), MARC, etc. - or binary formats at the file level). TeraText is a database system developed from first principles to process and manage hierarchically structured and linked information. For or indexing hierarchically structured textual knowledge (e.g., that which can be represented in SGML or XML) TeraText's indexing capability is orders of magnitude faster and prodigiously scaleable by comparison to object oriented or relational databases. Production implementations of TeraText are able to index literally terabytes of text daily, CONCURRENTLY with processing queries against the same multiple terabyte databases.

Licensing of the core system includes the indexing repository server, a powerful web server, admin, security and logging servers, and a very powerful OYO application creation language. The document (and document component) management system is a powerful add on including all document and content management functionality along with a workflow capability.

TeraText's largest market is probably the US defence intelligence community, although its application construction environment, Ace, allows it to handle virtually any KM task where the knowledge is expressed textually. I don't know how the intelligence community uses TeraText, but the Federation of American Scientist's (http://www.fas.org) web pages on Echelon leads to some obvious guesses.

Tenix has had nothing to do with Tower Software or TRIM, but I am aware of it through monitoring defence activities.

Objective Corporation's Objective document and records management

Objective is a publicly listed company based in Sydney with a number of offices in Australia and overseas - including in the US) which has become quite successful in the document and records workflow management area - objective.com. Objective is advertised as a knowledge and process manager.

The Objective Suite is popular with a wide range of government and other organisations and has achieved some export success into the UK. The easily configured workflow component and metadata creation capabilities provide the capacity to capturing some of the surrounding context of a document which make it a good record processing and management system. Unlike TeraText, Objective does not offer much to manage content within structured documents - it is primarily concerned to protect and manage the document as a well controlled object.

Tenix implemented the system around 1995 to provide revision control and check in / check out capabilities for a class of maintenance related documents. It served quite capably in this role, but did not provide us with the capacity to control and reuse elements of text within the documents.

Non-Australian content management product not already listed include:

Software AG's Tamino suite (softwareag.com) native XML database

James Robertson adds

I would recommend having a look at the following sites, which provide a comprehensive list of CMS solutions (along with a summary of features):

clueful.com, hartman.nl, allen.com cmsinfo.org

That should get you started ...

Also, if you are looking for CMS resources, can I strongly recommend that you join the following list: cms-list.org

(This is without a doubt _the_ most valuable mailing list I've joined.)

30.

Modular docbook XML files writeup

Bob Stayton

I've written up the process I use to set up modular DocBook XML files. It is available at: sagehill.com

It uses a combination of XIncludes and olinks to enable you to create modular DocBook XML files like chapters or sections that validate on their own, yet can be assembled into larger valid documents like books. It requires a bit of setup, but I'm using it successfully, and I know of at least one other person using it too.

31.

Do the stylesheets and DTDs fall under any licenses?

Mike Smith


> Do the stylesheets and DTDs fall under any licenses?

They're 100% free software, meeting all the terms of the GNU Free Software Definition, the Debian Free Software Guidelines, the Open Source Definition -- meaning you're free to use them for any purpose, modify them in any way you want, and distribute your modified versions, without restriction and without needing to ask anybody for permission.

As far as specific licenses, the wording of the license distributed with the stylesheets is pretty much the same as the MIT/X Consortium license.

I'm not sure whether the language of the license distributed with the DTD is based on any existing license, but it seems like a shortened version of the MIT/X Consortium license, without the advertising clause. Regardless, it's definitely a 100% free software license.


> How about copyrights?  Does anyone hold copyrights on any portion of
> DocBook?

Both the stylesheets and DTD are copyrighted. But that's a good thing, not a bad thing. It just ensures that anybody who redistributes modified versions has to do it under the terms of the same 100% free-software license the copyright holders chose, so it all stays free.

32.

HOWTO for docbook

Kevin Conder



> Does anyone know a specific HOWTO deal with DocBook/XML on Debian Linux?
> The Oasis and docbook.org have plenty on how to write a docbook file, but
> are scarce on how to process it. 

Not Debian specific, but helpful: tldp.org

It has a section about rendering DocBook files: tldp.org

33.

A Docbook HowTo

Kevin Conder



> Does anyone know a specific HOWTO deal with DocBook/XML on Debian Linux?
> The Oasis and docbook.org have plenty on how to write a docbook file, but
> are scarce on how to process it. 

Not Debian specific, but helpful: en.tldp.org

It has a section about rendering DocBook files: en.tdlp.org

34.

Installing and using docbook - Documentation

Oliver Fischer

This document covers the SGML and the XML version too. May it is interessting for someone. Birmingham Uni

35.

An Introduction to docbook by example

Camille Begnis

I just created a little archive containing a detailed procedure and some sample documents and stylesheets so that a beginner could write his first docbook documents in minutes. It has been written to work on the Mandrake Linux system but should work on other Linux distributions. Just download the file, uncompress it and follow README instructions.

See my site

Waiting for your improvement requests and bug reports.

36.

German docbook mailing list

Lars Trieloff

This Mailinglist will cover all topics of the official docbook- and docbook-apps-Mailinglist and should offer quick help in mother tounge for all german users.

You will find the Mailinglist Archives at placebo.hpi.uni-potsdam.de an general list information, where you can subscribe as well at ditto

Thank you for your interest and I hope for many subscribers.

37.

Czech DocBook site

Jirka Kosek

I just launched docbook.cz Site is written in the Czech language so it is usable only for few users of this list. But every DocBook user counts