1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
|
The user manual is written in XML DocBook format, version 4.3.
It uses the official DocBook XSL stylesheets, and will build with
versions as old as 1.65.1. (Why these versions? They're what comes
with CentOS 3, the oldest system I still use.)
To make the HTML version of the user manual, just type 'make' in this
directory. (Or 'make html' if you want to be pedantic.) To make the
PDF version of the manual, say 'make pdf'. To make both versions,
say 'make all'.
The most likely cause of build failures is not having the right
processing programs installed. The DocBook processing model looks
like this:
DocBook --[XSLT proc.]-+-> HTML
^ |
| +-> XSL-FO --[XSL-FO proc.]--> PDF
|
{XSL stylesheets}
"DocBook" above is a file in DocBook XML format. In this case,
it's in userman.dbx.
There are many alternatives for the tools in the square brackets:
The first replaceable piece is an XSLT processor, which
translates XML into other text formats, such as HTML or other
varieties of XML. We use xsltproc from the Gnome project.
(http://xmlsoft.org/XSLT/) There are numerous alternatives,
but each supports different extensions to the standard, so it's
simplest if everyone uses the same processor for a given document.
We use the XSLT processor to do two transforms. One is directly to
HTML. The other is to XSL-FO, an XML-based page layout language.
We do this intermediary transform because XSLT is not good at
creating binary formats like PDF.
The second replaceable piece in the diagram above is an XSL-FO
processor, which converts XSL-FO to a more directly useful page
layout format, like PDF. The user manual's build system supports
several alternatives.
The build system relies on a simple script in this directory --
fo2pdf -- to find an XSL-FO formatter and run it. It looks first
for RenderX's XEP, which comes in a free-as-in-beer version for
personal use. (http://renderx.com/download/personal.html) If
you're in a commercial environment, RenderX wants you to use their
commercial trial version which will format this manual without
complaint, but it puts watermarks and blank pages into the output.
They want $300 for the single-user to get clean output. It's the
same as the free personal version, just with a different license.
You don't need the higher-end versions of XEP; they don't do
anything we need here.
If fo2pdf can't find XEP, it then looks for Antenna House's XSL
Formatter (http://antennahouse.com/). It's pretty much the same
deal as XEP: crippled demo version for testing, and a single-user
version for $300. There is no free version for personal use,
however.
Failing all that, fo2pdf falls back to the only free-as-in-speech
XSL-FO formmatter, Apache FOP (http://xmlgraphics.apache.org/fop/).
You might be wondering why this isn't the default. It's just that
it's a good bet that if there's a commercial processor on the
system, it was put there quite purposefully by someone who paid (or
caused money to be paid) for it, and so wants it to be used. The
commercial vendors can still get money for their products because
FOP hasn't caught up with them in several important areas. That
said, don't feel that you need to go and buy an XSL-FO processor
just to build the manuals. We try to always keep the manual in a
state where FOP can generate adequate output.
The third replaceable piece above is the DocBook XSL stylesheet set.
The stylesheets are the XSLT processor's rules, controlling how
the input XML gets transformed to the output format. The standard
DocBook stylesheet set (link below) includes stylesheets for HTML
and XSL-FO output. If you don't have them on your system, the XSLT
processor will try to download them using your Internet connection
during processing. This slows processing quite a bit even if you
have a fast Internet connection, and it obviously doesn't work when
your net connection is down.
A better option is to have a copy of the stylesheets on your system.
It's likely that there is a pre-built package for your system:
Red Hat/Fedora: docbook-style-xsl RPM package
Mac OS X: docbook-xsl Fink package (http://fink.sf.net)
Cygwin: docbook-xml?? package (?? = DocBook version)
(Please send the name of the package for your system to the mailing
list if it isn't listed above, and I'll add it to the list.)
If you can't find a package for your system, you can get the DocBook
stylesheets from the source: http://docbook.sourceforge.net/ They're
a bit tricky to set up correctly, so it's better to use a pre-built
package if you can.
If you are still having problems, post the details about it to the
MySQL++ mailing list, and I'll try to help you debug the problem.
You might also find the FOP and/or DocBook mailing lists helpful.
If you're looking to hack on the manual, here are some helpful
resources for getting up to speed on DocBook:
Mills' "Installing And Using An XML/SGML DocBook Editing Suite"
article:
http://tinyurl.com/8alb2
This is the best tutorial I've found.
Walsh and Muellner's _DocBook: The Definitive Guide_ book, second
edition, online version:
http://www.docbook.org/tdg/en/html/docbook.html
This is the official DocBook referece.
DocBook FAQ:
http://www.dpawson.co.uk/docbook/
Go here when you have a question that the tutorials and
references do not answer.
The official DocBook site:
http://docbook.org/
|
