# XML - Managing Data Exchange/DocBook

------------------------------------------------------------------------

## Learning objectives

Upon completion of this chapter, you will be able to

-   Learn the basics of DocBook
-   Create a DocBook document by using the DocBook XML DTD
-   Convert a text document to a DocBook document
-   Use XSL Stylesheets to transform a DocBook XML document to multiple
    formats as HTML, PDF or presentation slides.

## Introduction

DocBook is general purpose XML and SGML vocabulary particularly well
suited to books, articles, and papers. It has a large, powerful and easy
to understand Document Type Definition (DTD), and its main structures
correspond to the general concept of what constitutes a book. DocBook is
a substantial subject that we can\'t exactly cover in a few pages. Thus,
for the purposes of this chapter, we will talk about creating a simple
DocBook document with major elements in the DocBook DTD and the details
of publishing the document in order to give you a feel about DocBook. If
you would like to study the subject further, we suggest you to have a
look at the references provided at the end of the chapter.

## What is DocBook?

-   DocBook enables you to author and store document content in a
    presentation-neutral form that captures the logical structure of the
    content.
-   It has an easy-to-understand and widely used DTD. The DocBook tags
    are applied so that they have a certain \"common sense\" semantic
    content, at least to English speakers.
-   There are no official versions of the DocBook W3C XML Schema at this
    time. The DocBook Technical Committee is planning to offer an
    official Schema in the DocBook V5.0 time frame. The examples
    provided in this chapter will use the current official DTD.

### DTD vs. Schema:

A DTD is the XML Document Type Definition contains or points to markup
declarations that provide a grammar for a class of documents. A Schema
is a set of shared vocabularies that allow machines to carry out rules
made by people. It provides a means for defining the structure, content
and semantics of XML documents. In summary, schemas are a richer and
more powerful means of describing information than DTDs.

`<small>`{=html}Table 1: Here is a simple XML document`</small>`{=html}

``` XML
<author>
   <firstname>Rusen</firstname>
   <lastname>Gul</lastname>
 </author>
```

`<small>`{=html}Table 2: Here is the DTD for this
document`</small>`{=html}

``` XML
<!ELEMENT author(firstname, lastname)>
<!ELEMENT firstname(#PCDATA)>
<!ELEMENT lastname(#PCDATA)>
```

`<small>`{=html}Table 3: And here is the SCHEMA `</small>`{=html}

``` XML
<xs:element name="author">
   <xs:complexType>
     <xs:sequence>
       <xs:element name="firstname" type="xs:string"/>
       <xs:element name="lastname" type="xs:string"/>
     </xs:sequence>
   </xs:complexType>
</xs:element>
```

### Output formats for DocBook

XSL (Extensible Style Language) stylesheets can transform DocBook XML
into the following formats:

-   HTML
-   HTML Help (for Windows Help)
-   Java Help
-   XHTML
-   XSL Formatting Objects (FO)
-   PDF

DSSSL (Document Style Semantics and Specification Language) stylesheets
can transform DocBook SGML into the following formats:

-   HTML
-   MIF
-   RTF
-   TeX

### A Brief History

DocBook was created around 1991 by HaL Computer Systems and O\'Reilly &
Associates. It was developed primarily for the purpose of holding the
results of troff conversion of UNIX documentation, so that the files
could be interchanged. Now it is maintained by OASIS. The official web
site for DocBook is <http://www.oasis-open.org/docbook/>

### DocBook is used for:

1.  Books for print/trade publication. Many authors are using DocBook
    for writing books of all kinds, in various print and online formats,
    worldwide. Some examples include:
    -   Processing XML with
        Java
    -   Learning
        XML
    -   DocBook: The Definitive Guide
    -   Installing and Using
        DocBook
    -   Dive into Python
2.  Articles, theses and dissertations
3.  Maintaining websites
4.  Producing presentation slides, printed handouts, and whitepapers
5.  Documentation for commercial software and hardware

### DocBook Tools

DocBook is officially available as a DTD for both XML and SGML. You can
download both the latest DocBook XML DTD and DocBook SGML DTD from the
official DocBook site at OASIS. The examples provided in this chapter
will use DocBook XML DTD. Some experimental DocBook schemas are
available at sourceforge.net. DocBook is supported by a number of
commercial and open source tools. Easily customizable and extensible
\"standard\" DocBookStylesheets are available from the
DocBookOpenRepository along with the other free open source tools. See
DocBookTools on the
DocBook Wiki for a more complete list of commercial and open source
tools.

#### Other Free Tools:

1.  **XSLTProc:** One of the most known and fast processors. Available
    at <http://xmlsoft.org/XSLT/>.
2.  **Apache FOP:** XSL-FO implementation. Available at
    <http://xmlgraphics.apache.org/fop/>.
3.  **Xt:** One of original XSLT processors. Less frequently used now.
    Available at www.jclark.com.
4.  **DocBook2x:** Converts DocBook to man and Texinfo pages. Available
    at Sourceforge.
5.  **Refdb:** Creates reference databases and bibliographies from
    DocBook. Available at Sourceforge.

#### Commercial Tools:

1.  **Arbortext Epic:** Comprehensive suite of both editing and
    processing tools. Available at Arbortext
    website.
2.  **RenderX XEP:** FO to PDF rendering engine. Available at RenderX
    website.
3.  **Antenna House XSL Formatter:** FO to PDF rendering engine.
    Available at Antenna Housewebsite.

### SGML vs XML

The syntax of SGML and XML DTD is very similar but not identical. The
biggest difference between the DocBook DTD for SGML and the one for XML
is that the SGML DTD contains SGML exclusions in some content models.

**Example:**SGML DTD excludes `<footnote>`{=html} as a descendent of
`<footnote>`{=html}, 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.

## Creating a DocBook Document

In order to get started, you will need:

-   An XML editor. Download NetBeans IDE if
    you haven\'t done so yet.
-   The DocBook XML DTD. Although it is optional to use one, DTD\'s are
    useful when one wants to validate a document to check that it
    conforms to the DTD to which one claims it conforms. Hence, the
    DocBook DTD can be used to validate that a purported DocBook
    document. DocBook XML 4.2 is the current version of DocBook DTD.
    Download at the official DocBook
    website
-   The DocBook XSL stylesheets are maintained primarily by Norman
    Walsh. There are two sets of stylesheets: XSL and DSSSL. Download
    the latest version XSL 1.65.1 at
    Sourceforge.net
-   An XSLT processor (covered in the further sections)

`<small>`{=html}Table 4: A simple DocBook Book,
\"book.xml\"`</small>`{=html}

``` XML
 <?xml version="1.0"?>
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 <book>
  <bookinfo>
   <title>XML – Managing Data Exchange</title>
   <author>
    <firstname>Rusen</firstname>
    <surname>Gul</surname>
   </author>
  </bookinfo>
  <chapter>
   <title>Introduction</title>
   <sect1>
    <title>First Section</title>
    <para>This is a paragraph.</para>
   </sect1>
   <sect1>...</sect1>
  </chapter>
  <chapter>...</chapter>
  <chapter>...</chapter>
  <chapter>...</chapter>
  <appendix>...</appendix>
  <appendix>...</appendix>
 </book>
```

`<small>`{=html}Table 5: A simple DocBook article,
\"article.xml\"`</small>`{=html}

``` XML
 <?xml version="1.0"?>
 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
 <article>
  <articleinfo>
   <title>A Simple Approach To DocBook</title>
   <author>
    <firstname>Rusen</firstname>
    <surname>Gul</surname>
   </author>
  </articleinfo>
  <para>This is the introductory paragraph of my article.</para>
  <sect1>
   <title>First Section</title>
   <para>This is a paragraph in the first section.</para>
  <sect2>
   <title>This is the title for section2.</title>
   <para>This is a paragraph in section2.</para>
  </sect2>
  <sect2>...</sect2>
  <sect2>...</sect2>
  </sect1>
  <sect1>This is a high level section</sect1>
  <sect1>...</sect1>
  <sect1>...</sect1>
 </article>
```

Let's examine the details of a typical DocBook document. Standard header
to a DocBook XML file is a **DocType declaration**:

`<small>`{=html}Standard header`</small>`{=html}

`<!DOCTYPE name FORMALID "Owner//Keyword Description//Language">`

This tells the XML manipulation tools the DTD in use. Name is the name
of the root element in the document. **FORMALID** is replaced with
either **PUBLIC** or **SYSTEM** identifier or both. **PUBLIC**
identifies the DTD to which the document conforms. **SYSTEM** explicitly
states the location of the DTD used in the document by means of a
**URI** (Uniform Resource Indicator). **PUBLIC** identifiers are
optional in XML documents although **SYSTEM** Identifiers are mandatory
in the DOCTYPE declaration.

`<small>`{=html}Header example `</small>`{=html}

```{=html}
<?xml version="1.0"?>
```
`<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"`\
`"``http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd``">`

**Owner:** Oasis\
**Keyword Description:** DTD DocBook XML V4.2\
**Language:** EN - English

`<small>`{=html}**Caution!** If you are not online, you need to change
the URL system identifier to path where DTD is
installed:`</small>`{=html}

```{=html}
<?xml version="1.0"?>
```
`<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"`\
`"/usr/share/sgml/docbook/xml-dtd-4.2/docbookx.dtd">`

## Breaking a Document into Physical Portions

Before getting started, here is a useful tip! For the purposes of
convenience and performance, you might consider breaking a document into
physical chunks and work on each chunk separately. If you have a book
that consists of three chapters and two appendixes, you might create a
file called *book.xml*, which looks like this:

`<small>`{=html}Table 6: A physically divided book, "dividedbook.xml"
`</small>`{=html}

``` XML
 <?xml version="1.0"?>
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN"
 [<!ENTITY chap1 SYSTEM "chap1.xml">
 <!ENTITY chap2 SYSTEM "chap2.xml">
 <!ENTITY chap3 SYSTEM "chap3.xml">
 <!ENTITY appa SYSTEM "appa.xml">
 <!ENTITY appb SYSTEM "appb.xml">]
 <book>
  <title>A Physically Divided Book</title>
  &chap1;
  &chap2;
  &chap3;
  &appa;
  &appb;
 </book>
```

You can then write the chapters and appendixes conveniently in separate
files. This is why DocBook is well suited to large contents. Note that
these separate files do not and must not have document type
declarations.

For example, Chapter 1 might begin like this:

`<chapter id="ch1">`{=html}\

```{=html}
<title>
```
My First Chapter

```{=html}
</title>
```
```{=html}
<para>
```
My first paragraph.

```{=html}
</para>
```
...

`……………………………………………………………`

## Breaking a Document into Logical Portions

Here is a quick reference guide for DocBook Elements:
<http://www.docbook.org/tdg/en/html/ref-elements.html>

There are--literally--hundreds of DocBook elements. This is what makes
docBook very powerful. We will try to cover the major ones here and let
you review the rest on your own. Firstly, a classification; DocBook
Elements can be divided broadly into these categories:

  Sets                        collection of books
  --------------------------- ------------------------------------------
  Books                       books
  Divisions                   divide books into parts
  Components                  divide books or divisions into chapters
  Sections                    subdivide components
  Meta-information Elements   contain information about other elements
  Block Elements              occur at paragraph level
  Inline Elements             used to mark up running text

## Major DocBook Elements

### Set: A collection of books

*Set* is the very top of the DocBook structural hierarchy. There\'s
nothing that contains a *Set*.

**Some children elements:** Book, SetIndex, SetInfo, Subtitle, Title,
TitleAbbrev, ToC(table of contents).

**Reference page:**
<http://www.oreilly.com/catalog/docbook/chapter/book/set.html>

`<small>`{=html}Table 7: `<set>`{=html} element,
\"lordoftherings.xml\"`</small>`{=html}

``` XML
 <!DOCTYPE set PUBLIC "-//OASIS//DTD DocBook V4.2//EN">
 <set>
  <title>Lord of the Rings</title>
  <setinfo>
   <author>J.R. Tolkien</author>
  </setinfo>
  <book><title>The Fellowship of the Ring</title> ... </book>
  <book><title>The Two Towers</title> ... </book>
  <book><title>Return of the King</title> ... </book>
 <set>
```

### Book: A book

A *Book* is probably the most common top-level element in a document.
The DocBook definition of a book is very loose and general. It gives you
free rein by not imposing a strict ordering of elements.

**Some children elements:** Appendix, Article, Bibliography, BookInfo,
Chapter, Colophon, Dedication, Glossary, Index, LoT, Part, Preface,
Reference, SetIndex, Subtitle, Title, TitleAbbrev, ToC.

**Reference page:**
<http://www.oreilly.com/catalog/docbook/chapter/book/book.html>

``` XML
<small>Table 8: <book> element, "xmlbook.xml"</small>
 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.2//EN">
 <book>
  <title>XML – Managing Data Exchange</title>
  <titleabbrev>XML</titleabbrev>
  <bookinfo>
   <legalnotice><para>No notice is required.</para></legalnotice>
   <author><firstname>Rusen</firstname><surname>Gul</surname></author>
  </bookinfo>
  <dedication>
   <para>This book is dedicated to MIST 7700 class of 2004 at UGA.</para>
  </dedication>
  <preface>
   <title>Forword</title>
   <para>The book aims to fulfill the need for an introductory XML
   textbook. It contains the basics of XML as well as several tools
   using XML.</para>
   </preface>
  <chapter>
   <title>Introduction</title>
   <para>At least one chapter, reference, part, or article is required.</para>
  </chapter>
  <appendix>
   <title>Optional Appendix</title>
   <para>Appendixes are optional but handy.</para>
  </appendix>
 </book>
```

### Division: A collection of parts and references (optional)

*Division*s are the first hierarchical level below Book.

**Children elements:** Part (contain components), Reference (contain
RefEntrys)

### Components: Chapter-like elements of a Book or Part

These are Preface, Chapter, Appendix, Glossary, Bibliography, and
Article. Components generally contain block elements -or sections, and
some can contain navigational components and RefEntrys.

`<small>`{=html}Table 9: `<Bibliography>`{=html} element,
\"references.xml\"`</small>`{=html}

``` XML
 <!DOCTYPE bibliography PUBLIC "-//OASIS//DTD DocBook 4.2//EN">
 <bibliography>
  <title>References</title>
  <bibliomixed>
   <bibliomset relation=article>
    <surname>Watson</surname>
    <firstname>Richard</firstname>.
    <title role=article>Managing Global Communities </title>
   </bibliomset>
   <bibliomset relation=journal>
    <title>The World Wide Web Journal</title>
    <volumenum>2</volumenum>
    <issuenum>1</issuenum>.
    <publishername>O'Reilly & Associates, Inc.</publishername> and
    <corpname>The World Wide Web Consortium</corpname>.
    <pubdate>Winter, 1996</pubdate>
   </bibliomset>.
  </bibliomixed>
 </bibliography>
```

### Sections: Several sectioning elements

**a. Sect1...Sect5 elements** - the most common sectioning elements that
can occur in most component-level elements. These numbered section
elements must be properly nested (Sect2s can only occur inside Sect1s,
Sect3s can only occur inside Sect2s, and so on).

**b. Section element** - an alternative to numbered sections Sections
are recursive, meaning that you can nest them to any depth desired.

**c. SimpleSect element** - a terminal section that can occur at any
level SimpleSect cannot have any other sectioning element nested within
it.

**d. BridgeHead element** - a section title without any containing
section

**e. RefSect1...RefSect3 elements** - numbered section elements in
RefEntrys **f. GlossDiv, BiblioDiv, and IndexDiv elements** - do not
nest

Please see Table 4 and Table 5 for examples.

**Reference page:**
<http://www.oreilly.com/catalog/docbook/chapter/book/section.html>

### Meta-Information Elements -- contain bibliographic information

All of the elements at the section level and above include a wrapper for
meta-information about the content. Examples of meta-wrappers: BookInfo,
ArticleInfo, ChapterInfo, PrefaceInfo, SetInfo, GlossaryInfo.

`<small>`{=html}Table 10: `<bookinfo>`{=html} element`</small>`{=html}

``` XML
 <!DOCTYPE bookinfo PUBLIC "-//OASIS//DTD DocBook V4.2//EN">
 <bookinfo>
  <title>XML – Managing Data Exchange</title>
  <authorgroup>
   <author>
    <firstname>Richard</firstname>
    <surname>Watson</surname>
   </author>
   <author>
    <firstname>Hendrik</firstname>
    <surname>Fischer</surname>
   </author>
   <author>
    <firstname>Rusen</firstname>
    <surname>Gul</surname>
    <affiliation>
     <orgname>University of Georgia</orgname>
    </affiliation>
   </author>
  </authorgroup>
  <edition>Introduction to XML - Version 1.0 </edition>
  <pubdate>1997</pubdate>
  <copyright>
   <year>1999</year>
   <year>2000</year>
   <year>2001</year>
   <year>2002</year>
   <year>2003</year>
   <holder> O'Reilly & Associates, Inc. </holder>
   </copyright>
   <legalnotice>
     <para>Permission to use, copy, modify and distribute the DocBook
     DTD and its accompanying documentation for any purpose and without
     fee is hereby granted in perpetuity, provided that the above
     copyright notice and this paragraph appear in all copies.
     </para>
    </legalnotice>
 </bookinfo>
```

#### Block vs. Inline Elements

There are two classes of paragraph-level elements: *block* and *inline*.

Block elements are usually presented with a paragraph break before and
after them. Most can contain other block elements, and many can contain
character data and inline elements. Examples of block elements are:
Paragraphs, lists, sidebars, tables, and block quotations.

Inline elements are generally represented without any obvious breaks.
The most common distinguishing mark of inline elements is a font change,
but inline elements may present no visual distinction at all. Inline
elements contain character data and possibly other inline elements, but
they never contain block elements. They are used to mark up data. Some
examples are: cross references, filenames, commands, options, subscripts
and superscripts, and glossary terms.

### Block Elements - paragraph-level elements

The block elements occur immediately below the component and sectioning
elements.

#### Lists

  ---------------------------------------- ---------------------------------------------------------------------------------------------------------------------------
  `<b>`{=html}CalloutList`</b>`{=html}     A list of marks, frequently numbered and typically on a graphic or verbatim environment and their descriptions.
  `<b>`{=html}GlossList`</b>`{=html}       A list of glossary terms and their definitions.
  `<b>`{=html}ItemizedList`</b>`{=html}    An unordered (bulleted) list.
  `<b>`{=html}OrderedList`</b>`{=html}     A numbered list.
  `<b>`{=html}SegmentedList`</b>`{=html}   A repeating set of named items. For example, a list of states and their capitals might be represented as a SegmentedList.
  `<b>`{=html}SimpleList`</b>`{=html}      An unadorned list of items.
  `<b>`{=html}VariableList`</b>`{=html}    A list of terms and definitions or descriptions.

  ---------------------------------------- ---------------------------------------------------------------------------------------------------------------------------

`<small>`{=html}Table 11:

```{=html}
<segmentedlist>
```
element, \"statecapital.xml\"`</small>`{=html}

``` XML
 <!DOCTYPE para PUBLIC "-//OASIS//DTD DocBook V4.2//EN">
 <para>The capitals of the states of the United States of America are:
  <segmentedlist>
   <title>State Capitals</title>
   <segtitle>State</segtitle>
   <segtitle>Capital</segtitle>
   <seglistitem>
    <seg>Georgia</seg>
    <seg>Atlanta</seg>
   </seglistitem>
   <seglistitem>
    <seg>Alaska</seg>
    <seg>Juneau</seg>
   </seglistitem>
   <seglistitem>
    <seg>Arkansas</seg>
    <seg>Little Rock</seg>
   </seglistitem>
  </segmentedlist>
 </para>
```

`<small>`{=html}Table 12: \"statecapital.xml\" output`</small>`{=html}

------------------------------------------------------------------------

The capitals of the states of the United States of America are:

**State Capitals**

**State:** Georgia

**Capital:** Atlanta

**State:** Alaska

**Capital:** Juneau

**State:** Arkansas

**Capital:** Little Rock

------------------------------------------------------------------------

``` XML
 <small>Table 13: <orderedlist> element, "mashpotatoe.xml"</small>
 <!DOCTYPE para PUBLIC "-//OASIS//DTD DocBook V4.2//EN">
 <para>
  <orderedlist numeration="upperroman">
   <listitem>
    <para>Preparation</para>
    <orderedlist numeration="upperalpha">
     <listitem><para>Chop tomatoes</para>
     </listitem>
     <listitem><para>Peel onions</para>
     </listitem>
     <listitem><para>Mash potatoes</para>
     </listitem>
    </orderedlist>
   </listitem>
   <listitem>
    <para>Cooking</para>
    <orderedlist numeration="upperalpha">
     <listitem><para>Boil water</para>
     </listitem>
      <listitem><para>Put tomatoes and onions in </para></listitem>
      <listitem><para>Blanch for 5 minutes</para>
     </listitem>
    </orderedlist>
   </listitem>
  </orderedlist>
 </para>
```

`<small>`{=html}Table 14: \"mashpotatoe.xml\" output`</small>`{=html}

------------------------------------------------------------------------

I.Preparation\
    A.Chop tomatoes\
    B.Peel onions\
    C.Mash potatoes\
II.Cooking\
    A.Boil water\
    B.Put tomatoes and onions in\
    C.Blanch for 5 minutes\
\-\-\--

#### Admonitions

There are five types of *admonition*s: Caution, Important, Note, Tip,
and Warning.

``` XML
<small>Table 15: <caution> element, "caution.xml"</small>
 <!DOCTYPE caution PUBLIC "-//OASIS//DTD DocBook V4.2//EN">
 <caution>
  <title>This is a caution</title>
  <para>Be careful while opening the box!</para>
 </caution>
```

#### Line-specific environments

*Line-specific environments* preserve whitespace and line breaks.

  ----------------------------------------- --------------------------------------------------------------------------------------
  `<b>`{=html}Address`</b>`{=html}          A real-world address, generally a postal address
  `<b>`{=html}LiteralLayout`</b>`{=html}    A block of text in which line breaks and white space are to be reproduced faithfully
  `<b>`{=html}ProgramListing`</b>`{=html}   A literal listing of all or part of a program
  `<b>`{=html}Screen`</b>`{=html}           Text that a user sees or might see on a computer screen
  `<b>`{=html}ScreenShot`</b>`{=html}       A representation of what the user sees or might see on a computer screen
  `<b>`{=html}Synopsis`</b>`{=html}         A general-purpose element for representing the syntax of commands or functions
  ----------------------------------------- --------------------------------------------------------------------------------------

`<small>`{=html}Table 16:

```{=html}
<literallayout>
```
element, \"If_by_Kipling.xml\"`</small>`{=html}

``` XML
 <!DOCTYPE blockquote PUBLIC "-//OASIS//DTD DocBook V4.2//EN">
 <blockquote>
  <attribution>Rudyard Kipling,
   <citetitle>If</citetitle>
  </attribution>
  <literallayout>
      If you can force your heart and nerve and sinew
 To serve your turn long after they are gone,
 And so hold on when is nothing in you
 Except the Will
 which says to them:
      Hold on!
  </literallayout>
 </blockquote>
```

#### Common block-level elements

*Common block-level elements* include Examples, figures, and tables. The
distinction between formal and informal elements is that formal elements
have titles while informal ones do not.

**Example, InformalExample**

`<small>`{=html}Table 17:

```{=html}
<example>
```
element`</small>`{=html}

``` XML
 <!DOCTYPE example PUBLIC "-//OASIS//DTD DocBook V4.2//EN">
 <example>
  <title>Sample code</title>
  <programlisting>print "Hello, world!"</programlisting>
 </example>
```

**Figure, InformalFigure**

`<small>`{=html}Table 18:

```{=html}
<figure>
```
element`</small>`{=html}

``` XML
 <!DOCTYPE figure PUBLIC "-//OASIS//DTD DocBook V4.2//EN">
 <figure>
  <title>Revenues for Q1</title>
  <mediaobject>
   <imageobject>
    <imagedata fileref="q1revenue.jpg" format="JPG"/>
   </imageobject>
  </mediaobject>
 </figure>
```

**Table, InformalTable**

`<small>`{=html}Table 19: \<table\> element`</small>`{=html}

``` XML
<!DOCTYPE table PUBLIC "-//OASIS//DTD DocBook V4.2//EN"><br>
<table frame="frametype">
 <title>frame="frametype"</title>
 <tgroup cols="1">
  <thead>
   <row>
    <entry>row 1, cell 1</entry>
    <entry>row 1, cell 2</entry>
    <entry>row 1, cell 3</entry>
   </row>
  </thead>
  <tbody>
   <row>
    <entry>row 2, cell 1</entry>
    <entry>row 2, cell 2</entry>
    <entry>row 3, cell 3</entry>
   </row>
  </tbody>
 </tgroup>
</table>
```

#### Paragraphs

*Paragraphs* are Para, SimPara (simple paragraphs may not contain other
block-level elements), and FormalPara (formal paragraphs have titles).
Paragraphs are the most commonly used high-level elements that can
contain block elements such as itemizedlist and Mediaobject and can
contain almost all inline elements.

**Reference page:** <http://www.docbook.org/tdg/en/html/para.html>

`<small>`{=html}Table 20:

```{=html}
<para>
```
element, \"Nietzsche.xml\"`</small>`{=html}

``` XML
<!DOCTYPE para PUBLIC "-//OASIS//DTD DocBook V4.2//EN">
<para>
 <quote>Behold the superfluous. They are always sick. They vomit their gall and call it a newspaper.</quote>
 -Friedrich Wilhelm Nietzsche,
 <citetitle>Twilight of the Idols</citetitle>
</para>
```

#### Equations

Equation and InformalEquation (without titles)

`<small>`{=html}Table 21:

```{=html}
<informalequation>
```
element inside a

```{=html}
<para>
```
element`</small>`{=html}

``` XML
<!DOCTYPE para PUBLIC "-//OASIS//DTD DocBook V3.1//EN"> <para>
  The equation
  <informalequation>
   <alt>e^(pi*i) + 1 = 0</alt>
   <graphic fileref="figures/epi10"></graphic>
  </informalequation>
is delightful because it joins together five of the most important mathematical constants.
</para>
```

#### Graphics

InlineGraphic, MediaObject, InlineMediaObject

These elements may contain video, audio, image, and text data. A single
media object can contain several alternative forms from which the
presentation system can select the most appropriate object.

Please see Table 18 for example.

### Inline Elements -- used to mark up running text

In published documents, inline elements often cause a font change or
other small change, but they do not cause line or paragraph breaks.

```{=html}
<table border="1" cellspacing="0" cellpadding="2">
```
```{=html}
<tr>
```
```{=html}
<td>
```
`<b>`{=html}Abbrev `</b>`{=html}

```{=html}
</td>
```
```{=html}
<td>
```
An abbreviation, especially one followed by a period.

```{=html}
</td>
```
```{=html}
</tr>
```
```{=html}
<tr>
```
```{=html}
<td>
```
`<b>`{=html}Acronym`</b>`{=html}

```{=html}
</td>
```
```{=html}
<td>
```
An often pronounceable word made from the initial (or selected) letters
of a name or phrase.

```{=html}
</td>
```
```{=html}
</tr>
```
```{=html}
<tr>
```
```{=html}
<td>
```
`<b>`{=html}Emphasis`</b>`{=html}

```{=html}
</td>
```
```{=html}
<td>
```
Emphasized text.

```{=html}
</td>
```
```{=html}
</tr>
```
```{=html}
<tr>
```
```{=html}
<td>
```
`<b>`{=html}Footnote `</b>`{=html}

```{=html}
</td>
```
```{=html}
<td>
```
A footnote. The location of the Footnote element identifies the location
of the first reference to the footnote. Additional references to the
same footnote can be inserted with FootnoteRef.

```{=html}
</td>
```
```{=html}
</tr>
```
```{=html}
<tr>
```
```{=html}
<td>
```
`<b>`{=html}Phrase`</b>`{=html}

```{=html}
</td>
```
```{=html}
<td>
```
A span of text.

```{=html}
</td>
```
```{=html}
</tr>
```
```{=html}
<tr>
```
```{=html}
<td>
```
`<b>`{=html}Quote`</b>`{=html}

```{=html}
</td>
```
```{=html}
<td>
```
An inline quotation.

```{=html}
</td>
```
```{=html}
</tr>
```
```{=html}
<tr>
```
```{=html}
<td>
```
`<b>`{=html}Trademark`</b>`{=html}

```{=html}
</td>
```
```{=html}
<td>
```
A trademark.

```{=html}
</td>
```
```{=html}
</tr>
```
```{=html}
<tr>
```
```{=html}
<td>
```
`<b>`{=html}Citation`</b>`{=html}

```{=html}
</td>
```
```{=html}
<td>
```
An inline bibliographic reference to another published work.

```{=html}
</td>
```
```{=html}
</tr>
```
```{=html}
<tr>
```
```{=html}
<td>
```
`<b>`{=html}GlossTerm`</b>`{=html}

```{=html}
</td>
```
```{=html}
<td>
```
A glossary term.

```{=html}
</td>
```
```{=html}
</tr>
```
```{=html}
<tr>
```
```{=html}
<td>
```
`<b>`{=html}Link`</b>`{=html}

```{=html}
</td>
```
```{=html}
<td>
```
A hypertext link.

```{=html}
</td>
```
```{=html}
</tr>
```
```{=html}
<tr>
```
```{=html}
<td>
```
`<b>`{=html}ULink `</b>`{=html}

```{=html}
</td>
```
```{=html}
<td>
```
A link that addresses its target by means of a URL (Uniform Resource
Locator).

```{=html}
</td>
```
```{=html}
</tr>
```
```{=html}
<tr>
```
```{=html}
<td>
```
`<b>`{=html}XRef`</b>`{=html}

```{=html}
</td>
```
```{=html}
<td>
```
A cross reference to another part of the document.

```{=html}
</td>
```
```{=html}
</tr>
```
```{=html}
<tr>
```
```{=html}
<td>
```
`<b>`{=html}ForeignPhrase`</b>`{=html}

```{=html}
</td>
```
```{=html}
<td>
```
A word or phrase in a language other than the primary language of the
document.

```{=html}
</td>
```
```{=html}
</tr>
```
```{=html}
<tr>
```
```{=html}
<td>
```
`<b>`{=html}ComputerOutput `</b>`{=html}

```{=html}
</td>
```
```{=html}
<td>
```
Data, generally text, displayed or presented by a computer.

```{=html}
</td>
```
```{=html}
</tr>
```
```{=html}
<tr>
```
```{=html}
<td>
```
`<b>`{=html}Markup `</b>`{=html}

```{=html}
</td>
```
```{=html}
<td>
```
A string of formatting markup in text that is to be represented
literally.

```{=html}
</td>
```
```{=html}
</tr>
```
```{=html}
<tr>
```
```{=html}
<td>
```
`<b>`{=html}Replaceable`</b>`{=html}

```{=html}
</td>
```
```{=html}
<td>
```
Content that may or must be replaced by the user.

```{=html}
</td>
```
```{=html}
</tr>
```
```{=html}
<tr>
```
```{=html}
<td>
```
`<b>`{=html}UserInput `</b>`{=html}

```{=html}
</td>
```
```{=html}
<td>
```
Data entered by the user.

```{=html}
</td>
```
```{=html}
</tr>
```
```{=html}
<tr>
```
```{=html}
<td>
```
`<b>`{=html}Literal`</b>`{=html}

```{=html}
</td>
```
```{=html}
<td>
```
Inline text that is some literal value.

```{=html}
</td>
```
```{=html}
</tr>
```
```{=html}
<tr>
```
```{=html}
<td>
```
`<b>`{=html}Command `</b>`{=html}

```{=html}
</td>
```
```{=html}
<td>
```
The name of an executable program or other software command.

```{=html}
</td>
```
```{=html}
</tr>
```
```{=html}
<tr>
```
```{=html}
<td>
```
`<b>`{=html}MsgText `</b>`{=html}

```{=html}
</td>
```
```{=html}
<td>
```
The actual text of a message component in a message set.

```{=html}
</td>
```
```{=html}
</tr>
```
```{=html}
<tr>
```
```{=html}
<td>
```
`<b>`{=html}Optional `</b>`{=html}

```{=html}
</td>
```
```{=html}
<td>
```
Optional information.

```{=html}
</td>
```
```{=html}
</tr>
```
```{=html}
<tr>
```
```{=html}
<td>
```
`<b>`{=html}Email`</b>`{=html}

```{=html}
</td>
```
```{=html}
<td>
```
An email address.

```{=html}
</td>
```
```{=html}
</tr>
```
```{=html}
<tr>
```
```{=html}
<td>
```
`<b>`{=html}Database `</b>`{=html}

```{=html}
</td>
```
```{=html}
<td>
```
The name of a database, or part of a database.

```{=html}
</td>
```
```{=html}
</tr>
```
```{=html}
<tr>
```
```{=html}
<td>
```
`<b>`{=html}Filename`</b>`{=html}

```{=html}
</td>
```
```{=html}
<td>
```
The name of a file.

```{=html}
</td>
```
```{=html}
</tr>
```
```{=html}
<tr>
```
```{=html}
<td>
```
`<b>`{=html}Token `</b>`{=html}

```{=html}
</td>
```
```{=html}
<td>
```
A unit of information.

```{=html}
</td>
```
```{=html}
</tr>
```
```{=html}
<tr>
```
```{=html}
<td>
```
`<b>`{=html}Type`</b>`{=html}

```{=html}
</td>
```
```{=html}
<td>
```
The classification of a value.

```{=html}
</td>
```
```{=html}
</tr>
```
```{=html}
<tr>
```
```{=html}
<td>
```
`<b>`{=html}Application `</b>`{=html}

```{=html}
</td>
```
```{=html}
<td>
```
The name of a software program.

```{=html}
</td>
```
```{=html}
</tr>
```
```{=html}
</table>
```
`<b>`{=html}Entities for Special Characters`</b>`{=html}

The following entities are provided for special characters:

```{=html}
<table border="1" cellspacing="0" cellpadding="2">
```
```{=html}
<tr>
```
```{=html}
<td align="left" bgcolor="#ffff66">
```
`<span style="color:black;">`{=html}Character`</span>`{=html}

```{=html}
</td>
```
```{=html}
<td align="left" bgcolor="#ffff66">
```
`<span style="color:black;">`{=html}Entity`</span>`{=html}

```{=html}
</td>
```
```{=html}
</tr>
```
```{=html}
<tr>
```
```{=html}
<td>
```
\<

```{=html}
</td>
```
```{=html}
<td>
```
& lt;

```{=html}
</td>
```
```{=html}
</tr>
```
```{=html}
<tr>
```
```{=html}
<td>
```
\>

```{=html}
</td>
```
```{=html}
<td>
```
& gt;

```{=html}
</td>
```
```{=html}
</tr>
```
```{=html}
<tr>
```
```{=html}
<td>
```
&

```{=html}
</td>
```
```{=html}
<td>
```
& amp;

```{=html}
</td>
```
```{=html}
</tr>
```
```{=html}
<tr>
```
```{=html}
<td>
```
\"

```{=html}
</td>
```
```{=html}
<td>
```
& quot;

```{=html}
</td>
```
```{=html}
</tr>
```
```{=html}
<tr>
```
```{=html}
<td>
```
\'

```{=html}
</td>
```
```{=html}
<td>
```
\'

```{=html}
</td>
```
```{=html}
</tr>
```
```{=html}
</table>
```
## Publishing a DocBook Document

**DSSSL vs XSL Stylesheets:**

*Document Style Semantics and Specification Language (DSSSL)* is a
stylesheet language for both print and online rendering. It is mainly
intended to work with SGML.

*Extensible Stylesheet Language (XSL)* is a language for expressing
stylesheets written in XML. It includes the formatting object language,
but refers to separate documents for the transformation language and the
path language. In this chapter, we will use XSL Stylesheets because
they're more powerful, you are already familiar with them, and they are
intended to work with XML.

### Step 1: Get the Standard StyleSheets

DocBook strictly separates the content and appearance of a document. A
DocBook document only explains the semantics of the document, not its
formatting or appearance. In order to publish your DocBook Document, you
will need to use a set of DSSSL or XSL Stylesheets describing the
formatting and an XSL processor.

If you're thinking that it would be a lot of work to write your own XSL
stylesheets, you're right. The good news is that you don't need to.
There are a large number of freely available standard XSL stylesheets
for DocBook maintained primarily by Norman Walsh.

Make sure that you download the latest version of these stylesheets at
Sourceforge.net - Stylesheets
Repository.
The stylesheet distribution consists of a collection of modular XSL
files that are assembled into several complete XSL stylesheets. There is
a stylesheet for generating a single HTML file, and one for generating
multiple smaller HTML files from a single DocBook document. There are
stylesheets for print output, XHTML output, HTML Help output, and
JavaHelp output. Since there are XSL processors for all major computer
types, you can use DocBook on Unix, Linux, Windows, and Macintosh
computers. By using these default stylesheets installed on your system,
it is quite easy to create customized stylesheets. But don't forget to
note that the common approach to customize the stylesheets is creating a
customization layer rather than editing them directly.

### Step 2: Download an XSLT processor

To publish HTML from your XML documents, you will need an XSLT engine.
To print, you need an XSLT engine to produce formatting objects (FO),
which then must be processed with an FO engine to produce PostScript or
PDF output. A variety of XSLT engines are available. Here\'s a list of
some free/open-source ones you might consider. Note that xsltproc and
Saxon are currently the only recommended XSLT engines for use with
DocBook.

#### XSLT Engines

1.  **Xsltproc:** A free processor written in C, available as part of
    the open source libxml2 library from the Gnome development project.
    It is considered the fastest of the processors, and is highly
    conformant to the specification. Download at
    <http://xmlsoft.org/XSLT/>
2.  **Saxon:** A free processor written in Java, that can be run on any
    operating system with a modern Java interpreter. It uses the Aelfred
    XML parser internally, which has some bugs, so many people
    substitute the Xerces parser. Download at
    <http://saxon.sourceforge.net/>
3.  **Xalan:** Xalan is part of the Apache XML Project. It has versions
    written in both Java and C++, both of them free. The Java version is
    highly portable and more fully developed. Generally Xalan is used
    with the Xerces XML parser (Java or C++), also available from the
    Apache XML Project. Download at <http://xml.apache.org/>

Your choice of an XSLT engine may depend a lot on the environment in
which you\'ll be running the engine. Many DocBook users who need or want
a non-Java application use xsltproc. It\'s very fast and the developers
respond very quickly to bug reports and questions. But one current
limitation xsltproc has is that it doesn\'t yet support Norm Walsh\'s
DocBook-specific XSLT extension functions.

Saxon is the most popular one for use in a Java environment. It also
supports Norm Walsh\'s DocBook-specific XSLT extension functions.

*NetBeans IDE*, the XML editor we've been using for other chapters'
exercises, has a built-in XSLT processor using the XALAN parser by
default. NetBeans IDE not only lets you validate your XML documents but
also does XSL transformations right there in the IDE. It will work for
this chapter's purpose well enough. It doesn't provide any XSLT
debugging though, so you might want to get yourself a decent XSL IDE
(e.g.,XML Spy or Xcelerator) for serious XSLT work.

#### FO Engines

For generating print/PDF output from FO files, there are two
free/open-source FO engines:

1.  **PassiveTeX:** available at
    <http://www.tei-c.org.uk/Software/passivetex/index.xml.ID=body.1_div.1>.
    Download and installation information at
    <http://www.tei-c.org.uk/Software/passivetex/index.xml.ID=body.1_div.3>.
2.  **FOP:** a Java-based processor from the Apache XML Project,
    available at <http://xml.apache.org/fop/>

### Step 3: Customize the XSL stylesheets

#### Output to HTML

-   The main strength of standard stylesheets is that they are easily
    customizable.
-   Parameters found in params.xsl
-   Call your customization layer instead of the standard stylesheet

`<small>`{=html}Table 22: A customized XSL stylesheet,
\"myxsl1.xsl\"`</small>`{=html}

``` XML
 <?xml version="1.0"?>
   <!-- Customization layer -->
 <xsl:stylesheet xmlns:xsl="http://www.w3.org/1999/XSL/Transform" version="1.0">
   <nowiki><!-- Use 'chunk.xsl' in line below to chunk files. --></nowiki>
 <xsl:import href="/usr/share/sgml/docbook/docbook-xsl-1.51.1/html/docbook.xsl"/>
 <xsl:param name="chapter.autolabel" select="1"/>
 <xsl:param name="section.autolabel" select="1"/>
 <xsl:param name="section.label.includes.component.label" select="1"
 doc:type="boolean"/>
   <!-- Insert more parameters here. -->
 </xsl:stylesheet>
```

-   Beyond setting parameters, you can modify XSLT \"templates\" to
    override default behavior
-   You need at least a minimal knowledge of XSLT

`<small>`{=html}Table 23: A customized XSL stylesheet,
\"myxsl2.xsl\"`</small>`{=html}

``` XML
 <xsl:template match="emphasis">
 <xsl:choose>
 <xsl:when test="(@role='strong') or (@role='bold')">
   <xsl:call-template name="inline.boldseq"/>
 </xsl:when>
 <xsl:otherwise>
   <xsl:call-template name="inline.italicseq"/>
 </xsl:otherwise>
 </xsl:choose>
 </xsl:template>
```

#### Output to PDF

It generally requires a two-stage process:

1.  Generation of FO from XML
2.  Generation of PDF from FO

`<small>`{=html}Table 24: An XSL stylesheet to generate FO,
\"myxsl3.xsl\"`</small>`{=html}

`xsltproc -o sample.fo  $DB/fo/docbook.xsl sample.xml`\
`fop.sh -fo sample.fo -pdf sample.pdf`

#### Extensions

**a. Slides Doctype**

-   Creation of presentation slides from DocBook XML
-   You can create HTML (with or without frames) and FO
-   Uses DocBook elements within a specific hierarchical framework
-   Downloadable from DocBook Open Repository at SourceForge

`<small>`{=html}Table 25: \"slides.xml\"`</small>`{=html}

``` XML
<!DOCTYPE slides SYSTEM "/usr/share/sgml/docbook/xsl-slides-1.1/slides.dtd">
<slides>
 <slidesinfo>
  <title>A Simple Approach to DocBook</title>
 </slidesinfo>
 <foil>
  <title>My first slide</title>
  <itemizedlist>
   <listitem><para>...</para></listitem>
   <listitem><para>...</para></listitem>
   <listitem><para>...</para></listitem>
  </itemizedlist>
 </foil>
 <foil>
  <title>My second slide</title>
  <para>... </para>
 </foil>
</slides>
```

`<b>`{=html}b. Website Doctype`</b>`{=html}

-   Creation of web sites from a collection of DocBook XML files
-   Uses most DocBook elements within specific framework. It has
    separate files that control page navigation and hierarchy.
-   Downloadable from DocBook Open Repository at SourceForge.

`<small>`{=html}Table 26: \"website.xml\"`</small>`{=html}

``` XML
<!DOCTYPE webpage SYSTEM "../website.dtd" [
<!NOTATION XML SYSTEM "xml">
<!ENTITY test1a SYSTEM "test1a.xml" NDATA XML>
<!ENTITY test3 SYSTEM "test3.xml" NDATA XML>
<!ENTITY about.xml SYSTEM "about.xml" NDATA XML>]>
<webpage id="home">
    <config param="desc" value="The Test Home Page"/>
    <config param="rcsdate" value="$Date: 2001/11/08 20:44:20 $"/>
    <config param="footer" value="about.html" altval="About..."/>
    <head>
        <title>Welcome to Website</title>
        <summary>Introduction</summary>
        <keywords>Rusen Gul, XSL, XML, DocBook, Website</keywords>
    </head>
    <para> This website demonstrates the DocBook.</para>
   <webtoc/>
        <section>
            <title>What is a Website?</title>
               <para>A website is a collection of pages organized, for the purposes of navigation, into one or more hierarchies. In Website, each page is a separate XML document authored according to the Website DTD, a customization of <ulink url="http://www.oasis-open.org/docbook/">DocBook</ulink>.</para>
        </section>
</webpage>
```

## Why use DocBook?

This certainly looks like too much work, doesn't it? You're not wrong.
Why do we bother to use DocBook then?

-   It is portable! A document written in DocBook markup can be
    converted into HTML, PostScript, PDF, RTF, DVI, plain ASCII text
    easily and quickly without any expensive tools.

```{=html}
<!-- -->
```
-   It is flexible! It enables output to multiple formats, including
    HTML, PDF, Slides, and many others.

```{=html}
<!-- -->
```
-   It separates the content from format! DocBook is only concerned with
    the structure of a document. It frees the author from worrying about
    the formatting and layout of a document.

```{=html}
<!-- -->
```
-   It is easy to understand! Most of DocBook elements are self
    explanatory.

```{=html}
<!-- -->
```
-   It can handle large quantities of content. You can physically divide
    the document into different files and work on them separately and
    conveniently.

```{=html}
<!-- -->
```
-   It is free! There a lot of freely available open source tools used
    to work with DocBook.

DocBook is well suited to any collection of technical documentation that
is regularly maintained and published. Multiple authors can contribute
to a single document, and their content can easily be merged because all
the authors are using a highly structured, standard markup language.
Just one little point to keep in mind; because the formatting for
DocBook documents is strictly accomplished by stylesheets, DocBook is
not well matched to highly designed layout-driven content like
magazines.

Setting up a DocBook system will certainly take some time and effort.
The payoff will be an efficient, flexible, and inexpensive publishing
system that is iterative and that can grow with your needs. Therefore,
it is worth the effort!

## DocBook Filters - Reading and Writing DocBook XML Using OpenOffice.org

The goal of the project is to use OpenOffice.org as a WYSIWYG editor of
XML content to edit structured documents using styles. When exported,
these styles are then transformed to XML tags. This section shows you
how to enable and use DocBook filters. Below are some links to
stylesheets that can be download to use the latest transformations.

### Enabling the DocBook XSLT\'s in OpenOffice.org 1.1 Beta 2/RC

There are three different ways to enable the DocBook filters.

1.  Download the DocBook XSLT Stylesheets and OpenOffice.org Style
    Template
    -   Using this method will make certain that the most recent
        stylesheets and OpenOffice.org style template will be used for
        import and export. It is required to download the following to
        import, export and modify DocBook documents in OpenOffice.org:
    -   The relevant XSLT stylesheets for the XML transformations (All
        available
        here)
    -   An OpenOffice.org style template that contains custom styles
        corresponding to DocBook tags (Available
        here)

The most recent stylesheets support the import and export of DocBook
documents with article or chapter as the top-level tag. The different
stylesheets required for each of these operation are listed below:

-   Stylesheets required for import Article
    docbooktosoffheadings.xsl
-   Stylesheets required for import Chapter
    docbooktosoffheadings.xsl
-   Stylesheets required for export Article
    sofftodocbookheadings_article.xsl
-   Stylesheets required for export Chapter
    sofftodocbookheadings_chapter.xsl

OpenOffice.org Template required for Article and Chapter documents:

-   DocBookTemplate.stw

Creating a new DocBook filter

-   Go to Tools -\> XML Filter Settings\...
-   Set Filter Name and Name of File Type to DocBook (Chapter)
-   Go to the Transformation tab
-   Set DocType to `<chapter>`{=html}
-   For XSLT for Export browse to the chapter export stylesheet
    (docbooktosoffheadings.xsl).
-   For XSLT for Import browse to the chapter import stylesheet
    (sofftodocbookheadings_chapter.xsl).
-   For Template for Import browse to the style template
    (DocBookTemplate.stw).
-   Click OK and close the XSLT Filter Setting dialog

To create a DocBook Article filter, the above steps can be repeated with
article replacing chapter

1.  Download the DocBook XSLT Jar Packages for Article or Chapter

This method is more convenient, however there is no guarantee that the
most recent stylesheets and OpenOffice.org template will be used.

1.  Download the DocBook UNO component for Article only

The DocBook UNO component adds filter support for the retention of
unresolved XML entities.

-   Download the DocBookFilter
-   Unzip it to the `<OOo install Dir>`{=html}/
-   Run pkgchk in the `<OOo install Dir>`{=html}/program dir
-   The DocBook Article filter will now import DocBook unresolved
    entities as OpenOffice.org set variables

### How to Import a DocBook document

A DocBook article or chapter document can now be opened using the File
-\> Open dialog.

-   Go to File -\> Open\...
-   Browse to the DocBook document.
-   Click OK

The DocBook XSLT filter should automatically determine the root element
of the document and import it with the matching XSLT filter.
Alternatively, it is possible to browse manually to the desired DocBook
filter in the File Type combo-box in the File -\> Open dialog.

### How to Export a DocBook document

The DocBook document can also be exported using the File -\> Save As
dialog.

-   Go to File -\> Save As\...
-   Browse to the location where the document is to be saved
-   Click Save

Again, the DocBook XSLT filter should automatically determine the file
type and export with the matching XSLT filter. Alternatively, it is
possible to browse manually to the desired DocBook filter in the File
Type combo-box in the File -\> Save As dialog.

### Using OpenOffice.org Headings and Styles for different DocBook tags

Using OpenOffice.org styles to represent DocBook tags The style template
supplies all of the custom styles that are currently supported. Once a
DocBook document has been imported to OpenOffice.org, the available
DocBook specific styles can be viewed using the Stylist. On import, each
of the supported DocBook tags will be mapped to formatted OpenOffice.org
content. Similarly, to modify the imported DocBook document,
OpenOffice.org text styles can be used to represent the DocBook tags
marking-up the text. NOTE: A new DocBook document can be created in
OpenOffice.org by opening the DocBookTemplate.stw. The document can then
be saved as a DocBook document, and the new content will be represented
as DocBook mark-up. How to create new DocBook content:

-   Press F11 to display the Stylist
-   Select Custom Styles in the Stylist combo-box
-   Click the Character Styles icon (second from left on the Stylist)
-   Double-click the SubScript style
-   Enter text in the OpenOffice.org document
-   On exporting as DocBook, the text formatted as the SubScript custom
    style will be marked-up with the DocBook tag `<subscript>`{=html}

How to create DocBook sections: Initially the DocBook project used
OpenOffice.org sections to enforce the nesting of DocBook sections.
Feedback has shown that authors wish to use the common word processing
styles such as Heading1, Heading2, etc. The following instructions
describe how to create a `<sect1>`{=html} that contains a
`<sect2>`{=html}

-   Press F11 to display the Stylist
-   Select All Styles in the Stylist combo-box
-   Click the Paragraph Styles icon (first in the left on the Stylist)
-   Double-click the Heading 1 style
-   Enter the text to be the `<sect1>`{=html} title
-   All the text below this heading will now be the content of the
    DocBook `<sect1>`{=html}
-   Enter other DocBook styles, tables, etc.
-   Enter other DocBook styles, tables, etc. to be included in
    `<sect1>`{=html}

1.  Double-click the Heading 2 style
2.  Enter the text to be the `<sect2>`{=html} title
3.  All the text below this heading will now be the content of the
    DocBook `<sect2>`{=html}
4.  Enter other DocBook styles, tables, etc. to be included in
    `<sect2>`{=html}

-   This nesting of DocBook sect\'s using OpenOffice headings can go as
    far as `<sect4>`{=html} / Heading 4

Navigating through the document: If you wish to see how DocBook sections
are nested as OpenOffice.org headings, use the F5 key to Display the
Navigator window. Expand the headings tag, to display the layout of the
headings within the document. You can skip to the start of a given
DocBook section/OpenOffice.org heading, by double-clicking on it.

## Exercises

```{=html}
<div style="color:#8b4513;">
```
1.  Download the latest DocBook DTD at
    <http://www.oasis-open.org/docbook/xml/>. Convert the Learning
    Objectives part of Chapter 2 of this textbook into a DocBook
    document. Check that it is well-formed and valid.
2.  Download the DocBook XSL Stylesheets at
    Sourceforge.net.
    Transform the DocBook document you created in the first exercise
    into an HTML file by using the *docbook.xsl* stylesheet in the
    *HTML* folder.

```{=html}
</div>
```
## References and Useful Links

1.  DocBook Official Website
2.  DocBook: The Definitive Guide, by Norman Walsh and Leonard Muellner,
    published by O\'Reilly & Associates, October 1999
    <http://www.docbook.org/>
3.  Sourceforge - DocBook Open
    Repository
4.  Installing and Using DocBook - Copyright 2002, The University Of
    Birmingham
5.  Using the DocBook XSL Stylesheets -
    <http://www.sagehill.net/docbookxsl/index.html>
6.  Setting Up A Free XML/SGML DocBook Editing Suite For Windows And
    Unix
7.  <http://lists.oasis-open.org/archives/docbook-apps/>
8.  <http://www.dulug.duke.edu/~mark/docbookmarks/>
9.  <http://www.linuxdoc.org/LDP/LDP-Author-Guide/>
10. <http://www.nwalsh.com/docs/>
11. <http://www.e-smith.org/docs/docprocess.html>
12. <http://www.lodestar2.com/people/dyork/talks/docbook/>
13. DocBook mailing list:
    mailto:docbook@lists.oasis-open.org
14. <http://xml.openoffice.org/xmerge/docbook/>


# XML - Managing Data Exchange/SMIL

`<b>`{=html}Learning objectives`</b>`{=html}

Upon completion of this chapter, you will be able to

-   Understand SMIL fundamentals.
-   Understand how and why SMIL is used.
-   Locate and use SMIL technical specifications, tutorials and open
    source SMIL tools.
-   Create simple SMIL markup.
-   Watch your SMIL file come to life in a SMIL viewer.

## Introduction

With the explosion of the late 90\'s popularity of the internet, The
World Wide Web Consortium (W3C) saw the need to extend the capabilities
of the web with respect to information structure and media presentation.
This is how they arrived at XML, the extensible language for describing
information structure. Furthermore, SMIL is built upon XML: it is a
specialized language to describe the presentation of media objects.
Since the W3C (and everyone else) doesn\'t know what media types will be
around in the future (virtual environments, brainwave-synch experiences,
psychic/holographic/video), XML was an appropriate choice in designing
SMIL to be extended to support these media.

In order to integrate this technology with HTML and extend the
application of media in HTML, the W3C decided to make a push towards
modularizing these languages or protocols. SMIL is one of many modular
languages which \'plug-in\' to the larger framework of XML.

### What is SMIL?

SMIL (pronounced \"smile\") is an acronym for Synchronized Multimedia
Integration Language. It is thought of as an open-standard version of
PowerPoint for the internet. SMIL is an XML-based language, similar in
appearance to HTML, that allows for the authoring of interactive
audiovisual presentations. SMIL enables the streaming of audio and video
with images, text or other media types. It is a language describing the
temporal and spacial placement of one or more media objects. Although
SMIL can be written with a simple text editor, hand-writing SMIL
documents can be a time-consuming and complicated endeavor. Therefore it
is better to use a tool for generating complicated SMIL documents.

### World Wide Web Consortium (W3C) SYMM group

Since November 1997, the W3C SYMM group has been
developing the SMIL language. It finalized SMIL 1.0 in June of 1998 and
SMIL 2.0 in August of 2001.

### Why SMIL?

Although plug-ins and media players have the ability to show many
different types of media with varying support for interaction, only SMIL
offers the ability to define the presentation in the form of text as a
script. This feature could be called media composition. This is a
powerful ability when you think about it: text presentations can be
generated from other applications. Also, SMIL offers accessibility
options and powerful features not
present in these media players.

-   Macromedia products such as *Flash*, which require a plug-in to view
    flash inside a web page.
-   RealAudio\'s *Realplayer*
-   Microsoft\'s *PowerPoint*
-   OpenOffice.org\'s *Impress*
-   Apple\'s *Quicktime*
-   Microsoft has already created a proprietary alternative to SMIL. It
    is called Microsoft\'s Synchronized Accessible Media Interchange
    (SAMI), which
    plays ASX files through Windows Media Player (WiMP).

Given that SMIL is extensible, the SMIL language has the ability to show
many of proprietary objects which are used by the above players. SMIL
was designed to be the overarching language for describing the
presentation of all media, all layouts and interactive controls.
Therefore, SMIL is not a substitute for flash, mpeg-4, or HTML. Rather,
it is a new standard for describing and using all of these.

### SMIL History

SMIL is still being developed. Currently, attempts are being made to
make SMIL easier to use in web browsers. Since SMIL is XML, the W3C
developed the latest standard as an addendum to the hybrid of XML and
HTML (XHTML). The following is an outline of the history of SMIL.

-   The SMIL 1.0 specification defined the layout and time sequence of
    multimedia elements.
-   The HTML+TIME specification introduced Timing, Linking, Media, and
    Content controls to HTML elements.
-   The SMIL 2.0 specification brought interactivity (i.e.: HTML+TIME)
    such as media linking and controls.
-   BHTML proposal included transitions to be used in SMIL 2.0
-   Finally, the XHTML+SMIL specification extends SMIL 2.0 capabilities
    to XHTML elements.

When fully realized and implemented in the latest web browsers,
XHTML+SMIL will be able to define how media elements can be controlled.
HTML supports only static images and links. Web browsers use plug-ins to
show videos and other media objects, so the control and interaction of
the objects is left to the implementation of the plug-in. With
XHTML+SMIL, the supported objects can be placed, moved or displayed
according to a time-frame, interacted with using custom controls, and
linked to other media objects, web pages or presentations. And since XML
is extensible, support for more media objects is on the horizon. This
technology has the potential to make the WWW far more interactive,
allowing presenters far more control over presentations.

The current SMIL 2.0 is comprehensive and fairly complete. It is divided
into modules which describe different aspects of the presentation. For
example, there is a structure module to describe the structure of the
SMIL document itself, and there is a metadata module for describing what
the SMIL document is all about. Modularity is useful for extending the
SMIL schemas on a module-to-module basis when necessary, without causing
unwanted interactions with the elements in other modules.

------------------------------------------------------------------------

## Implementing SMIL

### Common SMIL implementations

-   Internet or Intranet presentations.
-   Slide show presentations.
-   Presentations which link to other SMIL files.
-   Presentations which have Control buttons (stop, start, next, \...)
-   Defining sequences and duration of multimedia elements.
-   Defining position and visibility of multimedia elements.
-   Displaying multiple media types such as audio, video, text
-   Displaying multiple files at the same time.
-   Displaying files from multiple web servers.

Currently, SMIL\'s most widespread usage is with MMS. MMS (Multimedia
Messaging System) is a mobile device technology that is used as an
envelope for sending multimedia messages to cellphones. SMIL content is
placed inside the MMS message along with any associated media binaries.
In this context, MMS is a kind of transport mechanism for SMIL.

### SMIL files and MIME Types

-   SMIL files have the extension \*.smil (but can also have \*.sml,
    \*.smi)
-   SMIL files contain tags and content necessary for showing a
    presentation. This includes the layout of multimedia elements, the
    timeline for the elements and the source for the multimedia files.

In order for a MIME user-agent to recognize SMIL 2.0 files, the
user-agent needs to be defined:

-   application/smil \[deprecated\]
-   application/smil+xml \[current MIME type\]
-   application/xhtml+smil \[MIME type for embedding smil in XHTML\]

When adding this new mime-type to a web browser, the definition will
need to include the \'smil\' extension.

### SMIL Schema

The following hyperlink will direct you to the SMIL 2.0 Schemas,
provided by the W3C.org. The main schema is a general description of
SMIL 2.0 modules. It is followed by each module\'s schema. The main
schema contains the include statements for all of the module\'s schemas.

W3C.Org\'s SMIL Schema
description

### SMIL Namespace Declarations

SMIL 2.0 files need to have the following namespace declaration in the
beginning `<smil>`{=html} tag:

`<small>`{=html}SMIL 2.0 namespace`</small>`{=html}

+---------------+-----------------------------------------------------------+
|     <nowiki>  |     <nowiki>                                              |
|     1         |     <smil xmlns="http://www.w3.org/2001/SMIL20/Language"> |
|     </nowiki> |     </nowiki>                                             |
+---------------+-----------------------------------------------------------+

SMIL 1.0 files have the following namespace declaration:

`<small>`{=html}SMIL 1.0 namespace`</small>`{=html}

+---------------+--------------------------------------------------+
|     <nowiki>  |     <nowiki>                                     |
|     1         |     <smil xmlns="http://www.w3.org/TR/REC-smil"> |
|     </nowiki> |     </nowiki>                                    |
+---------------+--------------------------------------------------+

If no default namespace is declared within the

    <nowiki><smil></nowiki>

root element, the document will be processed as SMIL 1.0.

------------------------------------------------------------------------

## SMIL Syntax

### Guidelines and Rules

SMIL documents look a lot like HTML. SMIL files need to be written
according to the following rules:

-   SMIL documents must follow the *XML rules of well-formedness*.
-   SMIL tags are *case sensitive*.
-   All SMIL tags are written with *lowercase letters*.
-   SMIL documents *must* start with a `<smil>`{=html} tag and end with
    a `</smil>`{=html} closing tag.
-   SMIL documents *must* contain a
    ```{=html}
    <body>
    ```
    tag for storing the contents of the presentation.
-   SMIL documents can have a
    ```{=html}
    <head>
    ```
    element (like HTML) for storing metadata information about the
    document itself, as well as presentation layout information.

### SMIL template

`<small>`{=html}SMIL 1.0 template`</small>`{=html}

+---------------+----------------------+
|     <nowiki>  |     <nowiki>         |
|     1         |     <smil>           |
|     2         |     <head>           |
|     3         |     <layout>         |
|     4         |     ...              |
|     5         |     </layout>        |
|     6         |     </head>          |
|     7         |                      |
|     8         |     <body>           |
|     9         |     ...              |
|     10        |     </body>          |
|     11        |     </smil></nowiki> |
|     </nowiki> |                      |
+---------------+----------------------+

### A Simple SMIL

`<small>`{=html}Abbreviated SMIL markup`</small>`{=html}

``` XML
<?xml version="1.0" encoding="ISO-8859-1"?>
<smil xmlns="http://www.w3.org/SMIL20/Language">
<head>

<!-- The layout section defines regions in which to place content -->
<layout>
...
</layout>

<!-- Transitions defined in head act on content defined in body -->
<transition id="fade" type="fade" dur="1s"/>
<transition id="push" type="pushWipe" dur="0.5s"/>

</head>

<!-- The body section defines the content to be used and how it will be displayed -->
<body>

<par>
<img src="imagefile.jpg" transIn="fade"/>
<video src="soundfile.aif" transOut="push"/>
</par>

</body>
</smil>
```

### An example SMIL

`<small>`{=html}Example SMIL which has in-line text and an
image`</small>`{=html}

``` XML
<smil xmlns="http://www.w3.org/2001/SMIL20/Language">
<head>
<layout>
<root-layout width="320" height="240"/>
<region id="text1_region" left="0" top="0" width="160" height="120"/>
<region id="text2_region" left="160" top="120" width="160" height="120"/>
<region id="text3_region" left="80" top="60" width="160" height="120"/>
<region id="image_region" left="0" top="0" width="320" height="240"/>
</layout>
</head>
<body>
<seq>
<text src="data:text/plain,First%20Slide" region="text1_region" dur="2s"/>
<text src="data:text/plain,Second%20Slide" region="text2_region" dur="3s"/>
<text src="data:text/plain,Third%20Slide" region="text3_region" dur="3s"/>
<img src="sample_jpg.jpg" region="image_region" dur="3s"/>
</seq>
</body>
</smil>
```

Note that when using in-line text instead of referring to separate
plain-text files as the text source, you will have to encode the text
for any non-alphanumeric characters. This example uses \'%20\' in lines
{13,14,15} as a space character. Also note that in line {13} the source
for the text content begins with \'<data:text/plain>\'. In SMIL 2.0 this
is the default mime-type for text sources, so specifying it here is
optional. In SMIL 1.0, however, this would have to be specified in order
to use inline text.

## SMIL 2.0 Modules

SMIL 2.0 divides the language description by functionality into ten
modules. Each module contains elements to describe structure, content,
actions or attributes. The following 10 modules are associated with the
SMIL 2.0 namespace.

`  1. Timing  `\
`  2. Time Manipulations`\
`  3. Animation`\
`  4. Content Control`\
`  5. Layout`\
`  6. Linking`\
`  7. Media Objects `\
`  8. Metainformation `\
`  9. Structure `\
` 10. Transitions`

The **timing** module provides a framework of elements to decide whether
elements appear concurrently, in sequence, or out of order and called by
interactive events such as clicking on a hyperlink.

The **time manipulations** module provides the ability to associate
media objects with time-related information such the as length of time a
media object should be displayed, and a description of the timeline used
as a frame of reference for the timing module.

The **animation** module allows media objects to be placed on a timeline
defined by the time manipulations module.

The **content control** module allows for choices of which content is
played, depending on such things as language and playback capabilities,
using tags such as **switch** present a test of the system\'s
capabilities.

The **layout** module contains elements that describe the spacial
placement of media objects in the presentation.

The **linking** module describes hyperlinks and linking references to
media objects.

The **media objects** module describes the pathing and typing of media
objects.

The **metainformation** module contains elements that describe meta
information about the SMIL file itself or the media objects it contains.

The **structure** module is a framework to describe the structure of the
SMIL file such as the head and body and SMIL elements.

The **transitions** module is a framework to describe transitions such
as wiping and fading between the presentation of media objects.

## Viewing a SMIL file

In order to view a SMIL presentation, a client will need to have a SMIL
player installed on his/her computer. Currently, Apple\'s Quicktime
player, Windows Media Player (WiMP) and RealNetworks RealPlayer are
among the most popular media players.

It would be convenient to be able to show these SMIL files natively in
web browser, eliminating the requirement of a separate SMIL player or
plug-in. Currently, Microsoft\'s Internet Explorer has limited support
for SMIL features. The open-source Mozilla project is slowly
incorporating SMIL and other XML-related technologies such as SVG and
MathML into their browsers, but progress is slow. It is possible they
are waiting for these XML-based languages to mature.

## Embedding SMIL files into XHTML web pages

As mentioned, SMIL is not yet native to web browsers, so in order to put
SMIL in a web page, one must embed it and open it in a plug-in.
Embedding SMIL files into web pages is somewhat beyond the scope of this
chapter. However, should you have a need to do this, the following links
are included as references to help you.

-   Embedding a SMIL file is easy to do with Apple\'s
    Quicktime
    media player.
-   Use the Windows Media Player to view SMIL files in a web page on a
    non-IE browser.
-   The Internet Explorer 5.5+ browser has support for SMIL.
-   Visit this W3Schools
    page for details on
    how to use SMIL in IE-only web pages.

## SMIL for phones

As mentioned, SMIL is often used in the latest cellular phones. Phones
and vendors have varied support for MMS (multimedia messaging service),
but generally, MMS uses SMIL to define the layout of multimedia content.
If the MMS message contains a SMIL file, it will include other media
objects, which can be text or binary (text is treated here as a media
object or file to be referenced in a smil file).

Just a general note on MMS: the telecommunications industry needed a
system in order to charge for messages by throughput as well as a system
for pushing multimedia messages from phone to phone, computer to phone
or phone to computer. MMS is a standard, international system for these
purposes. SMIL was adopted because it was a well-defined, standard
language to describe the layout and timing of the content inside MMS
messages. In adhering to these (and other) standards developed by the
3GPP in partnership with the European Telecommunications Standards
Institution (ETSI) and the W3C, the industry was able to ensure
interoperability of new services between vendors, providing mutual
benefit and equal opportunity.

## SMIL tools and SMIL Info

Given that WikiBooks is a publicly-available \'open\' book, it would be
inappropriate to include information about or links to any commercial
SMIL tools. In other words, everything that is not free or open source
is not considered here.

Just a sidenote: some commercial tools cost upwards of \$800. It is
therefore in our best interest to evaluate, provide feedback for, and
contribute to opensource projects.

The following are useful links (March 18th, 2004) to free and opensource
tools, current SMIL projects, specifications, and tutorials:

-   The official W3C SMIL page
-   X-Smiles - a Java-based, \"an open XML
    browser for exotic devices.\" Supports XSLT, XSLFO, SMIL, XForms and
    SVG.
-   Ambulant\'s Open SMIL Player
-   W3school\'s *excellent*
    tutorial on SMIL.
-   PerlySMIL is a perl script
    for generating SMIL files from perl.
-   LimSee2 - is an
    opensource, Java application for generating SMIL. It is this
    author\'s experience that several media-related Java dependencies
    must be properly installed before LimSee2 will work properly.

## SMIL in netbeans?

One can create a SMIL file in Netbeans just as one would create an XML
file. Just type it up and save it as a SMIL file. You can check for
well-formedness, but validation might be trickier. As mentioned
previously, SMIL 2.0 requires a namespace declaration, so don\'t forget
it.

For our simple exercises, just type up a well-formed SMIL document and
save it as .smil That\'s it!

## Summary

We\'ve seen how SMIL could be used to make standalone presentations. Yet
the future of SMIL may be in the connection of mobile devices to the
internet. As XML standards and SMIL tools reach maturity, SMIL will be
increasingly implemented in order to define interactive presentations in
the same way that Macromedia FLASH does, only this presentation will be
native to web browsers and micro browsers used in mobile devices. Since
SMIL is an open standard and it is extensible, there will likely be
other applications which will use also SMIL.

Visionaries foresee the increasing ubiquity of the internet in our homes
and work, on computers and mobile devices. This ubiquity is also called
\'pervasive computing\'. Mobile commerce would be an example of
pervasive computing as cellular phones and portable devices become more
useful for business and location-based services. SMIL is a language
which facilitates this trend by providing either a pretty face for
future business services or value-added multimedia content.

```{=html}
<div style="color:#8b4513;">
```
## SMIL Exercises

1.  Create a simple SMIL file which displays the words, \'Hello World\'.
    Confirm that the file works in a SMIL-conformant player.
2.  Author a SMIL file which displays \'Hello World\' for 3 seconds,
    then displays \'Goodbye World\' for 1 second. Confirm that the file
    works in a SMIL-conformant player.
3.  Take an existing Openoffice.org present (or PowerPoint) presentation
    and turn it into a SMIL file. Double check it in a SMIL browser.
4.  Embed one of the previously created SMIL files into an XHTML web
    page and store the SMIL file and web page on a server. Confirm that
    the SMIL file works for two different computers.

```{=html}
</div>
```
## SMIL Answers

## References

Ayars, J., Bulterman, D., Cohen, A., et al. (ed., 2001). Synchronized
Multimedia Integration Language (SMIL 2.0). Retrieved April 4, 2004 from
the World Wide Web Consortium Dot Org Web Site:
<http://www.w3.org/TR/smil20/smil-modules.html>

Castagno, Roberto (ed., 2003, January). Multimedia Messaging Service
(MMS); Media formats and codes. Retrieved April 4, 2004 from the Third
Generation Partnership Project (3GPP) Dot Org Web Site:
<http://www.3gpp.org/ftp/Specs/html-info/26140.htm>

Michel, T. (2004, March). Syncronized Multimedia (n.a., n.d). Retrieved
April 4, 2004 from the World Wide Web Consortium Web Dot Org Site:
<http://www.w3.org/AudioVideo/>

Newman, D., Patterson, A., Schmitz, P. (ed., 2002, January). XHTML+SMIL.
Retrieved April 4, 2004 from the World Wide Web Consortium Dot Org Web
Site: <http://www.w3.org/TR/XHTMLplusSMIL/>

SMIL Tutorial Home (n.d.). Retrieved April 4, 2004 from the W 3 Schools
Dot Com Web Site: <http://www.w3schools.com/smil/default.asp>


# XML - Managing Data Exchange/WDDX

## Learning objectives

Upon completion of this chapter, you will be able to answer the
following questions:

-   What is WDDX?
-   What are the uses of WDDX?
-   What are Web Syndicate Networks?
-   What are the benefits of WDDX?

## Introduction

`<b>`{=html}WDDX (Web Distributed Data eXchange)`</b>`{=html} was
created by Allaire, now known as
Macromedia, to solve the problem of
exchanging data between different web applications. It was originally
intended to be used to exchange data between
ColdFusion and other
web application languages. This XML-based technology enables complex
data to be exchanged between totally different Web programming languages
by creating \'Web Syndicate Networks.\' WDDX consists of a
language-independent representation of data based on an XML 1.0 DTD, and
a set of modules for a wide variety of languages that use WDDX.

### Features

-   can be used with HTTP, SMTP, POP, FTP and other Internet protocols
    that support transferring textual data
-   must be using Netscape 3.0+ or Internet Explorer for Windows or any
    versions for Unix and Mac platforms
-   supports boolean, number, date-time, and string data types
-   supports complex data types like arrays, structures, and recordsets
-   not a formal standard, but is free and widely distributed and is
    based on standard-base technologies like XML 1.0

## How it Works

The way that the web distributed data exchange works is by assigning a
specific module for the given programming language to translate the data
into an abstract XML format. Another specific module then translates the
XML back into another programming language for another web application.
For example, if you had an array in a ColdFusion program that you wanted
to send to an ASP program, it would first be serialized into XML and
sent to the ASP server. The ASP server would then deserialize it and
convert it to VBScript for use in the ASP program.

## Web Syndicate Networks

The term \'Web Syndicate Network\' refers to a group of websites that
share their content and transactions. This allows for economies of scale
as each site can use shared database content or even transactions and
procedures.

## References

OpenWDDX - <http://www.openwddx.org>\
WDDX Functions for PHP - <http://www.php.net/wddx>\
WDDX FAQ by Macromedia -
<http://www.macromedia.com/v1/handlers/index.cfm?id=5622&method=full>\


# XML - Managing Data Exchange/RPC

**Author:** Nathan Slider\
**Editor:** Nathan Slider\
UGA Master of Internet Technology
Program, 2005

## Learning Objectives

Upon completion of this chapter, you will be able to

-   Discuss XML-RPC
-   Create XML-RPC Code based on Examples

## RPC Defined

In order to fully understand XML-RPC, we should fist define RPC. A
**Remote Procedure Call** (**RPC**) is a protocol that allows a computer
program running on one host to cause code to be executed on another host
without the programmer needing to explicitly code for this. An RPC is
initiated by the caller (client) sending a request message to a remote
system (the server) to execute a certain procedure using arguments
supplied. A result message is returned to the caller. There are many
variations and subtleties in various implementations, resulting in a
variety of different (incompatible) RPC protocols.

In order to allow servers to be accessed by differing clients, a number
of standardized RPC systems have been created. Most of these use an
Interface Description Language (IDL) to allow various platforms to call
the RPC. Web services were the first real attempt to implement RPC
between platforms. Using Web services a .NET client can call a remote
procedure implemented in Java on a Unix server (and vice versa).

Web services use XML as the IDL, and HTTP as the
network protocol. The advantage of this system is simplicity and
standardization, the IDL is a text file that is widely understood, and
HTTP is built into almost all modern operating systems. An example of
such an RPC system is XML-RPC.

## XML-RPC Defined

**XML-RPC** (**Extensible Markup Language Remote Procedure Call**) is a
Remote Procedure Call protocol encoded in XML. It is a
very simple protocol, defining only a handful of data types and
commands, and the entire description can be printed on two pages of
paper. This is in stark contrast to most RPC systems, where the
standards documents often run into the thousands of pages and require
considerable software support in order to be used.

It was first created by  in 1995 with
. However, Microsoft considered it too
simple and started adding functionality. After several rounds of this,
the standard was no longer so simple and became what is now
.

\"We wanted a clean, extensible format that\'s very simple. It should be
possible for an HTML coder to be able to look at a file containing an
XML-RPC procedure call, understand what it\'s doing, and be able to
modify it and have it work on the first or second try\... We also wanted
it to be an easy to implement protocol that could quickly be adapted to
run in other environments or on other operating systems.\"
-xmlrpc.com

## Data Types

Data Types Referenced from

+-----------+---------------------------+---------------------------+
| Name      | Tag Example               | Description               |
+===========+===========================+===========================+
| array     | ``` XML                   | Array of values, storing  |
|           |  <array>                  | no keys                   |
|           |    <data>                 |                           |
|           |      <va                  |                           |
|           | lue><i4>1404</i4></value> |                           |
|           |                           |                           |
|           |     <value><string>Someth |                           |
|           | ing Here</string></value> |                           |
|           |                           |                           |
|           | <value><i4>1</i4></value> |                           |
|           |    </data>                |                           |
|           |  </array>                 |                           |
|           | ```                       |                           |
+-----------+---------------------------+---------------------------+
| base64    | `<base64>`{=h             | \[Base 64\]-encoded       |
|           | tml}eW91IGNhbid0IHJlYWQgd | binary data               |
|           | GhpcyE=`</base64>`{=html} |                           |
+-----------+---------------------------+---------------------------+
| boolean   | `<boolean>`{=             | \[Boolean                 |
|           | html}1`</boolean>`{=html} | datatype\|\[Boolean\]     |
|           |                           | logical value (0 or 1)    |
+-----------+---------------------------+---------------------------+
| date/time | \<dateTi                  | Date and time             |
|           | me.iso8601\>19980717T14:0 |                           |
|           | 8:55\</dateTime.iso8601\> |                           |
+-----------+---------------------------+---------------------------+
| double    | `<double>`{=html          | Double \[precision\]      |
|           | }-12.53`</double>`{=html} | floating number           |
+-----------+---------------------------+---------------------------+
| integer   | `<i4                      | Whole number, \[integer\] |
|           | >`{=html}42`</i4>`{=html} |                           |
+-----------+---------------------------+---------------------------+
| string    | `<string>`{=html}Hello    | String of characters.     |
|           | world!`</string>`{=html}  | Must follow               |
|           |                           | XML     |
|           |                           | encoding.                 |
+-----------+---------------------------+---------------------------+
| struct    | ``` XML                   | Array of values, storing  |
|           |  <struct>                 | keys                      |
|           |    <member>               |                           |
|           |      <name>foo</name>     |                           |
|           |                           |                           |
|           | <value><i4>1</i4></value> |                           |
|           |    </member>              |                           |
|           |    <member>               |                           |
|           |      <name>bar</name>     |                           |
|           |                           |                           |
|           | <value><i4>2</i4></value> |                           |
|           |    </member>              |                           |
|           |  </struct>                |                           |
|           | ```                       |                           |
+-----------+---------------------------+---------------------------+
| nil       | `<nil/>`{=html}           | Discriminated null value; |
|           |                           | an XML-RPC                |
|           |                           | ext                      |
|           |                           | ension |
+-----------+---------------------------+---------------------------+

### Examples

An example of a typical XML-RPC request would be:

``` XML
 <?xml version="1.0"?>
 <methodCall>
   <methodName>examples.getStateName</methodName>
   <params>
     <param>
         <value><i4>41</i4></value>
     </param>
   </params>
 </methodCall>
```

An example of a typical XML-RPC response would be:

``` XML
 <?xml version="1.0"?>
 <methodResponse>
   <params>
     <param>
         <value><string>South Dakota</string></value>
     </param>
   </params>
 </methodResponse>
```

A typical XML-RPC fault would be:

``` XML
 <?xml version="1.0"?>
 <methodResponse>
   <fault>
     <value>
       <struct>
         <member>
           <name>faultCode</name>
           <value><int>4</int></value>
         </member>
         <member>
           <name>faultString</name>
           <value><string>Too many parameters.</string></value>
         </member>
       </struct>
     </value>
   </fault>
 </methodResponse>
```

A final example, comparing a PHP associative array with an equivalent
XML-RPC `<struct>`{=html}. This array:

``` PHP
Array
(
    [0] => 'dogs',
    [1] => 'cats',
    ['animals'] => Array(
        [0] => FALSE,
        [1] => 'little_dogs',
        [2] => 'little_cats',
        [3] => 5,
        [4] => 2.3,
        [5] => 1,
            ),
);
```

Becomes the following XML-RPC:

``` XML
<?xml version="1.0" encoding="utf-8"?>
<methodResponse>
      <params>
         <param>
            <value>
               <struct>
                  <member>
                     <name>0
                     </name>
                     <value><string>dogs</string>
                     </value>
                  </member>
                  <member>
                     <name>1
                     </name>
                     <value><string>cats</string>
                     </value>
                  </member>
                  <member>
                     <name>animals
                     </name>
                     <value>
                           <array>
                              <data>
                                 <value><boolean>0</boolean>
                                 </value>
                                 <value><string>little_dogs</string>
                                 </value>
                                 <value><string>little_cats</string>
                                 </value>
                                 <value><i4>5</i4>
                                 </value>
                                 <value><double>2.3</double>
                                 </value>
                                 <value><boolean>1</boolean>
                                 </value>
                              </data>
                           </array>
                     </value>
                  </member>
               </struct>
            </value>
         </param>
      </params>
</methodResponse>
```

## References

-   XML-RPC Homepage
-   XML-RPC Specification
-   Free Online Dictionary of
    Computing
-   Forum
-   Tutorials
-   Technology Reports
-   Citations from CiteSeer


# XML - Managing Data Exchange/JSTL

The **JavaServer Pages Standard Tag Library** (Short Form: **JSTL**) is
a collection of four custom-tag libraries which extend the JSP
specification. As a component it is allocated in the Java EE Web
application development platform. The JSTL is administrated in the
setting of the Java Community Process (JCP) 052. Within the
Jakarta-Project there are reference implementations to these
specifications.

## Components

In version 1.1 the following libraries were intended:

-   core: iterative, conditional, URL-specific and general Tags
-   xml: Tags from the field XML and XML-transformation
-   sql: Tags for direct data base administration
-   i18n: Tags for formatting and internationalization

## History

In its original Version 1.0 an „Expression Language" was intended in
comparison to Version 1.1. With JSP 2.0 JSP-EL was taken up in the
JSP-specifications itself. Therefore the primary goal of JSTL 1.1 is the
adaption of the libraries to the JSP-EL for JSP 2.0. With the libraries
in version 1.2 the JSTL is up to date concerning the unification of the
Expression Language by the JSP 2.1 and JSF-1.2-specifications.
Furthermore the JSTL in Version 1.2 is part of the Java-EE-5-Platform.

## Usage of JSTL 1.1

As for the use of JSTL 1.1 the JSP-EL is required, a servlet-container
has to be conform to at least the JSP-2.0 specifications in order to be
be used on this. The reference implementation is made up of two JAR --
archives „standard.jar" and „jstl.jar". In most containers they usually
need to be located in the lib-path of the web application only. To
ensure backwards compatibility the JSTL 1.1 is referenced by the URI
„http://java.sun.com/jsp/jstl/fmt" whereas
„http://java.sun.com/jstl/fmt" is used for JSTL 1.0.

**Example JSP-page in XML-notation (JSPX):**

``` xml
<?xml version="1.0" encoding="utf-8" ?>
<jsp:root
  xmlns:jsp="http://java.sun.com/JSP/Page"
  xmlns:c="http://java.sun.com/jsp/jstl/core"
  xmlns:fmt="http://java.sun.com/jsp/jstl/fmt"
version="2.0">

<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en">
<head>
  <title>JSTL 1.1</title>
</head>
<body>

<h1>Iteration</h1>
<ul>
  <c:forEach var="num" begin="1" end="10">
    <li>Number<c:out value="${num}"/></li>
  </c:forEach>
</ul>

<h1>Formatting</h1>
<p>
  Currency: <fmt:formatNumber value="10000" type="currency" currencyCode="EUR" />
</p>

</body>
</html>
</jsp:root>
```

**Code-Explanations:**

In the *jsp:root* -- element the usage of the basis- und the
I18N-Taglibs (core and fmt) from the JSTL is indicated and linked to the
according XML-namespace. Under the headline *Iteration* the
*forEach-Tag* from the core-library is used: It displays the tag-body
(i.e., the content of the Tag) ten times. In this loop with *`${num}`*
you can find JSP -- Expression. With every loop cycle the current data
from *num* is displayed here. Under the headline *Formatting* the
*formatNumber*-tag from the fmt -- library of JSTL is used. Depending on
the adjusted language (this can be set by fmt:setLocale for example) the
number 10000 will be formatted (e.g. in German as „EUR 10.000,00" and in
English as „EUR 10,000.00")

## Alternatives to the JSTL

**Struts vs. JSTL:** There are in fact many instances where a Struts tag
and JSTL tag will perform equivalent functions. Unlike the
Struts-Framework the JSTL is not linked to a certain
architecture--paradigm, like the *Model--View--Controller* separation.
JSTL tags are more powerful compared to struts tags, because JSTL is a
more standard part of the J2EE specification, while at the same time
many options are available like condition checking, comparing strings,
triming white spaces, converting upper case or lower case, etc. Both
libraries own tags with identical name. So if these libraries are mixed
in applications, what is possible, it needs to be attended to use unique
prefixes(JSP) or namespaces (JSPX).

## Example Applications & Tutorials

-   Using JSTL to handle
    internationalization
-   Examples

## Weblinks

-   Suns Java JSTL Homepage
-   JSTL
    Reference
-   Jakarta Taglibs