Integration of BoostBook with DocBook

---

This page is dedicated to the work related to Google Summer of Code (GSoC 2010) project: "Integration of BoostBook with DocBook".

Organisation: DocBook

Mentor: Stefan Seefeld

Student Name: Muhammad Rehan Shaukat

Abstract

BoostBook is a part of Boost project and provides the mechanism for documentation of C++ libraries. The existing implementation of BoostBook is based on the data type definition (DTD) format. DocBook is a semantic markup language for technical documentation. DocBook v5.0 is based on the REgular LAnguage for XML Next Generation (RELAX NG) format that is more flexible than DTD and XML schema. There is a need to merge BoostBook with DocBook v5.0 in order to extend the existing functionality of DocBook to document APIs. The successful integration of BoostBook with DocBook will enable DocBook to provide vocabulary for both technical and API documentations.

Proposed Plan

State-of-the-art Technologies

• XML
• DTD
• RELAX NG
• XSL
• XMLmind
• Jing
• Trang
• xsltproc

Introduction

RELAX NG

RELAX NG (REgular LAnguage for XML Next Generation) is a schema language for XML documents. RELAX NG schema can be written in both XML and non-XML (compact) format. RELAX NG is comparitively easy to learn and simple to write. Support for XML namespaces, datatyping, regular expressions and ability to reference complex definitions make it different from traditional DTDs.

XML documents are validated against RELAX NG schemas by adding namespace information. In this project, we are using jing to validate XML documents against RELAX NG schema.

java -jar jing.jar -c -i api.rnc any.xml

In the above command 'api.rnc' is the RELAX NG schema in compact format and 'any.xml' is the XML document to be validated.

DocBook V5.0

DocBook is a schema available in different formats (SGML or XML DTD, RELAX NG Grammar, or W3C XML Schema) and is maintained by DocBook Technical Committee of OASIS. DocBook provides support for technical documentation (books and papers related to computer hardware and software). DocBook version 5.0 schema is based on RELAX NG and uses a namespace: http://docbook.org/ns/docbook. DocBook V5.0 specification defined a list of changes in the new version that can be read here: http://www.docbook.org/specs/wd-docbook-docbook-5.0a1.html#docbook.

BoostBook

BoostBook augments DocBook with semantic markup that aids in the documentation of C++ libraries, specifically the Boost C++ libraries, by providing the ability to express and refer to C++ constructs such as namespaces, classes, overloaded functions, templates, and specializations. BoosBook uses DTD based schema as an extension to DocBook V4.2 DTD schema.

Motivation

BoostBook provides a strong support to document libraries and apis that DocBook lacks in current versions. Integration of BoostBook with DocBook will provide DocBook with support of documenting api (not only restricted to C++ but also others). Here, the motivation arises to add a new extension to DocBook V5.0 that will incorporate the features of BoostBook into DocBook.

BoostBook Grammar: Graphical Representation

The first part of the project was to understand the schema defined by BoostBook. For this purpose, reperesting the DTD schema into a graphical format was a good idea to get understand how the schema is defined. The graphical representation is not very accurate because of the complexity of the schema but it shows the basic hierarchy of elements and their dependencies.

Graphical representations are generated by using an online tool: gliffy.com. There are two main levels that can be seen in BoostBook schema language:

Library

Namespace

DTD to Relax NG conversion

...

XML Version

...

Compact Version

...

New Grammar Codebase

...

Integration of new Grammar with DB5

...

Backward Compatibility Support in New Grammar

...

Graduated!!!

...

XSL Stylesheets Adjustments

...

HTML

...

Design Related Questions

...

Contact

Email: <muhammad.shaukat AT members DOT em-a DOT eu>

---

CategoryHomepage