2. Installation

This chapter explains how to install and configure ecromedos on your system. ecromedos is developed on Debian/GNU Linux, but should run on any system which offers the dependencies listed in section 2.2.

2.1. Obtaining the Latest Version

If you are considering contributing to ecromedos, you may clone the complete source repository from GitHub:

git clone https://github.com/tobijk/ecromedos.git

If you are only interested in installing ecromedos for day-to-day use, you can download the sources in a tarball:

trunk (3.0~beta, recommended): https://github.com/tobijk/ecromedos/archive/master.tar.gz
2.1.0 (very old): https://github.com/tobijk/ecromedos/archive/2.1.0-2.tar.gz

Please note that trunk is currently being prepared for the stable 3.0 release.

2.2. Dependencies

In order to benefit from ecromedos' full feature set, you will need to install the following third-party tools and libraries on your system.

Python 3: A powerful scripting language. Python is available for all popular operating systems and can be obtained from the website of the Python Software Foundation at http://www.python.org. ecromedos requires a recent version of Python 3 to run. Using ecromedos with Python 2 is not officially supported anymore, your mileage may vary.
libxml and libxslt: Two super fast and stable libraries for processing XML, developed by Daniel Veillard for the GNOME project. The project homepage is located at http://www.xmlsoft.org.
lxml: A pythonic binding to libxml and libxslt implementing the Element Tree API with extensions. The project homepage is located at http://lxml.de.
Imagemagick: A set of tools for image manipulation. ecromedos uses Imagemagick for resizing bitmap images and for format conversions. You can download the software from http://www.imagemagick.org.
TeX: If you want to produce PostScript or PDF, you need an installation of the TeX typesetting system. It is recommended that you use a recent version of TeX Live, available from http://www.tug.org/texlive/. Make sure to install language packs for the languages that you are going to write in.
dvipng: A utility to convert DVI files to PNG or GIF bitmaps. ecromedos uses dvipng to convert mathematical formulas to bitmap graphics when generating XHTML output. dvipng is available from http://www.nongnu.org/dvipng/, it may also be included in your TeX distribution.
Pygments: Pygments is a powerful syntax highlighter that can lex a vast amount of programming languages and scripts. ecromedos uses Pygments for automatic syntax highlighting of code samples. Find out more about Pygments at http://pygments.org.

2.3. Step-by-step Installation

Step 1: Installing Dependencies:

Double check that you have installed all the dependencies listed in section 2.2. If you are working on Debian/GNU Linux, you can install all dependencies using APT from the command line as root:

apt-get install python3 python3-lxml dvipng imagemagick python3-pygments \
    texlive texlive-latex-extra texlive-lang-english texlive-lang-german \
    texlive-fonts-extra texlive-xetex

Step 2: Unpacking the Tarball

ecromedos can be installed anywhere in the file system. It is recommended, however, that you place it in /opt. In order to do so, open a shell and become superuser root by typing

su -

Then change your working directory to /opt

cd /opt

and unpack the tarball. The following example assumes that the tarball resides in the home directory of user tobias:

tar -xvzf ~tobias/ecromedos-x.y.z.tar.gz

Step 3: Adding the Executable to the System Path

Now change to /usr/local/bin and create a symbolic link to the main executable:

cd /usr/local/bin
ln -s /opt/ecromedos-x.y.z/bin/ecromedos

By placing this link in the system path, you will be able to call ecromedos by name without having to enter the canonical path to the executable.

Step 4: Pre-compiling the Source Files

Since you would typically install ecromedos in a location to which unprivileged users don't have write access, you should pre-compile the Python source files to bytecode, so that users can benefit from faster start-up times. In order to do so, go into the installation directory and issue the following command:

find . -name "*.py" -exec \
    python -c "import py_compile; py_compile.compile('{}')" \;

Step 5: Adapting the Configuration

Having completed the installation procedure described above, you may now want to edit the configuration file ecmds.conf, which is located in the etc subdirectory below the installation folder. ecromedos is designed to be relocatable, so in many cases it should just work out of the box. However, ecromedos interfaces with a number of third-party programs whose installation paths may differ between platforms. Pay particular attention to all configuration parameter names ending in _bin or _dir.

Parameter values can be reused in arguments to other settings by prefixing the name of the parameter to be referenced with a dollar sign. For instance, if base_dir is set to

/opt/ecromedos-x.y.z/

then you can set lib_dir to

/opt/ecromedos-x.y.z/lib

by simply writing

lib_dir = $base_dir/lib

ecromedos version 2 introduced the automatic variable $install_dir, which is always available and contains the path to the installation directory.