Move "Contributing" to top, merge with src/README, split windows-dependencies
Esse commit está contido em:
Martin d'Allens
+38
-150
@@ -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/"]
|
||||
@@ -10,19 +10,46 @@ 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
|
||||
|
||||
Having installed the dependencies, the following commands will build the PDF and HTML versions of the documentation.
|
||||
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.
|
||||
|
||||
== 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
|
||||
@@ -30,9 +57,14 @@ Having installed the dependencies, the following commands will build the PDF and
|
||||
cmake ../
|
||||
make
|
||||
|
||||
=== Docker
|
||||
=== Debian / Ubuntu
|
||||
|
||||
Read utils/docker/README.adoc if you want to build the documentation in a container.
|
||||
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-*
|
||||
|
||||
=== Docker
|
||||
Read link:utils/docker/README.adoc[] if you want to build the documentation in a container.
|
||||
|
||||
=== CMake Build Options
|
||||
|
||||
@@ -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/
|
||||
|
||||
@@ -1,20 +0,0 @@
|
||||
README
|
||||
======
|
||||
|
||||
This is the multiformat, multilanguage KiCad documentation effort.
|
||||
In order to be able to produce/update the content of this archive,
|
||||
you need to install:
|
||||
|
||||
* asciidoc >= 8.6.9
|
||||
* po4a >= 0.45
|
||||
* dblatex >= 0.3.4
|
||||
* gettext >= 0.18
|
||||
* source-highlight
|
||||
|
||||
To participate to the translation effort it is also recomended:
|
||||
|
||||
1) a good po editor like: poedit, lokalize, virtall, emacs or vi;
|
||||
|
||||
2) the DVC tool git.
|
||||
|
||||
Happy documentation effort!
|
||||
@@ -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
|
||||
Referência em uma Nova Issue
Bloquear um usuário