DocBook v5.1 is now an official OASIS Standard!

OASIS is pleased to announce that DocBook Version 5.1. has been approved by the membership as an OASIS Standard [1].

The call to vote was made on 09 November 2016 [2] and the ballot closed on 22 November 2016. A minimum of 42 affirmative votes was needed in order to win approval. The finally vote tally was 63 affirmative votes with 4 abstentions. 

Our congratulations to the members of the TC and to the community of implementers, developers and users who have brought the work successfully to this milestone

DocBook is a general purpose [XML] schema particularly well suited to books and papers about computer hardware and software (though it is by no means limited to these applications).

The Version 5.1 release introduces assemblies for topic-oriented authoring. It also addresses a selection of bugs and feature requests.

The Technical Committee provides the DocBook 5.1 schema in other schema languages, including W3C XML Schema and an XML DTD, but the RELAX NG Schema is the normative schema.

URIs:

The prose specifications and related files are available here:

DocBook Version 5.1

HTML (Authoritative): 

http://docs.oasis-open.org/docbook/docbook/v5.1/os/docbook-v5.1-os.html 

PDF: 

http://docs.oasis-open.org/docbook/docbook/v5.1/os/docbook-v5.1-os.pdf

Editable source:

http://docs.oasis-open.org/docbook/docbook/v5.1/os/docbook-v5.1-os.xml

Schemas: 

http://docs.oasis-open.org/docbook/docbook/v5.1/os/schemas/

DocBook V4.x conversion tools: 

http://docs.oasis-open.org/docbook/docbook/v5.1/os/tools/

Distribution ZIP files

For your convenience, OASIS provides a complete package of the prose specification and related files in a ZIP distribution file. You can download the ZIP file here:

http://docs.oasis-open.org/docbook/docbook/v5.1/os/docbook-v5.1-os.zip

Voting opens for DocBook v5.1 as an OASIS Standard

The ballot to approve DocBook v5.1 as an OASIS standard is now open, starting at 09 November 2016 at 00:00 UTC. The ballot closes at 22 November 2016 at 11:59 UTC. 

This is a call to the primary or alternate representatives of OASIS Organizational Members to vote. 

If your company is a member of OASIS, please encourage your representative to vote in favor of this standard at: https://www.oasis-open.org/committees/ballot.php?id=3010 

The Version 5.1 release introduces assemblies for topic-oriented authoring. It also addresses a selection of bugs and feature requests.

To view the specification, please see:

http://docs.oasis-open.org/docbook/docbook/v5.1/cos01/docbook-v5.1-cos01.html

DocBook for eLearning

I'm very happy to announce the formation of the DocBook Subcommittee for eLearning! The DocBook Technical Committee approved the subcommittee and following charter on 21 Oct 2009:

Background

For more than a decade, DocBook has provided a structured markup vocabulary for hardware and software documentation. DocBook is now widely used in both commercial and Open Source environments. DocBook has a very broad element set, and applies to much more than just technical documentation. The DocBook TC is engaged in evolving the suite of DocBook specifications. The community benefits from having a standard, open, interchangeable vocabulary in which to write structured content. DocBook has been, and will continue to be, designed to satisfy this requirement.

The OASIS DocBook SubCommittee for eLearning is chartered to develop and maintain official variants of DocBook in support of the eLearning industry. Specifically, the subcommittee will focus on schema and stylesheet customizations to support:

1. Develop and design a DocBook-based method for creating reusable learning objects, and the learning content types needed to support them. Some specifics of the design for learning content include:
   1. learning types, including assessments and exercises
   2. a content assembly for structuring, sequencing and managing the learning types as reusable learning objects
   3. linking and relationships between learning objects
   4. interactions
2. Establish guidelines that promote best practices for applying DocBook markup to learning content

Scope of Work

This subcommittee will submit additional enhancements back to the full DocBook standard as appropriate. The scope of this DocBook subcommittee is eLearning content. Broadly, this includes online learning, instructor-led training and other related educational materials.

This effort will deliver on the following goals:

• Build official DocBook variants, based against the DocBook v5.0 schemas.
• Address issues and enhancement requests that have arisen from experience with real-world DocBook and eLearning implementations.
• Add support for features specific to the eLearning industry.

We already have 5 members, who are very eager to get started! If you are an OASIS member and would like to participate, please let me know!

DocBook: A Successful Open Source Project?

A few weeks ago, I found an interesting article on gauging the success of Open Source projects. Since I contribute to several open source and standards initiatives, I thought I'd put the article to the test with the most prominent of these: DocBook.

To give a little history, DocBook has been around since 1991. It is a very robust content model and considered the "de facto" standard for technical documentation. Given it's broad adoption, does that necessarily mean it is successful? Why? The article provides a 9-point checklist, so I'll address each of these in turn.

1. A thriving community - DocBook has one of the most active user communities around. Don't believe me? Check out the docbook-apps mailing list and the docbook mailing list and by tuning into the DocBook irc channel. You can get expert help from around the world almost 24-7 and in multiple languages, too! Many of these are contributors to the DocBook project on sourceforge.net, and participation is welcomed and encouraged.

2. Disruptive goals - Many would agree that DocBook provides much more control and semantics to what is currently available in Microsoft Word or other commercial documentation solutions. DocBook aims to be the preeminent solution for creating books and papers about computer hardware and software (though it is by no means limited to these applications).

3. A benevolent dictator - Two words: Norm Walsh. Norm is very well known in the XML community. He is not afraid to speak his mind concerning requested features, but is very open to new ideas and contributions.

4. Transparency - DocBook is maintained by a technical committee at OASIS. All activities and correspondence is archived and available for public review and input. The DocBook mailing lists are also archived by several different services. You can't get much more transparent than that.

5. Civility - This has never been an issue in the DocBook community. All participants are very professional, and willing to help the newbies as well as experts with any DocBook-related issues.

6. Documentation - Not only is the DocBook specification publicly available, but Norm Walsh has open-sourced his book, "DocBook: The Definitive Guide" and Bob Stayton has open-sourced his book, "DocBook XSL: The Complete Guide". These are the best sources of documentation available for DocBook, but several parameter references as well as the DocBook wiki are also publicly available.

7. Employed developers - While DocBook does not have any official paid developers, several of the contributors work full-time on DocBook and DocBook implementations.

8. A clear license - The standard is freely available from OASIS as well as the docbook.org site. The specifications are covered under OASIS IPR Policy, where you can read all of the details.

9. Commercial support - Last, but not least, DocBook is supported in many commercial products.

In consideration of these 9 items in the checklist, I would posit that DocBook is, indeed, a very successful open-source project and well worth considering for your documentation.

I'd also like to point out to the naysayers that DocBook is NOT dead! In fact, it is more active than ever! The latest version of the standard (v5.0) has been in development for the last several years and is expected to reach official OASIS standard status some time this year. The DocBook TC is also establishing subcommittees to address industry-specific needs.

The first of these is the DocBook Publishers subcommittee, which is addressing the needs of the publishing industry (as opposed to computer hardware and software documentation industry). The specification for an official Publishers schema was recently approved and will be available for public review shortly.

If you have specific needs in publishing, documentation, or content management, we would be very pleased to assist you. Please visit the new Flatirons Solutions website at: http://www.flatironssolutions.com

If you're not RelaxNG, you're working too hard!

This has been my favorite catch phrase, now it's my bumper sticker. The beauty, is that it can be yours too!

http://www.cafepress.com/RelaxNG. Everything is sold at cost, so I'm not in this to make a profit, just to spread the word!

Metadata and Interoperability

Jim Earley has a very thoughtful post on metadata interoperability: http://jims-thoughtspot.blogspot.com/2008/04/metadata-interoperability.html

As part of DocBook v5, we added the ability to include content from other namespaces in the <info> block to support adding Dublin Core directly in your content. The <info> element's purpose is to house metadata that is not intended for display, so it's a really good fit.

Jim's argument, is that the various standards out there (DocBook, DITA, ODF at a minimum) should move to Dublin Core for metadata, and stop re-inventing the wheel. Dublin Core is an internationally accepted standard for metadata, so why not use it directly?!

I whole-heartedly agree. This approach would add more compatibility between standards, and maybe even facilitate better search! Along with that, Dublin Core is extensible, so it shouldn't be too difficult to add additional metadata fields if you need to.

more on DocBook vs. DITA

Teresa Mulvihill has written an article on DocBook vs. DITA at: http://www.dclab.com/dita_docbook.asp.

It's a well thought-out article, but I'd like to make a few clarifications:

As you may know, Jim Earley and I have presented on this topic and our Doc Standards Interoperability Framework at several conferences, and still hope to form an OASIS TC on document standards interoperability.

In the article, Teresa states:

"DocBook is hierarchical by nature, and must be developed to allow for single-sourced content. DocBook has a fixed element and attribute set."

I've successfully used and recommended single-sourcing approaches with DocBook, without additional development. It's quite easy to set up a book or article and use XIncludes or even file entity references to pull in content from a common pool of content structures (usually section or chapter).

It's also fairly easy to extend the elements and attributes in DocBook. This has been made even easier with DocBook v5.0 and RelaxNG. In fact, the DocBook Subcommittee for Publishers that I chair, has helped organize the source patterns for DocBook v5 with a modular approach, enabling easier customizations to be created. Our subcommittee has created a customization geared specifically to publishers, without all of the technical blocks and inlines in full DocBook. This significantly reduces the tag set for folks that do not produce software or technical documentation to use the DocBook standard for general publishing!

DocBook can generate more than PDF, HTML and HTMLHelp. The docbook-xsl-1.73.2 stylesheet distribution supports: html, htmlhelp, javahelp, manpages, xhtml, Word roundtrip, slides and websites!

I would also argue that DocBook can be used on very high volume documentation projects, as well as small and medium projects. Just ask Sun, HP, various Linux distros, and more listed here: http://wiki.docbook.org/topic/WhoUsesDocBook

You might also find Norm's blog on DocBook vs. DITA interesting: http://norman.walsh.name/2005/10/21/dita

We are also working on some exciting developments for the Interoperability Framework, so stay tuned!

DocBook vs. DITA: revisited

The Content Wrangler has published a very interesting article by Dick Hamilton on choosing an XML schema.

I get asked very similar questions all the time! I think I'll start sending folks to this article as recommended reading...

DocBook v5.0 now an official Committee Draft!

I'm pleased to announce that DocBook v5.0 is now an official Committee Draft! The schema can be downloaded here: http://docbook.org/xml/5.0/.

This is the result of several years work. Special thanks to all of the Committee members involved:

    * Steve Cogorno, Sun Microsystems
    * Gary Cornelius, Individual
    * Adam Di Carlo, Debian
    * Paul Grosso, Arbortext
    * Dick Hamilton, Individual
    * Nancy Harrison, IBM
    * Scott Hudson, Individual
    * Mark Johnson, Debian
    * Gershon Joseph, Tech-Tav Documentation Ltd.
    * Jirka Kosek, Individual
    * Larry Rowland, Hewlett-Packard
    * Michael Smith, Individual
    * Robert Stayton, Individual (Secretary)
    * Norman Walsh, Sun Microsystems (Chair, Editor)

Next step: OASIS standard!

DITA Learning Content accepted for DITA 1.2

More big news in the standards world today! The DITA 1.2 feature proposal #12058, "Design and language specification for DITA learning and training content," submitted by the DITA Learning and Training Content sub-committee was approved at today's DITA TC meeting.

Congratulations to John Hunt and all the members of the DITA Learning Content SC! The specification and sample plugins are all publicly available. Next steps for us is to work on our Best Practices for Implementation and create some sample processing for the DITA OT. This effort will continue into the first quarter of 2008.

DocBook v5.0 now an official Committee Draft!

I was on the road last week and didn't have a chance to post the GREAT news!

At the DocBook TC meeting on November 7, 2007, DocBook V5.0 was approved as a Committee Draft! This draft was a result of several years of hard design work, especially by Norm Walsh, who created 9 Beta Releases and 7 Candidate Releases since October of 2005.

The most exciting feature, IMO, that this standard is based on RelaxNG rather than DTD. DTD and XSD are still supported/provided, but the canonical format is now RelaxNG (RNC). Vendors, start your engines and add support for RelaxNG validation! Actually, several vendors are already "ahead of the game" with RelaxNG support: oXygen XML Editor, XML Mind XXE, Editix, Emacs nXML, Cladonia Exchanger XML Editor. Conspicuously missing: PTC Arbortext Editor and XMetal. [NUDGE: C'mon big guys!]

The other exciting result of DocBook v5 and RelaxNG, is that it makes customization layers EXTREMELY easy to manage. The DocBook Subcommittee for Publishers proposed a new modularization of the RNC schemas for DocBook v5 to create Core DocBook and additional schema modules, which have now been incorporated into the v5 source. As a result, we've also been able to produce an initial draft of an official DocBook Publishers customization very easily!

This is great news for the entire DocBook TC and community!

DITA Learning Content specialization open for review!

The OASIS DITA Learning and Training Content Specialization Subcommittee is proud to announce the availability of our specification for DITA Learning Content for public review.

The design and language specification for the DITA learning and training content is available here, and the DITA Open Toolkit plugin with working DTD, XSD, DITA content samples, and documentation is available here.

The goal of the subcommittee is to develop a general top-level design for structured, intent-based authoring of learning content with good learning architecture, following DITA principles and best practices.

This specification was formally submitted to the full OASIS DITA Technical Committee today, after we completed the designs, samples, and language specifications for the learning topic types, the learning map domain, the learning interaction domain, and IEEE LOM learning metadata. The intention is to have this specification approved by the TC for inclusion in DITA 1.2, though most of this work is built on the existing DITA 1.1 infrastructure.

Please send any review comments via the public comment facility.

Doc Standards Interoperability Framework whitepaper now available!

Jim Earley and I have presented about the Doc Standards Interoperability Framework at XML 2006, DITA West 2007, Open Publish 2007, OASIS Symposium 2007 and DITA West 2007.

The whitepaper is now available at:
http://www.flatironssolutions.com/downloads/Interoperability_Framework.pdf.
This whitepaper contains greater detail on the business case for interoperability, as well as specifics on the framework. If you are interested in exchanging content between DocBook, DITA, ODF and/or other document standards, you should definitely check it out!

We are still working on the charter for the proposed OASIS Doc Standards Interoperability TC. Hopefully we can get that finished soon to form the TC before year-end.

DITA 1.1 Officially Released!

It's been a lot of work, but we've finally released version 1.1 of DITA! I've been involved heavily in DITA 1.1, as well as the Learning Content specialization subcommittee.

The full press release is available here:
http://www.oasis-open.org/news/oasis-news-2007-08-13.php

Key features of this release include:

• Enhanced print publishing capabilities with the new DITA Bookmap specialization, including extended book metadata.
• New elements (<index-see>, <index-see-also>, and <index-sort-as>) for "see" and "see-also" references.
• New elements (<abstract>, <data>) for defining structured metadata, as well as the ability to add new metadata attributes through specialization.
• New elements for image scaling.
• The glossary specialization, adding new elements for glossary entries.
• Support for foreign content vocabularies (<unknown> element)

UPDATE: The DITA OpenToolkit 1.4 has also been released, including support for DITA 1.1. For more information, please see:
http://sourceforge.net/forum/forum.php?forum_id=724798

Czech Comments for Office Open XML (in English!)

Jirka Kosek has graciously provided an English translation of the Czech Standards Institute's comments on the Microsoft-created Office Open XML standard.

The English version is here: http://xmlguru.cz/2007/08/czech-ooxml-comments-in-english

I also thought it was interesting to visually see the size of this monster spec. See the photos here: http://xmlguru.cz/2007/07/czech-comments-ooxml

Personally, I'm glad Microsoft finally got around to providing the specs for their XML export from their products. I also despise the markup, but at least it's documented. I also thought it was a bit underhanded and deliberate to name it "Office Open XML" which is so incredibly similar to the Open Office product that uses the OASIS Open Document Format. They could have just named it MOM - Microsoft Office Markup language...

Thanks for the comments on the standard, Jirka!

Interoperability getting some attention!

We're getting some exposure on the Doc Standards Interoperability Framework now! Check out this entry on the Gilbane blog:
http://gilbane.com/blog/2007/04/dita_docbook_and_odf_interoper.html

Thanks to Jim for sending me the link...

SKYWARN at the OASIS Symposium

SWEET! Being a trained SKYWARN spotter and HAM operator, I was really impressed by the presentation from Michelle Raymond on the Emergency Management TC. During the presentation, she sent an alert to an OASIS demo web service that alerted many blackberries in the audience. Wish I had a subscription to that service :-)

The Emergency Data eXchange Language (EDXL) was described in detail, including the Common Alerting Progocal (CAP). NWS uses the CAP already today!

This may be one of the few times I will ever get to use the tags "Weather" and "OASIS" on the same blog post! :-)

Some interesting sites related to this include: http://www.esi911.com/esi/products/webeoc.shtml

Interoperability at OASIS Symposium 2007

I'm presenting this week at the OASIS Symposium in San Diego.

A very interesting theme has emerged in the morning sessions, which is that of interoperability. I find this very encouraging and other standards bodies should stand up and take notice!

Bob Sutor, VP of Open Source and Standards at IBM gave a very interesting keynote that included this theme. He gave a great example of ODF and how they are addressing accessibility and interoperability as part of the standard.

Another interesting tidbit from his preso was on how to measure the "openness" of a standard:

• Development - how was it developed, who got to play, who contributed, how much did they contribute?
• Maintenance – who is maintaining? How are RFEs handled? Errors? What happens after v1?
• Implementation – are there any roadblocks preventing open source? Can it be implemented?
• Acquisition – can you get a hold of the standard? Can you download for free? Many standards orgs are not that way! Can you afford it around the world?

Following Bob's keynote, another terrific presentation was given by Bob Stayton. Bob Stayton was talking about interoperability between DocBook and DITA. Bob primarily focused on a form of processing interoperability, where source DITA content is transformed to DocBook to take advantage of the DocBook publishing toolchain.

After Bob, I presented "A Doc Standards Interoperability Framework for DocBook, DITA, ODF and more!". I'll provide a link here when the slides are available online.

Overall, the talk was well received and I look forward to getting the proposed Document Standards Interoperability TC started at OASIS! I also had the pleasure of meeting Alex Wang, from the UOML TC, who has been very active on the docstandards-interop-discuss list at OASIS recently. I look forward to exchanging ideas about interoperability!

This is the first OASIS Symposium I've attended. Hats off to Patrick Gannon, Mary McRae, Jane Harnad and the other OASIS folks who've put this together. I'm quite pleased with the level of technical detail and expertise here at the Symposium.

I'm attending some presos on BPEL, BPM and SCA (Business Process Modeling and SOA Component Architectures) right now. Will blog additional detail later!

DocBook v5.0 CR3 already!

Norm Walsh is quick on the turnaround! Please give the latest candidate release of DocBook v5 a test drive and report any issues. You can download the schemas here: http://docbook.org/xml/5.0CR3/. There is also a set of stylesheets released that support v5.0 as well. You can find them here:
http://sourceforge.net/project/showfiles.php?group_id=21935&package_id=219178

I was a bit of a "problem child" with my RFEs that are now included:

• RFE 1588693: Added an <acknowledgements> element, peer to <dedication>, replacing <ackno> which had only been available at the end of <article>.
• allow <info> in HTML tables.

You can specifically blame me for these. :-) I do think they will be quite useful enhancements.

DocBook SubCommittee for Publishers approved!

I am very pleased to announce the formation of a DocBook SubCommittee for Publishers was approved by the DocBook TC during yesterday's meeting. The charter as approved is a as follows:

OASIS DocBook SubCommittee for Publishers

Background

For more than a decade, DocBook has provided a structured markup vocabulary for hardware and software documentation. DocBook is now widely used in both commercial and Open Source environments. DocBook has a very broad element set, and applies to much more than just technical documentation. The DocBook TC is engaged in evolving the suite of DocBook specifications. The community benefits from having a standard, open, interchangeable vocabulary in which to write structured content. DocBook has been, and will continue to be, designed to satisfy this requirement.

The OASIS DocBook SubCommittee for Publishers is chartered to develop and maintain official variants of DocBook in support of the publishing industry. Specifically, the subcommittee will focus on schema and stylesheet customizations to support: periodicals as regularly published technical notes or journals, book publishing (such as business, legal, medical, and other non-technical domains), educational textbooks and other document types as appropriate for this industry.

Scope of Work

This subcommittee will submit additional enhancements back to the full DocBook standard as appropriate. The scope of this DocBook subcommittee is publishing industry content. Broadly, this includes books, journals and other related publications.

This effort will deliver on the following goals:

• Build official DocBook variants, based against the DocBook v5.0 schemas.
• Address issues and enhancement requests that have arisen from experience with real-world DocBook implementations.
• Add support for features specific to the publishing industry.

If you are a Publisher, and would like to be involved, please let me know! I have a good-size core group of about 8 folks at this point, but would be interested in all the industry expertise we can gather!