Versions Compared

Key

  • This line was added.
  • This line was removed.
  • Formatting was changed.

...

This

...

document

...

provides

...

an

...

overview

...

of

...

the

...

different

...

features

...

of

...

the

...

Maven

...

Docbkx

...

Plugin.

...

With

...

almost

...

200

...

+

...

customizable

...

properties

...

per

...

type

...

of

...

output

...

format,

...

it

...

would

...

be

...

impossible

...

list

...

all

...

of

...

those

...

in

...

this

...

document.

...

For

...

more

...

detailed

...

information

...

on

...

these

...

customizable

...

properties,

...

please

...

consult

...

the

...

online

...

plugin

...

documentation.

...

Instead

...

of

...

being

...

a

...

reference

...

guide,

...

this

...

document

...

is

...

intended

...

to

...

get

...

you

...

started,

...

and

...

at

...

least

...

to

...

get

...

some

...

flavour

...

of

...

the

...

scope

...

of

...

this

...

plugin.

...

In

...

this

...

document,

...

we

...

will

...

discuss

...

every

...

feature

...

with

...

an

...

example,

...

showing

...

the

...

relevant

...

configuration

...

code.

...

You

...

are

...

encouraged

...

to

...

work

...

through

...

these

...

examples

...

in

...

the

...

given

...

order.

...

Example

...

Usage

...

This

...

is

...

by

...

far

...

the

...

simplest

...

example

...

that

...

you

...

can

...

possibly

...

imagine.

...

At

...

a

...

bare

...

minimum,

...

you

...

need

...

to

...

specify

...

a

...

dependency

...

on

...

the

...

jar

...

file

...

containing

...

the

...

DocBook

...

DTD.

...

That

...

is,

...

if

...

your

...

source

...

documents

...

are

...

refering

...

to

...

a

...

DocBook

...

DTD

...

at

...

all.

...

There

...

are

...

however

...

good

...

reasons

...

to

...

include

...

a

...

DTD

...

reference,

...

as

...

you

...

will

...

find

...

out

...

in

...

one

...

of

...

the

...

following

...

examples.

...

Using

...

this

...

configuration,

...

you

...

can

...

build

...

a

...

document

...

from

...

the

...

sources

...

by

...

invoking

...

docbkx:generate-html.

...

This

...

will

...

try

...

to

...

convert

...

all

...

files

...

matching

...

the

...

*.xml

...

file

...

pattern

...

in

...

$

...

basedir

...

/src/docbkx

...

to

...

HTML

...

pages.

...



Example 1. Minimal configuration

Code Block

  <build>
    <plugins>
      <plugin>
        <groupId>com.agilejava.docbkx</groupId>
        <artifactId>docbkx-maven-plugin</artifactId>
        <dependencies>
          <dependency>
            <groupId>org.docbook</groupId>
            <artifactId>docbook-xml</artifactId>
            <version>4.4</version>
            <scope>runtime</scope>
          </dependency>
        </dependencies>
      </plugin>
    </plugins>
  </build>

Normally

...

you

...

would

...

of

...

course

...

want

...

generation

...

of

...

the

...

documents

...

to

...

happen

...

automatically.

...

In

...

this

...

sense,

...

the

...

Docbkx

...

Maven

...

Plugin

...

is

...

hardly

...

any

...

different

...

than

...

all

...

of

...

the

...

other

...

existing

...

Maven

...

2

...

plugins.

...

Simply

...

add

...

an

...

execution

...

element

...

to

...

specify

...

the

...

goal

...

and

...

the

...

phase.

...

The

...

example

...

below

...

specifies

...

that

...

the

...

documents

...

in

...

src/docbkx

...

should

...

be

...

turned

...

into

...

HTML

...

in

...

the

...

pre-site

...

phase.

...



Example 2. Attached to a phase

Code Block

  <build>
    <plugins>
      <plugin>
        <groupId>com.agilejava.docbkx</groupId>
        <artifactId>docbkx-maven-plugin</artifactId>
        <executions>
          <execution>
            <goals>
              <goal>generate-html</goal>
            </goals>
            <phase>pre-site</phase>
          </execution>
        </executions>
        <dependencies>
          <dependency>
            <groupId>org.docbook</groupId>
            <artifactId>docbook-xml</artifactId>
            <version>4.4</version>
            <scope>runtime</scope>
          </dependency>
        </dependencies>
      </plugin>
    </plugins>
  </build>

Adding

...

other

...

output

...

formats

...

is

...

easy.

...

Simply

...

specify

...

it

...

as

...

additional

...

goals.

...

In

...

the

...

example

...

below,

...

we

...

are

...

not

...

only

...

rendering

...

HTML

...

but

...

also

...

PDF

...

and

...

UNIX

...

man

...

pages.

...

(Note

...

however

...

that

...

it

...

does

...

not

...

make

...

a

...

lot

...

of

...

sense

...

to

...

render

...

man

...

pages

...

from

...

an

...

appendix.

...

You

...

still

...

need

...

to

...

add

...

your

...

own

...

common

...

sense

...

to

...

figure

...

out

...

which

...

output

...

formats

...

make

...

sense

...

with

...

your

...

documents.

...



Example 3. Multiple output formats

Code Block

  <build>
    <plugins>
      <plugin>
        <groupId>com.agilejava.docbkx</groupId>
        <artifactId>docbkx-maven-plugin</artifactId>
        <executions>
          <execution>
            <goals>
              <goal>generate-html</goal>
              <goal>generate-pdf</goal>
              <goal>generate-manpages</goal>
            </goals>
            <phase>generate-sources</phase>
          </execution>
        </executions>
        <dependencies>
          <dependency>
            <groupId>org.docbook</groupId>
            <artifactId>docbook-xml</artifactId>
            <version>4.4</version>
            <scope>runtime</scope>
          </dependency>
        </dependencies>
      </plugin>
    </plugins>
  </build>

So

...

now

...

we

...

are

...

able

...

to

...

render

...

different

...

types

...

of

...

output.

...

You

...

might

...

however

...

not

...

be

...

impressed

...

too

...

much

...

by

...

the

...

default

...

output

...

of

...

the

...

plugins.

...

The

...

good

...

news

...

is

...

that

...

there

...

is

...

a

...

lot

...

(

...

!)

...

to

...

customize.

...

Every

...

goal

...

(every

...

output

...

format)

...

defines

...

its

...

own

...

collection

...

of

...

customizable

...

properties.

...

The

...

entire

...

list

...

would

...

be

...

far

...

to

...

big

...

to

...

list

...

here,

...

so

...

we

...

will

...

just

...

give

...

a

...

simple

...

example.

...

Let's

...

just

...

assume

...

that

...

you

...

crafted

...

your

...

own

...

CSS

...

file

...

containing

...

the

...

essential

...

bling

...

bling

...

for

...

your

...

DocBook

...

output

...

file.

...

In

...

that

...

case

...

you

...

can

...

simply

...

link

...

this

...

stylesheet

...

to

...

all

...

HTML

...

pages

...

generated

...

by

...

addding

...

the

...

htmlStylesheet

...

property,

...

like

...

shown

...

below.

...



Example 4. Additional customization

Code Block

  <build>
    <plugins>
      <plugin>
        <groupId>com.agilejava.docbkx</groupId>
        <artifactId>docbkx-maven-plugin</artifactId>
        <dependencies>
          <dependency>
            <groupId>org.docbook</groupId>
            <artifactId>docbook-xml</artifactId>
            <version>4.4</version>
            <scope>runtime</scope>
          </dependency>
        </dependencies>
        <configuration>
          <htmlStylesheet>http://.....</htmlStylesheet>
        </configuration>
      </plugin>
    </plugins>
  </build>

The

...

example

...

given

...

above

...

highlights

...

one

...

of

...

200

...

+

...

customizable

...

properties

...

that

...

correspond

...

to

...

XSL

...

parameters

...

defined

...

by

...

the

...

DocBook

...

stylesheets.

...

In

...

addition,

...

the

...

plugin

...

also

...

defines

...

a

...

couple

...

of

...

properties

...

of

...

its

...

own.

...

You

...

will

...

probably

...

find

...

the

...

includes

...

property

...

among

...

the

...

ones

...

you

...

will

...

use

...

most

...

often.

...

This

...

property

...

allows

...

you

...

to

...

specify

...

a

...

comma

...

separated

...

list

...

of

...

file

...

patterns

...

to

...

include

...

in

...

the

...

transformation.

...

The

...

example

...

given

...

below

...

specifies

...

that

...

any

...

file

...

matching

...

$

...

basedir

...

/src/docbkx/

...

-docbkx.xml

...

should

...

be

...

included

...

in

...

the

...

transformation.

*

...

Example 5. Explicit source file selection

Code Block

  <build>
    <plugins>
      <plugin>
        <groupId>com.agilejava.docbkx</groupId>
        <artifactId>docbkx-maven-plugin</artifactId>
        <dependencies>
          <dependency>
            <groupId>org.docbook</groupId>
            <artifactId>docbook-xml</artifactId>
            <version>4.4</version>
            <scope>runtime</scope>
          </dependency>
        </dependencies>
        <configuration>
          <includes>*-docbkx.xml</includes>
        </configuration>
      </plugin>
    </plugins>
  </build>

One

...

of

...

the

...

more

...

advanced

...

and

...

interesting

...

things

...

of

...

the

...

Docbkx

...

Maven

...

Plugin

...

is

...

that

...

it

...

allows

...

you

...

to

...

refer

...

to

...

POM

...

properties

...

from

...

within

...

your

...

DocBook

...

documents.

...

Take

...

some

...

time

...

to

...

think

...

that

...

over...

...

The

...

plugin

...

solves

...

this

...

by

...

mapping

...

entities

...

to

...

values

...

defined

...

in

...

your

...

POM.

...

And

...

in

...

your

...

POM

...

you

...

can

...

define

...

the

...

values

...

to

...

be

...

composed

...

of

...

other

...

POM

...

properties.

...

An

...

example

...

will

...

help

...

you

...

to

...

understand

...

what

...

this

...

means.

...

First

...

of

...

all,

...

it

...

is

...

not

...

uncommon

...

for

...

documents

...

to

...

refer

...

to

...

a

...

version

...

of

...

the

...

software.

...

Maintaining

...

the

...

dependency

...

by

...

hand

...

would

...

be

...

a

...

lot

...

of

...

work,

...

and

...

there

...

would

...

be

...

severe

...

chance

...

that

...

it

...

would

...

go

...

out

...

whack

...

in

...

no-time.

...

So,

...

would

...

it

...

not

...

be

...

awesome

...

if

...

we

...

could

...

refer

...

to

...

the

...

Maven

...

version

...

number

...

from

...

within

...

our

...

DocBook

...

source

...

document?

...

The

...

good

...

news

...

is:

...

you

...

can.

...

Look

...

at

...

the

...

code

...

snipped

...

below

...

to

...

figure

...

out

...

how

...

to

...

do

...

it.

...

In

...

all

...

honesty,

...

it

...

is

...

not

...

that

...

complicated

...

at

...

all.

...

Within

...

the

...

entities

...

section,

...

you

...

simply

...

define

...

an

...

entity

...

called

...

version,

...

and

...

define

...

it

...

to

...

be

...

the

...

value

...

of

...

the

...

POM

...

property

...

version.

...

The

...

plugin

...

will

...

make

...

sure

...

that

...

any

...

reference

...

to

...

&

...

version;

...

will

...

be

...

translated

...

to

...

the

...

version

...

number

...

defined

...

in

...

your

...

POM.

...



Example 6. Entity substitution

Code Block

  <build>
    <plugins>
      <plugin>
        <groupId>com.agilejava.docbkx</groupId>
        <artifactId>docbkx-maven-plugin</artifactId>
        <dependencies>
          <dependency>
            <groupId>org.docbook</groupId>
            <artifactId>docbook-xml</artifactId>
            <version>4.4</version>
            <scope>runtime</scope>
          </dependency>
        </dependencies>
        <configuration>
          <entities>
            <entity>
              <name>version</name>
              <value>${{version}}</value>
            </entity>
          </entities>
        </configuration>
      </plugin>
    </plugins>
  </build>

Hopefully

...

all

...

of

...

the

...

above

...

will

...

make

...

you

...

consider

...

using

...

DocBook.

...

DocBook

...

does

...

not

...

need

...

to

...

be

...

hard

...

at

...

all,

...

and

...

-

...

if

...

you

...

want

...

to

...

-

...

DocBook

...

authoring

...

can

...

be

...

almost

...

like

...

....

...

coding.

...

The

...

fact

...

that

...

it

...

is

...

plain

...

old

...

XML

...

just

...

makes

...

it

...

a

...

very

...

interesting

...

candidate

...

for

...

completely

...

automating

...

your

...

document

...

generation.

...

And

...

with

...

all

...

of

...

the

...

XML

...

based

...

metadata

...

available

...

in

...

your

...

projects,

...

it

...

would

...

actually

...

be

...

incredibly

...

easy

...

to

...

accomplish.

...

The

...

only

...

problem

...

that

...

might

...

get

...

in

...

the

...

way

...

if

...

you

...

are

...

thinking

...

about

...

generating

...

DocBook

...

sources

...

is

...

the

...

fact

...

that

...

Maven

...

does

...

not

...

really

...

provide

...

a

...

clear

...

hook

...

or

...

phase

...

for

...

it.

...

For

...

that

...

reason,

...

the

...

Maven

...

Docbkx

...

Plugin

...

defines

...

the

...

preProcess

...

and

...

postProcess

...

properties.

...

When

...

your

...

project

...

requires

...

you

...

to

...

generate

...

some

...

content

...

just

...

in

...

time,

...

right

...

before

...

rendering

...

PDF

...

or

...

HTML

...

from

...

DocBook,

...

or

...

if

...

you

...

need

...

to

...

do

...

some

...

post

...

processing,

...

then

...

the

...

plugin

...

allows

...

you

...

to

...

'script'

...

it

...

in

...

Ant

...

vocabulary

...

as

...

part

...

of

...

the

...

plugins

...

configuration.

...

The

...

example

...

below

...

does

...

not

...

really

...

do

...

anything

...

interesting

...

before

...

rendering

...

PDF

...

output.

...

It

...

does

...

however

...

demonstrate

...

how

...

you

...

could

...

include

...

your

...

own

...

scripts

...

to

...

be

...

executed

...

right

...

before

...

or

...

right

...

after

...

the

...

DocBook

...

to

...

output

...

format

...

transformation.

...



Example 7. Preprocessing DocBook sources

Code Block

  <build>
    <plugins>
      <plugin>
        <groupId>com.agilejava.docbkx</groupId>
        <artifactId>docbkx-maven-plugin</artifactId>
        <dependencies>
          <dependency>
            <groupId>org.docbook</groupId>
            <artifactId>docbook-xml</artifactId>
            <version>4.4</version>
            <scope>runtime</scope>
          </dependency>
        </dependencies>
        <configuration>
          <preProcess>
            <echo>Some script executing.</echo>
          </preProcess>
        </configuration>
      </plugin>
    </plugins>
  </build>

This

...

example

...

demonstrates

...

how

...

you

...

can

...

split

...

up

...

your

...

HTML

...

output

...

document

...

in

...

multiple

...

parts.

...

Simply

...

set

...

the

...

chunkedOutput

...

property

...

to

...

true.

...

That's

...

all.

...

The

...

plugin

...

will

...

continue

...

to

...

use

...

target

...

file

...

name,

...

but

...

reserve

...

it

...

for

...

the

...

first

...

chunk

...

of

...

HTML.

...

The

...

remainder

...

of

...

the

...

document

...

will

...

broken

...

up

...

into

...

several

...

pieces,

...

depending

...

on

...

the

...

policies

...

you

...

specified

...

with

...

customization

...

properties.

...



Example 8. Chunked output

Code Block

  <build>
    <plugins>
      <plugin>
        <groupId>com.agilejava.docbkx</groupId>
        <artifactId>docbkx-maven-plugin</artifactId>
        <dependencies>
          <dependency>
            <groupId>org.docbook</groupId>
            <artifactId>docbook-xml</artifactId>
            <version>4.4</version>
            <scope>runtime</scope>
          </dependency>
        </dependencies>
        <configuration>
          <chunkedOutput>true</chunkedOutput>
        </configuration>
      </plugin>
    </plugins>
  </build>

In

...

the

...

past,

...

the

...

only

...

way

...

to

...

compose

...

a

...

DocBook

...

document

...

from

...

several

...

parts

...

required

...

system

...

entity

...

include

...

statements

...

as

...

part

...

of

...

your

...

DTD

...

declaration.

...

XInclude

...

provides

...

an

...

alternative

...

and

...

much

...

more

...

sophisticated

...

way

...

to

...

pull

...

in

...

data

...

from

...

other

...

sources.

...

If

...

you

...

want

...

XInclude

...

support,

...

then

...

you

...

should

...

set

...

the

...

'xincludeSupport'

...

property

...

to

...

'true'.

...

Note

...

that

...

this

...

feature

...

is

...

still

...

fairly

...

experimental.

...



Example 9. XInclude Support

Code Block

  <build>
    <plugins>
      <plugin>
        <groupId>com.agilejava.docbkx</groupId>
        <artifactId>docbkx-maven-plugin</artifactId>
        <dependencies>
          <dependency>
            <groupId>org.docbook</groupId>
            <artifactId>docbook-xml</artifactId>
            <version>4.4</version>
            <scope>runtime</scope>
          </dependency>
        </dependencies>
        <configuration>
          <xincludeSupported>true</xincludeSupported>
        </configuration>
      </plugin>
    </plugins>
  </build>

The

...

easiest

...

way

...

to

...

customize

...

your

...

DocBook

...

output

...

is

...

probably

...

by

...

changing

...

property

...

values,

...

as

...

outlined

...

above.

...

However,

...

there

...

may

...

be

...

situations

...

in

...

which

...

you

...

need

...

more

...

flexbility.

...

The

...

plugin

...

provides

...

this

...

flexibility

...

by

...

allowing

...

you

...

to

...

pass

...

a

...

reference

...

to

...

your

...

own

...

stylesheet.

...

The

...

mechanism

...

is

...

similar

...

to

...

what

...

you

...

would

...

do

...

normally

...

when

...

adding

...

your

...

own

...

customization

...

layer.

...

You

...

create

...

a

...

customization

...

stylesheet

...

that

...

starts

...

by

...

importing

...

the

...

standard

...

docbook.xsl

...

stylesheet.

...

The

...

trick

...

is

...

how

...

to

...

locate

...

the

...

'standard'

...

docbook.xsl

...

stylesheet.

...

After

...

all,

...

the

...

plugin

...

would

...

normally

...

hide

...

it

...

from

...

you

...

entirely,

...

right?

...

The

...

trick

...

is

...

to

...

use

...

a

...

'symbolic'

...

reference

...

instead

...

of

...

a

...

real

...

location

...

in

...

your

...

import.

...

By

...

using

...

this

...

import:

...

<xsl:import

...

href="urn:docbkx:stylesheet" />,

...

you

...

basically

...

tell

...

the

...

plugin

...

to

...

import

...

the

...

standard

...

stylesheet

...

for

...

your

...

specific

...

output

...

format.

...

Once

...

you

...

have

...

your

...

own

...

customization

...

stylesheet

...

(probably

...

based

...

on

...

some

...

of

...

the

...

tips

...

in

...

Bob

...

Sagehills

...

excellent

...

book),

...

you

...

can

...

simply

...

tell

...

the

...

plugin

...

to

...

use

...

that

...

customization,

...

by

...

setting

...

the

...

foCustomization

...

property

...

(in

...

case

...

of

...

PDF

...

output)

...

or/and

...

the

...

htmlCustomization

...

property

...

(for

...

HTML

...

output).

...



Example 10. Advanced Customization

Code Block

  <build>
    <plugins>
      <plugin>
        <groupId>com.agilejava.docbkx</groupId>
        <artifactId>docbkx-maven-plugin</artifactId>
        <dependencies>
          <dependency>
            <groupId>org.docbook</groupId>
            <artifactId>docbook-xml</artifactId>
            <version>4.4</version>
            <scope>runtime</scope>
          </dependency>
        </dependencies>
        <configuration>
          <foCustomization>src/test/resources/docbook-fo.xsl</foCustomization>
        </configuration>
      </plugin>
    </plugins>
  </build>