KiCad Documentation
===================

This repository contains the official link:http://www.kicad-pcb.org/[KiCad] documentation.

image:http://ci.kicad-pcb.org/buildStatus/icon?job=any-kicad-doc-head["Build Status",
link="http://ci.kicad-pcb.org/job/any-kicad-doc-head/"]
image:https://img.shields.io/badge/docs-stable-brightgreen.svg["Stable version docs",
link="http://docs.kicad-pcb.org/"]
image:https://img.shields.io/badge/docs-nightly-lightgrey.svg["Nightly docs",
link="http://ci.kicad-pcb.org/job/any-kicad-doc-head/lastSuccessfulBuild/artifact/src/"]

== Contributing

You can discuss the documentation and its translations in the
link:https://github.com/KiCad/kicad-doc/issues[repository issues].

To participate to the translation effort read the link:translation_instructions.adoc[].

The following instructions explain how to test changes before
link:https://github.com/KiCad/kicad-doc/fork[submitting a pull-request].

== Dependencies

* http://asciidoc.org/[AsciiDoc] >= 8.6.9 is both the language of the
documentation and the tool used to generate the PDF and HTML outputs.
We don't use http://asciidoctor.org/[asciidoctor] because PDF generation is currently missing support for inline images (see the
http://asciidoctor.org/docs/convert-asciidoc-to-pdf/[asciidoctor-pdf] project).

* https://po4a.alioth.debian.org/[po4a] >= 0.45 is used to translate the English
AsciiDoc documentation to other languages before the last compilation steps.
* CMake >= 2.8
* dblatex >= 0.3.4
* gettext >= 0.18
* source-highlight
* The _VL Gothic_ font is required when you build the japanese PDFs. Look for a
package named `fonts-vlgothic`. Otherwise use the SINGLE_LANGUAGE option
to avoid build errors.

=== Debian / Ubuntu

To install the dependencies on Debian / Ubuntu  run the following (requires about 1.5GiB of space):

    sudo apt-get install git make cmake asciidoc pandoc gettext po4a dblatex
    texlive-xetex fonts-vlgothic source-highlight texlive-lang-english
    texlive-lang-french texlive-lang-italian texlive-lang-japanese
    texlive-lang-dutch texlive-lang-polish texlive-lang-german texlive-lang-cyrillic
    texlive-lang-other

NOTE: in Ubuntu 14:04 there is no texlive-lang-japanese. Install
texlive-lang-cjk instead.

NOTE: in Debian Jessie the package texlive-lang-dutch is a transitional
package, Install texlive-lang-european instead.

or, if you do not have space problems:

    sudo apt-get install git make cmake asciidoc pandoc gettext po4a dblatex
    texlive-xetex fonts-vlgothic source-highlight texlive-lang-all

=== Fedora

To install the dependencies on Fedora run the following:

    sudo dnf install git make cmake asciidoc pandoc gettext po4a dblatex
    source-highlight texlive vlgothic-fonts perl-Unicode-LineBreak
    texlive-scheme-full texlive-collection-xetex gnu-free-serif-fonts
    gnu-free-mono-fonts gnu-free-sans-fonts

== Building the docs

=== Windows

Start with link:windows_dependencies.adoc[] then run:

    cd kicad-doc
    mkdir build
    cd build
    cmake -G "MinGW Makefiles" -DPDF_GENERATOR=FOP ../
    make

=== MacOS / Linux

    cd kicad-doc
    mkdir build
    cd build
    cmake ../
    make

=== Docker
Read link:utils/docker/README.adoc[] if you want to build the documentation in a container.

=== CMake Build Options

==== BUILD_FORMATS

By default **BUILD_FORMATS** is set to `html;pdf;epub` 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`

When only one build format is enabled the package name is transformed to include
the format.

==== SINGLE_LANGUAGE

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.

==== PDF_GENERATOR

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.

=== Packaging the docs
The docs use CMake as mentioned earlier, so to install it as a packager use the
normal CMake way, for example:

    mkdir build; cd build
    cmake -DCMAKE_INSTALL_PREFIX=/usr ..
    make install

And if on OS X you might want something like:

    mkdir build; cd build
    cmake -DCMAKE_INSTALL_PREFIX="/Library/Application Support/kicad" ..
    make install

