Chapter 1
Installation & Configuration


1.1 Requirements

We have tested the system on Mac OS X and Linux. It is designed to run on Unix platforms. Windows is not supported although it may run with a Unix-like shell under Windows.

Further requirements for running LTC are as follows.

Java
1.6 or above. The Java Runtime Environment (JRE) should suffice.
Version Control System
One of the version control systems below:
git
1.7.2 or above.
svn
1.6.3 or above.
Emacs
23 or above. Only if the user wants to use ltc-mode in Emacs to interact with LTC. XEmacs is not supported.

1.2 Installation and Update

Currently, we provide a shell script ltc-install.sh to perform LTC installation and updates. It can be downloaded from http://sourceforge.net/projects/latextrack/files/. Use it to install the LTC JAR file in a location of your choice. Also, if you use the Emacs ltc-mode, be prepared to supply the location where to put the Emacs Lisp files (see more details below in Section 1.3.3).

In the future, we may provide installers for the target platforms.

Let us assume for the remainder of this manual, that you have used a directory called $LTC as the installation location. Then, you would install LTC using the script in the following way. Note that you will need a second argument to install LTC for Emacs. In this case, you can jump to Section 1.3.3 below for details on the installation of LTC.

  $> bash ltc-install.sh -h
  [... prints help message about using LTC install script]
  $> bash ltc-install.sh $LTC
  [...]
  Done with installing LTC in $LTC
  To start LTC server with default options, use the following command:
  
    java -jar $LTC/LTC.jar
  

To update from an earlier LTC version, run the ltc-install.sh script again with the same argument(s). The script will download the latest version from the web site and configure the link in $LTC/LTC.jar so that future invocations will resolve to the newest version.

After installing LTC, you can look at the command line options of LTC Server using the switch -h or omit the switch to start LTC Server with default values.

  $> java -jar $LTC/LTC.jar -h
  [... prints help message about using LTC Server]

1.3 Configuration

This section contains details of configuring git or svn, LTC and Emacs to work together. These steps typically only need to be carried out once per installation of LTC.

Note that the system decides automatically whether your LaTeX file is under git or svn version control.

1.3.1 General Git Configuration

If you are already using git for other things, you may skip the following few steps as your git is probably already configured. However, we do recommend to add the common LaTeX build products with wildcards to the list of ignored files as outlined at the end of this section, which may not be configured if git has not been used to manage repositories with LaTeX files.

You may want to check the version of your git installation:

  $> git --version
  git version 1.7.2

If you haven’t done already, configure git with your name and email address:

  $> git config --global user.name "John Doe"
  $> git config --global user.email doe@inter.net

Typically, you don’t want to track automatic backups and build products of your LaTeX project, so create a file ~/.gitignore_global (or any name and location of your choice) and add the following lines as contents.

  *~
  *.out
  *.aux
  *.bbl
  *.blg
  *.bst
  *.dvi
  *.idx
  *.lof
  *.log
  *.toc
  *.lol
  *.lot

Then, issue the git config command below (with a possibly adjusted file name and location).

  $> git config --global core.excludesfile ~/.gitignore_global

To learn how to set up a new writing project under a git repository for using it with LTC refer to Section 3.1.

1.3.2 General Subversion Configuration

If you are already using svn for other things, you may skip the following steps. However, we do recommend to add the common LaTeX build products with wildcards to the list of ignored files as outlined below, which may not be configured if svn has not been used to manage repositories with LaTeX files.

You may want to check the version of your subversion installation:

  $> svn --version
  svn, version 1.6.18 (r1303927)
     compiled Aug  4 2012, 19:46:53
  
  ...

Subversion uses only your Unix user name but not your email address to attribute changes. Hence, we do not need to configure these.

Typically, you don’t want to track build products of your LaTeX project, so you may want to edit your file ~/.subversion/config to change the line with globale-ignores in your favorite text editor. You will want to add these patterns to the existing line:

  global-ignores = <current values> \
    *.out *.aux *.bbl *.blg *.bst *.dvi *.idx *.lof *.log *.toc *.lol *.lot

To learn how to set up a new writing project under a subversion repository for using it with LTC refer to Section 3.2.

1.3.3 Emacs ltc-mode

To use the supplied ltc-mode in Emacs, you will have to put the relevant mode files into a directory where Emacs can load them. There are two alternatives of letting Emacs know where to find Emacs Lisp files:

  1. Use a location that is already included in the load-path. To view the contents of this path in your Emacs, execute the command C-h v load-path. On Mac OS X systems with Aquamacs, this could be for example ~/Library/Preferences/Emacs/.
  2. Add a new directory where you will extract the Emacs Lisp files to the load-path. Assuming the Emacs Lisp files will be installed in directory ~/.emacs.d/, add the following line to your .emacs or other Emacs configuration file:
      (add-to-list ’load-path "~/.emacs.d")

Now based on which method of the above you choose, supply the chosen directory as $EMACS_DIR in the second argument to the install script:

  $> bash ltc-install.sh $LTC $EMACS_DIR

In order to enable the LTC mode in Emacs, add the following line to your Emacs configuration file (for example, ~/Library/Preferences/Emacs/Preferences.el is the default for Aquamacs under Mac OS X; ~/.emacs is the default on Unix systems):

  (autoload ’ltc-mode "ltc-mode" "" t)

We recommend to avoid loading LTC automatically when opening .tex files. Therefore, do not add a hook from latex-mode to ltc-mode (usually done with add-hook). The reason is that our mode requires the latex-mode to be fully executed before LTC works. The hooks are not guaranteed to be executed in particular order, so it is best to manually invoke ltc-mode after you have opened a .tex file.


figures/emacs-port.png

Figure 1.1: Using M-x customize-variable <RET> ltc-port <RET> to set LTC port number in Emacs


If you need to change the port number that Emacs uses to communicate with the LTC Server (for example, if the default number is already in use on your computer), you first have to load LTC mode at least once using command M-x ltc-mode, possibly with a failure as the server is not running or not using the default port. Then, you can view the current port setting using C-h v ltc-port <RET>. You can customize the port number using M-x customize-variable <RET> ltc-port <RET> or open the customization buffer and browse to the LTC group under the Tex group, which may be located under the Wp (word processing) top-level group. See Figure 1.1 for a screenshot when customizing the port number in Aquamacs under Mac OS X.

1.4 Troubleshooting

We are keeping a list of frequently-asked-questions at the project’s web site \baseurl that may help for troubleshooting.