Censorship banner.png

Guri:Latex and Subversion

From Wiki - Hipatia
Jump to: navigation, search
The help pages are provided by Hipatia volunteers to help wiki contributors.
Help index: Mediawiki Server configuration LaTeX Streaming Templates

Search for help:


Guri

Guri logo.png

Educazione e conoscenza libera

Risorse

Sito Ufficiale
Notizie ed eventi
Galleria Fotografica
Video
Mailing List
IRC
Ufficio

Attività correnti

Itis 2012
La Bottega dei Saperi
Cluster
Attività - Eventi passati

Offrici una birra
Contatti

Mailing List
IRC
Contattaci

Partecipanti attivi
Argon

Palby

Lio

Jucar

GlaxY
Stato: Attivo
Copyleft.svg Copyleft
All wrongs reversed


Introduction

This is a short reference about how to configure a Debian GNU/Linux server to use Subversion in conjunction with Latex, using the Apache web server. Following this guide you should be running a subversion repository on a server with shell access. Of course all this software are free (as in freedom). This guide is tailored for our purposes and does not cover a general Subversion usage, neither for complex projects. It will not explain how to tag some files, develop different branches for the projects and so on.

Packages needed

On your remote server you need:

  • Apache
  • libapache2-svn

In your local machine you need:

  • Subversion
  • Texlive
  • Texlive-latex-extra
  • cjk-latex

Latex

LaTeX is a document markup language and document preparation system for the TeX typesetting program. The term LaTeX refers only to the language in which documents are written, not to the editor used to write those documents.

LaTeX is distributed under a free software license, the LaTeX Project Public License (LPPL). The LPPL is not compatible with the GNU General Public License, as it requires that modified files must be clearly differentiable from their originals (usually by changing the filename).The LPPL is DFSG compliant.

Thanks to Latex it is possible to write many kind of documents (letters, article, books, slides, reports) focusing just on the content, without being distracted by the layout of the document. Latex provides many powerful instruments to write formulas and to include graphics, figures and tables. The output of a Latex file can be compiled into dvi, pdf or other formats. To have a short Latex reference you can read the guide we made to realize our book, in which you can find the commands we used for the document and how to replicate our work.

Subversion

Apache Subversion (henceforth SVN) is a libre software versioning and a revision control system used to manage developing projects, released under the Apache License. Since even small modifications can be tracked over time Subversion is very useful also for Latex files, providing also an easy way to get the source files of the Latex document.

For a complete SVN manual, please refer to this guide.

Basic Subversion review

We report here a short sum up of the main commands of Subversion, with the aim to introduce you to its main features. In this way, everyone who wants to help us can get a short starting guide <ref name="svnbook"> For a complete reference please read the official Subversion documentation </ref>.

Subversion provides a repository for content, along with a database that tracks all the contents and every modification which is made to that. The remote repository serves as a common place to put all the content in order to provide to anyone the same files in all their versions. Every user who has access to the repository can then make a local copy of the whole tree of directories and files and start working on them, syncing with the remote repository to commit his/her changes to the files.

When such a change is committed, Subversion stores some important information about that:

  • the user who made the change
  • a description of the change (given by the user)
  • when the change was committed
  • which files (or directories) were changed

For each change subversion increments the repository version number, tracking the changes for the whole directory instead of only for files (as CVS does).

Server preparation

This reference assumes that you already have a running server with Apache installed.

First thing to do is to install Subversion: <syntaxhighlight lang="bash" enclose="div">apt-get install subversion</syntaxhighlight>

otherwise you can install it as an Apache module by doing: <syntaxhighlight lang="bash" enclose="div">apt-get install libapache2-svn</syntaxhighlight> this command provides the subversion module mod_dav_svn, which permits to connect to repository though a http connection. For our purposes we chose this way. Now let's make a directory for the repository: <syntaxhighlight lang="bash" enclose="div">mkdir /var/svn mkdir /var/svn/guri</syntaxhighlight> the last directory we created is where we are going to host our project files.

Now we have to grant write access to the Apache user (www-data): <syntaxhighlight lang="bash" enclose="div">chown www-data:www-data -R /var/svn/guri</syntaxhighlight> this command changes the owner of the directory /var/svn/guri recursively. Then we change the permissions in order to remove read access to every one other than the Apache user: <syntaxhighlight lang="bash" enclose="div">chmod 770 -R /var/svn/guri</syntaxhighlight>

Let's configure Apache to grant access to authenticated users, in order to track who is committing changes to the repository:

Configure Apache

On Debian Apache by default uses virtual hosts. Now you need to configure Apache to point to the correct path to the repository. Add this lines to the correct file in /etc/apache2/sites-available/ <syntaxhighlight lang="text" enclose="div"># Uncomment this to enable the repository

DAV svn

# Set this to the path to your repository
#SVNPath /var/svn
 # Alternatively, use SVNParentPath if you have multiple repositories under
 # under a single directory (/var/lib/svn/repo1, /var/lib/svn/repo2, ...).
 # You need either SVNPath and SVNParentPath, but not both.
SVNParentPath /var/svn/guri
SVNListParentPath on

If we want to require authentication to the repository, we need to add to the same file the following lines:

# Basic Authentication is repository-wide.  It is not secure unless
  # you are using https.  See the 'htpasswd' command to create and
  # manage the password file - and the documentation for the
  # 'auth_basic' and 'authn_file' modules, which you will need for this
  # (enable them with 'a2enmod').
AuthType Basic
AuthName "Subversion Repository"
AuthUserFile /etc/apache2/dav_svn.passwd
Require valid-user</syntaxhighlight>

Note: in this way you have configured the server just for http connection. If you want to provide authentication also for secure connections (requires openssl installed and configured), you need to repeat this lines in the file, configuring them for openssl support.

Now we have to enable the site, by creating a symlink in /etc/apache2/sites-enabled: <syntaxhighlight lang="bash" enclose="div">cd ../sites-enabled ln -s ../sites-available/svn</syntaxhighlight>

Another thing to do before proceeding with the creation of the repository is to create users for it. <syntaxhighlight lang="bash" enclose="div">htpasswd2 -c /etc/apache2/dav_svn.passwd user</syntaxhighlight> and supply to user a password.

In addition, since Debian uses a different way to enable modules from the standard Apache way, we need to enter this command: <syntaxhighlight lang="bash" enclose="div">cd /etc/apache2/mods-available echo "LoadModule dav_svn_module /usr/lib/apache2/modules/mod_dav_svn.so" > dav_svn.load echo "LoadModule authz_svn_module /usr/lib/apache2/modules/mod_authz_svn.so" > authz_svn.load</syntaxhighlight>

If the libapache2-svn module installation haven't already did so, we need to enable this modules, by creating a symlink in /etc/apache2/mods-enabled: <syntaxhighlight lang="bash" enclose="div">cd ../mods-enabled ln -s ../mods-available/dav.load ln -s ../mods-available/dav_svn.load</syntaxhighlight>

When we have finished we need to enable the site. Use the command: <syntaxhighlight lang="bash" enclose="div">a2ensite name_of_the_site</syntaxhighlight> where name_of_the_site is the name you gave in sites-enabled

Finally we can make Apache load the new configuration with the command: <syntaxhighlight lang="bash" enclose="div">/etc/init.d/apache2 reload</syntaxhighlight>

Creating an empty repository

After the server has been configured we can proceed creating the repository. Log in to the server. Let's start creating the svn repository: <syntaxhighlight lang="bash">svnadmin create /path/to/your/repository/</syntaxhighlight> where /path/to/your/repository/ is the path where you want your repository to be placed in. Now you can prepare all the file you want in the repository in a directory and then import them to the repository. Let's suppose they are in /path/to/local/files in your server: <syntaxhighlight lang="bash">svn import -m "initial import" /path/to/local/files file:///path/to/repository/</syntaxhighlight> where file:///path/to/repository/ is the complete path to the svn repository directory (to be put after file://. The option -m "some text" is given to provide a description of the change made to the repository. The text of the description must be passed between the double quotes.

Once you have created the repository, remember to restart Apache and to test it. <syntaxhighlight lang="bash">/etc/init.d/apache2 restart</syntaxhighlight>

Now you have a working repository. The following sections will describe how to configure the repository and how to checkout files from it to your local machine.

Checking out the repository

To get a local copy of the online repository enter this command only the first time on your machine: <syntaxhighlight lang="bash">svn checkout url/to/the/server/repository name</syntaxhighlight> where name is the name you want to give to the root directory of the local copy of the repository.

Basic subversion usage

This Subversion and Latex integration is meant to make easier the cooperative writing of a document (such as our book). In fact this way provides an online common repository which everyone can get an updated copy of the work from, then review the document and modify it, and finally commit his/her changes to update the repository, in order to have an online updated version. (Of course thanks to Apache it is possible to restrict the access to the repository only to authenticated users).

Once you have checked out a local copy of the repository, you can start working on it. From this time on you don't have to check out every time you want to sync your local copy with the new changes to the remote one. You have just to update your local repository: <syntaxhighlight lang="bash">svn up</syntaxhighlight> after you changed to the root directory of your local copy. Subversion will update your repository with the remote content. The output is what files are being update. For example:

U cap1.tex
A cap14.tex
D cap13-a.tex
G cap12.tex

U stands for Updated, A for Added, D for Deleted and G for the file as been updated but you have local changes that are not present in the remote repository, but this changes don't conflict.

Changes to the structure of the directories

If you make changes to a file which is both present locally and remotely, you can just do them with you text editor. If you make changes to the structure of directories (adding new files, deleting files...) you have use some commands of Subversion. <syntaxhighlight lang="bash">svn add files svn delete files</syntaxhighlight> will tell subversion to add or delete file the next time you commit changes to the remote repository. To create a copy of file called foo and schedule the addition of foo to the repository the next time you commit, use: <syntaxhighlight lang="bash">svn copy files foo</syntaxhighlight> To move file to foo, use the following command: <syntaxhighlight lang="bash">svn move files foo</syntaxhighlight> This creates a copy of file called foo. Then, the next time you commit, foo will be added and file will be deleted.

A good practice is to review all the changes you made before committing to the remote repository. Change to the root of your local copy of the repository and issue: <syntaxhighlight lang="bash">svn status</syntaxhighlight> Subversion will return a list of file, preceded by a letter, indicating what kind of changes has been done to the file:

M file 
A file 
D file 
C file 

where:

M: file has been modified since last updating;
A: file will be added to the repository;
D: file will be deleted from the repository;
C: file conflicts with an update.

For a more advanced usage, Subversion provides an integration with the GNU diff program, which shows differences between files, line by line. Change to the root directory of your local copy of the repository and type: <syntaxhighlight lang="bash">svn diff</syntaxhighlight> this will return a list of the modified files.

Committing to the repository

When committing your changes to the remote repository, subversion will record the above mentioned data (who, what, where and when) and then increment the revision number of the whole repository, even if you just changed one file. With this method it is possible to track all the changes that have been made to the files over time, in order to get them back if needed. It is advised to commit very often, in order to be able to track every change, because in the future everything could be useful. When you are ready to commit, you have to enter this command for every file you want to sync with the repository: <syntaxhighlight lang="bash">svn commit -m "Description of change" file</syntaxhighlight> This will record the file in your working copy and then the author (and date) of the changes in the repository database.

Subversion integration with Latex

After this short introduction to the subversion commands which will be useful for our purpose of writing the book, we will deal with the integration with Latex. Tracking revision information on Latex files is possible thanks to the svn-multi Latex package. In Debian GNU/Linux you can find this in the package texlive-latex-extra in the main repository. We chose this package among others because it is very useful if you work with multiple Latex files (e.g. the chapters of our book) and then include them in a root file. Thanks to this package we can now register revision information in the documents and have them displayed<ref name="Latex">Source: Kalderon, Mark Eli. "Latex and Subversion". The PracTEX Journal, 2007, No. 3, p.12 .</ref>.

For every .tex file you want to put on the repository, include these lines in the preamble: <syntaxhighlight lang="latex" enclosure="div"> \usepackage{svn-multi} % loads the package svn-multi \svnidlong % stores revision information in the variables below {$LastChangedBy$} % author of the change {$LastChangedRevision$} % revision number for the change {$LastChangedDate$} % date of the change {$HeadURL$} % url of the changed file</syntaxhighlight>

and these lines in the document environment, (whose meaning will be explained here): <syntaxhighlight lang="latex" enclosure="div">\footnote{Last changed by: \svnauthor</font>; Revision: \svnrev; Last changed on: \svndate; URL: \url{\svnurl}}</syntaxhighlight>

If you want to check in detail what changes were made to a .tex file, you use this command: <syntaxhighlight lang="bash">svn log -r n file.tex</syntaxhighlight> where n is the revision number.

To make the commands specified in the preamble interact with Subversion, we need to enter this command only once for each .tex file: <syntaxhighlight lang="bash">svn propset svn:keywords ’LastChangedBy LastChangedRevision LastChangedDate HeadURL’ file.tex</syntaxhighlight> from this time on, whenever you will update or commit the repository, these information will be stored.

Revision information in the document

Now that we set up Subversion and configured our Latex files, it is a good idea tho show in every document (e.g. the one you get when you compile the latex files) the revision information. These command, which come from the svn-multi package, will provide these features: <syntaxhighlight lang="latex">\svnauthor</syntaxhighlight> displays the author registered by: <syntaxhighlight lang="latex">{$LastChangedBy$}</syntaxhighlight> in the preamble, who is the one who made the last change to the document. The command: <syntaxhighlight lang="latex">\svnrev</syntaxhighlight> displays the revision number registered by: <syntaxhighlight lang="latex">{$LastChangedRevision$}</syntaxhighlight> in the preamble. This is the revision number of the last committed change to the document. The command: <syntaxhighlight lang="latex">\svndate</syntaxhighlight> displays the date registered by: <syntaxhighlight lang="latex">{$LastChangedDate$}</syntaxhighlight> in the preamble. This is the date of the last committed revision in the repository. The command: <syntaxhighlight lang="latex">\svnurl</syntaxhighlight> displays the URL registered by: <syntaxhighlight lang="latex">{$HeadURL$}</syntaxhighlight>

In the previous section it is explained how to include them in a footnote, in order to have them displayed in the Latex generated document. To include this information in a Latex compiled document, you have to run Latex twice on it. The first time a .svn file will be generated. On the second run of Latex, the contents of the .svn file will be added to the document (the same procedure for index and bibliography files).

Quick sum up

Now that you learned how to work with Latex and Subversion, you can find here a quick sum up dealing with how to proceed to add the tex files of the different chapters to the repository.

The first time, check up the repository to get a local working copy on your machine: <syntaxhighlight lang="bash">svn checkout URL/book book</syntaxhighlight>

If it is not the first time and you already have a copy of the repository, update it. Change to the directory you wish to update (e.g the root directory of the repository) and run: <syntaxhighlight lang="bash">svn up</syntaxhighlight> Then create the chapter tex file you want to add, including these command lines in the preamble, and the commands for the footnote. Save the file as a .tex (e.g. chapt1.tex) file and then add it to the Subversion schedule for the next commitment: <syntaxhighlight lang="bash">svn add chapt1.tex</syntaxhighlight> then commit the addition: <syntaxhighlight lang="bash">svn commit -m "Added Chapter 1 as chapt1.tex" chapt1.tex</syntaxhighlight> Set the Subversion keywords by entering: <syntaxhighlight lang="bash">svn propset svn:keywords ’LastChangedBy LastChangedRevision LastChangedDate HeadURL’ chapt1.tex</syntaxhighlight> Update again: <syntaxhighlight lang="bash">svn up</syntaxhighlight> And commit the changes: <syntaxhighlight lang="bash">svn commit -m "Svn keywords set on chapt1.tex" chapt1.tex</syntaxhighlight>

Now, if you run Latex on the document twice, you should see the information in the footnote.

External Links

<references/>