Figure 3.1: A typical work cycle for a version controlled file and when using LaTeX Track Changes
| Up | Next | Prev | PrevTail | Tail |
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.
| Up | Next | Prev | PrevTail | Front |
