docbook: a case study and anecdotes
TRANSCRIPT
![Page 1: DocBook: A Case Study and Anecdotes](https://reader031.vdocument.in/reader031/viewer/2022030110/621ca6ea7b3c7c13137560c2/html5/thumbnails/1.jpg)
DocBook: A Case Studyand Anecdotes
Norman WalshSun Microsystems, Inc.
![Page 2: DocBook: A Case Study and Anecdotes](https://reader031.vdocument.in/reader031/viewer/2022030110/621ca6ea7b3c7c13137560c2/html5/thumbnails/2.jpg)
What is DocBook?A DocBook DocumentDocBook HistoryDocBook’s Purpose
2 / 30http://www.sun.com/
Background
![Page 3: DocBook: A Case Study and Anecdotes](https://reader031.vdocument.in/reader031/viewer/2022030110/621ca6ea7b3c7c13137560c2/html5/thumbnails/3.jpg)
• DocBook is an XML vocabulary for writing documentation.It is particularly well-suited to books and papers aboutcomputer hardware and software, though it is by no meanslimited to them.
• It has been subset down to something that resemblesHTML.
• It has been extended to do things as different as websitesand presentations, like this one.
3 / 30http://www.sun.com/
What is DocBook?
![Page 4: DocBook: A Case Study and Anecdotes](https://reader031.vdocument.in/reader031/viewer/2022030110/621ca6ea7b3c7c13137560c2/html5/thumbnails/4.jpg)
<book xmlns="http://docbook.org/ns/docbook"><info><title>A Book Title</title><author> <personname> <firstname>John</firstname> <surname>Doe</surname> </personname></author></info><chapter><title>The First Chapter</title><para>Some <emphasis>text</emphasis>.</para></chapter></book>
4 / 30http://www.sun.com/
A DocBook Document
![Page 5: DocBook: A Case Study and Anecdotes](https://reader031.vdocument.in/reader031/viewer/2022030110/621ca6ea7b3c7c13137560c2/html5/thumbnails/5.jpg)
• DocBook has been actively maintained for more than adecade.
• It has always been maintained by a committee of somesort. It is now being developed by an OASIS TechnicalCommittee.
• DocBook was an SGML DTD for many years. It is nowprincipally an XML DTD. It will officially be a RELAX NGGrammar real soon now.
5 / 30http://www.sun.com/
DocBook History
![Page 6: DocBook: A Case Study and Anecdotes](https://reader031.vdocument.in/reader031/viewer/2022030110/621ca6ea7b3c7c13137560c2/html5/thumbnails/6.jpg)
• DocBook documents are mostly hand authored. UnlikeSOAP envelopes, purchase orders, and XML/RPC invoca-tions, humans write DocBook.
• It’s mostly read by humans. DocBook documents, aren’tusually consumed by unmarshalling processes buildingobject graphs.
• DocBook contains a lot of mixed content. Very few ele-ments have “simple content,” dates, numbers, etc.
6 / 30http://www.sun.com/
DocBook’s Purpose
![Page 7: DocBook: A Case Study and Anecdotes](https://reader031.vdocument.in/reader031/viewer/2022030110/621ca6ea7b3c7c13137560c2/html5/thumbnails/7.jpg)
http://norman.walsh.name/It's all about the metadata
7 / 30http://www.sun.com/
Case Study: norman.walsh.name
![Page 8: DocBook: A Case Study and Anecdotes](https://reader031.vdocument.in/reader031/viewer/2022030110/621ca6ea7b3c7c13137560c2/html5/thumbnails/8.jpg)
8 / 30http://www.sun.com/
It's all about the metadata
![Page 9: DocBook: A Case Study and Anecdotes](https://reader031.vdocument.in/reader031/viewer/2022030110/621ca6ea7b3c7c13137560c2/html5/thumbnails/9.jpg)
OverviewDocBook 5.0 and XSLT 2.0A new hierarchy rootHTML markupHTML markup (2)HTML markup (3)Geographic metadataGeographic metadata (2)…
9 / 30http://www.sun.com/
DocBook Customizations
![Page 10: DocBook: A Case Study and Anecdotes](https://reader031.vdocument.in/reader031/viewer/2022030110/621ca6ea7b3c7c13137560c2/html5/thumbnails/10.jpg)
We'll look at schema and stylesheet customizations thatsupport:
• A new hierarchy root• HTML markup• Geographic metadata• “Database generated” trip itineraries• Inline markup for metadata• Inline markup for personal names
10 / 30http://www.sun.com/
Overview
![Page 11: DocBook: A Case Study and Anecdotes](https://reader031.vdocument.in/reader031/viewer/2022030110/621ca6ea7b3c7c13137560c2/html5/thumbnails/11.jpg)
The examples in the slides that follow are taken from Doc-Book V5.0 and from the DocBook XSLT 2.0 stylesheets.
If you're interested in exploring these customizations, youcan find everything online:
• http://norman.walsh.name/schema/essay.rnc• http://norman.walsh.name/style/essay2html.xsl• http://sourceforge.net/projects/docbook for the
base schemas and stylesheets.
Share and enjoy!
11 / 30http://www.sun.com/
DocBook 5.0 and XSLT 2.0
![Page 12: DocBook: A Case Study and Anecdotes](https://reader031.vdocument.in/reader031/viewer/2022030110/621ca6ea7b3c7c13137560c2/html5/thumbnails/12.jpg)
This one's easy. In the schema, place the new root elementin the start pattern:
include "http://docbook.org/xml/5.0/rng/docbook.rnc" { start = db.essay}
In the stylesheet, place it (exclusively) in the set of rootelements.
<xsl:param name="root.elements"> <db:essay/></xsl:param>
And, naturally, a template for db:essay.
12 / 30http://www.sun.com/
A new hierarchy root
![Page 13: DocBook: A Case Study and Anecdotes](https://reader031.vdocument.in/reader031/viewer/2022030110/621ca6ea7b3c7c13137560c2/html5/thumbnails/13.jpg)
The principle target for these essays is HTML. Every nowand then, the easiest way to support some HTML feature issimply to insert some HTML:
<essay ...><info>...<html:style xmlns:html="http://www.w3.org/1999/xhtml" type="text/css">div.classvalue { margin-left: 0.5in; }</html:style></info>...</essay>
13 / 30http://www.sun.com/
HTML markup
![Page 14: DocBook: A Case Study and Anecdotes](https://reader031.vdocument.in/reader031/viewer/2022030110/621ca6ea7b3c7c13137560c2/html5/thumbnails/14.jpg)
We can allow that by adding patterns to the schema:
db.info.elements |= html.style
html.style = element html:style { attribute type { text }, attribute media { text }?, attribute title { text }?, text}
14 / 30http://www.sun.com/
HTML markup (2)
![Page 15: DocBook: A Case Study and Anecdotes](https://reader031.vdocument.in/reader031/viewer/2022030110/621ca6ea7b3c7c13137560c2/html5/thumbnails/15.jpg)
And templates to the stylesheet:
<xsl:template match="html:*" priority="200"> <xsl:element name="{local-name(.)}"> <xsl:copy-of select="@*"/> <xsl:apply-templates/> </xsl:element></xsl:template>
This relies on an <xsl:apply-templates/> in the templatethat processes db:info (and on the fact that the defaultnamespace is the XHTML namespace).
15 / 30http://www.sun.com/
HTML markup (3)
![Page 16: DocBook: A Case Study and Anecdotes](https://reader031.vdocument.in/reader031/viewer/2022030110/621ca6ea7b3c7c13137560c2/html5/thumbnails/16.jpg)
In a metadata-rich vocabulary, one solution is to use thestandard geographic metadata namespace:
<essay xmlns="http://docbook.org/ns/docbook" xmlns:geo="http://www.w3.org/2003/01/geo/wgs84_pos#"><info><title>norman.walsh.name</title>...<geo:lat>42.3382</geo:lat><geo:long>-72.45</geo:long></info>...</essay>
16 / 30http://www.sun.com/
Geographic metadata
![Page 17: DocBook: A Case Study and Anecdotes](https://reader031.vdocument.in/reader031/viewer/2022030110/621ca6ea7b3c7c13137560c2/html5/thumbnails/17.jpg)
For essays about a particular place, the Dublin Core cover-age element makes more sense:
<essay xmlns="http://docbook.org/ns/docbook" xmlns:dc='http://purl.org/dc/elements/1.1/'><info><title>XML Prague, 16-17 June</title>...<dc:coverage rdf:resource="http://norman.walsh.name/knows/where#cz-prague"/></info>...</essay>
17 / 30http://www.sun.com/
Geographic metadata (2)
![Page 18: DocBook: A Case Study and Anecdotes](https://reader031.vdocument.in/reader031/viewer/2022030110/621ca6ea7b3c7c13137560c2/html5/thumbnails/18.jpg)
Like the HTML example, we do this with new patterns in thegrammar:
db.info.elements |= geoElement | dcElement
geoElement = element geo:* { rdfContentModel }dcElement = element dc:* { rdfContentModel }
rdfContentModel = rdfResource | rdfLiteral
rdfResource = attribute rdf:resource { text }
rdfLiteral = attribute rdf:datatype { text }?, text
18 / 30http://www.sun.com/
Geographic metadata (3)
![Page 19: DocBook: A Case Study and Anecdotes](https://reader031.vdocument.in/reader031/viewer/2022030110/621ca6ea7b3c7c13137560c2/html5/thumbnails/19.jpg)
And rules to the stylesheet:
<xsl:template match="db:essay"> ... <xsl:choose> <xsl:when test="db:info/geo:lat"> <meta name="ICBM"> <xsl:attribute name="content"> <xsl:value-of select="db:info/geo:lat"/> <xsl:text>,</xsl:text> <xsl:value-of select="db:info/geo:long"/> </xsl:attribute> </meta> </xsl:when> ...
19 / 30http://www.sun.com/
Geographic metadata
![Page 20: DocBook: A Case Study and Anecdotes](https://reader031.vdocument.in/reader031/viewer/2022030110/621ca6ea7b3c7c13137560c2/html5/thumbnails/20.jpg)
It starts with my PDA:
20 / 30http://www.sun.com/
“Database generated” trip itineraries
![Page 21: DocBook: A Case Study and Anecdotes](https://reader031.vdocument.in/reader031/viewer/2022030110/621ca6ea7b3c7c13137560c2/html5/thumbnails/21.jpg)
• PDA event (flights, speaking engagements, etc) data be-comes XML then RDF
• PDA contact (hotel, venue, etc.) data becomes XML thenRDF
• Augmented with geographic metadata about countries,cities, and airports.
• Stirred and shaken into a great big bag
21 / 30http://www.sun.com/
Trip data
![Page 22: DocBook: A Case Study and Anecdotes](https://reader031.vdocument.in/reader031/viewer/2022030110/621ca6ea7b3c7c13137560c2/html5/thumbnails/22.jpg)
Itineraries are extracted from this data and incorporatedinto an essay:
<essay ...><info><title>XML Prague, 16-17 June</title> ...</info><para xml:id='p1'>I'm presenting at the XML Prague conference.</para><trip xmlns="http://nwalsh.com/rdf/itinerary#" startDate="2007-06-14T11:00:00-04:00" endDate="2007-06-19T17:40:00-04:00" trip="06-14-xmlprague"> <itinerary> <leg class="flight"> <startDate>2007-06-14T06:30:00-04:00</startDate> <endDate>2007-06-14T07:45:00-04:00</endDate> <description>BDL-JFK/Delta 6189</description> ... </leg> ...</trip>
22 / 30http://www.sun.com/
Trip itineraries
![Page 23: DocBook: A Case Study and Anecdotes](https://reader031.vdocument.in/reader031/viewer/2022030110/621ca6ea7b3c7c13137560c2/html5/thumbnails/23.jpg)
Add the itinerary markup to the informal blocks, so that itcan appear in an essay:
db.informal.blocks |= tripItinerary
tripItinerary = element it:trip { attribute startDate { xsd:date | xsd:dateTime }, attribute endDate { xsd:date | xsd:dateTime }, attribute trip { text }?, attribute nomap { text }?, anyElement*}
With appropriate stylesheet modifications too.
23 / 30http://www.sun.com/
Integrating trip itineraries
![Page 24: DocBook: A Case Study and Anecdotes](https://reader031.vdocument.in/reader031/viewer/2022030110/621ca6ea7b3c7c13137560c2/html5/thumbnails/24.jpg)
• Metadata is only useful if it exists.• It is more likely to exist if the barrier to entry is as low as
possible.• One useful set of metadata identifies what an essay is
about.• I use Wikipedia URIs to identify topics for cross-referen-
cing.
<para xml:id='p1'>Last week, ...the JAXP team released<link xlink:href="https://jaxp.dev.java.net/1.4/">version1.4.2</link> of <wikipedia>JAXP</wikipedia>.</para>
24 / 30http://www.sun.com/
Inline markup for metadata
![Page 25: DocBook: A Case Study and Anecdotes](https://reader031.vdocument.in/reader031/viewer/2022030110/621ca6ea7b3c7c13137560c2/html5/thumbnails/25.jpg)
db.markup.inlines |= db.wikipedia
db.wikipedia = element db:wikipedia { db.common.attributes, attribute page { text }?, text}
25 / 30http://www.sun.com/
Metadata markup
![Page 26: DocBook: A Case Study and Anecdotes](https://reader031.vdocument.in/reader031/viewer/2022030110/621ca6ea7b3c7c13137560c2/html5/thumbnails/26.jpg)
• This is for another sort of index.• It could be used for more interesting linking.
26 / 30http://www.sun.com/
Inline markup for personal names
![Page 27: DocBook: A Case Study and Anecdotes](https://reader031.vdocument.in/reader031/viewer/2022030110/621ca6ea7b3c7c13137560c2/html5/thumbnails/27.jpg)
The standard way to markup a personal name is verbose:
<personname><firstname>Norman</firstname><surname>Walsh</surname></personname>
Borrowing form FOAF, I've adopted two more abbreviatedmechanisms:
<foaf:name>Norman Walsh</foaf:name>
and
<foaf:nick>ndw</foaf:nick>
27 / 30http://www.sun.com/
Personal names
![Page 28: DocBook: A Case Study and Anecdotes](https://reader031.vdocument.in/reader031/viewer/2022030110/621ca6ea7b3c7c13137560c2/html5/thumbnails/28.jpg)
db.bibliography.inlines |= foafName | foafNick
foafName = element foaf:name { text}
foafNick = element foaf:nick { text}
28 / 30http://www.sun.com/
Personal name markup
![Page 29: DocBook: A Case Study and Anecdotes](https://reader031.vdocument.in/reader031/viewer/2022030110/621ca6ea7b3c7c13137560c2/html5/thumbnails/29.jpg)
<xsl:template match="foaf:name"> <xsl:variable name="allFriends" select="key('foaf:names', ., $allrdf)"/>
<xsl:choose> <xsl:when test="count($allFriends) != 1"> ... </xsl:when> <xsl:otherwise> <xsl:choose> <xsl:when test="$allFriends/foaf:weblog"> ... </xsl:when> <xsl:otherwise> <span class="foafName"> <xsl:value-of select="$allFriends/foaf:firstName"/> </span> </xsl:otherwise> </xsl:choose> </xsl:otherwise> </xsl:choose></xsl:template>
29 / 30http://www.sun.com/
Styling personal names
![Page 30: DocBook: A Case Study and Anecdotes](https://reader031.vdocument.in/reader031/viewer/2022030110/621ca6ea7b3c7c13137560c2/html5/thumbnails/30.jpg)
This set of slides will be online soon; other useful pointers:
• http://norman.walsh.name/Makefile• http://norman.walsh.name/schema/essay.rnc• http://norman.walsh.name/style/essay2html.xsl• http://sourceforge.net/projects/docbook for the
base schemas and stylesheets.
Share and enjoy!
30 / 30http://www.sun.com/
Q&A