Merge pull request #856 from alerque/document-installation

README.md

@@ -27,7 +27,7 @@ First, have a look at the [usage examples gallery][examples]. SILE allows you to
 
 ### For macOS
 
-A formula is available for [Homebrew][brew] that can install both stable and head versions. Just run `brew install sile` for the latest stable release or `brew install sile --HEAD` to build from the latest git commit.
+A formula is available for [Homebrew][brew] that can install either stable or head versions. Just run `brew install sile` for the latest stable release or `brew install sile --HEAD` to build from the latest git commit.
 
 Note the Homebrew package does not automatically install the [default font](#default-font). The easiest way to install Gentium Plus is through the [Homebrew Fonts caskroom][brewfonts]:
 
@@ -38,7 +38,7 @@ Note the Homebrew package does not automatically install the [default font](#def
 
 #### Arch Linux
 
-Arch Linux packages are available in the [AUR][aur] that can be installed using your prefered package manager (e.g. `yay -S sile`). Use [sile][aur-rel] for the latest stable release or [sile-git][aur-dev] to build from the latest git commit.
+Arch Linux packages are available in the [AUR][aur] that can be built manually or with an AUR helper (e.g. `yay -S sile`). Use [sile][aur-rel] for the latest stable release or [sile-git][aur-dev] to build from the latest git commit. Pre-built packages that may be directly installed with `pacman -S sile` are available in [@alerque’s package repository][alerque-arch].
 
 #### Ubuntu
 
@@ -93,7 +93,7 @@ One notable issue with using SILE from a Docker contaner is that it will not hav
 
 SILE source code can be downloaded from [its website][sile] or directly from [the Github releases page][releases].
 
-SILE is written in the Lua programming language, so you will need a working Lua installation on your system (Lua 5.1, 5.2, and 5.3 are fully supported. Lua 5.4, LuaJIT, and Lua Resty should work, but are not currently tested). It also relies on external libraries to access fonts and write PDF files. Its preferred combination of libraries is [Harfbuzz][harfbuzz] and [libtexpdf][], a PDF creation library extracted from TeX. Harfbuzz (minimum version 1.1.3) should be available from your operating system's package manager. For Harfbuzz to work you will also need fontconfig installed. SILE also requires the [ICU][icu] libraries for Unicode handling.
+SILE is written in the Lua programming language, so you will need a working Lua installation on your system (Lua 5.1, 5.2, and 5.3 are fully supported. Lua 5.4, LuaJIT, and Lua Resty should work, but are not currently tested).  It also relies on external libraries to access fonts and write PDF files. Its preferred combination of libraries is [Harfbuzz][harfbuzz] and [libtexpdf][], a PDF creation library extracted from TeX. Harfbuzz (minimum version 1.1.3) should be available from your operating system's package manager. For Harfbuzz to work you will also need fontconfig installed. SILE also requires the [ICU][icu] libraries for Unicode handling.
 
 On macOS, ICU can be installed via Homebrew:
 
@@ -104,7 +104,7 @@ After that, you might need to set environment variables. If you try to `brew lin
     For pkg-config to find icu4c you may need to set:
       export PKG_CONFIG_PATH="/usr/local/opt/icu4c/lib/pkgconfig"
 
-Optionally you may install the Lua libraries listed in the [rockspec][] to your system (using either your system's package manage or [luarocks][] (`luarocks install sile-dev-1.rockspec`). By default all the required Lua libraries will be downloaded and bundled alongside the SILE the instalation. If you downloaded a source tarball these dependencies are included, if you are using a git clone of the source repository the build system will require `luarocks` to fetch them during build. Note that *openssl-devel* will be required for one of the Lua modules to compile¹. If your system has all the required packages already you may add `--with-system-luarocks` to the `./configure` command to avoid bundling them.
+Optionally you may install the Lua libraries listed in the [rockspec][] to your system (using either your system's package manager or [luarocks][] (`luarocks install sile-dev-1.rockspec`). By default all the required Lua libraries will be downloaded and bundled alongside the SILE the instalation. If you downloaded a source tarball these dependencies are included, if you are using a git clone of the source repository the build system will require `luarocks` to fetch them during build. Note that OpenSSL development headers will be required for one of the Lua modules to compile¹. If your system has all the required packages already you may add `--with-system-luarocks` to the `./configure` command to avoid bundling them.
 
 ¹ <sub>OpenSSL development headers are required to build *luasec*, please make sure they are setup _BEFORE_ trying to build SILE! If you use your system's Luarocks packages this will be done for you, otherwise make sure you can compile luasec. You can try just this step in isolation before building SILE using `luarocks --tree=/tmp install luasec`.</sub>
 
@@ -127,7 +127,7 @@ On some systems you may also need to run:
 
 ### Default Font
 
-Since SILE v0.9.5, the default font has been Gentium Plus freely available from [SIL's site][gentium]. It is not required that you install it, but if this font is not installed on your system, you won't be able to use the examples without modification. (Previously we used Gentium Basic, but that's getting harder to get hold of.)
+Since SILE v0.9.5, the default font has been Gentium Plus which is freely available from [SIL’s site][gentium]. It is not required that you install it, but if this font is not installed on your system, you won't be able to use the examples without modification. (Previously we used Gentium Basic, but that's getting harder to get hold of.)
 
 ### Testing
 
@@ -181,3 +181,4 @@ SILE is distributed under the [MIT licence][license].
   [nix]: https://nixos.org/nix
   [ports]: http://ports.su/print/sile
   [ppa]: https://launchpad.net/~sile-typesetter/+archive/ubuntu/sile
+  [alerque-arch]: https://wiki.archlinux.org/index.php/Unofficial_user_repositories#alerque

documentation/sile.sil

@@ -244,28 +244,41 @@ Downloads of SILE can be obtained from the home page at \silehp.
 
 \subsection{Installing Preconfigured Packages}
 
-For OS X machines the recommended way to install SILE is through the Homebrew
-package manager. Once you have Homebrew running (see \url{http://brew.sh}),
-installing SILE is as easy as running:
+For macOS the recommended way to install SILE is through the Homebrew package
+manager. Once you have Homebrew running (see \url{http://brew.sh}), installing
+SILE is as easy as running:
 
 \terminal{$ brew install sile}
 
 If you have not used Lua programs before, that will prompt you to manually
 install a couple dependencies. After running the commands it provides you can
 run the install command again to complete the installation.
 
-The formula also has instruction that can compile SILE from the current
-Git HEAD version. To test the latest unreleased code you can install using:
+The formula also has an option that can compile SILE from the current Git HEAD
+version. To test the latest unreleased code you can install using:
 
 \terminal{$ brew install sile --HEAD}
 
-For Linux users, preconfigured package build files are available for Arch
-Linux. The \code{sile} package has the latest stable release while the
-\code{sile-git} package will build a package using the latest unreleased code
-from the Git repository. If you use a package manager with AUR support you can
-install either one as you would any other package:
+For Linux users, preconfigured package build files are available for
+somedistributions.
 
-\terminal{$ yay -S sile}
+On Arch Linux the \code{sile} package in the AUR has the latest stable release
+while \code{sile-git} will build a package using the latest unreleased code
+from the Git repository. These may be built and installed like any other AUR
+package. Precompiled versions of these packages and all the dependencies are
+available in an unofficial repository
+\footnote{\url{https://wiki.archlinux.org/index.php/Unofficial_user_repositories#alerque}}
+that can be instaled using pacman:
+
+\terminal{$ pacman -S sile}
+
+For Ubuntu an official PPA is available with precompiled packages:
+
+\begin{terminal}
+sudo add-apt-repository ppa:sile-typesetter/sile
+sudo apt-get update
+sudo apt-get install sile
+\end{terminal}
 
 For all other systems you will need to follow the steps to download and compile
 the source yourself.
@@ -275,39 +288,63 @@ the source yourself.
 SILE requires a number of other software packages to be installed on the
 computer before it can work—the Lua programming language, and the Harfbuzz text
 shaping library. SILE provides its own PDF creation library, which has its own
-requirements: \code{freetype}, \code{fontconfig}, \code{libz} and
+requirements: \code{freetype}, \code{fontconfig}, \code{zlib} and
 \code{libpng}.
 
-It is suggested you use your distro's package manager to install as many of the
+It is suggested you use your distro’s package manager to install as many of the
 dependencies as possible. On DEB-based Linux machines such as Debian and
 Ubuntu, you should be able to install all of the needed dependencies by
 issuing the command:
 
-\terminal{$ apt-get install lua5.2 liblua5.2-dev lua-zlib lua-filesystem lua-expat
-lua-lpeg lua-socket lua-sec libharfbuzz-dev libfreetype6-dev
-libfontconfig1-dev libpng-dev libicu-dev}
+\terminal{$ apt-get install lua5.2 liblua5.2-dev lua-sec libharfbuzz-dev
+libfreetype6-dev libfontconfig1-dev libpng-dev libicu-dev}
 
 Here’s an incantation that will work on most Redhat-based Linux distros:
 
 \terminal{$ yum install harfbuzz-devel make automake libtool gcc
-freetype-devel fontconfig-devel lua-devel lua-lpeg lua-expat libpng-devel
-libicu-devel}
+freetype-devel fontconfig-devel lua-devel lua-sec libng-gevel libicu-devel}
 
 If you are on another system you will have to come up with the correct equivalent
-packages yourself. If your system does not have the Lua libraries available as
-packages, you may install them from luarocks:
+packages yourself.
+
+There are a large number of lua dependencies required to run SILE. You may
+either install them to your system using your system’s package manager or
+\code{luarocks}, or let the SILE build process fetch and bundle them for you
+(this is the default unlessy you specify otherwise). You cannot mix and match
+these two methods, either the system path has to have all the dependencies or
+all of them will be bundled with SILE.
+
+If you choose to the Lua rock dependencies to your system you may use any
+combination of your system’s packages and installing them via \code{luarocks
+install}. The list of dependencies is the easiest way is to let Luarocks
+figure it out based on the included Rockspec:
+
+\terminal{$ luarocks install sile-dev-1.rockspec}
 
-\terminal{$ luarocks install lpeg luaexpat lua-zlib luafilesystem luasocket
-$ luarocks install luasec OPENSSL_DIR=...}
+Note that the \code{luasec} package requires OpenSSL libraries on your system
+in order to compile. On some systems such as macOS you may need to configure
+the location of the header files manually it install it:
+
+\terminal{$ luarocks install luasec OPENSSL_DIR=...}
 
 Once you have these requirements in place, you should then be able to unpack
 the file that you downloaded from SILE’s home page, change to that directory
 \footnote{If you downloaded a copy of the SILE source by cloning the git
 repository rather than dowloading one of the release packages you will also
 need to run \code{./bootstrap.sh} to setup the configure script at this point
-before continuing to the next step.}, and run:
+before continuing to the next step.}, and configure the build envirenment.
+
+If you supplied all the Lua dependencies yourself, run:
+
+\terminal{$ ./configure --with-system-luarocks}
+
+Otherwise to go with default of bundling them, just run:
+
+\terminal{$ ./configure}
+
+If that comand was successfull, you can build SILE itself:
 
-\terminal{$ ./configure; make}
+\terminal{$ make}
 
 You can now run SILE as is, uninstalled: