Obviously, CMake is required. V2.8 or later is required. Building (once you’ve got the required pre-requisites) is as simple as:
Having installed the pre-requisites:
cd kicad-doc mkdir build cd build cmake -G "MinGW Makefiles" -DPDF_GENERATOR=FOP ../ make
The following options are available when configuring a build with CMake:
By default BUILD_FORMATS is set to html;pdf to enable building all supported
document formats.
It’s possible to set BUILD_FORMATS in order to build only a subset of formats,
e.g. -DBUILD_FORMATS=html or -DBUILD_FORMATS=pdf
When only one build format is enabled the package name is transformed to include the format.
By default CMake will configure to build all languages available for each document.
You can build just a single language by using the SINGLE_LANGUAGE option when
configuring a build with CMake, e.g. -DSINGLE_LANGUAGE=it, etc.
Currently, the available languages are : en, fr, it, ja, nl, and pl however, any
language code can be selected. Only translated documents will be built, so for
some languages there may only be a partial documentation output.
When the SINGLE_LANGUAGE option is set, the package name is transformed to include the language.
By default CMake will use dblatex building PDFs.
You can build PDFs however using either DBLATEX or FOP by using the
PDF_GENERATOR option whilst configuring a CMake build.
For example, use -DPDF_GENERATOR=FOP to use FOP to build the PDFs. If the
BUILD_FORMATS option doesn’t include pdf, the PDF_GENERATOR option
will have no effect on the build.
This option doesn’t transform the built package name.
PO4A 0.45+ is required. It’s used to translate the English asciidoc documentation to another language before compilation to a final output format.
PO4A is a perl script and so requires PERL to be installed. If you’re using a POSIX emulation layer with package management, grab the perl package.
Outside of a POSIX emulation you’ll need to grab PERL. ActivePerl is recommended.
Install the CPAN modules which are required by PO4A. After installing perl, on the command line type:
cpan Unicode::GCString
Grab the latest PO4A distribution from Alioth, decompress it somewhere on your harddrive and make sure the directory containing po4a is available in your PATH environment variable. CMake will be able to find PO4A on Windows so long as Perl is working and PO4A is in your path.
That’s all there is to get PO4A working on Windows; It’s just used in-place.
|
Note
|
Be careful with any other projects you may have because PERL installs a MinGW compiler which it uses to compile perl modules. Usually it puts this at the start of your path so this version of the MinGW compiler becomes your default compiler! |
AsciiDoc is also required for building the documentation.
Asciidoc is the format of the documentation and is used to generate both PDF and HTML versions of the documentation.
Grab your distribution’s ASCIIDOC package which will also install asciidoc’s pre-requisites too.
To install asciidoc on windows, get the latest version from Sourceforge and unzip somewhere on your drive. Make sure the asccidoc.py file is available in your path in order for CMake to be able to find it.
asciidoc cannot produce PDF output without a PDF generator which can be either dblatex or Apache FOP. On Linux dblatex is usually a dependency of the asciidoc package, but on Windows we must satisfy the PDF generator dependency ourselves.
Details of how to install dblatex and FOP are included below.
|
Warning
|
Although dblatex support is provided for under Windows, it has only been unsuccessfully tested, failing due to a race condition with file permissions on successive xsltproc invocations. However, please do try it if you can because it will probably work one day! |
dblatex has experimental support in the project for PDF generation on Windows. However, it has not been proven to work so currently FOP is the only supported PDF generator on Windows.
In order for CMake to use DBLATEX, use the following when configuring with CMake:
-DPDF_GENERATOR=DBLATEX
dblatex is currently the default PDF generator anyway, so omitting the above will also work if you just want to build using the default tools (in future we may change to something else, like FOP for example)
Make sure you have the latest version of python 2 installed.
Download and install MikTex which provides the latex backend for dblatex. It’s recommended during install to set the "Install packages on the fly" to yes so MikTex doesn’t have to ask before installing packages - it’s a real pain when installing dblatex otherwise!! It also appears that if you miss that setting dblatex will fail to install because of some crashes of MikTex which then reports missing elements in the toolchain.
Download and install libxml2 which is pain. You’ll need to download and decompress all the zip files. Then, manually copy each of the folders into a common directory so that you end up with one bin directory and one lib directory, etc. You must then make sure the bin path of your installation directory is added to your PATH environment variable.
Then download the latest dblatex .tar.bz2 from Sourceforge
Decompress the tar.bz2 somewhere and then install dbltatex:
cd dblatex-0.45 python setup.py install
|
Note
|
Although CMake can find that you have dblatex installed, it’s not possible for a2x to run dblatex on windows without supplying a dblatex executable. This can be done by placing the dblatex.cmd file from the CMakeSupport/windows directory in your path and modifying it as necessary. |
So long as the install works, CMake will be able to find dblatex in your python installation
|
Note
|
This is currently the only way of building PDF documents on Windows. |
It’s possible to use Apache FOP for PDF generation with Asciidoc instead of dbaltex. Some people will prefer the output of Apache FOP compared to dblatex. It brings with it a dependency on a Java runtime.
In order for CMake to use FOP, use the following when configuring with CMake:
-DPDF_GENERATOR=FOP
|
Warning
|
ASCIIDOCTOR is not currently supported! |
It’s possible to use asciidoctor to produce both HTML and PDF output (PDF through the asciidoctor-pdf project). Asciidoctor has good development and support, but the PDF generation is currently missing support for inline images, so it’s not currently used. It brings with it a dependency on Ruby.