TEACHING DOCUMENT PRODUCTION AND MANAGEMENT

WITH DOCBOOK

Alberto González Téllez

Department of Computer Engineering, Polytechnic University of Valencia, E.U. Informática, Valencia, Spain

Keywords: Teaching document production, document management, Docbook, XML.

Abstract: Document production is an important aspect of academic activity. Nowadays the most common tools used

to create teaching documents are office suites and e-learning oriented authoring applications. We found that

none of these options fulfill our requirements of content repository management, content filtering and

presentation format selection, and last but not least being open and free. Docbook is a book production

oriented XML compliant language, so it has the capability of using the standard XML processing tools like

XSLT, XPath, XInclude and XQuery. The main parts of Docbook (DTD and stylesheets) are open source.

These basic components can be customized and complemented in order to get adapted to application

requirements and final users. After some years of experience using Docbook to produce our teaching

material we found productive tools and we developed some Docbook customizations.

1 INTRODUCTION

Traditional teaching based on blackboard and

lecturer speech is nowadays dying due to the

availability of computers and the Internet. The use of

these technologies requires new tools to create

learning and teaching material.

The most common tools are office suites like

Microsoft Office and Open Office. This is the case

for example in our university. Office suites have a

good user interface and are flexible enough to cover

many requirements of authoring learning/teaching

content. But after years of work lecturers find

themselves with piles of documents, many of them

redundant, and in spite of being in electronic format

it is difficult to reuse them because almost

everything has to be made by hand. Another

inconvenient is that document formats are

proprietary so users become linked to software

companies and products.

There are many authoring tools specifically

oriented to e-learning (e-learning, 2006). This

market has expanded mainly because of the interest

of business organizations in creating their own

learning resources. These tools are very productive

and fulfill almost all the e-learning platform

requirements. But they use to be very expensive and

they also create a strong link between users and

software companies. Like office suites, these

applications have their own data formats. In spite of

being able to export open formats, it is impractical to

work on them directly. Also a big effort is required

in order to port these formats to another application.

We decided to get another way and try to find an

authoring environment that was productive, open

and flexible. Some attempts have been made in this

direction (Kirsch-Pinheiro, K., 2001 and Süß, Ch.,

2002) but we have found them unsatisfactory

because they rely on unstable applications, they do

not focus on the aspects we are more interested on

(exercise management, exam generation, multiple

presentation formats, etc) or they use non standard

formats.

1.1 XML and Docbook

In 1998 the World Wide Web consortium published

the XML specification (W3C rec 04, 2004) with the

aim of becoming an open standard to data

representation and application interoperability. This

specification was complemented with a set of

standard tools to support data processing. The main

XML tools are:

– DTDs and schemas: Techniques to define XML

languages (W3C rec 28, 2004).

188

González Téllez A. (2006).

TEACHING DOCUMENT PRODUCTION AND MANAGEMENT WITH DOCBOOK.

In Proceedings of WEBIST 2006 - Second International Conference on Web Information Systems and Technologies - Society, e-Business and

e-Government / e-Learning, pages 188-195

DOI: 10.5220/0001238901880195

 SciTePress

– XSLT stylesheets: XML processing language

(W3C rec 16, 1999).

– XPath: XML data climbing language (W3C rec

16, 1999).

– XQuery: XML data querying language (W3C

cand 3, 2005).

– XLink (W3C rec 27, 2001) and XInclude (W3C

rec 20, 2004): XML data linking and modular

composing.

Every markup language that is XML compliant

can benefit from all of these techniques. The

particular language we choose will depend on the

application we are involved with. There are XML

languages defined for many applications:

– SVG for vector graphics (W3C rec 14, 2003).

– MathML for mathematical equations (W3C rec

21, 2003).

– XHTML for web pages (W3C rec 26.1, 2002).

– SMIL for multimedia presentations (W3C rec

13, 2005).

– Web services (SOAP, WSDL)

– Business interoperability (ebXML)

– Etc…

Docbook (Docbook, 2006) is an XML language

oriented to book production and management that

we found very well suited for producing and

organizing teaching content. The basic Docbook

tools are the DTD and the XSLT stylesheets to

produce web and printing formats. Both of them are

open source and can be found on the Docbook site.

These basic tools have to be complemented with

authoring tools and some customizations in order to

fulfill application requirements. Either DTD and

stylesheets are fully customizable at several levels of

complexity (Walsh, N., 2003 and Stayton, B., 2005),

usually simple customizations will suffice.

End users have to be kept completely away from

XML details, so user friendly tools have to be

offered. Nowadays this is not so well accomplished

in Docbook as in office suites, but some tools are

evolving quickly in this direction. The authoring

toolset we use includes:

– Content editor. We have found XXE (XXE,

2006) a good choice, but many others are

available.

– Format generator. XFC (XFC, 2006) is a

general application with a GUI interface. We

think that a more customized one is desirable.

– Content manager. Qizx (Qizx, 2005) is a freely

available XQuery tool.

After some years using Docbook to produce and

manage teaching documents, we raised the

conclusion that the effort of customizing Docbook

and developing user friendly tools is worthwhile. In

this work we first describe briefly Docbook basic

tools and customization techniques. Next we

describe some customizations we have implemented

and the tools that we selected and developed to

produce and manage documents. Finally some

conclusions and future work directions.

2 BASIC TOOLS

Docbook DTD and XSLT stylesheets are available

on Docbook source forge project (Docbook, 2006)

whose main administrators are Norman Walsh and

Bob Stayton. The DTD and stylesheets main books

are public in web format. Authoring tools usually

include these basic tools.

2.1 Docbook DTD

There are two techniques to validate XML

documents: DTDs and schemas. DTDs are inherited

from SGML and they are a compact way to specify

XML syntax. However they have light control over

some syntax aspects. Schemas have a stronger

syntax control capability but they are more complex.

DTDs simplicity has avoided their complete

replacement by schemas and many XML languages

are still specified by means of DTDs. DocBook

specification is available in DTD and in the schema

language RelaxNG.

Docbook elements can be classified as:

– Hierarchical elements

– Sets

– Books

– Divisions

– Components

– Sections

– Meta-information elements

– Content elements

– Block elements

– Inline elements

Sets are collections of books. A book can begin

with a dedication element followed by navigational

components (tocs, lots and indexes). Divisions are

the first hierarchical level after book, they include

part elements and reference elements. Parts contain

components which include the book content and

reference elements contain refentrys. Components

TEACHING DOCUMENT PRODUCTION AND MANAGEMENT WITH DOCBOOK

189

are chapter-like elements: preface, chapter,

appendix, glossary and bibliography. Sections

organize the chapter contents, there are several kinds

of sections: sect1…sect5, section, simpesect,

bridgehead, refsect1…refsect3, glossdiv, bibliodiv

and indexdiv. Sect, section and refsect elements can

nest. All elements in the section level and above

include a wrapper for meta-information about the

content.

Immediately below the sectioning elements

Docbook defines block elements that are paragraph-

level elements. Some examples of block elements

are: paragraph, lists, admonitions, examples, figures,

tables, etc. Inside block elements we can define

inline elements like emphasis, quote, subscript,

superscript, crossreferences, etc. There are several

kinds of block and inline elements.

All Docbook elements also have attributes that

define specific element features like list bullets and

numbering, table lines and sizes, etc.

The next is a simple example of Docbook

document structure:

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

<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML

V4.3//EN"

"http://www.oasis-

open.org/docbook/xml/4.3/docbookx.dtd">

<book>

</section>

</chapter>

</book>

First we find the XML processing instruction

that is the required first line in every XML

document. Next there is the DOCTYPE declaration

that identifies the root element and the DTD using a

public identifier. These identifiers can be resolved

on the web or locally by means of a catalog 0. The

book element is the document root and it has a title

and a chapter children. The chapter element only has

a section with a title and a paragraph. Titles and

paragraphs are examples of block elements that

include final content.

2.2 Stylesheets

Once we have written a Docbook document we have

to deliver it in some presentation format. The most

frequently used formats are HTML for the web and

PDF for printing. To get our book in this ways we

have to apply some transformations, these

transformations are performed by XSLT stylesheets.

The engine that executes stylesheets over XML

data is an XLST processor. Many of them are freely

available: xsltproc (Xsltproc, 2006), Xalan (Xalan-J,

2005), XT (XT, 2005) and Saxon (Saxon, 2005).

Xsltproc is implemented in C and then it is faster

than Xalan, XT and Saxon that are implemented in

Java. The user interface to these utilities is a console

command but they also offer APIs to use them from

applications.

HTML is obtained by simply applying the

corresponding stylesheet. PDF generation requires

two steps, first Docbook is converted to XSL-FO

(W3C rec 15, 2001) applying XLST, and then a FO

to PDF converter is required. FOP (FOP, 2006) is an

open source option but it does not implement the

whole FO specification. XEP (XEP, 2006) is a

commercial product fully compliant with XSL-FO.

Recently XEP has become freely available for non

commercial use.

3 DOCBOOK CUSTOMIZATION

Docbook customization can be done in two aspects:

markup and presentation. Markup customization

means to change, extend or reduce the markup

defined by Docbook DTD. Presentation

customization deals with Docbook stylesheets.

3.1 DTD Customization

Customizing Docbook markup is generally not

recommended because when the markup is modified

compatibility is lost; but sometimes applications

demand some customization level.

When Docbook is customized we say that we

create a customization layer (Walsh, N., 2003). A

markup customization layer consists of a file with

the next content:

(1) Overrides of Entity Declarations

(2) <!ENTITY % orig-docbook "-//OASIS//DTD

DocBook V3.1//EN">

%orig-docbook;

(3) New/Modified Element and Attribute

Declarations

“Overrides of entity declaration” means to assign

values to Docbook DTD parameters. These

parameters are defined in the DTD in order to allow

some kinds of usual customizations like:

WEBIST 2006 - E-LEARNING

190

– Adding a new kind of already existing elements

(%*.class; parameters).

– Changing the content model of some kind of

elements (%*.mix; elements).

– Ignoring or redefining an element (%*.module;

parameters).

– Control marked sections around individual

element declarations or attribute list declarations

(%*.element; and %*.attlist; parameters).

– Making global changes to the inclusions and

exclusions in the DTD (%*.inclusion; and

%*.exclusion; parameters).

– Adding markup to most entity declarations

(%local.*; parameter entities).

The Docbook DTD is included by means of an

ENTITY declaration. Finally the new or redefined

elements are declared. An example of a markup

customization layer is:

<!ENTITY % local.tech.char.class |MethodName">

<!ENTITY % DocBookDTD PUBLIC

"-//OASIS//DTD DocBook V3.1//EN">

%DocBookDTD;

<!ELEMENT MethodName ((%smallcptr.char.mix;)+)>

<!ATTLIST MethodName

%common.attrib;

%classname.role.attrib;

%local.classname.attr

To use a customization layer in a document we

have to include a DOCTYPE declaration that

references the file that defines the customization.

The reference can be done using a system or a public

identifier. In case of a public identifier a new one

has to be created in order to avoid confusion with

the original DTD.

3.2 Stylesheets Customization

A common need when using Docbook is to

customize presentation, either HTML or printing

formats. Presentation is generated from Docbook by

means of XSLT stylesheets. In order to facilitate

customization many parameters are defined in

Docbook stylesheets.

Setting parameter values is the most straight

forward customization method. This can be done on

the XSLT processor command line or using a file.

Parameter setting in the command line depends on

the XSLT processor command syntax. If a file is

used then it will be an XSLT stylesheet like the next:

<?xml version='1.0'?>

<xsl:stylesheet

xmlns:xsl="http://www.w3.org/1999/XSL/Transform

" version="1.0">

<xsl:import

href="/usr/share/xsl/docbook/html/docbook.xsl"/

<xsl:param name="html.stylesheet"

select="'corpstyle.css'"/>

<xsl:param name="admon.graphics" select="1"/>

</xsl:stylesheet>

First we import the Docbook stylesheet and then

we set parameter values. There are many parameters

available and then many format customizations can

be performed in this way. A complete parameter

reference can be found in Stayton, B., 2005.

When parameter setting is not appropriate other

more sophisticated methods are available:

– Setting attribute sets.

– Completing placeholder templates.

– Generating new templates.

– Customizing generated text.

– Replacing templates.

XSLT attribute sets are similar to parameters. As

an example you can turn off boldface and left-align

sections titles with the next attribute set setting:

<xsl:attribute-set

name="section.title.properties">

<xsl:attribute name="font-weight">Normal

</xsl:attribute>

<xsl:attribute name="text-align">left

</xsl:attribute>

</xsl:attribute-set>

An example of placeholder template is

user.header.content that is called by chunking

HTML stylesheet at the beginning of every HTML

page:

<xsl:template name="user.header.content">

</xsl:template>

New templates generation is a mechanism that

allows redefining some format properties (for

example title pages). There are some XML

templates that can be modified and then an XSLT

stylesheet will replace the original Docbook

stylesheets by the new ones (XLST is itself XML).

TEACHING DOCUMENT PRODUCTION AND MANAGEMENT WITH DOCBOOK

191

By customizing generated text we can change

some text that is not present in the input document

but appears in the presentation, this is because

stylesheets create it. Generated text can be

customized on the stylesheet distribution files for all

the languages supported (for example English file is

common/en.xml). Customization can also be

included in a customization layer leaving

distribution files unmodified.

Replacing templates is simply to rewrite the

XSLT templates we want to customize. This is done

after the main stylesheet import in the customization

layer. This kind of customization requires a deep

understanding of Docbook stylesheets and XSLT

itself because there are many subtleties that can get

into errors.

4 AUTHORING TOOLS

Creating content in a user friendly way is perhaps

the user most important demand. Docbook as any

other XML compliant language can be edited using

a raw text editor. From the point of view of

authoring production it is not the most adequate

option. Fortunately there are many editors that offer

a more specific environment.

XXE (XMLMind XML Editor at XXE, 2006) is

a particularly interesting editor because it offers a

WYSIWYG like interface that hides the markup to

the user (Figure 1). It is a Java application and then

it runs on many platforms. Besides of being a

general XML editor it has been completely

customized to Docbook. It is a commercial product

but XMLMind offers a standard version that is

freely distributed an only lacks for some

functionalities. The most relevant is that it does not

support schemas. In our experience we have found

standard version adequate.

We include non textual content (images,

graphics, equations and plots) using JPEG format by

means of ‘fileref’ attribute. JPEG seems to be the

most universally supported image format. We hope

that in the near future there will be better support for

non-textual information XML languages, mainly

MathML and SVG. The tool we use to edit non

textual content is OpenOffice suite.

Figure 1: Editor XXE.

To generate presentation XMLMind offers XFC

(XMLMind FO Converter at XFC, 2006). It is a Java

application that generates several format from

Docbook: HTML (one page or chunked), PDF, RTF

and WordML (Figure 2). It uses Saxon as XLST

processor and FOP as default PDF generator.

Figure 2: XMLMind FO Converter.

4.1 Collaborative Authoring

Docbook documents are plain text this allows to use

concurrent versioning systems like CVS to

collaborative authoring teaching material. We use a

CVS server on Linux and the java client SmartCVS.

WEBIST 2006 - E-LEARNING

192

Figure 3: SmartCVS client.

To avoid conflicts between versions the author

team has to agree which document part every

member is going to work on. In this way CVS

merges changes automatically in a common

document.

All auxiliary content is declared as binary format

and concurrent edition of this material is not

possible. This is not an issue because in our

approach text is the backbone content.

5 TEACHDB

We are developing markup and stylesheet

customization layers taking account of our previous

experience with Docbook as teaching content

production framework. We call the customized

markup TeachdB. The requirements we want to

satisfy are:

– Class material repository building.

– Lab guides repository building.

– Class material and lab guides generation from

repositories.

– Class and lab exams generation from

repositories.

– Printing format and slides format generation

from the same content.

5.1 TeachdB Markup

We have minimized markup customization in order

to maintain the maximum compatibility level with

Docbook. This means to avoid creating new

elements and attributes if Docbook existing ones are

usable. TeachdB markup extensions can be

summarized as:

– ‘Role’ attribute of element ‘article’ is restricted

to ‘class’ and ‘lab’ values.

– A new root element ‘exam’ is added through

local.article.class parameter.

– Exercises are implemented using Docbook

‘qandaentry’ element with some extensions:

– Two new attributes ‘lastusetype’ and

‘lastusedate’ are added to ‘qandaentry’.

– A new element ‘options’ is added to

‘question’ in order to implement test

questions.

– A new attribute ‘type’ is added to ‘answer’

elements, with values ‘response’ and

‘solution’.

As you can notice the most significant

customization is related to exercises. This is not by

chance because we think that exercises are the most

important component of a learning material.

Exercise management is the most complex process

to implement. Exercises will be used in three ways:

– Class or lab examples.

– Class or lab exercises.

– Exam exercises.

In order to reuse already authored exercises some

information is required: last use type and last use

date. This information is included in two new

‘qandaentry’ attributes: ‘lastusetype’ and

‘lastusedate’. These attributes permit to select

exercises automatically, according to a certain

criteria, by means of XLST or XQuery.

The new element ‘exam’ introduces a structure

specifically oriented to exam authoring. It has two

children: ‘header’ and ‘questions’. Element ‘header’

includes information about the exam (subject, date,

etc). Element ‘questions’ is a sequence of ‘Question’

elements that have attributes to implement exam

version. These attributes define question and

response options orderings for every exam version.

A ‘qandaentry’ child defines the question content.

An important requirement is content reuse.

Content repository management can be implemented

in two ways:

– Content filtering based on attribute values.

– Content selection with XInclude.

Content filtering is adequate if the final

document is a single document subset, otherwise

content selection from several sources can be

implemented with XInclude.

When repositories grow in size it is convenient to

automate content location. This can be achieved

TEACHING DOCUMENT PRODUCTION AND MANAGEMENT WITH DOCBOOK

193

using XQuery over metadata elements and element

attributes.

5.2 TeachdB Stylesheets

In order to get presentation formats adapted to

document use, we have developed some stylesheet

customizations. In particular we have defined

formats for:

– Student class notes (PDF).

– Lecturer class presentation (chunked HTML).

– Lab guides (PDF).

– Class exams (PDF).

– Lab exams (HTML forms).

Student class notes have a printed book like

format: header, footer, page number, numbered

sections, etc (Figure 4). All this customizations are

documented in 0.

To generate lecture presentation we have

converted Docbook to Slides. This is fairly easy

because Slides and Docbook have the same content

elements; they only differ in hierarchical elements.

Slides offer several chunked HTML templates that

include navigation controls and appropriate font

sizes (Figure 5).

Figure 4: Example of class notes PDF format.

Lab guides have similar format than class notes

but they include a question set that is used to

generate lab exams from a web server. When the

PDF lab guide is generated the exam question set is

filtered. The question set is obtained by means of an

XSLT transformation and it is put on the server as a

question repository. Students perform the exam

accessing to the exam URL after the lab session and

the web server delivers a question subset in HTML

form format (González, A., 2005).

Figure 5: Example of class session slide.

Class exams are generated in two steps, first the

exam markup is translated to Docbook, then a

customized stylesheet is applied to generate PDF.

There are two options: exam without solution and

exam with solutions.

5.3 Format Generation

In order to facilitate format generation we have

implemented a Java application that is specifically

customized to our needs. It is a front-end to shell

scripts that execute xmllint parser to solve

XIncludes, xlstproc to transform XML, XEP to

generate PDF and web clients or PDF visors to

shown the result. The use of native parser and XLST

processor gives a satisfactory response time.

Figure 6: Customized format generator.

The application use is very simple. First the

content document is specified. Then the type of

presentation desired is set by means of fixing the

mark in a radio button group. Finally the

presentation document is generated by pushing a

button.

WEBIST 2006 - E-LEARNING

194

6 CONCLUSIONS AND FUTURE

WORK

We consider Docbook an interesting tool for

teaching document authoring and management.

Being XML compliant it allows using all the

standard XML document processing technologies.

Simple markup and stylesheets customization permit

to get some capabilities like several formats from

one source, content filtering and repository

management; that are not available in other more

widespread tools.

Docbook weakest point has been the lack of user

friendly editors. Nowadays the situation is changing;

XXE is a good example of a Docbook productive

editor. Nevertheless there is a long way in this

respect to compete with office suites.

As future work we will try to achieve the next

goals:

– To customize Qizx to locate repository content.

– To include LOM markup (LOM, 2002) in

Docbook elements metadata in order to integrate

documents in LMS environments (Dhraief, H.,

2001; Allert, H., 2002).

– To use XML for as much content types as

possible, particularly graphics (SVG) and math

equations (MathML).

REFERENCES

e-learning, 2006. e-learning center site.

http://www.elearningcentre.co.uk/eclipse/vendors/auth

oring.htm

Kirsch-Pinheiro, K., 2001. A Cooperative Environment for

E-Learning Authoring. In Documents Numériques :

Espaces d'Information et de Coopération, vol. 5, n. 3-

4, pp. 89-114, Hermes Science, France.

Süß, Ch., 2002. LMML – The Learning Material Markup

Language Framework. In Int. Worshop ICL, Villach,

Austria.

W3C rec 04, 2004. XML specs.

http://www.w3.org/TR/REC-xml/

W3C rec 28, 2004. W3C schema. Specs.

http://www.w3.org/TR/xmlschema-1/,

http://www.w3.org/TR/xmlschema-2/

W3C rec 16, 1999. XSLT and XPath specs.

http://www.w3.org/TR/xslt

http://www.w3.org/TR/xpath

W3C rec 15, 2001. XLST-FO specs.

http://www.w3.org/TR/xsl/

W3C cand 3, 2005 XQuery apecs.

http://www.w3.org/TR/xquery/

W3C rec 27, 2001. XLink specs.

http://www.w3.org/TR/xlink

W3C rec 20, 2004. XInclude specs.

ttp://www.w3.org/TR/xinclude/

W3C rec 14, 2003. SVG language.

http://www.w3.org/TR/SVG11/

W3C rec 21, 2003. MathML language.

http://www.w3.org/TR/MathML/

W3C rec 26.1, 2002. XHMTL language.

http://www.w3.org/TR/xhtml1/

W3C rec 13, 2005. SMIL language.

http://www.w3.org/TR/SMIL2/

Docbook, 2006. Docbook main sites.

http://www.docbook.org

http://docbook.sourceforge.net/

Walsh, N., 2003. DocBook: The Definitive Guide. O'Reilly

Stayton, B., 2005. DocBook XSL: The Complete Guide.

Sagehill Enterprises.

XXE, 2006. XMLMind XML Editor site.

http://www.xmlmind.com/xmleditor/

XFC, 2006. XMLMind FO Converter site.

http://www.xmlmind.com/foconverter/

Qizx, 2005. Qizx open site.

http://www.axyana.com/qizxopen/

Xsltproc, 2006. Libxslt site. http://xmlsoft.org/XSLT/

Xalan-J, 2005. Java implementation of Xalan site.

http://xml.apache.org/xalan-j/

XT, 2005. XT site. http://www.blnz.com/xt/

Saxon, 2005. Saxon site. http://saxon.sourceforge.net/

FOP, 2006. Apache Formatting Objects Processor site.

http://xmlgraphics.apache.org/fop/

XEP, 2006. RenderX site for XEP.

http://www.renderx.com/

González, A., 2005. Entorno web para la generación y

corrección automatizada de exámenes basado en XML

y Java, I Congreso Español de Informática, Granada,

Spain,

LOM, 2002. Learning Object Metadata specs.

http://ltsc.ieee.org/wg12/20020612-Final-LOM-

Draft.html

Dhraief, H., 2001. Open Learning Repositories and

Metadata Modelling, in Proc. of Int. Semantic Web

Working Symposium, Stanford, USA

Allert, H., 2002. How are Learning Objects Used in

Learning Processes? Instructional Roles of Learning

Objects in LOM. ED-MEDIA 2002, World Conference

on Educational Multimedia, Hypermedia &

Telecommunications, Denver Colorado, USA

TEACHING DOCUMENT PRODUCTION AND MANAGEMENT WITH DOCBOOK

195