Back

Note: This is an automatically generated HTML conversion of a LaTeX file, provided for convenience. The authoritative version is the PDF version.

August 12, 2015

## Acknowledgements and Disclaimer

This project would not exist without Peter Karp, who had the original idea to bring track changes to the LaTeX world. My colleagues Grit Denker and Tomer Altman have also been involved in furthering this project. Recently, Skip Breidbach has joined the development effort. Finally, we thank everyone who tested the prototype and gave us feedback and SRI International to provide the funding to pursue this project.

Please note that LaTeX Track Changes (LTC) is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version. This program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License for more details.

Contents

## Chapter 1Installation & 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

$> 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

...

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:

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):

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.

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.

## Chapter 2Tutorials

This chapter contains a number of tutorials adjusted to the user’s preference of text editor and version control system. The following diagram allows to easily identify the best fit for your situation and names the specific tutorial sections. Whether you are using git or svn as a version control system, you will want to visit the respective section to setup your example repository first (Sec. 2.1 or Sec. 2.4). Then move on to the respective section for the editor you will be using, Emacs or the bundled Java application LTC Editor (sections 2.2, 2.3, 2.5, or 2.6).

### 2.1 Creating the Example Git Repository

The git-based tutorials use two example git repositories called “independence.bundle” and “independence-sherman.bundle,” which can be downloaded from http://sourceforge.net/projects/latextrack/files/examples/. First, save the bundled repositories into a directory of your choice. We call this directory $TUTORIAL. Then, clone from the first bundle to obtain a valid git working tree.$> cd $TUTORIAL/$> git clone independence.bundle independence
Cloning into ’independence’...
Receiving objects: 100% (18/18), done.
Resolving deltas: 100% (4/4), done.
$> cd independence/$> git status
# On branch master
nothing to commit (working directory clean)
$> git log --oneline d3f904c sixth version 203e0ce fifth version 36eeab0 fourth version fa2be39 third version bac2f51 second version d6d1cf8 first version Now we impersonate John Adams to work on this writing project for the Declaration of Independence.$> git config --add user.name "John Adams"
$> git config --add user.email "adams@usa.gov"$> git config --list | grep -e "[Aa]dams"

Another way to investigate the current git repository are graphical tools such as gitk (comes with git distribution) or GitX under Mac OS X. Note that GitX is not required to run LTC. Figure 2.1 for using GitX on the just created repository.

The other point to note here is the way that GitX displays the changes in the file independence.tex when using the graphical git interface. It shows the lines in the file that have changed (much like a standard Unix diff would) – however, when looking at changes in LaTeX source code, the granularity of the line-based difference is much too coarse. An author would most likely only care about the change in words of line 15 or even characters such as removing the mistaken ‘d’ in the word “Roger” in line seven.

#### 2.1.1 Collaborating

Collaboration on your writing project mainly happens through git so we show how to setup an example here. Your actual setup for writing projects may differ. Whatever the configuration, it will probably show up under the list of registered remotes for your repository. In our example, we cloned from the downloaded .bundle file, so looking at the remotes will look like this:

$> git remote -v origin$TUTORIAL/independence.bundle (fetch)
origin $TUTORIAL/independence.bundle (push) As an example of interacting with another repository, let us create a second one on our local file system. In practice, the remote repository will most likely be on a different computer and accessed via certain network protocols reflected in the address. Feel free to adjust the file locations in the example below to your taste.$> cd $TUTORIAL/$> git clone independence-sherman.bundle independence-sherman
Cloning into ’independence-sherman’...
Receiving objects: 100% (24/24), done.
Resolving deltas: 100% (6/6), done.
$> cd independence-sherman/$> git log --oneline
39cd617 todo item for indictment
45710ff more text for preamble
d3f904c sixth version
203e0ce fifth version
36eeab0 fourth version
fa2be39 third version
bac2f51 second version
d6d1cf8 first version

Now we impersonate Roger Sherman in the newly created repository above, and also check the setting for its remotes.

$> git config --add user.name "Roger Sherman"$> git config --add user.email "sherman@usa.gov"
$> git config --list | grep -e "[Ss]herman" remote.origin.url=$TUTORIAL/independence-sherman.bundle
user.name=Roger Sherman
user.email=sherman@usa.gov
$> git remote -v origin$TUTORIAL/independence-sherman.bundle (fetch)
origin $TUTORIAL/independence-sherman.bundle (push) Next, we make the first repository aware of the second and vice versa. At the same time, we may want to remove the reference to the original bundle so as to not get confused with which repository to synchronize. So in both repositories do$> git remote remove origin  # this is optional!

Then, we go into the first one and add a new remote location there:

$> cd$TUTORIAL/independence/
$> git remote add sherman$TUTORIAL/independence-sherman
$> git remote -v sherman$TUTORIAL/independence-sherman (fetch)
sherman $TUTORIAL/independence-sherman (push) Afterwards, we go into the second one and add a new remote location there:$> cd $TUTORIAL/independence-sherman/$> git remote add adams $TUTORIAL/independence$> git remote -v
adams $TUTORIAL/independence (fetch) adams$TUTORIAL/independence (push)

Now you can pull from each directory what the other person has done. Notice that you cannot push changes to the other directory, as these git repositories are not “bare.” This means, they contain working copies and thus cannot be altered remotely. However, in most situations you may be using a central repository (such as GitHub or a server) that indeed contains a bare repository. Then, you are typically able to pull and push changes with such a remote repository while your coauthors can do the same to synchronize your work.

We will see examples below in Sections 2.2.7 and 2.3.7 how John Adams and Roger Sherman synchronize changes with each other.

### 2.2 Tutorial with Git and Emacs

In this section, we assume that the example git repository has been created according to the instructions in Section 2.1 above. And we assume that LTC has been installed using the Emacs directory, as well as Emacs configuration adjustments made that are mentioned in Section 1.3.3.

#### 2.2.1 Starting LTC Server and ltc-mode

First, we start the LTC Server from the command line. Assuming you have installed LTC in the directory $LTC, we run this command line for the server. The output will be similar to the following. Leave the server running while performing the rest of this tutorial.$> java -jar $LTC/LTC.jar LaTeX Track Changes (LTC) Copyright (C) 2009-2013 SRI International This program comes with ABSOLUTELY NO WARRANTY; for details use command line switch -c. This is free software, and you are welcome to redistribute it under certain conditions. <current date> | CONFIG: Logging configured to level CONFIG <current date> | CONFIG: LTC version: <version info> <current date> | INFO: Started RPC server on port 7777. Next, we switch to Emacs and open the tutorial file$TUTORIAL/independence/independence.tex. This should put Emacs into latex-mode but any other mode should work as well. Then, start LTC mode using the command M-x ltc-mode in Emacs. You will see a few messages appearing briefly in the mini buffer (you can also look at them in the *Messages* buffer), such as the following.

Starting LTC mode for file "\$TUTORIAL/independence/independence.tex"... Using ‘xml-rpc’ package version: 1.6.8.2 LTC session ID = 1 Starting LTC update... LTC updates received Emacs should now look similar to the screen shot in Figure 2.2. In this figure, we see the changes marked up in various colors and fonts: underlined for additions and inverse for deletions. There is also a smaller buffer called “LTC info (session N)” with N as the session ID, at the bottom (or the right, if your Emacs is in landscape mode) of the buffer with the tutorial file. There, we display the history of the current file under git. We can also see what git currently perceives as the current user at the top of the graph – now John Adams because we had overridden the git settings in this tutorial repository. #### 2.2.2 Showing and Hiding Certain Changes The LTC menu and “LTC info” buffer in Emacs allow us to customize the way LTC displays the changes of the file. Section 3.3 contains all the details of how LTC displays the changes including limiting the file history and filtering. In this tutorial, we will just use some of the options and see their effect. First, notice the colors assigned to each of the authors. To change an author color, for example Roger Sherman’s, perform a single left-click on the name of Roger Sherman. This opens another buffer called *Colors* with a preview of colors and their names. Also look at the mini buffer that requests input. You can enter a name or an RGB value in hex notation. The color names can also be auto-completed, for example type Bro<TAB> (if TAB is your completion key in Emacs) to see Brown. You will want something with contrast to the white background, so brown is a fine choice. When clicking the RETURN key, notice how the text in the editor panel on the top changes color for those parts that are attributed to Roger Sherman’s edits. To abort choosing a color simply enter an empty value. Next, focus on the typographical errors in the command “\maketitle” in line 11 and the beginning of the first paragraph in line thirteen as well as the spelling errors in the word “political.” Open the LTC menu (in the menu bar and in the mode line) and then the sub-menu “Show/Hide” as seen in Figure 2.3. If you first uncheck the item LTC Show/Hide Show small changes , and second, also the item LTC Show/Hide Show deletions , notice how the text rendering in the editor panel changes. Figures 2.4 show that “\maketitle” as well as the typos in the word “political” are no longer marked up, and in the third image, the deletion beginning with “If” at the beginning of the paragraph is now omitted. #### 2.2.3 Understanding the Commit Graph Now draw your attention back to LTC info buffer with the history of the current file under git (located at the bottom or right of your tracked file). The Emacs representation is using small box characters to draw the graph and its edges. In our current tutorial repository, there are no branches and the graph is a sequential line. Refer to Figure 2.5 for a screen shot of the example file history. Versions that are included in the tracked changes are not printed in gray. How far we go back in history depends on some filtering settings, which are discussed further in Section 2.2.4 below. By default, we first include all version of the current author at the top. In our example with impersonating John Adams, there are currently no further recent commits of him. Then, we continue down the path and collect all versions of different authors until we find the next version of John Adams in the commit with the message “second version.” #### 2.2.4 Limiting History We allow the user to filter and customize how the potentially rich history of a .tex file is selected, so as to provide a better view of the tracked changes. The user can show and hide changes as seen above, limit the authors of interest, and specify a date or revision number to tell LTC how far back in time the history should be considered. To limit the history by authors, choose menu item LTC Limit by Set of authors... . This will prompt the user to enter author names to limit by in the mini buffer. Again, automatic completion works, so you can enter Ro<TAB> <RET> and Th<TAB> <RET> <RET> to select authors Roger Sherman and Thomas Jefferson and exit the dialog. After the last author was selected, the system automatically updates the displayed changes. Notice how any version by the ignored authors Benjamin Franklin and John Adams is now gray as only commits from the selected authors are considered. The first line in the LTC info buffer still shows the currently active author John Adams, so this line is not gray. Again, the history is only taken until the next revision of the current author but since he is being ignored, we go all the way back to the first revision. Compare your Emacs now with the screen shot in Figure 2.6 and see how the file history has changed. To reset limiting by authors, simply choose the same menu LTC Limit by Set of authors... again and enter an empty author as the first one. Now the display is back in the original state. Next, we apply limits on revision and date to control how far back the history of the file is considered. As we had seen, the first version is not taken into account because it was committed before the next commit by the current author John Adams. Let us now choose menu item LTC Limit by Start at revision... . This will prompt the user to specify a known revision number. Type the first few characters d6d<RET> of the SHA-1 key of the first commit. If unique, it is not necessary to expand the revision number using the TAB key (or whatever key is used for completion in your Emacs configuration). See how the first version is listed in color and considered in the tracked changes above as seen in Figure 2.7. Since changes by the current author John Adams from the first to the second version are now included, notice the text marked up in red appearing in the editor window. We see that John Adams must have added himself as an author in the LaTeX preamble among other edits in the second commit of the file. Another way of limiting by revision number is to simply left-click the number in the display. To remove the limit by revision number, simply choose the same menu LTC Limit by Start at revision... again and enter an empty revision. Or, click into the empty revision column of the first line (denoting the currently active author) to achieve the same effect. Now the display is back in the original state. Limiting the history by date works similarly. Select menu item LTC Limit by Start at date... . At the prompt, you can enter a date from the history of the file using auto-completion. For example, enter 2<TAB>11<TAB> <RET> to get the exact date of the third revision. Or, type a date such as Jul 23, 2010 1:11p (should yield the same results if you are in the Central Time Zone) into the field. We employ some software to process times and dates in natural language, and if successful, the field will contain the date string as it was understood translated into the format used in the commit tree. You may also perform a left-click on the date in the history to achieve the same effect. See Figure 2.8 for a screen shot of the effect of limiting to the date of the third revision. To remove the limit by date, either left-click on the empty date column of the first line of the file history or enter an empty date after selecting menu item LTC Limit by Start at date... again. #### 2.2.5 Condensing History Sometimes the list of commits considered is getting long and the resulting markup of the changes confusing. One additional way to customize how the changes are displayed is a setting to “condense authors.” Now check the menu Condense authors Other settings LTC. Then, only the latest version of an author of consecutive commits is considered – in our example, only the sixth version is colored while the fifth version by Roger Sherman is now grayed out as seen in Figure 2.9. See Figure 2.10 for an example of how condensing authors affects the markup. Since we are only considering the changes that Roger Sherman made in the sixth version, his correction of the name is no longer shown. Condensing authors makes sense when users commit versions often so that they do not loose too much history. Their last version after a number of commits generally has the flavor of a “final” version, ready to be shared with others. Hence, the changes made there compared to the last version of another author is commonly of most interest. #### 2.2.6 Editing, Saving, and Committing Let us start the next step by resetting all filters to the default configuration, i.e., no limit by authors, date, and revision. Then, we will edit the text in the top buffer to see the latest changes. Click into the text buffer and enter some text, for example a LaTeX comment reminding John Adams to work on a list of charges against King George III in line nineteen: % list charges against King George III here The added text will be rendered in red (or the color code for the current author) and underlined. Notice how the commit graph displays the label “modified” in the revision column of the first line of the file history. The mode line of Emacs also displays the symbol ** to denote a modified buffer. Now delete some of the characters you have just entered, for example the word here at the end. The characters simply disappear as they were added by the same author. Now delete other characters that are either rendered black or a different color than red but not marked as deletions (inverse color). Notice how these characters remain visible but are now colored red and marked up with inverse colors. If you tried to delete anything that is already marked as deletion (i.e., anything in inverse color), nothing will happen as this text is already deleted in a prior version. See Figure 2.11 for a screen shot of the above edits: text in red and underlined was added and text in inverse red was deleted. Finally, you will want to save the current file to disk. This will cause the label “modified” to change to “on disk” after saving in Emacs, for example with C-x s. If you would then again edit, the label would switch back to “modified” of course. Saving the file, however, does not tell git to create a new version under its management. In order to commit the current file to git, first, make sure that the .tex file is saved under Emacs and the first line of the commit graph does not say “modified.” Then, on a command line, switch to the directory with the tutorial file and perform the following commit command (printed in bold below). You may want to check the status of git before and after the commit:$> git status
# On branch master
# Changes not staged for commit:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
# modified:   independence.tex
#
no changes added to commit (use "git add" and/or "git commit -a")
$> git commit -am "added comment about list of charges" [master 8629257] added comment about list of charges 1 file changed, 3 insertions(+), 1 deletion(-)$> git status
# On branch master
# Your branch is ahead of ’origin/master’ by 1 commit.
#   (use "git push" to publish your local commits)
#
nothing to commit, working directory clean

To make Emacs aware of the underlying commit, use menu item LTC  Update buffer or use the command M-x ltc-update. Notice how the recent commit gets included at the top of the list as seen in Figure 2.12.

#### 2.2.7 Collaborating with Roger Sherman

Next we perform an example collaboration with Roger Sherman’s example repository as setup in Section 2.1.1 above. Remember that Roger Sherman’s repository has had two more commits than the original one we used for John Adams. Since we have made edits and commits as John Adams, both repositories have diverged. To synchronize them, we first pull Roger Sherman’s changes into our working copy after checking that we are in a good state:

$> git pull sherman master remote: Counting objects: 8, done. remote: Compressing objects: 100% (3/3), done. remote: Total 6 (delta 2), reused 5 (delta 1) Unpacking objects: 100% (6/6), done. From$TUTORIAL/independence-sherman
Auto-merging independence.tex
CONFLICT (content): Merge conflict in independence.tex
Automatic merge failed; fix conflicts and then commit the result.

Unfortunately, the two repositories have diverged too much and a so-called “merge conflict” has arisen. Now we have to tell git how to fix this before we can proceed. Next, we look at the markers that git has put into our file. You can run M-x ltc-update in Emacs to see these markers as seen in Figure 2.13. On the command line, the file looks similar to this:

$> cat independence.tex [...] <<<<<<< HEAD % list charges against King George III ======= That to secure these rights, Governments are instituted among Men, [...] %TODO: indictment here >>>>>>> 39cd6172613d1065a4cddc854cf30067869fc727 We decide that the comment in the version HEAD means the same as the last comment in the merged version 39cd617... so we modify the text so that it looks like this:$> cat independence.tex
[...]

That to secure these rights, Governments are instituted among Men, [...]

% list charges against King George III

It is important to remove the git marker lines starting with <<<<<<<, =======, and >>>>>>> for git to recognize that we have resolved the conflicts. Now committing on the command line yields:

$> git commit -am "merging Roger Sherman’s edits" [master 34c1bde] merging Roger Sherman’s edits This has resolved the conflict and incorporated Roger Sherman’s prior changes, as a look at the git log with the graphing function reveals:$> git log --oneline --graph --date-order
*   34c1bde merging Roger Sherman’s edits
|\
| * 39cd617 todo item for indictment
| * 45710ff more text for preamble
|/
* d3f904c sixth version
* 203e0ce fifth version
* 36eeab0 fourth version
* fa2be39 third version
* bac2f51 second version
* d6d1cf8 first version

Once we update Emacs using for example M-x ltc-update, we see the paragraph that was part of the conflicting region now correctly attributed to Roger Sherman. Furthermore, the git commit graph has gotten more interesting with the branching and merging symbolized by parallel vertical lines and empty rows for connecting them at merge points. Refer to Figure 2.14 for a screen shot of the git commit graph and text changes after resolving the conflict, committing and updating Emacs.

One thing to notice in the commit graph with branches is the grayed out row of the commit 8629257 that we had performed just a little while ago as John Adams. When we obtain the history of the file and one commit has more than one ancestor (a merge point), we walk the branch that has the older commit time in order to create a sequential path through the commits. In the future, we want to allow the user to select the branch to use or even overlay parallel branches for better control of the system. You can watch ticket #15 for when we address this problem.

Next we make sure to tell Roger Sherman about our effort to merge changes in the current document. He will want to pull our effort using the following commands.

$> cd$TUTORIAL/independence-sherman
$> git pull adams master remote: Counting objects: 10, done. remote: Compressing objects: 100% (4/4), done. remote: Total 6 (delta 2), reused 0 (delta 0) Unpacking objects: 100% (6/6), done. From ../independence * branch master -> FETCH_HEAD Updating 39cd617..34c1bde Fast-forward independence.tex | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) A look at the git graph on the command line shows that the merge has been applied without conflict.$> git log --oneline --graph --date-order
*   34c1bde merging Roger Sherman’s edits
|\
| * 39cd617 todo item for indictment
| * 45710ff more text for preamble
|/
* d3f904c sixth version
* 203e0ce fifth version
* 36eeab0 fourth version
* fa2be39 third version
* bac2f51 second version
* d6d1cf8 first version

Now both can continue working on their versions but to prevent future merge conflicts it would be wise if they told each other immediately about newer versions and devised a plan to edit the file at different times. In larger writing projects, we recommend to break up the document into smaller .tex files to be included in a master .tex file. Then, editing different files at the same time for multiple authors minimizes the risk of merge conflicts.

### 2.3 Tutorial with Git and LTC Editor

In this section, we assume that the example git repository has been created according to the instructions in Section 2.1 above.

#### 2.3.1 Running the LTC Editor

First, we start the LTC Editor to interact with LTC and track the changes of the file. Assuming you have installed LTC in the directory $LTC, we can look at the command line options of the editor:$> java -cp $LTC/LTC.jar com.sri.ltc.editor.LTCEditor -h LaTeX Track Changes (LTC) Copyright (C) 2009-2013 SRI International This program comes with ABSOLUTELY NO WARRANTY; for details use command line switch -c. This is free software, and you are welcome to redistribute it under certain conditions. usage: java -cp ... com.sri.ltc.editor.LTCEditor [options...] [FILE] with FILE : load given file to track changes -c : display copyright/license information and exit -h : display usage and exit -l LEVEL : set console log level SEVERE, WARNING, INFO, CONFIG (default), FINE, FINER, FINEST -r : reset to default settings To open our tutorial file at$TUTORIAL/independence/independence.tex when starting the editor, execute the following command. This will open the editor as a window similar to the screen shot in Figure 2.15.

$> java -cp$LTC/LTC.jar \
com.sri.ltc.editor.LTCEditor $TUTORIAL/independence/independence.tex In this figure, we see a panel at the bottom-right that resembles the upper part of the GitX graphical interface to git. There, we display the history of the current LaTeX file under git. We can also see what git currently perceives as the current user – now John Adams because we had overridden the git settings in this tutorial repository. #### 2.3.2 Showing and Hiding Certain Changes The bottom-left panels of the editor allows us to customize the way LTC displays the changes of the file. Section 3.3 contains all the details of how LTC displays the changes including limiting the file history and filtering. In this tutorial, we will just use some of the options and see their effect. First, notice the colors assigned to each of the authors. To change an author color, for example Roger Sherman’s, perform a double-click on the colored square next to Roger Sherman in the list of authors to open a dialog and choose a dark color such as brown (you will want something with contrast to the white background). Notice how the text in the editor panel on the top changes color for those parts that are attributed to Roger Sherman’s edits. Next, focus on the typographical errors in the command “\maketitle” in line 11 and the beginning of the first paragraph in line thirteen as well as the spelling errors in the word “political.” If you first uncheck the box for “small” changes and second, also the box for deletions, notice how the text rendering in the editor panel changes. Figures 2.16 show that “\maketitle” as well as the typos in the word “political” are no longer marked up, and in the third image, the deletion beginning with “If” at the beginning of the paragraph is now omitted. #### 2.3.3 Understanding the Commit Graph Now draw your attention back to the graph with the history of the current file under git (located in the bottom-right panel). In our current tutorial repository, this graph is just a line as the authors committed their versions in sequential order. Refer to Figure 2.17 for a screen shot of the example file history. The first line always contains the current author. Then, revisions that are included in the tracked changes are printed in black and denoted with a filled circle. How far we go back in history depends on some filtering settings, which are discussed further in Section 2.3.4 below. By default, we first include all versions of the current author at the top. In our example with impersonating John Adams, there are currently no further recent commits of him. Then, we continue down the path and collect all versions of different authors until we find the next version of John Adams in the commit with the message “second version.” #### 2.3.4 Limiting History We allow the user to filter and customize how the potentially rich history of a .tex file is selected, so as to provide a better view of the tracked changes. The user can show and hide changes as seen above, limit the authors of interest, and specify a date or revision number to tell LTC how far back in time the history should be considered. To limit the history by authors, select both authors Roger Sherman and Thomas Jefferson through clicking while holding down the CTRL or CMD key in the list of authors in the middle lower panel. Then, click the button “Limit” below the list, which will gray out the unselected authors. For a limiting action to take effect, you need to click “Update.” This is different from showing and hiding various changes as well as changing author colors, which is applied instantly. Notice how any version by the ignored authors Benjamin Franklin and John Adams is now gray as only commits from the selected authors are considered. Again, the history is only taken until the next revision of the current author but since he is being ignored, we go all the way back to the first revision. Compare your editor window with the screen shot in Figure 2.19 and see how the commit graph has changed. Then, clicking the “Reset” button followed by “Update” will remove and limits on the history by author, so the original view is restored. Next, we apply limits on revision and date to control how far back the history of the file is considered. As we had seen, the first version is not taken into account because it was committed before the next commit by the current author John Adams. Let us now type the first few characters d6d of the SHA-1 key of the first commit into the field labeled “Start at revision:” (refer to Figure 2.20) or simply drag the key from the entry in the commit graph, which will copy the complete SHA-1 sequence. Now click “Update” and see how the first version is listed in black and considered in the tracked changes above as seen in Figure 2.21. Since changes by the current author John Adams from the first to the second version are now included, notice the text marked up in red appearing in the editor window. We see that John Adams must have added himself as an author in the LaTeX preamble among other edits. To remove the limit by revision number, simply erase the text in the field “Start at revision:” and click “Update” again. Limiting the history by date works similarly. You may drag a date from the commit graph on the right, for example the date of the third version commit, and drop it into the field “Start at date:” on the left. Or, type a date such as Jul 23, 2010 1:11p into the field. We employ some software to process times and dates in natural language, and if successful, the field will contain the date string as it was understood translated into the format used in the commit tree. Again, you will need to click “Update” for the change to take effect or click RETURN while editing the text field. See Figures 2.22 and 2.23 for screenshots. To remove the limit by date, erase all text in the text field and update. #### 2.3.5 Condensing History Sometimes the list of commits considered is getting long and the resulting markup of the changes confusing. One additional way to customize how the changes are displayed is a setting to “condense authors.” Find a check box with that name under the list of authors for filtering. If checked, then only the latest version of an author of consecutive commits is considered – in our example, only the sixth version is shown in black while the fifth version by Roger Sherman is now grayed out as seen in Figure 2.24. See Figure 2.25 for an example of how condensing authors affects the markup. Since we are only considering the changes that Roger Sherman made in the sixth version, his correction of the name is no longer shown. Condensing authors makes sense when users commit versions often so that they do not loose too much history. Their last version after a number of commits generally has the flavor of a “final” version, ready to be shared with others. Hence, the changes made there compared to the last version of another author is commonly of most interest. #### 2.3.6 Editing, Saving, and Committing Let us start the next step by resetting all filters to the default configuration, i.e., no limit by authors, date, and revision. Also make sure to turn “condense authors” off. Then, we will edit the text in the editor panel to see the latest changes. Click into the text panel and enter some text, for example a LaTeX comment reminding John Adams to work on a list of charges against King George III in line nineteen: % list charges against King George III here The added text will be rendered in red (or the color code for the current author) and underlined. Notice how the commit graph adds a first line with the label “modified” and the “Save” button becomes enabled. Now delete some of the characters you have just entered, for example the word here at the end. The characters simply disappear as they were added by the same author. Now delete other characters that are either rendered black or a different color than red but not marked as deletions (strike-through font). Notice how these characters remain visible but are now colored red and marked up with strike-through. If you tried to delete anything that is already marked as deletion (i.e., anything in strike-through font), nothing will happen as this text is already deleted in a prior version. See Figure 2.26 for a screen shot of the above edits: text in red and underlined was added and text in red and strike-through was deleted. Finally, you will want to click “Save” to save the current file to disk. This will cause the label “modified” to change to “on disk.” If you would then again edit, the label would switch back to “modified” of course. Saving the file, however, does not tell git to create a new version under its management. In order to commit the current file to git, first, make sure that the .tex file is saved and the first line in the commit graph is set to “on disk.” Then, on a command line, switch to the directory with the tutorial file and perform the following commit command (printed in bold below). You may want to check the status of git before and after the commit:$> git status
# On branch master
# Changes not staged for commit:
#   (use "git add <file>..." to update what will be committed)
#   (use "git checkout -- <file>..." to discard changes in working directory)
#
# modified:   independence.tex
#
no changes added to commit (use "git add" and/or "git commit -a")
$> git commit -am "added comment about list of charges" [master 9438e4f] added comment about list of charges 1 file changed, 3 insertions(+), 1 deletion(-) To make LTC Editor aware of the underlying commit from the command line, click the “Update” button. Notice how the recent commit gets included at the top of the list as seen in Figure 2.27. Also see that we still include all revisions up to John Adams’ second revision a while ago—all revisions at the top of the graph before any other authors are skipped before looking for the default end point in history. Now two things can happen depending on your setting for showing changes in comments (lower-left most panel). If the checkbox was off, the newly added comment is no longer marked up in red with underlining. After updating the editor from the commit history, the settings of which changes to show influence the markup of the text. Now the newly entered comment is recognized as such, and if we hide changes in comments, the markup will not show. If the box for “changes in comments” is checked, you will see your latest text still marked up as an addition. Your editor should now look similar to the part shown in either Figure 2.28 or Figure 2.29. #### 2.3.7 Collaborating with Roger Sherman Next we perform an example collaboration with Roger Sherman’s example repository as setup in Section 2.1.1 above. Remember that Roger Sherman’s repository has had two more commits than the original one we used for John Adams. Since we have made edits and commits as John Adams, both repositories have diverged. To synchronize them, we first pull Roger Sherman’s changes into our working copy using the git pull command below:$> git pull sherman master
remote: Counting objects: 8, done.
remote: Compressing objects: 100% (3/3), done.
remote: Total 6 (delta 2), reused 5 (delta 1)
Unpacking objects: 100% (6/6), done.
From $TUTORIAL/independence-sherman * branch master -> FETCH_HEAD Auto-merging independence.tex CONFLICT (content): Merge conflict in independence.tex Automatic merge failed; fix conflicts and then commit the result. Unfortunately, the two repositories have diverged too much and a so-called “merge conflict” has arisen. Now we have to tell git how to fix this before we can proceed. So we look at the markers that git has put into our file. You can click the “Update” button in LTC Editor to see these markers there similar to Figure 2.30. On the command line, the file looks similar to this:$ cat independence.tex
[...]

% list charges against King George III
=======
That to secure these rights, Governments are instituted among Men, [...]

%TODO: indictment here
>>>>>>> 39cd6172613d1065a4cddc854cf30067869fc727

We decide that the comments in the HEAD version means the same as the last comment in the merged version 39cd617... so we modify the text so that it looks like this:

$> cat independence.tex [...] That to secure these rights, Governments are instituted among Men, [...] % list charges against King George III It is important to remove the git marker lines starting with <<<<<<<, =======, and >>>>>>> for git to recognize that we have resolved the conflicts. Notice that if you are editing in LTC Editor, all changes are currently marked up in the color of John Adams even though we imported a paragraph from Roger Sherman. This is because we still have not committed the changes to git and the current version on disk is attributed to John Adams. However, we now save and then commit on the command line:$> git commit -am "merging Roger Sherman’s edits"
[master 474d53b] merging Roger Sherman’s edits

This has resolved the conflict and incorporated Roger Sherman’s prior changes, as a look at the git log with the graphing function reveals:

$> git log --oneline --graph --date-order * 474d53b merging Roger Sherman’s edits |\ * | 9438e4f added comment about list of charges | * 39cd617 todo item for indictment | * 45710ff more text for preamble |/ * d3f904c sixth version * 203e0ce fifth version * 36eeab0 fourth version * fa2be39 third version * bac2f51 second version * d6d1cf8 first version Once we update LTC Editor, we see the paragraph that was part of the conflicting region now correctly attributed to Roger Sherman. Furthermore, the git commit graph has gotten more interesting with the branching and merging in the first column of the commit graph. Refer to Figure 2.31 for a screen shot of the git commit graph and text changes after resolving the conflict, committing and updating LTC Editor. ### 2.4 Creating the Example Subversion Repository This tutorial uses an example svn repository, which is either hosted on the Internet or on your local computer. The first Section 2.4.1 shows how to use a publicly accessible repository with an example file. This is the quickest way to try out LTC with Subversion but you cannot commit new versions to this repository so we cannot go through such advanced topics in the later parts of the tutorial. The second Section 2.4.2 shows how to create a local svn server and populates it with an example repository. This takes a bit more time to setup but then you can go through more advanced topics such as committing to the repository. #### 2.4.1 Using the Remote Subversion Repository To create the example file that is under remote svn version control, go into a directory of your choice (say$TUTORIAL) and do the following. If the server causes a certificate alert, you can accept it permanently by using p as shown in bold below.

$> cd$TUTORIAL
$> svn co https://rfs.csl.sri.com/svn/public/LTC/tutorial-svn independence Error validating server certificate for ’https://rfs.csl.sri.com:443’: - The certificate is not issued by a trusted authority. Use the fingerprint to validate the certificate manually! Certificate information: - Hostname: rfs.csl.sri.com - Valid: from Mon, 06 May 2013 00:00:00 GMT until Tue, 06 May 2014 23:59:59 GMT - Issuer: Thawte, Inc., US - Fingerprint: da:09:85:34:fc:19:86:bf:3d:79:3a:8c:f1:90:41:63:57:40:5b:14 (R)eject, accept (t)emporarily or accept (p)ermanently? p A independence/independence.tex Checked out revision 6. Now change into the new directory and confirm that the file has six revisions in its history$> cd independence/
$> svn log -q independence.tex ------------------------------------------------------------------------ r6 | sherman | 2012-11-13 13:01:00 -0600 (Tue, 13 Nov 2012) ------------------------------------------------------------------------ r5 | sherman | 2012-11-13 13:00:35 -0600 (Tue, 13 Nov 2012) ------------------------------------------------------------------------ r4 | jefferson | 2012-11-13 12:59:45 -0600 (Tue, 13 Nov 2012) ------------------------------------------------------------------------ r3 | franklin | 2012-11-13 12:59:03 -0600 (Tue, 13 Nov 2012) ------------------------------------------------------------------------ r2 | adams | 2012-11-13 12:58:04 -0600 (Tue, 13 Nov 2012) ------------------------------------------------------------------------ r1 | jefferson | 2012-11-13 12:51:35 -0600 (Tue, 13 Nov 2012) ------------------------------------------------------------------------ Unfortunately, we cannot accept changes to this repository so the tutorials based on svn do not cover how to commit new revisions and how to collaborate. We advise to install a local svn server and repository per the instructions below or to go through the git-based tutorial to cover those points. #### 2.4.2 Using a Local Subversion Repository The following will show you how to run a local subversion server on your machine. Then, we will create a subversion repository there and add a few users to it, so that you can impersonate different users throughout the later parts of the tutorial below. First, perform the following steps from a directory of your choice. We assume that this is again$TUTORIAL. There, you will create the root location of your tutorial repositories called svnrepos. You may choose another name but will then have to adjust the commands accordingly.

$> cd$TUTORIAL
$> svnadmin create svnrepos Now edit the two files •$TUTORIAL/svnrepos/conf/svnserve.conf
• $TUTORIAL/svnrepos/conf/passwd to contain the following lines:$> grep -v "^#" svnrepos/conf/svnserve.conf | sed ’/^$/d’ [general] anon-access = none auth-access = write password-db = passwd [sasl]$> grep -v "^#" svnrepos/conf/passwd | sed ’/^$/d’ [users] franklin = ltc adams = ltc sherman = ltc jefferson = ltc Finally, start the SVN server in daemon mode using:$> svnserve -d -r svnrepos

Now download the file tutorialsvn.dump from http://sourceforge.net/projects/latextrack/files/examples/ to, say, directory $TUTORIAL and load the repository into your server:$> svnadmin load svnrepos < tutorialsvn.dump
<<< Started new transaction, based on original revision 1
* adding path : tutorial-svn ... done.
* adding path : tutorial-svn/independence.tex ... done.

------- Committed revision 1 >>>

<<< Started new transaction, based on original revision 2
* editing path : tutorial-svn/independence.tex ... done.

------- Committed revision 2 >>>

<<< Started new transaction, based on original revision 3
* editing path : tutorial-svn/independence.tex ... done.

------- Committed revision 3 >>>

<<< Started new transaction, based on original revision 4
* editing path : tutorial-svn/independence.tex ... done.

------- Committed revision 4 >>>

<<< Started new transaction, based on original revision 5
* editing path : tutorial-svn/independence.tex ... done.

------- Committed revision 5 >>>

<<< Started new transaction, based on original revision 6
* editing path : tutorial-svn/independence.tex ... done.

------- Committed revision 6 >>>

Now, we will check out from this repository in a new directory, say independence. If you see a message svn: Can’t connect to host ’localhost’: Connection refused then most like the SVN server process is not running. Restart the server with the svnserve command above.

$> svn co --username adams svn://localhost/tutorial-svn independence A independence/independence.tex Checked out revision 6.$> cd independence
$> svn log -q ------------------------------------------------------------------------ r6 | sherman | 2012-11-13 13:01:00 -0600 (Tue, 13 Nov 2012) ------------------------------------------------------------------------ r5 | sherman | 2012-11-13 13:00:35 -0600 (Tue, 13 Nov 2012) ------------------------------------------------------------------------ r4 | jefferson | 2012-11-13 12:59:45 -0600 (Tue, 13 Nov 2012) ------------------------------------------------------------------------ r3 | franklin | 2012-11-13 12:59:03 -0600 (Tue, 13 Nov 2012) ------------------------------------------------------------------------ r2 | adams | 2012-11-13 12:58:04 -0600 (Tue, 13 Nov 2012) ------------------------------------------------------------------------ r1 | jefferson | 2012-11-13 12:51:35 -0600 (Tue, 13 Nov 2012) ------------------------------------------------------------------------ #### 2.4.3 Collaborating Using the Local Repository Collaboration on your writing project happens through the subversion repository so here we show you how to set up an example with a secondary checkout that Roger Sherman uses. You will need to download an additional file independence-sherman.tex from http://sourceforge.net/projects/latextrack/files/examples/, for example to the directory$TUTORIAL.

Now do the following to create the secondary repository with a new version of the file that is not yet committed.

$> cd$TUTORIAL/
$> svn co --username sherman svn://localhost/tutorial-svn independence-sherman A independence-sherman/independence.tex Checked out revision 6.$> cd independence-sherman/
$> cp ../independence-sherman.tex independence.tex$> svn status
M       independence.tex

#### 2.4.4 Cleaning Up the Local Repository

To clean up when you are done with the tutorial, you should stop the running svn server process by finding out the process ID <PID> as seen below. Then, replace it in the kill command before deleting the files associated with the repository.

$> ps ax | grep svnserve <PID> ?? Ss 0:00.00 svnserve -d -r svnrepos$> kill <PID>
$> rm -rf$TUTORIAL/svnrepos

Finally, you will also want to remove the working copies you had made from the now deleted local repository:

$> rm -rf$TUTORIAL/independence
$> rm -rf$TUTORIAL/independence-sherman

### 2.5 Tutorial with Subversion and Emacs

In this section, we assume that the example svn repository has been created according to the instructions in Section 2.4 above. The latter subsections require a local svn repository but the beginning can be done with either the remote example repository or a local one. And we assume that LTC has been installed using the Emacs directory, as well as Emacs configuration adjustments made that are mentioned in Section 1.3.3.

#### 2.5.1 Starting LTC Server and ltc-mode

First, we start the LTC Server from the command line. Assuming you have installed LTC in the directory $LTC, we run this command line for the server. The output will be similar to the following. Leave the server running while performing the rest of this tutorial.$> java -jar $LTC/LTC.jar LaTeX Track Changes (LTC) Copyright (C) 2009-2013 SRI International This program comes with ABSOLUTELY NO WARRANTY; for details use command line switch -c. This is free software, and you are welcome to redistribute it under certain conditions. <current date> | CONFIG: Logging configured to level CONFIG <current date> | CONFIG: LTC version: <version info> <current date> | INFO: Started RPC server on port 7777. Next, we switch to Emacs and open the tutorial file$TUTORIAL/independence/independence.tex. This should put Emacs into latex-mode but any other mode should work as well. Then, start LTC mode using the command M-x ltc-mode in Emacs. Beware that using LTC with a remote subversion server takes longer than using git or a local subversion server, as we have to query the distant server hosting the repository for each version of the .tex file. You will see a few messages appearing briefly in the mini buffer (you can also look at them in the *Messages* buffer), such as the following. While the potential time intensive task of downloading versions from the remote server happen, the mini buffer should say Starting LTC update..., which turns into LTC updates received when the process is done.

Starting LTC mode for file "$TUTORIAL/independence/independence.tex"... Using ‘xml-rpc’ package version: 1.6.8.2 LTC session ID = 1 Starting LTC update... LTC updates received Emacs should now look similar to the screen shot in Figure 2.32. In this figure, we see the changes marked up in various colors and fonts: underlined for additions and inverse for deletions. There is also a smaller buffer called “LTC info (session N)” with N as the session ID, at the bottom (or the right, if your Emacs is in landscape mode) of the buffer with the tutorial file. There, we display the history of the current file under svn. We can also see what svn perceives as the current user at the top of the graph – here the name of the local user. First, we will override what LTC thinks is the current author in order to make the following tutorial more meaningful. In real life situations you will rarely have to use this command as you typically want the changes in the repository attributed to yourself. In Emacs, type the command M-x ltc-set-self<RET>adams<RET> to impersonate John Adams. This updates the contents in the main buffer and info buffer at the bottom automatically, which may again take a little time with a remote subversion server. The info buffer will then look like the screen shot in Figure 2.33. #### 2.5.2 Showing and Hiding Certain Changes The LTC menu and “LTC info” buffer in Emacs allow us to customize the way LTC displays the changes of the file. Section 3.3 contains all the details of how LTC displays the changes including limiting the file history and filtering. In this tutorial, we will just use some of the options and see their effect. First, notice the colors assigned to each of the authors. To change an author color, for example Roger Sherman’s, perform a single left-click on the name of Roger Sherman. This opens another buffer called *Colors* with a preview of colors and their names. Also look at the mini buffer that requests input. You can enter a name or an RGB value in hex notation. The color names can also be auto-completed, for example type Bro<TAB> (if TAB is your completion key in Emacs) to see Brown. You will want something with contrast to the white background, so brown is a fine choice. When clicking the RETURN key, notice how the text in the editor panel on the top changes color for those parts that are attributed to Roger Sherman’s edits. To abort choosing a color simply enter an empty value. Next, focus on the typographical errors in the command “\maketitle” in line 11 and the beginning of the first paragraph in line thirteen as well as the spelling errors in the word “political.” Open the LTC menu (in the menu bar and in the mode line) and then the sub-menu “Show/Hide” as seen in Figure 2.34. If you first uncheck the item LTC Show/Hide Show small changes , and second, also the item LTC Show/Hide Show deletions , notice how the text rendering in the editor panel changes. Again, if you work with the remote repository, it might take a little while until all the updates are received from the server and the mini buffer shows the message “LTC updates received.” Figures 2.35 show that “\maketitle” as well as the typos in the word “political” are no longer marked up, and in the third image, the deletion beginning with “If” at the beginning of the paragraph is now omitted. #### 2.5.3 Understanding the Commit Graph Now draw your attention back to LTC info buffer with the history of the current file under svn (located at the bottom or right of your .tex file). The Emacs representation is using small box characters to draw the graph and its edges. In our current tutorial repository, there are no branches and the graph is a sequential line. Refer back to Figure 2.33 for the screen shot of the example file history. Versions that are included in the tracked changes are not printed in gray. How far we go back in history depends on some filtering settings, which are discussed further in Section 2.5.4 below. By default, we first include all version of the current author at the top. In our example with impersonating John Adams with the user name “adams,” there are currently no further recent commits of him. Then, we continue down the path and collect all versions of different authors until we find the next version of John Adams in the commit with the message “second version.” #### 2.5.4 Limiting History We allow the user to filter and customize how the potentially rich history of a .tex file is selected, so as to provide a better view of the tracked changes. The user can show and hide changes as seen above, limit the authors of interest, and specify a date or revision number to tell LTC how far back in time the history should be considered. To limit the history by authors, choose menu item LTC Limit by Set of authors... . This will prompt the user to enter author names to limit by in the mini buffer. Again, automatic completion works, so you can enter sh<TAB> <RET> and je<TAB> <RET> <RET> to select authors “sherman” and “jefferson” and exit the dialog. After the last author was selected, the system automatically updates the displayed changes. Notice how any version by the ignored authors “franklin” and “adams” is now gray as only commits from the selected authors are considered. The first line in the LTC info buffer still shows the currently active author “adams,” so this line is not gray. Again, the history is only taken until the next revision of the current author but since he is being ignored, we go all the way back to the first revision. Compare your Emacs now with the screen shot in Figure 2.36 and see how the file history has changed. To reset limiting by authors, simply choose the same menu LTC Limit by Set of authors... again and enter an empty author as the first one. Now the display is back in the original state. Next, we apply limits on revision and date to control how far back the history of the file is considered. As we had seen, the first version is not taken into account because it was committed before the next commit by the current author John Adams. Let us now choose menu item LTC Limit by Start at revision... . This will prompt the user to specify a known revision number. Type 1 as the revision number of the first commit and hit ENTER. See how the first version is now listed in color and considered in the tracked changes above as seen in Figure 2.37. Since changes by the current author John Adams from the first to the second version are now included, notice the text marked up in red appearing in the editor window. We see that John Adams must have added himself as an author in the LaTeX preamble among other edits in the second commit of the file. Another way of limiting by revision number is to simply left-click the number in the display of the commit graph. To remove the limit by revision number, simply choose the same menu LTC Limit by Start at revision... again and enter an empty revision. Or, click into the empty revision column of the first line (denoting the currently active author) to achieve the same effect. Now the display is back in the original state. Limiting the history by date works similarly. Select menu item LTC Limit by Start at date... . At the prompt, you can enter a date from the history of the file using auto-completion. For example, enter 2<TAB>2:59:0<TAB> <RET> to get the exact date of the third revision. Or, type a date such as Nov 13, 2012 12:59p (should yield the same results if you are in the Central Time Zone) into the field. We employ some software to process times and dates in natural language, and if successful, the field will contain the date string as it was understood translated into the format used in the commit tree. You may also perform a left-click on the date in the history to achieve the same effect. See Figure 2.38 for a screen shot of the effect of limiting to the date of the third revision. To remove the limit by date, either left-click on the empty date column of the first line of the file history or enter an empty date after selecting menu item LTC Limit by Start at date... again. #### 2.5.5 Condensing History Sometimes the list of commits considered is getting long and the resulting markup of the changes confusing. One additional way to customize how the changes are displayed is a setting to “condense authors.” Now check the menu LTC Condense authors . Then, only the latest version of an author of consecutive commits is considered – in our example, only the sixth version is colored while the fifth version by Roger Sherman is now grayed out as seen in Figure 2.39. See Figure 2.40 for an example of how condensing authors affects the markup. Since we are only considering the changes that Roger Sherman made in the sixth version, his correction of the name is no longer shown. Condensing authors makes sense when users commit versions often so that they do not loose too much history. Their last version after a number of commits generally has the flavor of a “final” version, ready to be shared with others. Hence, the changes made there compared to the last version of another author is commonly of most interest. #### 2.5.6 Editing and Saving Let us start the next step by resetting all filters to the default configuration, i.e., no limit by authors, date, and revision. Then, we will edit the text in the top buffer to see the latest changes. Click into the text buffer and enter some text, for example a LaTeX comment reminding John Adams to work on a list of charges against King George III in line nineteen: % list charges against King George III here The added text will be rendered in red (or the color code for the current author) and underlined. Notice how the commit graph displays the label “modified” in the revision column of the first line of the file history. The mode line of Emacs also displays the symbol ** to denote a modified buffer. Now delete some of the characters you have just entered, for example the word here at the end. The characters simply disappear as they were added by the same author. Now delete other characters that are either rendered black or a different color than red but not marked as deletions (inverse color). Notice how these characters remain visible but are now colored red and marked up with inverse colors. If you tried to delete anything that is already marked as deletion (i.e., anything in inverse color), nothing will happen as this text is already deleted in a prior version. See Figure 2.41 for a screen shot of the above edits: text in red and underlined was added and text in inverse red was deleted. Finally, you will want to save the current file to disk. This will cause the label “modified” to change to “on disk” after saving in Emacs, for example with C-x s. If you would then again edit, the label would switch back to “modified” of course. #### 2.5.7 Collaborating Through Commits In Subversion, your repository is a central entity that all collaborators commit to. Therefore, unlike distributed version control systems such as git, the collaboration happens when users commit their version. It is a good practice to update your working copy regularly to avoid conflicts during committing. Furthermore, users should communicate with each other to decide who is editing what file at a time. The following assumes that you are working with a local svn repository per the setup in Sections 2.4.2 and sec:svn-collaborating above. Next, we will simulate that Roger Sherman commits his modified version before John Adams can upload his version, resulting in a merge conflict. To prepare this scenario, first commit the modifications from Roger Sherman’s working copy:$> cd $TUTORIAL/independence-sherman/$> svn status
M       independence.tex
$> svn commit -m "todo item for indictment" --username sherman Sending independence.tex Transmitting file data . Committed revision 7. Now the shared repository is already at revision 7 while we (as John Adams) are still editing from revision six. First, check again that you have saved the file in Emacs and that the first entry in the commit graph says “on disk.” When we try to commit our latest changes from the Section 2.5.6 above, using the command line, we get the following error message.$> cd $TUTORIAL/independence/$> svn status
M       independence.tex
$> svn commit -m "added comment about list of charges" --username adams Sending independence.tex Transmitting file data .svn: Commit failed (details follow): svn: File ’/tutorial-svn/independence.tex’ is out of date Then, we try to update our repository first to mend the situation, which results in another error message about the conflicting versions. If Roger Sherman and John Adams had been modifying different .tex files in the same repository, we would have not gotten this conflict. To resolve, we choose to postpone so that we can see the differences in Emacs and resolve it there. Our input is marked in bold below.$> svn update
Conflict discovered in ’independence.tex’.
Select: (p) postpone, (df) diff-full, (e) edit,
(mc) mine-conflict, (tc) theirs-conflict,
(s) show all options: p
C    independence.tex
Updated to revision 7.
Summary of conflicts:
Text conflicts: 1

Our current file is now marked as in conflict, so let us update Emacs using menu item LTC  Update buffer or M-x ltc-update, to see something similar to the screen shot in Figure 2.42. The conflicting portion at the end is marked with additional lines and we see revision 7 in the history of the file. On the command line, the file looks similar to this:

$> cat independence.tex [...] <<<<<<< .mine % list charges against King George III ======= That to secure these rights, Governments are instituted among Men, [...] %TODO: indictment here >>>>>>> .r7 We decide that the comments in the version .mine version means the same as the last comment in version .r7 so we modify the text in Emacs and save, so that it looks like this on the command line:$> cat independence.tex
[...]

That to secure these rights, Governments are instituted among Men, [...]

% list charges against King George III

It is important to remove the svn marker lines starting with <<<<<<<, =======, and >>>>>>> for svn to recognize that we have resolved the conflicts. We also have to tell svn that the conflict has been resolved. Then we can finally perform the following commit command. The two important commands are printed in bold below. You may want to check the status of svn before and after the commit:

$> svn resolved independence.tex Resolved conflicted state of ’independence.tex’$> svn status
M       independence.tex
$> svn commit -m "added comment about list of charges" --username adams Sending independence.tex Transmitting file data . Committed revision 8.$> svn status

Once we update Emacs using for example M-x ltc-update, we see the latest revision 8 in the commit graph and the marked up latest edits attributed to John Adams and Roger Sherman similar to Figure 2.43.

### 2.6 Tutorial with Subversion and LTC Editor

In this section, we assume that the example svn repository has been created according to the instructions in Section 2.4 above. The latter subsections require a local svn repository but the beginning can be done with either the remote example repository or a local one.

#### 2.6.1 Running the LTC Editor

First, we start the LTC Editor to interact with LTC and track the changes of the file. Assuming you have installed LTC in the directory $LTC, we can look at the command line options of the editor:$> java -cp $LTC/LTC.jar com.sri.ltc.editor.LTCEditor -h LaTeX Track Changes (LTC) Copyright (C) 2009-2013 SRI International This program comes with ABSOLUTELY NO WARRANTY; for details use command line switch -c. This is free software, and you are welcome to redistribute it under certain conditions. usage: java -cp ... com.sri.ltc.editor.LTCEditor [options...] [FILE] with FILE : load given file to track changes -c : display copyright/license information and exit -h : display usage and exit -l LEVEL : set console log level SEVERE, WARNING, INFO, CONFIG (default), FINE, FINER, FINEST -r : reset to default settings To open our tutorial file at$TUTORIAL/independence/independence.tex when starting the editor, execute the following command. After the editor opens as a window, we open the combo box under the name for “Self:” by clicking on the small arrow right next to the name and select the author “adams” to impersonate John Adams for the remainder of this tutorial. This will again contact the server to obtain updates about the file history, which may take a little time if you are working with a remote repository. Finally, the window should look similar to the screen shot in Figure 2.44.

$> java -cp$LTC/LTC.jar \
com.sri.ltc.editor.LTCEditor $TUTORIAL/independence/independence.tex In this figure, we see a panel at the bottom-right that displays the history of the current LaTeX file under svn as well as the name of the current user – now John Adams because we had overridden the default, which was your user name. #### 2.6.2 Showing and Hiding Certain Changes The bottom-left panels of the editor allows us to customize the way LTC displays the changes of the file. Section 3.3 contains all the details of how LTC displays the changes including limiting the file history and filtering. In this tutorial, we will just use some of the options and see their effect. First, notice the colors assigned to each of the authors. To change an author color, for example Roger Sherman’s, perform a double-click on the colored square next to “sherman” in the list of authors to open a dialog and choose a dark color such as brown (you will want something with contrast to the white background). Notice, after the updates have come through from the server, how the text in the editor panel on the top changes color for those parts that are attributed to Roger Sherman’s edits. Next, focus on the typographical errors in the command “\maketitle” in line 11 and the beginning of the first paragraph in line thirteen as well as the spelling errors in the word “political.” If you first uncheck the box for “small” changes and second, also the box for deletions, notice how the text rendering in the editor panel changes. Figures 2.45 show that “\maketitle” as well as the typos in the word “political” are no longer marked up, and in the third image, the deletion beginning with “If” at the beginning of the paragraph is now omitted. #### 2.6.3 Understanding the Commit Graph Now draw your attention back to the graph with the history of the current file under svn (located in the bottom-right panel). Refer to Figure 2.46 for a screen shot of the example file history. The first line always contains the current author as set in the text field labeled “Self” above. Then, revisions that are included in the tracked changes are not printed in gray. How far we go back in history depends on some filtering settings, which are discussed further in Section 2.6.4 below. By default, we first include all versions of the current author at the top. In our example with impersonating John Adams with the user name “adams,” there are currently no further recent commits of him. Then, we continue down the path and collect all versions of different authors until we find the next version of John Adams in the commit with the message “second version.” #### 2.6.4 Limiting History We allow the user to filter and customize how the potentially rich history of a .tex file is selected, so as to provide a better view of the tracked changes. The user can show and hide changes as seen above, limit the authors of interest, and specify a date or revision number to tell LTC how far back in time the history should be considered. To limit the history by authors, select both authors “sherman” and “jefferson” through clicking while holding down the CTRL or CMD key in the list of authors in the middle lower panel. Then, click the button “Limit” below the list, which will gray out the unselected authors. For a limiting action to take effect, you need to click “Update.” This is different from showing and hiding various changes as well as changing author colors, which is applied instantly. Notice how any version by the ignored authors Benjamin Franklin and John Adams is now gray as only commits from the selected authors are considered. Again, the history is only taken until the next revision of the current author but since he is being ignored, we go all the way back to the first revision. Compare your editor window with the screen shot in Figure 2.48 and see how the commit graph has changed. Then, clicking the “Reset” button followed by “Update” will remove and limits on the history by author, so the original view is restored. Next, we apply limits on revision and date to control how far back the history of the file is considered. As we had seen, the first version is not taken into account because it was committed before the next commit by the current author John Adams. Let us now type 1 as the revision number of the first commit into the field labeled “Start at revision:” (refer to Figure 2.49) or simply drag the number from the entry in the commit graph into the field. Now click “Update” and see how the first version is listed in black and considered in the tracked changes above as seen in Figure 2.50. Since changes by the current author John Adams from the first to the second version are now included, notice the text marked up in red appearing in the editor window. We see that John Adams must have added himself as an author in the LaTeX preamble among other edits. To remove the limit by revision number, simply erase the text in the field “Start at revision:” and click “Update” again. Limiting the history by date works similarly. You may drag a date from the commit graph on the right, for example the date of the third version commit, and drop it into the field “Start at date:” on the left. Or, type a date such as Nov 13, 2012 12:59p into the field. We employ some software to process times and dates in natural language, and if successful, the field will contain the date string as it was understood translated into the format used in the commit tree. Again, you will need to click “Update” for the change to take effect or click RETURN while editing the text field. See Figures 2.51 and 2.52 for screenshots. To remove the limit by date, erase all text in the text field and update. #### 2.6.5 Condensing History Sometimes the list of commits considered is getting long and the resulting markup of the changes confusing. One additional way to customize how the changes are displayed is a setting to “condense authors.” Find a check box with that name under the list of authors for filtering. If checked, then only the latest version of an author of consecutive commits is considered – in our example, only the sixth version is shown in black while the fifth version by Roger Sherman is now grayed out as seen in Figure 2.53. See Figure 2.54 for an example of how condensing authors affects the markup. Since we are only considering the changes that Roger Sherman made in the sixth version, his correction of the name is no longer shown. Condensing authors makes sense when users commit versions often so that they do not loose too much history. Their last version after a number of commits generally has the flavor of a “final” version, ready to be shared with others. Hence, the changes made there compared to the last version of another author is commonly of most interest. #### 2.6.6 Editing and Saving Let us start the next step by resetting all filters to the default configuration, i.e., no limit by authors, date, and revision. Also make sure to turn “condense authors” off. Then, we will edit the text in the editor panel to see the latest changes. Click into the text panel and enter some text, for example a LaTeX comment reminding John Adams to work on a list of charges against King George III in line nineteen: % list charges against King George III here The added text will be rendered in red (or the color code for the current author) and underlined. Notice how the commit graph adds a first line with the label “modified” and the “Save” button becomes enabled. Now delete some of the characters you have just entered, for example the word here at the end. The characters simply disappear as they were added by the same author. Now delete other characters that are either rendered black or a different color than red but not marked as deletions (strike-through font). Notice how these characters remain visible but are now colored red and marked up with strike-through. If you tried to delete anything that is already marked as deletion (i.e., anything in strike-through font), nothing will happen as this text is already deleted in a prior version. See Figure 2.55 for a screen shot of the above edits: text in red and underlined was added and text in red and strike-through was deleted. Finally, you will want to click “Save” to save the current file to disk. This will cause the label “modified” to change to “on disk.” If you would then again edit, the label would switch back to “modified” of course. #### 2.6.7 Collaborating Through Commits In Subversion, your repository is a central entity that all collaborators commit to. Therefore, unlike distributed version control systems such as git, the collaboration happens when users commit their version. It is a good practice to update your working copy regularly to avoid conflicts during committing. Furthermore, users should communicate with each other to decide who is editing what file at a time. The following assumes that you are working with a local svn repository per the setup in Sections 2.4.2 and 2.4.3 above. Next, we will simulate that Roger Sherman commits his modified version before John Adams can upload his version, resulting in a merge conflict. To prepare this scenario, first commit the modifications from Roger Sherman’s working copy:$> cd $TUTORIAL/independence-sherman/$> svn status
M       independence.tex
$> svn commit -m "todo item for indictment" --username sherman Sending independence.tex Transmitting file data . Committed revision 7. Now the shared repository is already at revision 7 while we (as John Adams) are still editing from revision six. First, check again that you have saved the file in LTC Editor using the “Save” button and that the first entry in the commit graph says “on disk.” When we try to commit our latest changes from the Section 2.5.6 above, using the command line, we get the following error message.$> cd $TUTORIAL/independence/$> svn status
M       independence.tex
$> svn commit -m "added comment about list of charges" --username adams Sending independence.tex Transmitting file data .svn: Commit failed (details follow): svn: File ’/tutorial-svn/independence.tex’ is out of date Then, we try to update our repository first to mend the situation, which results in another error message about the conflicting versions. If Roger Sherman and John Adams had been modifying different .tex files in the same repository, we would have not gotten this conflict. To resolve, we choose to postpone so that we can see the differences in Emacs and resolve it there. Our input is marked in bold below.$> svn update
Conflict discovered in ’independence.tex’.
Select: (p) postpone, (df) diff-full, (e) edit,
(mc) mine-conflict, (tc) theirs-conflict,
(s) show all options: p
C    independence.tex
Updated to revision 7.
Summary of conflicts:
Text conflicts: 1

Our current file is now marked as in conflict, so let us click the “Update” button in LTC Editor to see something similar to the screen shot in Figure 2.56. The conflicting portion at the end is marked with additional lines and we see revision 7 in the history of the file. On the command line, the file looks similar to this:

$> cat independence.tex [...] <<<<<<< .mine % list charges against King George III ======= That to secure these rights, Governments are instituted among Men, [...] %TODO: indictment here >>>>>>> .r7 \end{document} We decide that the comments in the version .mine version means the same as the last comment in version .r7 so we modify the text in LTC Editor and save, so that it looks like the following on the command line or as seen in the screen shot in Figure 2.57.$> cat independence.tex
[...]

That to secure these rights, Governments are instituted among Men, [...]

% list charges against King George III

It is important to remove the svn marker lines starting with <<<<<<<, =======, and >>>>>>> for svn to recognize that we have resolved the conflicts. We also have to tell svn that the conflict has been resolved. Then we can finally perform the following commit command. The two important commands are printed in bold below. You may want to check the status of svn before and after the commit:

$> svn resolved independence.tex Resolved conflicted state of ’independence.tex’$> svn status
M       independence.tex
$> svn commit -m "added comment about list of charges" --username adams Sending independence.tex Transmitting file data . Committed revision 8. Once we click the “Update” button in LTC Editor, we see the latest revision 8 in the commit graph and the marked up latest edits attributed to John Adams and Roger Sherman similar to Figure 2.58. Also see that we still include all revisions up to John Adams’ second revision a while ago—all revisions at the top of the graph before any other authors are skipped before looking for the default end point in history. ## Chapter 3Using LTC The intended use of LTC is running the base system as a server and have a plugin of the user’s preferred LaTeX editor connect to it. The provided Emacs ltc-mode is an example of such a plugin and its use is described in Section 3.4. We hope to add more plugins for other popular LaTeX editors in the future. As a minimum implementation of a user interface to LTC, we also provide a Java application “LTC Editor” that uses the base system API but does not rely on running a separate LTC server. Its use is explained in Section 3.5. Before we address using these specific user interfaces, we discuss how to setup your repository for a LaTeX writing project with git (Section 3.1) or svn (Section 3.2) and then the general usage of LTC in Section 3.3. ### 3.1 Using a Git Repository For each writing project, LTC expects the history of the .tex files managed by a version control system, for example contained in a git repository. As git is a distributed version control system, this repository is local to your machine. If you need to exchange data with a collaborating author, you will push your repository or pull their repository and merge it with your local copy. This section only covers a small subset of what git can do with respect to setting up a repository for your writing project. Please refer to other git documentation about general git usage and how to further manage your writing project with git. Also note our suggestions for general, one-time git configuration in Section 1.3.1. #### 3.1.1 Initializing a Local Repository Assuming that your current LaTeX source files (and other files) are located in a directory structure called$PROJECT. To initialize the top-level directory for git perform the following commands.

$> cd$PROJECT/
$> git init Initialized empty Git repository in$PROJECT

Decide, what the final build products in your project will be. These should be ignored by git so as not to complain every time you recompile your LaTeX project. Let’s assume your project will create a file called “proposal.pdf,” then create a file called .gitignore in this directory that contains in each line the name of every build product. In a bash shell, you can do the following.

$> cat > .gitignore <<EOF > proposal.pdf > EOF Then check the contents of the file:$> less .gitignore
proposal.pdf

If you decide on more build products (e.g., files called “proposal-vol1.pdf” and “proposal-vol2.pdf”) in the future, simply edit the .gitignore file to include these file names in new lines. Make sure to do this before using a command such as git add ., which would mark any existing build products for addition.

Checking the current status of git, the output should be similar to the following.

$> git status # On branch master # # Initial commit # # Untracked files: # (use "git add <file>..." to include in what will be committed) # # .gitignore # proposal.tex nothing added to commit but untracked files present (use "git add" to track) Then, add the files already in your directory as well as the newly created file .gitignore and commit the first version, for example this way:$> git add .
$> git commit -a -m "initial commit of project" [master (root-commit) dfbf239] initial commit of project 2 files changed, 7 insertions(+), 0 deletions(-) create mode 100644 .gitignore create mode 100644 proposal.tex The option -m stands for a brief message that you would like to attach to your commit. Note that you have to give some sort of message for every commit you make. Do not try to skip the message part. Moreover, having meaningful one-line message for commit is always useful as other and you yourself can refer to later on to see what changes you made and why. #### 3.1.2 Uploading Your Initial Repository To share your local git repository, you can clone it to a shared file system or to a file server that each collaborator can access via ssh. Another option is that your system administrators provide you with a central git repository server. Contact them for details on how to upload your git repository there. In the following commands, we are giving the remote repository the name project.git but you can choose whatever you want. The ending .git is somewhat standard, though, so we advise to keep it. To clone to a shared file system, you will want to find a suitable directory$SHARED_PATH where you want to create the shared repository. The following command is issued from inside your initial repository.

$> cd$PROJECT/
$> git clone --bare .$SHARED_PATH/project.git

To clone to a file server accessible via ssh and scp, you would do the following from the top-level directory of your initial repository. The remote repository should be located under $REMOTE_PATH on the server. We assume that you have performed at least one commit since initializing the git repository.$> cd $PROJECT/..$> git clone --bare $PROJECT project.git Cloning into bare repository ’project.git’... done.$ touch project.git/git-daemon-export-ok
$scp -rq project.git username@server:$REMOTE_PATH

In either case, make sure that file permissions allow collaborators to access and read the files on the server.

Next, you will want to add a short name for the newly designated shared location called “origin” so that the push and pull command below work as if you had cloned the repository from someone else. If you used a git server, your system administrators can tell you how to configure your original repository to include the new remote location, or you can clone the remote repository anew as shown in the next section.

$> git remote add origin$SHARED_PATH/project.git

or

$> git remote add origin username@server:$REMOTE_PATH/project.git

Finally, your system administrator may already have a server for git repositories set up that you and your collaborators can use. Refer to their instructions on how to upload or create an initial repository.

#### 3.1.3 Cloning from a Remote Repository

To start a git repository from an existing one (either on a shared file server or a central repository), you want to clone it. You need to know the remote location in terms of user name, server address and path to the git repository. Your system administrator can tell you these in the form of username@server:path-to-git-repos/project.git, or, if you used a shared file system as in Section 3.1.2, you simply use $SHARED_PATH/project.git instead of the address above. Assuming that your local copy should be located in a directory my_project, you would need to execute the following command from the parent directory of my_project. Feel free to call your new working directory something else by substituting the last argument.$> git clone username@server:path-to-git-repos/project.git my_project
Cloning into my_project...
done.
$> cd my_project$> git remote -v

#### 3.1.4 Push and Pull

To exchange data with the central repository, you typically push and pull. In the simplest case, the following should work (if this is the original and not a cloned repository, you must have added the new short name “origin” via the git remote add origin command above).

$> git push origin master$> git pull origin master

If git complains about uncommitted changes and that the working copy is not clean, you may have to commit or stash changes before these commands can run successfully.

### 3.2 Using a Subversion Repository

For each writing project, LTC expects the history of the .tex files managed by a version control system, for example contained in a svn repository. As svn is a centralized version control system, the repository is typically in a remote location. To use LTC meaningfully, it has to download the different versions of the file history so you will need constant connectivity with the server. If you need to exchange data with a collaborating author, you will update from and commit to your remote repository, which also requires online access.

This section only covers a small subset of what svn can do with respect to setting up a repository for your writing project. Please refer to other svn documentation about general svn usage and how to further manage your writing project with svn. Also note our suggestions for general, one-time svn configuration in Section 1.3.2.

#### 3.2.1 Initializing a Repository

To create a working copy of an existing svn repository your system administrator will tell you the URL where the repository is hosted. Then, you will check out a working copy in a directory, say $PROJECT with that URL, which we call$REPOSITORY_URL. From the directory where you want $PROJECT to reside, call:$> svn checkout $REPOSITORY_URL$PROJECT

If this a new writing project, you may want to perform some initializations. For example, decide what the final build products in your project will be. These should be ignored by svn so as not to complain every time you recompile your LaTeX project. Let’s assume your project will create a file called “proposal.pdf,” then perform the following. First, we check whether there are already files ignored. Then, we will set a property to ignore “proposal.pdf” using a few bash commands. If you are running a different shell, you may have to adjust these commands.

$> cd$PROJECT/
$> svn propget svn:ignore .$> svn propedit svn:ignore .  # will open temporary editor in your terminal, \
where you type proposal.pdf, save and exit
Set new value for property ’svn:ignore’ on ’.’

Setting or updating a property puts a modification flag on the current directory ., which you will have to commit to the repository at the next opportunity for others to obtain this setting. Also, check that the property is now active in your working copy.

$> svn status M .$> svn commit -m "ignoring build product proposal.pdf"
Sending        .
Committed revision XXX.
$> svn propget svn:ignore . proposal.pdf #### 3.2.2 Other Typical Subversion Commands If you have a new FILE.tex file to add to the repository, do$> $svn st ? FILE.tex$> svn add FILE.tex
A         FILE.tex
$> svn commit -m "adding first version of FILE.tex" Adding FILE.tex Transmitting file data ... Committed revision XXX. When editing a FILE.tex file and saving it, it will have the modification flag set, which you can check using the status command. It is also a good idea to update your working copy before you start editing a file, in case others have committed any changes.$> svn update
At revision XXX.
$> svn status M FILE.tex$> svn commit -m "<message about recent edits in FILE.tex>"
Sending        FILE.tex
Transmitting file data ...
Committed revision XXX.

If you decide on more build products (e.g., files called “proposal-vol1.pdf” and “proposal-vol2.pdf”) in the future, call svn propedit svn:ignore . to edit the property and commit the changes to the svn repository. Make sure to do this before using a command such as svn add *, which would mark any existing build products for addition.

With a centralized repository, it is even more important to coordinate writing and editing activities among collaborators. Many say “commit early, commit often” and also make it a habit to update your working copy regularly and before beginning work. LaTeX is very well suited to be managed under version control as you can split the writing document into various files and then assign writing tasks on a one-author-per-file-at-a-time to avoid merge conflicts.

### 3.3 General Usage

In this section we describe abstractly how one would use LTC as a pattern of a work cycle. See the tutorials for more concrete examples. Also, the Sections 3.4 and 3.5 below contain more details on the specific user interface of interest, namely Emacs and the LTC Editor, respectively.

Typically, more than one author collaborate on a writing project that is kept under version control but it might be a good practice to put all your work under version control. Especially git is a well suited version control system to run locally on your computer and keeping track of your own changes if you are just interested in how a .tex file evolves over time.

We are assuming that the .tex file or files of interest are kept under version control so as to obtain a history of significant changes that have been made in the past. Significant changes are usually made through a “commit” action to the version control system. This is in contrast to merely saving edits to the file on the local file system. Such an operation can be done many more times just to preserve your current work in case of a problem with the editor or computer.

See Figure 3.1 on the left hand side for a diagram that shows a typical work cycle for a version controlled file from the perspective of one author. Often a user starts working by downloading changes that others have done—this step may be omitted if only one author is working with the revision control system, thus the action is drawn with dashed lines. Then, an author may edit and save the file. Finally, when significant changes have been made, it is often time to commit those and possibly upload them to a server where other authors can update from.

Now look at the right hand side of Figure 3.1; here we added a state for tracking changes. The user typically switches from editing and saving into tracking changes. In this mode, one can still edit and save the file. And also perform version control commands such as downloading and uploading changes. While in track changes mode, the .tex file of interest is marked up with information about changes in past versions of the file, so the text looks busier and can be longer when displaying deletions. Thus, most authors will want to switch in and out of tracking changes in order to work at times with only the latest version of the file to avoid being overwhelmed by the information shown.

#### 3.3.1 Filtering What is Shown

Since the amount of change information displayed can be quite large, we offer a few switches to tailor the view for the user. These switches can be turned on or off, meaning that certain changes are shown or hidden (not marked up or not included if deleted text). We currently support the following five switches.

Deletions  Deletions are text that was part of an earlier version but cannot be located in the latest version anymore. If shown, the deleted text is inserted where it was found and marked up as a deletion; i.e., with strike-through font in the LTC Editor and (unless the user customizes this setting) with inverse colors in Emacs. In the example on the right, the text “my” was deleted in the newer version.

“Small” Changes  We employ the following heuristic to detect so-called “small” changes, which attempts to find things such as typographical error corrections. If two lexemes1 are being compared and their Levenshtein distance2 is less than three and the shorter lexeme is longer than this metric, then we declare it a “small” change. For example, let us consider the two words “freind” and “friend” with the former being part of an earlier version and the latter part of the current text version. Someone had corrected the typographical error. The Levenshtein distance between the two words is two, as one of the characters ‘e’ and ‘i’ has to be removed and inserted at the correct position to change the older version into the newer one. Both words have length five, which is longer than two. Hence, we would mark up only the character difference in these words rather than mark the whole word as a deletion and addition. If users want to omit seeing such small changes to focus on the bigger changes, they can switch off seeing these. See the example on the right for how the markup on this small change looks.

In Preamble  If the file of interest contains the LaTeX preamble and the text “\begin{document},” this switch shows or hides any changes that occurs before this text. If turned off, it will suppress any deleted text and not mark up additions at the beginning of the file. If the file does not contain this marking text, the switch has no effect. In the example on the right, the newest version added a new package “something” compared to a prior version.

In Comments  If the file of interest contains comments (anything after a ‘%’ on the rest of the line), this switch controls whether the user wants to see any changes in those. In the example on the right, someone replaced the word “pet” with “dog” inside the comment. Note that comments, which have been deleted will not be affected by this switch. The reason is that deletions are inserted for display into the latest version (if deletions are currently shown) but they do not necessarily end with a new line, therefore, if they contain the unescaped comment character ‘%’ they might render text that is following the deletion on the same line falsely as a comment.

In Commands  When LTC parses text, it detects commands as any word following and including a ‘\’ but not any arguments that are declared in curly braces. Here we wanted to offer another way of tailoring the display of changes by ignoring possibly uninteresting parts of the LaTeX source text. On the other hand, our simple lexicographical analysis cannot count open and closing brackets, which may be nested inside the command’s arguments. Therefore, this switch may only be useful to blend out commands without arguments. In the example on the right, an author has added a LaTeX command to emphasize text by typesetting it in italics. Hiding this change will still result in showing the curly braces.

#### 3.3.2 History of a File

LTC obtains the history of the file of interest from a version control system—currently either git or svn. All version control systems maintain information about the file’s contents at different points in time; normally when the user “committed” a revision. Also, modern version control systems typically provide the option of branching away from the standard path of development. For writing projects, this could be the case when two authors need to work concurrently on the same text file and decide to make a branch for one author for the time being. Also, branching (and merging) is common in so-called distributed version control systems such as git when different authors synchronize their work.

In all cases, there exists a relationship of parent revision to a child revision imposing a graph structure on the revisions made at certain points of time. When branching, there is more than one child, and, conversely, when merging there is more than one parent. Thus, a history graph is a directed acyclic graph, which can be inferred from the revisions of a file in the past. See Figure 3.2 for an example of such a history graph. In version control systems, we typically draw the latest version as the top-most node.

LTC needs to transform this graph into a sequence of revisions therefore traversing the graph from the latest version. We do so by traversing the graph from the latest version to an oldest one in reverse direction. When a revision is a merge and thus has multiple parents, we currently choose the oldest revision as the next one in the list leaving out any other branches. However, we plan to make the branch selection the user’s choice in future releases as this heuristic does not always apply.

Figure 3.2 shows that LTC selects the shaded path on the left as revision ri happened at a later time than revision rj. It doesn’t matter when the versions just after the branching event were committed as we are traversing the graph in opposite direction to obtain a path.

Once we have a sequence of versions in LTC, we

condensing authors

### 3.4 Using Emacs

In this section, we explain how to use Emacs as the editor of the .tex file with LTC.

#### 3.4.1 Starting the LTC Server

Before you can use ltc-mode in Emacs, you must start the LTC server first. To do so, you call Java with the JAR-file that you installed in directory $LTC. This should produce output similar to the one below.$> java -jar $LTC/LTC.jar [...] <current date> | INFO: Started RPC server on port 7777. If you need to customize LTC, for example to change the port number, start the base system with option -p <PORT>:$> java -jar \$LTC/LTC.jar -p 5555
[...]
<current date> | INFO:  Started RPC server on port 5555.

The log messages from the LTC server are also saved in file ~/.LTC.log. This log file is created every time that the server starts, so if you need the contents, please make a copy before starting the server anew.

#### 3.4.2 Entering and Exiting ltc-mode

Once your Emacs has a .tex file loaded in plain latex-mode as seen on the left in Figure 3.3, you can invoke the minor-mode ltc-mode in different ways. Usually, the mode launching command M-x ltc-mode is available. If Emacs has its own window and supports context menus, you may be able to right-click on the word “LaTeX” in the mode line at the bottom of Emacs. Then, a list of minor modes appears from which you can select “LTC Mode.” Once the mode starts successfully, a number of status messages, a smaller window at the bottom of the text that contains LTC information, and changes in the text marked up by color and style appear. Emacs then looks similar to the right in Figure 3.3.

The mode can be toggled, i.e., the same command starts and stops ltc-mode.

Once the mode is started, a new menu “LTC” should appear in Emacs. This can be part of Emacs’ main menu or included in the mode line. From there, you can interact with the LTC system as shown in the following examples.

##### The “LTC info” Buffer

The new, smaller window at the bottom of the frame is called “LTC info” and contains a table resembling the commit graph of the current file. Newer versions of the file are at the top of the list. An asterisk at the beginning indicated that this version is taken into account when the history of changes is calculated. Conversely, if the asterisk is missing and the whole row is shown in gray color, then this version is currently skipped when calculating changes. The next column contains the SHA-1 key (abbreviated) and the third column the date of the corresponding git revision. The author colored in his or her key and finally the commit message follow. The first row of the commit table contains the current author.

##### Updating the Buffer

An important command is M-x ltc-update or the menu item LTC  Update buffer . This will update the view of the file based on current filtering and other settings. Use this command when the “LTC info” buffer ended up in a different frame or tab, or when you make changes such as a git commit from the command line.

#### 3.4.3 Customizing LTC Mode

To customize LTC mode, you can use the command M-x customize-group RET ltc RET. It will show you a list of options that can be changed. Once you have changed options, you may want to click “Save for future sessions” or abort using “Exit.”

Port
This denotes the port of the LTC server running on your local machine. Leave the default value unless there are problems and the port is already in use by another application.
Ltc Command Prefix
This is a global command prefix for all interactive LTC commands in Emacs. The Emacs convention for modes is to use ^C and another character (default is ^C ’) but you can adjust this to your liking if you like to use shortcuts to the LTC functions.
Here you can customize how LTC marks up additions and deletions respectively. You will not want to set the Foreground or Background color, as this will be overridden by the colors of the authors who made the change. On Mac OS X, the strike-through fonts may not be available so the default for deletions is also to invert the foreground and background coloring. On Linux, you may want to turn the color inversion off for a less intrusive scheme as the strike-through font is available there.

#### 3.4.4 Filtering Changes

To show and hide certain changes, simply choose from the menu LTC > Show/Hide > ... the appropriate entry. Figure 3.4 shows for example hiding changes in the preamble via the context menu. After selecting any of the menu items to show or hide certain changes, the contents in the main Emacs window is immediately updated to reflect the filtering settings.

To change the default limitation of the file’s history that is taken into account for viewing changes, you can do so by specifying a set of authors to limit to, and a revision number or date to indicate how far back in time you want to go. These functions are available via the menu LTC > Limit by > ... Each of these actions require additional input, therefore the menu item ends with ellipsis.

To define a set of authors to limit the history to, select the menu item or use command M-x ltc-limit-authors. This will prompt you to input the names of authors in the mini-buffer. You may use auto-completion with the TAB key. End the input of names by providing an empty name. If the first name is empty, this will reset to taking all known authors into account (i.e., not limiting by authors anymore).

Similarly, you can define how far back the file history is taken into account. Use commands M-x ltc-limit-rev and M-x ltc-limit-date respectively. Again, user input is needed via the mini-buffer. Use auto completion with the TAB key in order to automatically extend to known SHA-1 keys or revision dates. To reset the limit to the default, simply enter an empty value when prompted.

#### 3.4.5 Author Color Keys

To customize the color used to designate changes in the marked up text, click on the author name in the “LTC info” buffer. [TODO: MORE NEEDED]

[TODO]

[TODO]

#### 3.4.8 Misc

Customize ltc-mode:

M-x describe-face RET <face> to describe faces ltc-addition and ltc-deletion

C-u C-x = shows the face under point (among other information)

### 3.5 Using the “LTC Editor”

The LTC Editor is a Java application that allows to use LTC without a separate LTC server. It may also serve as a reference implementation showing how to use our API. Chapter 4 contains more details on writing your own editor plugin using our LTC API.

## Chapter 4Writing Your Own Front End

In this chapter, we explain the general flow that a new editor plugin should follow. We follow these flows in general in our reference implementation of the Emacs ltc-mode and the Java LTC Editor.

## Chapter 5Algorithms & Utilities

### 5.1 How Are Changes Calculated?

[or is this too technical for the manual?]

### 5.2 Utility Programs

Lexer

#### 5.2.5 Testing the XML-RPC Server

HelloLTC

Version 3, 29 June 2007

Copyright (C) 2007 Free Software Foundation, Inc. <http://fsf.org/>
Everyone is permitted to copy and distribute verbatim copies
of this license document, but changing it is not allowed.

Preamble

software and other kinds of works.

The licenses for most software and other practical works are designed
to take away your freedom to share and change the works.  By contrast,
the GNU General Public License is intended to guarantee your freedom to
share and change all versions of a program--to make sure it remains free
software for all its users.  We, the Free Software Foundation, use the
GNU General Public License for most of our software; it applies also to
any other work released this way by its authors.  You can apply it to
your programs, too.

When we speak of free software, we are referring to freedom, not
price.  Our General Public Licenses are designed to make sure that you
have the freedom to distribute copies of free software (and charge for
them if you wish), that you receive source code or can get it if you
want it, that you can change the software or use pieces of it in new
free programs, and that you know you can do these things.

To protect your rights, we need to prevent others from denying you
these rights or asking you to surrender the rights.  Therefore, you have
certain responsibilities if you distribute copies of the software, or if
you modify it: responsibilities to respect the freedom of others.

For example, if you distribute copies of such a program, whether
gratis or for a fee, you must pass on to the recipients the same
freedoms that you received.  You must make sure that they, too, receive
or can get the source code.  And you must show them these terms so they
know their rights.

Developers that use the GNU GPL protect your rights with two steps:
(1) assert copyright on the software, and (2) offer you this License
giving you legal permission to copy, distribute and/or modify it.

For the developers’ and authors’ protection, the GPL clearly explains
that there is no warranty for this free software.  For both users’ and
authors’ sake, the GPL requires that modified versions be marked as
changed, so that their problems will not be attributed erroneously to
authors of previous versions.

Some devices are designed to deny users access to install or run
modified versions of the software inside them, although the manufacturer
can do so.  This is fundamentally incompatible with the aim of
protecting users’ freedom to change the software.  The systematic
pattern of such abuse occurs in the area of products for individuals to
use, which is precisely where it is most unacceptable.  Therefore, we
have designed this version of the GPL to prohibit the practice for those
products.  If such problems arise substantially in other domains, we
stand ready to extend this provision to those domains in future versions
of the GPL, as needed to protect the freedom of users.

Finally, every program is threatened constantly by software patents.
States should not allow patents to restrict development and use of
software on general-purpose computers, but in those that do, we wish to
avoid the special danger that patents applied to a free program could
make it effectively proprietary.  To prevent this, the GPL assures that
patents cannot be used to render the program non-free.

The precise terms and conditions for copying, distribution and
modification follow.

TERMS AND CONDITIONS

0. Definitions.

"This License" refers to version 3 of the GNU General Public License.

"recipients" may be individuals or organizations.

To "modify" a work means to copy from or adapt all or part of the work
in a fashion requiring copyright permission, other than the making of an
exact copy.  The resulting work is called a "modified version" of the
earlier work or a work "based on" the earlier work.

A "covered work" means either the unmodified Program or a work based
on the Program.

To "propagate" a work means to do anything with it that, without
permission, would make you directly or secondarily liable for
infringement under applicable copyright law, except executing it on a
computer or modifying a private copy.  Propagation includes copying,
distribution (with or without modification), making available to the
public, and in some countries other activities as well.

To "convey" a work means any kind of propagation that enables other
parties to make or receive copies.  Mere interaction with a user through
a computer network, with no transfer of a copy, is not conveying.

An interactive user interface displays "Appropriate Legal Notices"
to the extent that it includes a convenient and prominently visible
feature that (1) displays an appropriate copyright notice, and (2)
tells the user that there is no warranty for the work (except to the
extent that warranties are provided), that licensees may convey the
work under this License, and how to view a copy of this License.  If
the interface presents a list of user commands or options, such as a
menu, a prominent item in the list meets this criterion.

1. Source Code.

The "source code" for a work means the preferred form of the work
for making modifications to it.  "Object code" means any non-source
form of a work.

A "Standard Interface" means an interface that either is an official
standard defined by a recognized standards body, or, in the case of
interfaces specified for a particular programming language, one that
is widely used among developers working in that language.

The "System Libraries" of an executable work include anything, other
than the work as a whole, that (a) is included in the normal form of
packaging a Major Component, but which is not part of that Major
Component, and (b) serves only to enable use of the work with that
Major Component, or to implement a Standard Interface for which an
implementation is available to the public in source code form.  A
"Major Component", in this context, means a major essential component
(kernel, window system, and so on) of the specific operating system
(if any) on which the executable work runs, or a compiler used to
produce the work, or an object code interpreter used to run it.

The "Corresponding Source" for a work in object code form means all
the source code needed to generate, install, and (for an executable
work) run the object code and to modify the work, including scripts to
control those activities.  However, it does not include the work’s
System Libraries, or general-purpose tools or generally available free
programs which are used unmodified in performing those activities but
which are not part of the work.  For example, Corresponding Source
includes interface definition files associated with source files for
the work, and the source code for shared libraries and dynamically
linked subprograms that the work is specifically designed to require,
such as by intimate data communication or control flow between those
subprograms and other parts of the work.

The Corresponding Source need not include anything that users
can regenerate automatically from other parts of the Corresponding
Source.

The Corresponding Source for a work in source code form is that
same work.

2. Basic Permissions.

All rights granted under this License are granted for the term of
copyright on the Program, and are irrevocable provided the stated
conditions are met.  This License explicitly affirms your unlimited
permission to run the unmodified Program.  The output from running a
covered work is covered by this License only if the output, given its
content, constitutes a covered work.  This License acknowledges your
rights of fair use or other equivalent, as provided by copyright law.

You may make, run and propagate covered works that you do not
convey, without conditions so long as your license otherwise remains
in force.  You may convey covered works to others for the sole purpose
of having them make modifications exclusively for you, or provide you
with facilities for running those works, provided that you comply with
the terms of this License in conveying all material for which you do
not control copyright.  Those thus making or running the covered works
for you must do so exclusively on your behalf, under your direction
and control, on terms that prohibit them from making any copies of
your copyrighted material outside their relationship with you.

Conveying under any other circumstances is permitted solely under
the conditions stated below.  Sublicensing is not allowed; section 10
makes it unnecessary.

3. Protecting Users’ Legal Rights From Anti-Circumvention Law.

No covered work shall be deemed part of an effective technological
measure under any applicable law fulfilling obligations under article
11 of the WIPO copyright treaty adopted on 20 December 1996, or
similar laws prohibiting or restricting circumvention of such
measures.

When you convey a covered work, you waive any legal power to forbid
circumvention of technological measures to the extent such circumvention
is effected by exercising rights under this License with respect to
the covered work, and you disclaim any intention to limit operation or
modification of the work as a means of enforcing, against the work’s
users, your or third parties’ legal rights to forbid circumvention of
technological measures.

4. Conveying Verbatim Copies.

You may convey verbatim copies of the Program’s source code as you
receive it, in any medium, provided that you conspicuously and
appropriately publish on each copy an appropriate copyright notice;
keep intact all notices stating that this License and any
non-permissive terms added in accord with section 7 apply to the code;
keep intact all notices of the absence of any warranty; and give all
recipients a copy of this License along with the Program.

You may charge any price or no price for each copy that you convey,
and you may offer support or warranty protection for a fee.

5. Conveying Modified Source Versions.

You may convey a work based on the Program, or the modifications to
produce it from the Program, in the form of source code under the
terms of section 4, provided that you also meet all of these conditions:

a) The work must carry prominent notices stating that you modified
it, and giving a relevant date.

b) The work must carry prominent notices stating that it is
7.  This requirement modifies the requirement in section 4 to
"keep intact all notices".

c) You must license the entire work, as a whole, under this
License to anyone who comes into possession of a copy.  This
License will therefore apply, along with any applicable section 7
additional terms, to the whole of the work, and all its parts,
regardless of how they are packaged.  This License gives no
permission to license the work in any other way, but it does not
invalidate such permission if you have separately received it.

d) If the work has interactive user interfaces, each must display
Appropriate Legal Notices; however, if the Program has interactive
interfaces that do not display Appropriate Legal Notices, your
work need not make them do so.

A compilation of a covered work with other separate and independent
works, which are not by their nature extensions of the covered work,
and which are not combined with it such as to form a larger program,
in or on a volume of a storage or distribution medium, is called an
"aggregate" if the compilation and its resulting copyright are not
used to limit the access or legal rights of the compilation’s users
beyond what the individual works permit.  Inclusion of a covered work
in an aggregate does not cause this License to apply to the other
parts of the aggregate.

6. Conveying Non-Source Forms.

You may convey a covered work in object code form under the terms
of sections 4 and 5, provided that you also convey the
in one of these ways:

a) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by the
Corresponding Source fixed on a durable physical medium
customarily used for software interchange.

b) Convey the object code in, or embodied in, a physical product
(including a physical distribution medium), accompanied by a
written offer, valid for at least three years and valid for as
long as you offer spare parts or customer support for that product
model, to give anyone who possesses the object code either (1) a
copy of the Corresponding Source for all the software in the
product that is covered by this License, on a durable physical
medium customarily used for software interchange, for a price no
more than your reasonable cost of physically performing this
conveying of source, or (2) access to copy the
Corresponding Source from a network server at no charge.

c) Convey individual copies of the object code with a copy of the
written offer to provide the Corresponding Source.  This
alternative is allowed only occasionally and noncommercially, and
only if you received the object code with such an offer, in accord
with subsection 6b.

d) Convey the object code by offering access from a designated
place (gratis or for a charge), and offer equivalent access to the
Corresponding Source in the same way through the same place at no
further charge.  You need not require recipients to copy the
Corresponding Source along with the object code.  If the place to
copy the object code is a network server, the Corresponding Source
may be on a different server (operated by you or a third party)
that supports equivalent copying facilities, provided you maintain
clear directions next to the object code saying where to find the
Corresponding Source.  Regardless of what server hosts the
Corresponding Source, you remain obligated to ensure that it is
available for as long as needed to satisfy these requirements.

e) Convey the object code using peer-to-peer transmission, provided
you inform other peers where the object code and Corresponding
Source of the work are being offered to the general public at no
charge under subsection 6d.

A separable portion of the object code, whose source code is excluded
from the Corresponding Source as a System Library, need not be
included in conveying the object code work.

A "User Product" is either (1) a "consumer product", which means any
tangible personal property which is normally used for personal, family,
or household purposes, or (2) anything designed or sold for incorporation
into a dwelling.  In determining whether a product is a consumer product,
doubtful cases shall be resolved in favor of coverage.  For a particular
product received by a particular user, "normally used" refers to a
typical or common use of that class of product, regardless of the status
of the particular user or of the way in which the particular user
actually uses, or expects or is expected to use, the product.  A product
is a consumer product regardless of whether the product has substantial
commercial, industrial or non-consumer uses, unless such uses represent
the only significant mode of use of the product.

"Installation Information" for a User Product means any methods,
procedures, authorization keys, or other information required to install
and execute modified versions of a covered work in that User Product from
a modified version of its Corresponding Source.  The information must
suffice to ensure that the continued functioning of the modified object
code is in no case prevented or interfered with solely because

If you convey an object code work under this section in, or with, or
specifically for use in, a User Product, and the conveying occurs as
part of a transaction in which the right of possession and use of the
User Product is transferred to the recipient in perpetuity or for a
fixed term (regardless of how the transaction is characterized), the
Corresponding Source conveyed under this section must be accompanied
by the Installation Information.  But this requirement does not apply
if neither you nor any third party retains the ability to install
modified object code on the User Product (for example, the work has
been installed in ROM).

The requirement to provide Installation Information does not include a
requirement to continue to provide support service, warranty, or updates
for a work that has been modified or installed by the recipient, or for
the User Product in which it has been modified or installed.  Access to a
network may be denied when the modification itself materially and
adversely affects the operation of the network or violates the rules and
protocols for communication across the network.

Corresponding Source conveyed, and Installation Information provided,
in accord with this section must be in a format that is publicly
documented (and with an implementation available to the public in
source code form), and must require no special password or key for

"Additional permissions" are terms that supplement the terms of this
License by making exceptions from one or more of its conditions.
Additional permissions that are applicable to the entire Program shall
be treated as though they were included in this License, to the extent
that they are valid under applicable law.  If additional permissions
apply only to part of the Program, that part may be used separately
under those permissions, but the entire Program remains governed by

When you convey a copy of a covered work, you may at your option
remove any additional permissions from that copy, or from any part of
it.  (Additional permissions may be written to require their own
removal in certain cases when you modify the work.)  You may place
for which you have or can give appropriate copyright permission.

Notwithstanding any other provision of this License, for material you
add to a covered work, you may (if authorized by the copyright holders of
that material) supplement the terms of this License with terms:

a) Disclaiming warranty or limiting liability differently from the
terms of sections 15 and 16 of this License; or

b) Requiring preservation of specified reasonable legal notices or
author attributions in that material or in the Appropriate Legal
Notices displayed by works containing it; or

c) Prohibiting misrepresentation of the origin of that material, or
requiring that modified versions of such material be marked in
reasonable ways as different from the original version; or

d) Limiting the use for publicity purposes of names of licensors or
authors of the material; or

e) Declining to grant rights under trademark law for use of some

f) Requiring indemnification of licensors and authors of that
material by anyone who conveys the material (or modified versions of
it) with contractual assumptions of liability to the recipient, for
any liability that these contractual assumptions directly impose on
those licensors and authors.

All other non-permissive additional terms are considered "further
restrictions" within the meaning of section 10.  If the Program as you
received it, or any part of it, contains a notice stating that it is
governed by this License along with a term that is a further
restriction, you may remove that term.  If a license document contains
a further restriction but permits relicensing or conveying under this
License, you may add to a covered work material governed by the terms
of that license document, provided that the further restriction does
not survive such relicensing or conveying.

If you add terms to a covered work in accord with this section, you
must place, in the relevant source files, a statement of the
additional terms that apply to those files, or a notice indicating
where to find the applicable terms.

Additional terms, permissive or non-permissive, may be stated in the
form of a separately written license, or stated as exceptions;
the above requirements apply either way.

8. Termination.

You may not propagate or modify a covered work except as expressly
provided under this License.  Any attempt otherwise to propagate or
modify it is void, and will automatically terminate your rights under
paragraph of section 11).

However, if you cease all violation of this License, then your
provisionally, unless and until the copyright holder explicitly and
holder fails to notify you of the violation by some reasonable means
prior to 60 days after the cessation.

reinstated permanently if the copyright holder notifies you of the
violation by some reasonable means, this is the first time you have
received notice of violation of this License (for any work) from that
copyright holder, and you cure the violation prior to 30 days after
your receipt of the notice.

Termination of your rights under this section does not terminate the
licenses of parties who have received copies or rights from you under
this License.  If your rights have been terminated and not permanently
reinstated, you do not qualify to receive new licenses for the same
material under section 10.

9. Acceptance Not Required for Having Copies.

You are not required to accept this License in order to receive or
run a copy of the Program.  Ancillary propagation of a covered work
occurring solely as a consequence of using peer-to-peer transmission
to receive a copy likewise does not require acceptance.  However,
nothing other than this License grants you permission to propagate or
modify any covered work.  These actions infringe copyright if you do
not accept this License.  Therefore, by modifying or propagating a
covered work, you indicate your acceptance of this License to do so.

10. Automatic Licensing of Downstream Recipients.

Each time you convey a covered work, the recipient automatically
propagate that work, subject to this License.  You are not responsible
for enforcing compliance by third parties with this License.

An "entity transaction" is a transaction transferring control of an
organization, or substantially all assets of one, or subdividing an
organization, or merging organizations.  If propagation of a covered
work results from an entity transaction, each party to that
licenses to the work the party’s predecessor in interest had or could
give under the previous paragraph, plus a right to possession of the
Corresponding Source of the work from the predecessor in interest, if
the predecessor has it or can get it with reasonable efforts.

You may not impose any further restrictions on the exercise of the
rights granted or affirmed under this License.  For example, you may
not impose a license fee, royalty, or other charge for exercise of
rights granted under this License, and you may not initiate litigation
(including a cross-claim or counterclaim in a lawsuit) alleging that
any patent claim is infringed by making, using, selling, offering for
sale, or importing the Program or any portion of it.

11. Patents.

A "contributor" is a copyright holder who authorizes use under this
License of the Program or a work on which the Program is based.  The
work thus licensed is called the contributor’s "contributor version".

A contributor’s "essential patent claims" are all patent claims
owned or controlled by the contributor, whether already acquired or
hereafter acquired, that would be infringed by some manner, permitted
by this License, of making, using, or selling its contributor version,
but do not include claims that would be infringed only as a
consequence of further modification of the contributor version.  For
purposes of this definition, "control" includes the right to grant
patent sublicenses in a manner consistent with the requirements of

Each contributor grants you a non-exclusive, worldwide, royalty-free
patent license under the contributor’s essential patent claims, to
make, use, sell, offer for sale, import and otherwise run, modify and
propagate the contents of its contributor version.

In the following three paragraphs, a "patent license" is any express
agreement or commitment, however denominated, not to enforce a patent
(such as an express permission to practice a patent or covenant not to
sue for patent infringement).  To "grant" such a patent license to a
party means to make such an agreement or commitment not to enforce a
patent against the party.

If you convey a covered work, knowingly relying on a patent license,
and the Corresponding Source of the work is not available for anyone
to copy, free of charge and under the terms of this License, through a
publicly available network server or other readily accessible means,
then you must either (1) cause the Corresponding Source to be so
available, or (2) arrange to deprive yourself of the benefit of the
patent license for this particular work, or (3) arrange, in a manner
consistent with the requirements of this License, to extend the patent
license to downstream recipients.  "Knowingly relying" means you have
actual knowledge that, but for the patent license, your conveying the
covered work in a country, or your recipient’s use of the covered work
in a country, would infringe one or more identifiable patents in that
country that you have reason to believe are valid.

If, pursuant to or in connection with a single transaction or
arrangement, you convey, or propagate by procuring conveyance of, a
covered work, and grant a patent license to some of the parties
receiving the covered work authorizing them to use, propagate, modify
or convey a specific copy of the covered work, then the patent license
you grant is automatically extended to all recipients of the covered
work and works based on it.

A patent license is "discriminatory" if it does not include within
the scope of its coverage, prohibits the exercise of, or is
conditioned on the non-exercise of one or more of the rights that are
specifically granted under this License.  You may not convey a covered
work if you are a party to an arrangement with a third party that is
in the business of distributing software, under which you make payment
to the third party based on the extent of your activity of conveying
the work, and under which the third party grants, to any of the
parties who would receive the covered work from you, a discriminatory
patent license (a) in connection with copies of the covered work
conveyed by you (or copies made from those copies), or (b) primarily
for and in connection with specific products or compilations that
contain the covered work, unless you entered into that arrangement,
or that patent license was granted, prior to 28 March 2007.

Nothing in this License shall be construed as excluding or limiting
any implied license or other defenses to infringement that may
otherwise be available to you under applicable patent law.

12. No Surrender of Others’ Freedom.

If conditions are imposed on you (whether by court order, agreement or
excuse you from the conditions of this License.  If you cannot convey a
covered work so as to satisfy simultaneously your obligations under this
License and any other pertinent obligations, then as a consequence you may
not convey it at all.  For example, if you agree to terms that obligate you
to collect a royalty for further conveying from those to whom you convey
the Program, the only way you could satisfy both those terms and this
License would be to refrain entirely from conveying the Program.

13. Use with the GNU Affero General Public License.

Notwithstanding any other provision of this License, you have
permission to link or combine any covered work with a work licensed
under version 3 of the GNU Affero General Public License into a single
combined work, and to convey the resulting work.  The terms of this
License will continue to apply to the part which is the covered work,
but the special requirements of the GNU Affero General Public License,
section 13, concerning interaction through a network will apply to the
combination as such.

14. Revised Versions of this License.

The Free Software Foundation may publish revised and/or new versions of
the GNU General Public License from time to time.  Such new versions will
be similar in spirit to the present version, but may differ in detail to

Each version is given a distinguishing version number.  If the
Program specifies that a certain numbered version of the GNU General
Public License "or any later version" applies to it, you have the
option of following the terms and conditions either of that numbered
version or of any later version published by the Free Software
Foundation.  If the Program does not specify a version number of the
GNU General Public License, you may choose any version ever published
by the Free Software Foundation.

If the Program specifies that a proxy can decide which future
versions of the GNU General Public License can be used, that proxy’s
public statement of acceptance of a version permanently authorizes you
to choose that version for the Program.

permissions.  However, no additional obligations are imposed on any
author or copyright holder as a result of your choosing to follow a
later version.

15. Disclaimer of Warranty.

THERE IS NO WARRANTY FOR THE PROGRAM, TO THE EXTENT PERMITTED BY
APPLICABLE LAW.  EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT
HOLDERS AND/OR OTHER PARTIES PROVIDE THE PROGRAM "AS IS" WITHOUT WARRANTY
OF ANY KIND, EITHER EXPRESSED OR IMPLIED, INCLUDING, BUT NOT LIMITED TO,
THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
PURPOSE.  THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE PROGRAM
IS WITH YOU.  SHOULD THE PROGRAM PROVE DEFECTIVE, YOU ASSUME THE COST OF
ALL NECESSARY SERVICING, REPAIR OR CORRECTION.

16. Limitation of Liability.

IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING
WILL ANY COPYRIGHT HOLDER, OR ANY OTHER PARTY WHO MODIFIES AND/OR CONVEYS
THE PROGRAM AS PERMITTED ABOVE, BE LIABLE TO YOU FOR DAMAGES, INCLUDING ANY
GENERAL, SPECIAL, INCIDENTAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE
USE OR INABILITY TO USE THE PROGRAM (INCLUDING BUT NOT LIMITED TO LOSS OF
DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD
PARTIES OR A FAILURE OF THE PROGRAM TO OPERATE WITH ANY OTHER PROGRAMS),
EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF
SUCH DAMAGES.

17. Interpretation of Sections 15 and 16.

If the disclaimer of warranty and limitation of liability provided
above cannot be given local legal effect according to their terms,
reviewing courts shall apply local law that most closely approximates
an absolute waiver of all civil liability in connection with the
Program, unless a warranty or assumption of liability accompanies a
copy of the Program in return for a fee.

END OF TERMS AND CONDITIONS

How to Apply These Terms to Your New Programs

If you develop a new program, and you want it to be of the greatest
possible use to the public, the best way to achieve this is to make it
free software which everyone can redistribute and change under these terms.

To do so, attach the following notices to the program.  It is safest
to attach them to the start of each source file to most effectively
state the exclusion of warranty; and each file should have at least
the "copyright" line and a pointer to where the full notice is found.

<one line to give the program’s name and a brief idea of what it does.>
Copyright (C) <year>  <name of author>

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.

Also add information on how to contact you by electronic and paper mail.

If the program does terminal interaction, make it output a short
notice like this when it starts in an interactive mode:

<program>  Copyright (C) <year>  <name of author>
This program comes with ABSOLUTELY NO WARRANTY; for details type ‘show w’.
This is free software, and you are welcome to redistribute it
under certain conditions; type ‘show c’ for details.

The hypothetical commands ‘show w’ and ‘show c’ should show the appropriate
parts of the General Public License.  Of course, your program’s commands
might be different; for a GUI interface, you would use an "about box".

You should also get your employer (if you work as a programmer) or school,
if any, to sign a "copyright disclaimer" for the program, if necessary.
For more information on this, and how to apply and follow the GNU GPL, see