The LATEX Track Changes Manual
v1.0.9
August 12, 2015
| Back |
Note: This is an automatically generated HTML conversion of a LaTeX file, provided for convenience. The authoritative version is the PDF version.
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.
See Appendix A or http://www.gnu.org/licenses/ for the complete license.
Contents
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.
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.
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.
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.
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:
If you haven’t done already, configure git with your name and email address:
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.
Then, issue the git config command below (with a possibly adjusted file name and location).
To learn how to set up a new writing project under a git repository for using it with LTC refer to Section 3.1.
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:
Subversion uses only your Unix user name but not your email address to attribute changes. Hence, we do not need to configure these.
Typically, you don’t want to track build products of your LaTeX project, so you may want to edit your file ~/.subversion/config to change the line with globale-ignores in your favorite text editor. You will want to add these patterns to the existing line:
To learn how to set up a new writing project under a subversion repository for using it with LTC refer to Section 3.2.
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:
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:
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.
We are keeping a list of frequently-asked-questions at the project’s web site \baseurl that may help for troubleshooting.
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).
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.
Now we impersonate John Adams to work on this writing project for the Declaration of Independence.
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.
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:
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.
Now we impersonate Roger Sherman in the newly created repository above, and also check the setting for its remotes.
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
Then, we go into the first one and add a new remote location there:
Afterwards, we go into the second one and add a new remote location there:
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.
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.
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.
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.
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.
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.
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.”
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.
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.
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:
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:
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.
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:
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:
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:
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:
This has resolved the conflict and incorporated Roger Sherman’s prior changes, as a look at the git log with the graphing function reveals:
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.
A look at the git graph on the command line shows that the merge has been applied without conflict.
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.
In this section, we assume that the example git repository has been created according to the instructions in Section 2.1 above.
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:
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.
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.
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.
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.”
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.
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.
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:
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:
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.
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:
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:
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:
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:
This has resolved the conflict and incorporated Roger Sherman’s prior changes, as a look at the git log with the graphing function reveals:
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.
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.
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.
Now change into the new directory and confirm that the file has six revisions in its history
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.
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.
Now edit the two files
to contain the following lines:
Finally, start the SVN server in daemon mode using:
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:
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.
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.
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.
Finally, you will also want to remove the working copies you had made from the now deleted local repository:
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.
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.
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.
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.
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.
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.”
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.
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.
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:
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.
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:
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.
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.
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:
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:
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:
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.
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.
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:
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.
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.
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.
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.”
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.
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.
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:
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.
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:
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.
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.
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:
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.
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:
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.
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.
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.
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.
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.
Then check the contents of the file:
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.
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:
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.
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.
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.
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.
or
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.
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.
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).
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.
Please refer to the many online resources to learn more about git, or ask you system administrator.
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.
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:
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.
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.
If you have a new FILE.tex file to add to the repository, do
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.
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.
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.
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.
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
In this section, we explain how to use Emacs as the editor of the .tex file with LTC.
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.
If you need to customize LTC, for example to change the port number, start the base system with option -p <PORT>:
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.
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 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.
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.
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.”
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.
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]
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)
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.
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.
[or is this too technical for the manual?]
Lexer
