single-source publishing with docbook 4 · linux documentation project. single-source publishing...

77
Single-source Publishing with DocBook 4 Bob Stayton Sagehill Enterprises

Upload: others

Post on 03-May-2020

43 views

Category:

Documents


0 download

TRANSCRIPT

Page 1: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with

DocBook 4

Bob Stayton Sagehill Enterprises

Page 2: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 2

What is Single-source

Publishing?

►Multiple outputs from single source file.

►Reusable content.

►Modular writing.

►Assembled documents.

►“Write once, publish many”.

Page 3: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 3

Multiple outputs

►Print, PDF, HTML, slides, Help files.

►Different product versions.

►Different user levels.

Page 4: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 4

Separate content from formatting

►XML file has no formatting.

►Separate stylesheets supply formatting.

►Match formats to element names

Page 5: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 5

Why Single-source?

►Reduce redundant writing.

►Writers can specialize.

►Update in a single place.

►Users get more accurate information.

►Fewer words to translate.

Page 6: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 6

What is DocBook?

►XML for technical documentation.

►Related stylesheets and tools.

►Started in 1991 as SGML, now XML.

►OASIS standard since 1998.

Page 7: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 7

Like HTML, except:

►A lot more tags.

►Tags identify document parts.

►All tags must be closed (or empty).

►No style information.

Page 8: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 8

Why use DocBook?

►Designed for technical documentation.

►Content kept separate from format.

►Quality check through validation.

►Open to computer processing.

Page 9: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 9

More reasons

►Choose your publishing tools.

►Cross platform.

►Automate your processing.

Page 10: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 10

Standard publishing features

►Front matter

►Graphics

►Tables

►Glossaries

►Bibliographies

►Indexes

Page 11: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 11

Technical publishing

►Nested section levels.

►Numbered figures, tables, examples.

►Tasks and procedures.

►Code synopses.

►Code examples.

►Running headers and footers.

Page 12: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 12

Free DocBook stylesheets

►Stylesheets for multiple outputs.

►Many advanced features.

►Customizable.

►Open source project on SourceForge.

►Active support community.

Page 13: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 13

DocBook output formats

► HTML

► XHTML

► XSL-FO

► PDF and PostScript

► HTML Help

► JavaHelp

► man pages

► TeX

► RTF

Page 14: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 14

What’s the downside?

►XML learning curve.

►Investment in setup.

►Technical staff needed.

Page 15: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 15

DocBook is not …

►Microsoft Word

►FrameMaker

►Quark Xpress

►InDesign

Page 16: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 16

Best for …

►Multiple output formats.

►Multiple releases over time.

►Large documentation sets.

►Batch processing environment.

►Shared authoring.

Page 17: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 17

Who uses DocBook?

► Sun

► IBM

► Microsoft

► Hewlett Packard

► Symantec

► Red Hat, SuSE, Mandrakesoft

► Linux Documentation Project

Page 18: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 18

What do you need?

►DocBook Document Type Definition

(DTD)

►Writing tools.

►XSL stylesheets.

►Processing tools.

Page 19: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 19

Processing DocBook

DocBook

XML file

DocBook

Stylesheet

HTML

files

XSLT

Processor

Page 20: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 20

Why a DTD?

►Defines element names and usage

rules.

►Used to validate documents.

►Improves reliability.

►Special characters with names:

• ™ instead of ™ for

Page 21: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 21

DocBook DTD

►OASIS maintains DocBook DTDs.

►Current version is 4.5.

►400 elements.

►Customizable: easy to subset or extend.

Page 22: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 22

Writing tools

►Notepad or other text editor.

►XMLMind’s XMLEditor (free).

►Oxygen XML.

►Just Systems’ XMetal.

►Syntext’s Serna (free).

►Arbortext Editor.

Page 23: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 23

Writing DocBook

►XML declaration

►DOCTYPE declaration

►Root element

Page 24: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 24

DocBook document

<?xml version="1.0"?>

<!DOCTYPE book

PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN"

"http://www.oasis-open.org/xml/4.5/docbookx.dtd">

<book>

<title>Using a mouse</title>

<para>A mouse is used for blah blah.</para>

<chapter>

<title>Mouse buttons</title>

<para>A mouse has one, two, or three buttons.</para>

</chapter>

</book>

Page 25: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 25

XMetal demo

►Formatted editing view.

►Element list based on context.

►Select attributes.

►Show or hide tags.

►Validate.

Page 26: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 26

Three classes of elements

►Hierarchy elements

►Block elements

►Inline elements

Page 27: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 27

Hierarchy elements

►Hierarchy elements establish divisions

and hierarchy of content

►Hierarchy elements are containers for

other elements.

►May contain other hierarchy elements

and block elements.

Page 28: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 28

Book hierarchy elements

<set>

<book>

<part> (optional)

<preface>

<chapter>

<reference>

<appendix>

<glossary>

<index>

Page 29: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 29

Section hierarchy<chapter>

<sect1>

<sect2>

<sect3>

<sect4>

OR <sect5>

<chapter>

<section>

<section>

<section>

<section>

<section>

Page 30: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 30

Article – alternative to book

►Less than a book.

►Like chapter, but not numbered.

►Good for:

• White paper.

• Short HOWTO.

Page 31: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 31

Block elements

►Paragraphs, lists, notes, examples.

►Block elements delineated by line

breaks before and after in output.

►Lines wrap within (with exceptions).

►May contain text, inline elements, and

other block elements (e.g., nested lists)

Page 32: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 32

Block examplesParagraph <para>Text</para>

Bullet list <itemizedlist>

<listitem>

<para>First</para>

</listitem>

</itemizedlist>

Numbered list <orderedlist>

<listitem>

<para>Item 1</para>

</listitem>

</orderedlist>

Page 33: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 33

More block elements

►<procedure>, containing <step>+

►<variablelist>, like HTML DL list

►<note>, <caution>, <important>,

<tip>, <warning>

►<synopsis>, <cmdsynopsis>,

<funcsynopsis>, for syntax.

►<qandaset> for FAQs

►<msgset> for error messages

Page 34: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 34

Text display elements

►Preserve whitespace.

►Optional line numbering attribute.

►<programlisting>

• Monospace font.

►<screen>

• Monospace font.

►<literallayout>

• not monspace font by default

Page 35: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 35

Program listing example

<programlisting>#!/usr/bin/perl

use LWP::UserAgent;

use XML::RSS;

my ($file, $url) = @_;

my $ua = LWP::UserAgent-&gt;new;

&amp;FetchSS($ua);

sub FetchSS {

return($_-&gt;GetSS)

}

</programlisting>

Page 36: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 36

CDATA to avoid escaping

<programlisting><![CDATA[#!/usr/bin/perl

use LWP::UserAgent;

use XML::RSS;

my ($file, $url) = @_;

my $ua = LWP::UserAgent->new;

&FetchSS($ua);

sub FetchSS {

return($_->GetSS)

}

]]></programlisting>

Page 37: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 37

Formal displays

►Elements

• figure

• example

• table

• equation

►Numbered and titled.

►Each can contain appropriate content.

Page 38: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 38

Graphics

►<mediaobject>

• Contains one or more <imageobject>

– Each contains one <imagedata>

►Separate object for each output format.

►Select by role attribute.

►Replaces simpler <graphic> element

Page 39: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 39

mediaobject example

<mediaobject>

<imageobject role="html">

<imagedata fileref="mouse.png"/>

</imageobject>

<imageobject role="fo">

<imagedata fileref="mouse.pdf"/>

</imageobject>

</mediaobject>

Page 40: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 40

Inline elements

►Commands, filenames, user input.

►Inline elements appear within a line of

text.

►No implied line break before or after.

►May contain text, other inline elements.

►Dozens of inline elements.

Page 41: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 41

Cross reference with xref

<chapter id=Mouse>

<title>Using a Mouse</title>

...

See <xref linkend="Mouse"/>.

►Output:

See <a href=#Mouse>Chapter 3, Using

a Mouse</a>.

Page 42: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 42

Cross reference with link

<chapter id="Mouse">

<title>Using a Mouse</title>

Use your

<link linkend="Mouse">mouse</link>

for ...

►Output:

Use your

<a href=#Mouse>mouse</a> for ...

<chapter id="Mouse">

<title>Using a Mouse</title>

...

Use your

<link linkend="Mouse">mouse</link>

for ...

►Output:Use your <a href=#Mouse>mouse</a>

for ...

Page 43: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 43

External cross references

►<olink> uses two attributes:

• targetdoc points to another document

• targetptr points to an id in it.

►Requires setting up target database.

►Creates dependencies between

documents.

Page 44: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 44

Glossaries

►A <glossary> contains <glossentry>s

►A <glossterm> can link to a

<glossentry>.

►Can do automatic linking based on word

match.

►Can generate a glossary from an

external master collection.

Page 45: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 45

Bibliographies

►A <bibliography> contains

<biblioentry>s.

►A <xref> can link to a <biblioentry>.

►Numbered [2] or abbrev [Brody2002]

link style.

►Can generate a bibliography from an

external master collection.

Page 46: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 46

Indexes

►Insert <indexterm>s in document.

►Add empty <index/> element at end.

►Stylesheet automatically generates the

index.

►HTML shows section titles.

►FO shows page numbers.

Page 47: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 47

Getting to HTML

DocBook

XML file

DocBook

HTML

Stylesheet

HTML

files

XSLT

Processor

Page 48: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 48

DocBook XSL stylesheets

►Written in XML using XSL namespace.

►Stylesheet variant for each output form.

►Designed for customization.

►Adapt to corporate style.

Page 49: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 49

XSLT processors

►xsltproc from Gnome’s xmlsoft.org

►Saxon 6 from SourceForge

►Xalan Java from Apache XML project

Page 50: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 50

HTML options

►HTML or XHTML

►Single file or multiple “chunks”.

►Use CSS classes for styling.

►Post process with

• HTML Help Workshop

• Java Help indexer

Page 51: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 51

HTML Help output

XML file

DocBook

HTMLHelp

Stylesheet

HTML files

.hhp .hhc files

.chm file

XSLT

Processor

HTML Help

Workshop

Page 52: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 52

Getting to print

XML file

DocBook

FO

Stylesheet

FO file

PDF file

XSLT

Processor

FO

Processor

Page 53: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 53

Leading XSL-FO processors

►XEP from RenderX.

►XSL Formatter from Antenna House

►FOP from Apache XML Project

Page 54: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 54

Automated print production

►Stylesheet flows content onto pages.

►Automatic TOC and index.

►Automatic page breaking.

►Writer does not do formatting.

Page 55: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 55

Tweaking for print

XML file

InDesign

template

InDesign

CSPDF file

Tweak

time

Page 56: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 56

Customizable stylesheets

►Modular design (~100 files)

►Reusable named templates.

►Empty, user-defined templates.

►Parameterized (~220 parameters)

►Title page tools.

►Templates for generated text.

Page 57: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Stock DocBook

Single-source Publishing with DocBook 4 57

Page 58: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Stock DocBook Customized

Single-source Publishing with DocBook 4 58

Page 59: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 59

Installing XSLT processor

►xsltproc

• Download libxml2 and libxslt C source.

• Configure and make.

• Windows binaries available.

►Saxon and Xalan

• Need Java runtime environment.

• Download and add to CLASSPATH.

• DocBook extensions available.

Page 60: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 60

Using xsltproc

►HTML output:xsltproc \

--output myfile.html \

/usr/share/docbook/html/docbook.xsl \

myfile.xml

►FO output:xsltproc \

--output myfile.fo \

/usr/share/docbook/fo/docbook.xsl \

myfile.xml

Page 61: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 61

Using Saxon

►HTML output:java -cp "/usr/java/saxon.jar:\

/docbook-xsl/extensions/saxon65.jar" \

com.icl.saxon.StyleSheet \

-o myfile.html \

myfile.xml \

/usr/share/docbook/html/docbook.xsl

Page 62: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 62

Generating PDF with FOP

►Convert a .fo file on Unix or Linux:fop.sh -fo myfile.fo -pdf myfile.pdf

►Convert a .fo file on Windows:

fop.bat -fo myfile.fo -pdf myfile.pdf

►Convert an XML source file:fop.sh -xsl /docbook-xsl/fo/docbook.xsl \

-xml myfile.xml -pdf myfile.pdf

Page 63: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 63

File not found …

►Most common beginner’s problem.

►Many components working together.

►Common problems:

• Path to DTD in file’s DOCTYPE.

• Missing XML character entities.

• Java CLASSPATH missing something.

Page 64: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 64

XML catalog

► Maps generic addresses to specific locations on local machine.

► Portable setup; just edit catalog file when move something.

► Adds flexibility, and complexity.

► SGML catalogs are less capable.

Page 65: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 65

Using parameters

►Named variables in stylesheet.

►Examples:• Specify CSS stylesheet name.

• Turn on section numbering.

• Shade verbatim output.

►Each processor has its own command

syntax.

Page 66: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 66

Parameter example

xsltproc --output myfile.html \

--stringparam html.stylesheet style.css \

--stringparam shade.verbatim 1 \

html/docbook.xsl myfile.xml

► Output

<link rel="stylesheet" href="style.css"

type="text/css">

<table border="0" bgcolor="#E0E0E0">

<tr><td><pre class="literallayout">

Page 67: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 67

Customization driver file

►New stylesheet that combines:

• Standard DocBook XSL templates

• Your customizations.

►Kept separate, so updates are easy.

►Used in place of DocBook stylesheet.

Page 68: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 68

Driver file content

►Standard XSL stylesheet elements.

►Pull in stock DocBook with:

<xsl:import

href="path/to/docbook.xsl"/>

►Parameter settings.

►Replacement templates.

►New generated text.

Page 69: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 69

Customization example

<?xml version='1.0'>

<xsl:stylesheet

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

Transform" version="1.0">

<xsl:import href="html/docbook.xsl"/>

<xsl:param name="shade.verbatim"

select="1"/>

<xsl:template ... </xsl:template>

</xsl:stylesheet>

Page 70: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 70

Special features

►Profiling.

►Modular documentation.

►Cross referencing.

►Localization.

Page 71: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 71

Profiling

►aka Conditional text.

►Multiple versions from same file.

►Marked with profiling attributes:

• os, userlevel, condition, etc.

►Use a profiling stylesheet.

►Select conditions at runtime:

profile.os="linux"

Page 72: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 72

Modular documentation

►Separate large documents into multiple

XML files.

►System entity != valid document.

• No DOCTYPE allowed.

• xrefs won’t resolve.

►Use Xinclude instead.

• Modules can be valid documents.

• Use olink to link between them.

Page 73: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 73

Cross referencing

►Author or generate hotlink text.

►Define cross reference “styles”.

►Link within or between documents

►Between documents:

• Within a concurrent set.

• Reference to previously published doc.

• Reference to remote content.

Page 74: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 74

Olinking

►Create olink database from documents.

►XSL processor reads the database.

►Can generate link text.

►Can link to base URI per document.

►Creates dependencies between docs.

Page 75: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 75

Localization

►Unicode and other encodings

►Generated text in 44 languages

►Index collation

►Mixed language documents

Page 76: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 76

DocBook community

►Mailing lists

• docbook-apps for processing questions.

• docbook for DTD questions.

►DocBook SourceForge project

• Stylesheet CVS files

• Bug reports and feature requests.

►DocBook Wiki

• User contributions.

Page 77: Single-source Publishing with DocBook 4 · Linux Documentation Project. Single-source Publishing with DocBook 4 18 ... Notepad or other text editor. ... • Need Java runtime environment

Single-source Publishing with DocBook 4 77

Questions?

References:► DocBook: The Definitive Guide

• https://tdg.docbook.org/tdg/4.5/docbook.html

► DocBook XSL: The Complete Guide

• http://www.sagehill.net/docbookxsl/