Skip to content
This repository has been archived by the owner on Apr 25, 2024. It is now read-only.

Commit

Permalink
Move "Contributing" to top, merge with src/README, split windows-depe…
Browse files Browse the repository at this point in the history 
…ndencies
  • Loading branch information
@Caerbannog
Caerbannog committed Jul 21, 2015
1 parent 6c5f5c7 commit 8c61fff
Show file tree
Hide file tree
Showing 3 changed files with 143 additions and 170 deletions.
188 changes: 38 additions & 150 deletions README.adoc
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
KiCad Documentation
===================

This respository contains the official 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/"]
Expand All @@ -10,29 +10,61 @@ 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/"]

== Building
== Contributing

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

To participate to the translation effort a PO editor like poedit, lokalize, virtall, emacs or vi is recommended.

The following instructions explain how to test changes before
link:https://github.com/ciampix/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.

Having installed the dependencies, the following commands will build the PDF and HTML versions of the documentation.
== 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

=== Linux/MacOS
=== MacOS

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

=== Docker
=== Debian / Ubuntu

Install all dependencies with the following packages, then follow MacOS instructions.

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

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

=== CMake Build Options

Expand Down Expand Up @@ -73,147 +105,3 @@ For example, use `-DPDF_GENERATOR=FOP` to use FOP to build the PDFs. If the
will have no effect on the build.

This option doesn't transform the built package name.

== Dependencies

=== CMake

CMake v2.8 or later is required.

=== AsciiDoc

http://asciidoc.org/[AsciiDoc] is the format of the documentation and is
used to generate both PDF and HTML versions of the documentation.

We don't use http://asciidoctor.org/[asciidoctor] because PDF generation is currently missing
support for inline images, so it's not used.
It's possible to use it to produce both HTML and PDF output (PDF through the
http://asciidoctor.org/docs/convert-asciidoc-to-pdf/[asciidoctor-pdf]
project).

=== po4a

https://po4a.alioth.debian.org/[po4a] 0.45+ is used to translate
the English AsciiDoc documentation to another language before compilation to a
final output format.

=== Fonts

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 dependencies

You can install all dependencies with the following packages:

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

=== Windows dependencies

==== AsciiDoc on Windows

To install AsciiDoc on windows, get the latest version from
http://sourceforge.net/projects/asciidoc/[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 Windows we must satisfy the PDF generator dependency
ourselves.

Details of how to install dblatex and FOP are included below.

==== po4a on Windows

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.
http://www.activestate.com/activeperl/downloads[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
https://alioth.debian.org/frs/?group_id=30267[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!

==== dblatex on Windows

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!

http://dblatex.sourceforge.net/[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 http://miktex.org/download[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 http://zlatkovic.com/libxml/[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
https://sourceforge.net/projects/dblatex/[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

==== FOP on Windows

NOTE: This is currently the only way of building PDF documents on Windows.

It's possible to use https://xmlgraphics.apache.org/fop/[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

== Contributing

Create pull requests at https://github.com/ciampix/kicad-doc/
20 changes: 0 additions & 20 deletions src/README.adoc
View file

This file was deleted.

105 changes: 105 additions & 0 deletions windows_dependencies.adoc
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,105 @@
Windows Dependencies
====================

== AsciiDoc

To install AsciiDoc on windows, get the latest version from
http://sourceforge.net/projects/asciidoc/[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 Windows we must satisfy the PDF generator dependency
ourselves.

Details of how to install dblatex and FOP are included below.

== po4a

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.
http://www.activestate.com/activeperl/downloads[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
https://alioth.debian.org/frs/?group_id=30267[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!

== dblatex

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!

http://dblatex.sourceforge.net/[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 http://miktex.org/download[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 http://zlatkovic.com/libxml/[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
https://sourceforge.net/projects/dblatex/[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

== FOP

NOTE: This is currently the only way of building PDF documents on Windows.

It's possible to use https://xmlgraphics.apache.org/fop/[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

0 comments on commit 8c61fff

Please sign in to comment.