File: README.adoc

package info (click to toggle)
kicad 5.0.2+dfsg1-1
  • links: PTS, VCS
  • area: main
  • in suites: buster
  • size: 234,592 kB
  • sloc: cpp: 505,330; ansic: 57,038; python: 4,886; sh: 879; awk: 294; makefile: 253; xml: 103; perl: 5
file content (160 lines) | stat: -rw-r--r-- 5,652 bytes parent folder | download | duplicates (2)
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
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
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[]. +
Submit your translation pull requests to the stable docs branch *4.0*, please. +
See link:docs-versioning.adoc[] for details about docs versioning.

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 will probably switch to http://asciidoctor.org/[asciidoctor] in the future,
when asciidoctor tools are stable enough, because of their ability to generate PDF
and epub document formats directly without the intervention of any other external
tool or intermediate format like dblatex or docbook. 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 **LANGUAGES** option
to avoid build errors.
* For building PDF files with Cyrillic characters (like Russian) the fonts
package _freefont-ttf_ is required, so you will need to look for similar named
package.

=== Debian / Ubuntu

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

    sudo apt-get install asciidoc cmake dblatex fonts-freefont-ttf \
    fonts-vlgothic gettext git make po4a source-highlight \
    texlive-lang-cyrillic texlive-lang-english texlive-lang-european \
    texlive-lang-french texlive-lang-german texlive-lang-italian \
    texlive-lang-japanese texlive-lang-other texlive-lang-polish \
    texlive-lang-spanish texlive-xetex texlive-lang-chinese

NOTE: Debian Jessie and Ubuntu 16.04 LTS has no package
texlive-lang-european, install the package texlive-lang-dutch instead.

NOTE: in Ubuntu 14.04 LTS there is no texlive-lang-japanese. Install
texlive-lang-cjk instead.

or, if you do not have space problems:

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

=== Fedora

To install the dependencies on Fedora run the following:

    sudo dnf install git make cmake asciidoc 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.

==== LANGUAGES

By default CMake will configure to build all languages available for each document.

You can build just one or some of the languages by using the **LANGUAGES** option
when configuring a build with CMake, e.g. `-DLANGUAGES=it;en;de`, etc.

Currently, the available languages are : `ca`, `de`, `en`, `es`, `fr`, `id`, `it`,
`ja`, `nl`, `pl`, `ru`  and `zh`, 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.

==== SINGLE_LANGUAGE

This option is deprecated, use **LANGUAGES** instead

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