From 8c61fff54207169e9fea108b7660616cab3b3e23 Mon Sep 17 00:00:00 2001 From: Martin d'Allens Date: Tue, 21 Jul 2015 21:33:28 +0200 Subject: [PATCH] Move "Contributing" to top, merge with src/README, split windows-dependencies --- README.adoc | 188 ++++++++------------------------------ src/README.adoc | 20 ---- windows_dependencies.adoc | 105 +++++++++++++++++++++ 3 files changed, 143 insertions(+), 170 deletions(-) delete mode 100644 src/README.adoc create mode 100644 windows_dependencies.adoc diff --git a/README.adoc b/README.adoc index bb7f7128..8a1a0a09 100644 --- a/README.adoc +++ b/README.adoc @@ -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 + +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 @@ -30,9 +57,14 @@ Having installed the dependencies, the following commands will build the PDF and 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 @@ -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/ diff --git a/src/README.adoc b/src/README.adoc deleted file mode 100644 index 5c6522b2..00000000 --- a/src/README.adoc +++ /dev/null @@ -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! diff --git a/windows_dependencies.adoc b/windows_dependencies.adoc new file mode 100644 index 00000000..44ad029d --- /dev/null +++ b/windows_dependencies.adoc @@ -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