Chapter 2
Tutorials


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

figures/manual-figure0.png

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"
  user.name=John Adams
  user.email=adams@usa.gov

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.


figures/gitx-screen.png

Figure 2.1: Investigating example git repository with a graphical tool such as GitX


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.


figures/emacs-open.png
Figure 2.2: Starting ltc-mode in Emacs with tutorial file under git


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.


figures/emacs-LTC-menu.png

Figure 2.3: Opening the LTC menu from the mode line in Emacs


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/emacs-filter-small1.png   figures/emacs-filter-small2.png   figures/emacs-filter-small3.png

Figure 2.4: Effect of hiding “small” changes first (middle) and then also deletions (right)


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.


figures/emacs-commit-graph.png

Figure 2.5: Example of commit graph


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.


figures/emacs-limit-authors.png

Figure 2.6: Effect on commit graph of limiting authors to Roger Sherman and Thomas Jefferson


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.


figures/emacs-limit-rev.png

Figure 2.7: Effect on commit graph of going back to first revision


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.


figures/emacs-limit-date.png

Figure 2.8: Effect on commit graph of limiting history to date of third version


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


figures/emacs-condense-on.png

Figure 2.9: Effect of condensing authors: ignoring the fifth version by Roger Sherman


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.


figures/emacs-condense-before.png  figures/emacs-condense-after.png

Figure 2.10: Example of markup change before (left) and after (right) condensing authors


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.


figures/emacs-modified.png

Figure 2.11: After editing the text as John Adams


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.


figures/emacs-new-commit.png

Figure 2.12: File history after committing latest version and updating Emacs


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
   * 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.


figures/emacs-merge-conflict.png

Figure 2.13: Git conflict markers in merged file


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


figures/emacs-merge-resolve.png

Figure 2.14: After resolving conflict, committing, and updating in Emacs


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
  |\
  * | 8629257 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 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
  |\
  * | 8629257 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

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


figures/editor-open.png
Figure 2.15: Initial opening of tutorial file under git in LTC Editor


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/editor-filter-small1.png   figures/editor-filter-small2.png   figures/editor-filter-small3.png

Figure 2.16: Effect of hiding “small” changes first (middle) and then also deletions (right)


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.


figures/commit-graph.png

Figure 2.17: Example of commit graph


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.


figures/editor-select-authors.png

Figure 2.18: Selecting authors for filtering
 
figures/editor-limit-authors.png
Figure 2.19: Effect of limiting authors to Roger Sherman and Thomas Jefferson after clicking “Update”


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.


figures/editor-select-rev.png

Figure 2.20: Selecting revision for filtering
 
figures/editor-limit-rev.png
Figure 2.21: Effect of going back to first revision after clicking “Update”


To remove the limit by revision number, simply erase the text in the field “Start at revision:” and click “Update” again.


figures/editor-select-date.png

Figure 2.22: Selecting date for filtering
 
figures/editor-limit-date.png
Figure 2.23: Effect of limiting history to date of third version after clicking “Update”


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.


figures/editor-condense-on.png

Figure 2.24: Effect of condensing authors: ignoring the 5th version by Roger Sherman
 
figures/editor-condense-before.png  figures/editor-condense-after.png
Figure 2.25: Example of markup change before (left) and after (right) condensing authors


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.


figures/editor-modified.png

Figure 2.26: After editing the text as John Adams


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.


figures/commit-cmd-line.png

Figure 2.27: Updated commit graph after command line commit


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.


figures/editor-commit-no-comment.png

Figure 2.28: Committing a comment but not showing it as an addition
 
figures/editor-commit-comment.png
Figure 2.29: Committing a comment and showing it as an addition


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.


figures/editor-merge-conflict.png

Figure 2.30: Git conflict markers in merged file


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
  [...]
  
  <<<<<<< 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 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


figures/editor-merge-resolve.png

Figure 2.31: After resolving conflict, committing, and updating in LTC Editor


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

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.


figures/svn-emacs-open.png
Figure 2.32: Starting ltc-mode in Emacs with tutorial file under svn


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.


figures/svn-adams.png

Figure 2.33: Emacs info buffer after setting current author to “adams”


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.


figures/svn-emacs-LTC-menu.png

Figure 2.34: Opening the LTC menu from the mode line in Emacs


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/svn-emacs-filter-small1.png   figures/svn-emacs-filter-small2.png   figures/svn-emacs-filter-small3.png

Figure 2.35: Effect of hiding “small” changes first (middle) and then also deletions (right)


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.


figures/svn-emacs-limit-authors.png

Figure 2.36: Effect on commit graph of limiting authors to “sherman” and “jefferson”


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.


figures/svn-emacs-limit-rev.png

Figure 2.37: Effect on commit graph of going back to first revision


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.


figures/svn-emacs-limit-date.png

Figure 2.38: Effect on commit graph of limiting history to date of third version


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


figures/svn-emacs-condense-on.png

Figure 2.39: Effect of condensing authors: ignoring the fifth version by Roger Sherman


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.


figures/svn-emacs-condense-before.png  figures/svn-emacs-condense-after.png

Figure 2.40: Example of markup change before (left) and after (right) condensing authors


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.


figures/svn-emacs-modified.png

Figure 2.41: After editing the text as “adams”


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


figures/svn-emacs-merge-conflict.png

Figure 2.42: Subversion conflict markers in merged file


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


figures/svn-emacs-merge-resolve.png
Figure 2.43: After resolving conflict and updating in Emacs


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


figures/svn-editor-open.png
Figure 2.44: Initial opening of tutorial file under svn in LTC Editor


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/svn-editor-filter-small1.png   figures/svn-editor-filter-small2.png   figures/svn-editor-filter-small3.png

Figure 2.45: Effect of hiding “small” changes first (middle) and then also deletions (right)


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


figures/svn-commit-graph.png

Figure 2.46: Example of commit graph


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.


figures/svn-editor-select-authors.png

Figure 2.47: Selecting authors for filtering
 
figures/svn-editor-limit-authors.png
Figure 2.48: Effect of limiting authors to to “sherman” and “jefferson” after clicking “Update”


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.


figures/svn-editor-select-rev.png

Figure 2.49: Selecting revision for filtering
 
figures/svn-editor-limit-rev.png
Figure 2.50: Effect of going back to first revision after clicking “Update”


To remove the limit by revision number, simply erase the text in the field “Start at revision:” and click “Update” again.


figures/svn-editor-select-date.png

Figure 2.51: Selecting date for filtering
 
figures/svn-editor-limit-date.png
Figure 2.52: Effect of limiting history to date of third version after clicking “Update”


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.


figures/svn-editor-condense-on.png

Figure 2.53: Effect of condensing authors: ignoring the 5th version by Roger Sherman
 
figures/svn-editor-condense-before.png  figures/svn-editor-condense-after.png
Figure 2.54: Example of markup change before (left) and after (right) condensing authors


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.


figures/svn-editor-modified.png

Figure 2.55: After editing the text as “adams”


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


figures/svn-editor-merge-conflict.png

Figure 2.56: Subversion conflict markers in merged file


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


figures/svn-editor-edit-conflict.png
Figure 2.57: Resolving subversion conflict through editing file


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.


figures/svn-editor-merge-resolve.png
Figure 2.58: After resolving conflict and updating in LTC Editor


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.