docbook pretty playout project is (yet) a simple set of .xsl
stylesheets used as a customization layer above a stock DocBook XSL stylesheets.
BTW, if you are interested in what customization layer is - see a perfect explanation in Bob Stayton's book
Project deals with a print-related DocBook XSL stylesheets only (location within stock stylesheets is a /fo
directory)
The aim of the project is to provide:
-
to any newcomer to DocBook or even to a seasoned DocBook user an affordable way to get a pretty, design-approved print output for the full spectrum of technical documentation exists: manuals, marketing brochures, whitepapers, etc.
-
a some kind of construction kit for any DocBook user to get a custom documents WITH a design layout without any hassle. The idea behind this project is to provide anyone to have a main ready-to-use design plus easy alternation gears within a design-approved boundaries.
If you want to get more details - see expanded explanation about, why this project was created.
- Any machine (PC, Mac, headless server, ...) with OS, that supports Java.
- Java (JRE) 1.6 or newer installed and working. Check if Java is installed correctly:
$ java -version
- Any XSLT processor (xsltproc, Xalan, Saxon) installed and working.
NOTE: XSLT 1.0 processor is recommended. Despite any of XSLT v2.0 or v3.0 processor can work with a v1.0 stylesheets, this can lead to annoying warnings about using an outdated (v1.0) stylesheets.
- Apache FOP 2.1 or newer. You can get the latest FOP from official download page. Check if Apache FOP is installed correctly:
$ fop -version
- Git - to clone the repo.
- Any utility (or web browser) - to download files (
wget
is recommended). - Any Docbook/XML v5.0/5.1 file (document) you need to convert to a PDF file.
NOTE 1: To check how the current project works, a sample source Docbook/XML (.xml
) document and additional files are provided within a docbook-samples
directory.
NOTE 2: Due to samples, used in this project, are the core of another project, docbook-samples
directory is provided as a git submodule within a current project.
- Create a directory, where you want to store a project:
$ mkdir docbook-pretty-playout
- Change directory to the created one:
$ cd docbook-pretty-playout
- Get the project files:
$ git clone --recursive https://github.com/eduardtibet/docbook-pretty-playout.git
NOTE: You have to use --recursive
option, because the directory with a samples is a separate author's project and is included as a git submodule here!
- Although it is not required (you can use any FOP configuration file or even don't use it at all), author highly recommends to use a foponts project in conjunction with a current one to get a fully satisfied result.
You can get .pdf
files from your source DocBook/XML files using either 1-step or 2-steps processing.
To get your .pdf
file with 1-step processing:
- Run Apache FOP with the following command line (use
-c
option and corresponding value only in case you use foponts project or any other custom generated configuration file for Apache FOP; in any other case - leave it out):
fop -c <your_path_to_foponts_project>/foponts.xml -xml docbook-samples/stdf/stdf_manual.xml -xsl docbook-pretty-playout.xsl -pdf docbook-samples/stdf/stdf_manual.pdf
- Look at the result by opening the generated file
stdf_manual.pdf
(or any other generated file of your own) in your favorite PDF viewer:
$ xpdf docbook-samples/stdf/stdf_manual.pdf
To get your .pdf
file with 2-steps processing (xsltproc
xslt engine is shown below as an example):
- First get a
.fo
file from a DocBook source (a sample below shows generating a sample file using adocbook-samples
subdirectory/project):
xsltproc -o docbook-samples/stdf/stdf_manual.fo docbook-pretty-playout.xsl docbook-samples/stdf/stdf_manual.xml
- Now, it's time to get a
.pdf
file:
fop -c <your_path_to_foponts_project>/foponts.xml -fo docbook-samples/stdf/stdf_manual.fo -pdf docbook-samples/stdf/stdf_manual.pdf
- Look at the result just opening the generated file
stdf_manual.pdf
(or any other generated file of your own) in your favorite PDF viewer:
$ xpdf docbook-samples/stdf/stdf_manual.pdf
NOTE: You can compare the result with the reference file, generated by the author using this project in conjunction with a foponts project. The file can be downloaded from:
$ wget http://www.singlesourcing.ru/pub/docbook-samples/stdf/stdf_manual.pdf
See FAQ.
See TODO.
It fully depends on a type of your contribution:
- If you found a bug or have any amazing RFE - just create an issue.
- If you want to add a new features to a docbook pretty playout - just fork this project, make any alternation you want and create a pull request.
- Eduard Tibet eduardtibet - initial work based on the stock DocBook XSL Stylesheets. See the original repository if you are interested in.
This project is licensed under the BSD 3-Clause License - see the LICENSE for more details.