...
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
...
...
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
...