Thursday, October 6, 2011

Latex listings definitions for modeling languages

Seems as if the Latex listings package does not let me go...

After blogging about how to nicely format listing with the Latex listings package, using a Eclipse syntax coloring style, and solving some tiny yet annoying problems with hyphenations of inline listings and labels within listings, I have compiled a couple of language definitions for (Eclipse) modeling languages.

Actually, these definitions are rather small, as they basically contain a list of keywords of a language. Besides the language definition, I usually define a command for quickly writing some inline listing code. I have explained this command in an earlier blog posting.

So, here are the definitions for QVT, ATL, ETL, Xtend, and Xtext.

QVT -- Query, View, Transformations

\lstdefinelanguage{QVT}{
  morekeywords={
% relations:  
   checkonly, domain, enforce, extends, implementedby, import, 
  key, overrides, primitive, query, relation, top, 
  transformation, when, where
% operational: 
 Bag, Collection, Dict, OrderedSet, Sequence, Set, Tuple, abstract, 
access, and, any, assert, blackbox, break, case, class, collect, 
collectNested, collectOne, collectselect, collectselectOne, 
composes, compute, configuration, constructor, continue, datatype, 
default, derived, disjuncts, do, elif, else, end, endif, 
enum, except, exists, extends, exception, false, forAll, forEach , 
forOne, from, helper, if, implies, import , in, inherits, init, 
inout, intermediate, invresolve, invresolveIn, invresolveone, 
invresolveoneIn , isUnique, iterate, late, let, library, literal, 
log, main, map, mapping, merges, metamodel, modeltype, new, not, 
null, object, one, or, ordered, out, package, population, primitive, property, 
query, raise, readonly, references, refines, reject, resolve, resolveIn, resolveone, 
resolveoneIn, return, select, selectOne, sortedBy, static, 
switch, tag, then, transformation, true, try, typedef, unlimited, 
uses, var, when, where, while, with, xcollect , xmap, xor, xselect 
 },
 keywordstyle=[2]{\textbf},
 morecomment=[l]{--},
 morestring=[b]{'},
 tabsize=4}
 
\newcommand{\lstQVT}[1]{\lstinline[language=QVT,breaklines=true,basicstyle=\listingsfontinline,mathescape,literate={\-}{}{0\discretionary{-}{}{}}]§#1§}

ATL -- Atlas Transformation Language

\lstdefinelanguage{ATL}{
  morekeywords={true,false,
   Bag,Set,OrderedSet,Sequence,Tuple,Integer,Real,Boolean,String,TupleType,
  not,and,or,xor,implies,module,create,from,uses,helper,def,context,
  rule,using,derived,to,mapsTo,distinct,
  foreach,in,do,if,then,else,endif,let,
  library,query,for,div,refining,entrypoint},
 keywordstyle=[2]{\textbf},
 morecomment=[l]{--},
 morestring=[b]{'},
 tabsize=4}
 
\newcommand{\lstATL}[1]{\lstinline[language=ATL,breaklines=true,basicstyle=\listingsfontinline,mathescape,literate={\-}{}{0\discretionary{-}{}{}}]§#1§}

ETL -- Epsilon Transformation Language

\lstdefinelanguage{ETL}{
  morekeywords={true,false,
   pre, rule, operation, 
  var, transform,to,
  select, selectOne, all,
  @greedy,
  for,if,else,
  not,and,or,
  Any,String,Boolean,
  true,false,return},
 keywordstyle=[2]{\textbf},
 morecomment=[l]{//}, 
 morecomment=[s]{/*}{*/}, 
 morestring=[b]",
 tabsize=4}
 
\newcommand{\lstETL}[1]{\lstinline[language=ETL,breaklines=true,basicstyle=\listingsfontinline,mathescape,literate={\-}{}{0\discretionary{-}{}{}}]§#1§}


Xtend 1.0.1

\lstdefinelanguage{Xtend}{
 morekeywords={cached,case,default,extension,false,import,JAVA,WORKFLOWSLOT,let,new,null,private,create,switch,this,true,reexport,around,if,then,else,context},
 keywordstyle=[2]{\textbf},
 morecomment=[l]{//}, 
 morecomment=[s]{/*}{*/}, 
 morestring=[b]",
 tabsize=4}
 
\newcommand{\lstXtend}[1]{\lstinline[breaklines=true,language=Xtend,basicstyle=\listingsfontinline,mathescape,literate={\-}{}{0\discretionary{-}{}{}}]\S#1\S}

Xtext 1.0.1

\lstdefinelanguage{Xtext}{
 morekeywords={grammar, with, hidden, generate, as, import, returns, current, terminal, enum},
 keywordstyle=[2]{\textbf},
 morecomment=[l]{//}, 
 morecomment=[s]{/*}{*/}, 
 morestring=[b]",
 tabsize=4}
 
\newcommand{\lstXtext}[1]{\lstinline[breaklines=true,language=Xtext,basicstyle=\listingsfontinline,mathescape,literate={\-}{}{0\discretionary{-}{}{}}]\S#1\S}

If you need a new language definition for your own Xtext based modeling or programming or domain specific or whatever language, it is very easy to retrieve the tokens of the language. Within the project of your Xtext grammar file, a special ANTLR file containing all the tokens will be generated. You will find that file in
src-gen//parser/antlr/internal/Internal.tokens

Xpand

[Updated February 2012] A friend of mine (thank you, Jens!) just sent me a new definition for Xpand:
\lstdefinelanguage{Xpand}{
 morekeywords={IMPORT, DEFINE, ENDDEFINE, LET, ENDLET, FOR, FILE, ENDFILE, ITERATOR, FOREACH, AS, IF, ENDFOREACH, ENDIF, EXPAND, INSTANCEOF, USING, SEPARATOR, CSTART, CEND, PROTECT, ENDPROTECT, ID, EXTENSION, ERROR, WARNING, INFO},
 inputencoding=latin1,
 extendedchars=true,
 % note: first and last guillemot of comments will not appear in comment style, guillemots are not possible in delimiters
 morecomment=[s]{REM}{ENDREM},
 morestring=[s]{"}{"},
 % for use with UTF-8
 literate={«}{\guillemotleft}{1}
          {»}{\guillemotright}{1}
}
This definition is a slight modification of the definitions posted in the Eclipse M2T forum (and also at the Rtsys Group Wiki, Uni Kiel) a while ago.

Saturday, July 23, 2011

Pimp your Kindle

I really like the idea of ebooks. These E Inks displays have an astonishing quality: I was very surprised to be even able to read a Din A4 PDF, downsized to fit the 6 inch display of a Kindle---although it is hard to read.

So, as I like the idea, I bought an ebook reader. I decided to buy Amazon's Kindle reader, as there are a lot of ebooks available thanks to Amazon. While I'm still enthusiastic about the really good display, I'm completely disappointed in the Kindle software. Most of all, ebooks are always displayed using justified text. But since hyphenation is not supported, this leads to really ugly layouts. The combination of justified text without hyphenation is a show-stopper!

So, I tried to figure out a solution to that problem. Fortunately, I found a Kindle version of the FBReader (fbkindle), which is not too complicated to be installed on the Kindle. FBReader displays ebooks in epubs format, and it provides hyphenation as known from TeX. Really nice! This blog entry summarizes the necessary steps along with a short presentation of additional tips.

Motivation


Before explaining the necessary steps to install FBReader, I just want to show you the differences between the original Kindle AZW reader and the FBReader.


Figure 1: Comparison of original Kindle AZW reader (left) and FBKindle epub reader (right)

Figure 1 shows two scans of the Kindle. I have used Melville's Moby Dick (free Amazon vs. Feedbooks version). It is freely available, not only at Amazon but also at some other ebook sites, and besides it is one book I always wanted to read. While some of the differences stem from the information stored in the ebooks themselves, other things are only (missing) features of the reader software. However, in my experience, the example is rather a typical one: I've found much worse (free) ebooks, and also slightly better ones. Let's go into the details:

The first obvious thing is hyphenation. As said above, the Kindle cannot hyphenate, which is a real problem due to the justified text layout used. The worst thing about that is, that it sometimes produces pseudo paragraphs, as you can see in the circle marked with "1a" (and also in the second line of the following chapter). FBReader supports hyphenation (circle marked "1b"). This is a software problem and no missing feature of the ebook. That is: No AZW ebook will support hyphenation, at least not with the current Kindle reader software.

The other differences stem from the ebooks themselves. As the headings demonstrate ("2a" vs. "2b"), the AZW book does not correctly layout the heading. That is, the title of the heading is formatted as plain text. While this is only ugly, I have found free AZW books with footnotes inserted into the plain text without anything indicating the footnote (the free version of Hegel's Logik). An even worse problem is, that some books do not come with no table of contents, and no chapter markers. As indicated with the "3a", the AZW version of Moby Dick does not provide any chapter markers, while the EPUB version does ("3b"). Actually, with out these markers and TOC, an ebook like Moby Dick is not usable at all. Sometime, it is possible to generate TOCs with tools such as Calibre, but, hey guys, I want to read a book, not create and fix it.

While the FBReader provides a much better layout, I really miss one feature the Kindle reader software provides: dictionary integration. This is a really cool feature, and although is is listed as a planned feature for FBReader, is is not implemented yet. At the moment, I'm using my Android's ColorDict to help me out, just as I used to do when reading books printed on paper. Weird! The dictionary coming with Kindle is an english dictionary, and I have installed a free german-english dictionary, as explained below.

Overview



Figure 2: Kindle root folder after installing 3rd-party software



Figure 2 shows my Kindle root folder, with some subfolder created by the software described below. It contains a folder with the collections database and some configuration files of the Kindle AZW reader (1), as well as your content (2). All third-party software is installed on the Kindle by first mounting the Kindle to your PC or Mac, and then by copying some installation file into the mounted root folder (0) (sometimes, this folder is referred to as "/mount/us", on MAc OS X, it is the root folder when you mount your Kindle). Then, the Kindle needs to be rebooted, and when starting up, the software is installed automatically (and the installer is removed). The installer usually creates a folder in the Kindle's root folder.

Frankly, I really hate to install hacks on the Kindle. So, please Amazon, improve your Kindle software! The hardware is really cool, but the software is rotten! Meanwhile, here's how to install alternative software. Frankly, this is not the first list, and you will find similar lists on the web. One of the best places is the mobileread.com forum, and a list of hacks can be found there as well.

The quick installation should only serve as a short guide, please read the documentation linked to before installing anything. You may lose warranty when applying the hacks described below, or you may break your Kindle. Use it on your own risk!

"Jailbreak" for Kindle


A small "security" feature built into the original Kindle software prevents arbitrary 3rd-party software to be installed. So, we first need a special piece of software, to work around this issue. This is the "jailbreak". There exists different software versions of the original Kindle software, and they require different software hacks as well. The Kindle (at the time writing this post) comes with version 3.1. Yifan Lu has published a jailbreak for that version:

Download
Yifan Lu's website: Kindle 3.1 Jailbreak
Quick install
  1. Unpack kindle-jailbreak.zip
  2. Copy installer update_jailbreak_*_*_install matching your kindle version into Kindle's root folder (Fig. 2 (0))
  3. Restart Kindle (Home, Menu - Settings, Menu - Restart
Documentation
See download location.


The ad-base Kindle is not that easy to jailbreak, and frankly: if you choose to save that little money and accept ads, then do not complain about the original software. However, according to Yifan Lu, some non-ad Kindles also come with the new 3.2.1 software, so here's the link on how to jailbreak this version as well (I didn't try it myself): Yifan Lu: Kindle 3.2.1 Jailbreak (also see thread at mobilreader).

Launchpad


In order to be able to start 3rd-party software, you need some launcher software (as there is no command line available by default). Launchpad is a small utility, which enables the user to execute commands after pressing a defined sequence of keys, as demonstrated on this Youtube video.. Launchpad is available via the mobileread.com forum:
Download
http://www.mobileread.com/forums/showthread.php?t=97636
Quick install
  1. Download and unpack lpad-pkg-001c.zip
  2. Copy installer update_launchpad_*_*_install.bin matching your kindle version into Kindle's root folder (Fig. 2 (0))
  3. Restart Kindle (Home, Menu - Settings, Menu - Restart
Documentation
See download location.

After successfully installing launchpad, a new subfolder should have been created in your Kindle's root folder, as shown in Figure 2 (3). Inside that folder, you will find the configuration files *.ini with defined key sequences and commands to be executed. Note that you always have to press Shift before the defined key sequences, and that you have to press all keys one after the other and not all at the same time.

FBReader (FBKindle)


Now we are ready to install FBReader, in order to be able to read DRM-free EPUB books on your Kindle. There exist two versions: FBReader by Dzha and FBKindle by Andy Wooden. I have chosen FBKindle , as it runs vis-a-vis with the original Kindle reader software, and one can easily switch between both version using a keyboard shortcut. Both versions are ports of the original C++ FBReader software. Unfortunately, this version has not been updated for quite some time, especially because nice things such as dictionary integration are still missing. Note: There also exists a sourceforge project called FBKindle, unfortunately it does not contain any files yet.

Download
http://www.mobileread.com/forums/showthread.php?t=107371
Quick install
  1. Download and copy fbKindle-bin.tar.gz into Kindle's root folder (Fig. 2 (0))
  2. Add the following lines to your launchpad/launchpad.ini file (or create launchpad/fbreader.ini containing these line):
    [Actions]
    F R = !/mnt/us/fbKindle/goqt.sh FBReader &
    U T = !cd /mnt/us; tar zxvf fbKindle-bin.tar.gz; rm fbKindle-bin.tar.gz;echo 101 >/proc/eink_fb/update_display
  3. Restart Kindle (Home, Menu - Settings, Menu - Restart) in order to activate new key sequences


  4. Activate FBKindle installation key-sequence, i.e. quickly press Shift, then U, and then T. This will unpack the FBKindle archive, and install FBReader in a subfolder fbKindle on your Kindle, as shown in Fig. 2 (4)


  5. Now, start FBKindle via Shift, then F, and then R. Actually, you will have to restart FBKindle every time after restarting your Kindle!


Documentation
See download location,german guide at e-reader-forum.de.
Unfortunately, the library management of FBReader/FBKindle is as bad as the the management functions of the original Kindle software. Seriously, I'm wondering how Amazon (or in that case the FBReader programmers) expects user's to install and manage more than 20 books. Anyways, the menu button will activate the FBReader menu, and from there on it should be self explaining (shortcuts are documented on the pages linked to above). The nice thing about FBKindle is, that you can easily switch forth and back between FBReader and the original Kindle software by pressing shift and alt simultaneously.

Free dictionaries for the Kindle software

Back to the original Kindle software. A really nice feature of the Kindle reader is that is comes with integrated dictionary support. Since I usually need english to german translations, I was looking for an english-german dictionary. There exists a lot of free dictionaries, and I found a free solution for the Kindle as well. Michael Sheldon (kudos to Michael) has converted free dictionaries into the mobi-format, which is supported by Kindle.
Download
http://mikeasoft.com/~mike/kindle-dicts/
Quick install
  1. Download dictionary file, e.g., English-German.mobi, and place it inside your documents folder
  2. Select this dictionary as your primary dictionary via menu - Settings, menu - Change Primary Dictionary
Documentation
Michael Sheldon's blog

Custom Screensaver

Not really necessary, but nice to have: screensaver with your own pictures. I really do not understand why Amazon does not directly support that feature. So, you have to firstly install a 3rd party screensaver hack. Then, you can copy your own pictures into a folder of the screensaver software.
Download
http://www.mobileread.com/forums/showthread.php?t=97636
Quick install
  1. Download and unpack kindle-ss-0.22.N.zip
  2. Copy installer update_ss_0.22.N_*_install.bin matching your kindle version into Kindle's root folder (Fig. 2 (0))
  3. Restart Kindle (Home, Menu - Settings, Menu - Restart
  4. Installer should have created a folder linkss, as shown in Figure 2 (5). Copy your images (600x800 pixels) into the created folder linkss/screensavers.
  5. Restart Kindle (Home, Menu - Settings, Menu - Restart) in order to activate new images.
Documentation
See download location.

Wednesday, May 11, 2011

Fun with Multiple VPN Connections on Mac OS X

Disclaimer: Frankly, I'm neither a Unix nerd nor a network freak. Maybe this is why I prefer using Mac OS X: In most cases things are simply working, or at least some nice graphical interfaces guides me through the network configuration jungle. So, use my tips on your own risk and feel free to write me a comment, if you can explain things better :-)

Virtual private network (VPN) are one of these things making me nervous without a nice GUI. Fortunately, OS X directly supports all the protocols I need (and thank you, Apple, for supporting the Cisco protocol as of OS X version 10.6). Setting up a VPN is as simple as installing a printer. Maybe even simplier ;-)

However, there are always new problems challenges waiting, and one of these challenges is the use of multiple VPNs simultaneously. I have the following situation: I can only connect to some local network, which does not allow any internet connections. For that purpose, I have to use a VPN "T" -- the VPN server "TServer" (names are only for simplify reading) is more or less the only thing accessible from that internal network. So, every connection to the internet runs through this VPN.

Now, I have to connect to a server "S", which only accepts connections from a local network, I call it "FNet". And my VPN server "TServer" is not part of this network "FNet". In order to access this server, I usually start another VPN "F" (with another VPN-server "FServ", virtually placing me (and my machine's IP address) inside the local network "FNet". Unfortunately, I can only connect to "FServ" via the first VPN. So, the question is, how to set up the second VPN?

Fortunately, it is possible to simply connect to two VPNs simultaneously. All you need to do is simply to configure both VPNs in your network settings.
Fig. 1:Simultaneously connect to multiple VPNs
I can then firstly connect to the VPN "T", and when this connection is establish I can use it to connect to the second VPN "F". Figure 1 shows the VPN menu in the system menu bar (OS 10.6, with elder versions, things look a bit different, as explained here).

Well, this is the easy part. The harder part is to tell the applications which VPN to use. This problem is (almost) the same problem as using different network interfaces (e.g., use the Ethernet connection for some tasks, and a WLan connection for others), as the VPNs create virtual network interfaces. So, it's time to start the console... ifconfig prints out the available network interfaces. E.g., my first VPN "T" has created a new interface called ppp0:

ppp0: flags=8051 mtu 1444
 inet 111.123.123.144 --> 111.123.123.166 netmask 0xffff0000

It is not that important to know exactly what you see here. The only important thing is the number 111.123.123.144 which is the IP-address assigned to my machine for VPN "T".

After connecting to the second VPN "F", another interface is available, representing the second VPN:

utun0: flags=8051 mtu 1280
 inet 222.123.123.155 --> 222.123.123.177 netmask 0xffffff00

Within this second VPN, I've got the IP 222.123.123.155.

So, I have two interfaces and two IP addresses, one for each VPN. This information can be used to tell applications to connect via one specific VPN.

In my case, I want to make an SSH connection to the server "S", which is only possible from within "FNet", that is, using the second VPN "F". Fortunately, I can tell ssh to use a certain IP address on my local machine. Let's assume 222.123.144.144 to be the IP address of the server S. This is how to connect to "S" via the second VPN "F":

>ssh -b 222.123.123.155 -l theUser 222.123.144.144

in which "theUser" the user login for "S". 222.123.123.155 is the IP of my machine within FNet (as F virtually places my machine in FNet). Note that you have to use the IP address rather then the name of the server (maybe some geek can tell me how to "update" the DNS stuff accordingly).

Other applications cannot be configured that easily, in these cases you have to add routing entries to your route table. E.g., instead of using the "-b" option of ssh, I could have added a new route (I found that tip here). To add a route, I need to be a super user, so we have to use sudo:

>sudo add route 222.123.144.144 222.123.123.155

Now, I can directly connect to S without the "-b" option:

>ssh -l theUser 222.123.144.144

Don't forget to delete the route when no longer needed:

>sudo delete route 222.123.144.144 222.123.123.155

Thursday, November 18, 2010

Problems with TortoiseSVN and authentication (on WinXP)

Newer versions of TortoiseSVN may produce errors when repositories reside on servers with unknown (untrusted, whatever) certificates. The very same repositories may be checked out and updated using a command line version (or with Mac tools). The error message may be a little too short and doesn't explain very much:
Update
OPTIONS of 'https://my.server.com/my/repository': SSL 
negotiation failed: Secure connection truncated (https://my.server.com)
Finished!
In order to fix this, you will have to change the underlying method of subversion/Tortoise for communicating with the server. This has to be specified in the server settings. This is a simple text file, hidden somewhere on your system. The easiest way of locating this file is by opening the Tortoise Settings and edit the "Subversion configuration file" (found under "General"). However, this only opens the "config" file, but what we need is the "server" file -- which luckily can be found in the very same folder as the "config" file. On my german Windows XP installation, its path is C:\Dokumente und Einstellungen\userid\Anwendungsdaten\Subversion\server. In "server" (pay attention to not accidentally add a ".txt" when saving the file), add a new server group in the group section, and set the http-library to "serf" for that group. E.g.,
[groups]
myserver = my.server.com

[myserver]
http-library = serf
Now, TortoiseSVN should work with your server.

P.S.: I found the solution at http://bugs.debian.org/cgi-bin/bugreport.cgi?bug=507374 (although I have no debian system, it solved my problem, so thank for the tip, Peter Samuelson) ;-). I adapted the solution for TortoiseSVN, as it fixes the problem with TortoiseSVN, and most TortoiseSVN forums suggest to downgrade to elder TortoiseSVN versions, which didn't worked in my case.


Tuesday, September 21, 2010

Mount Samsung GT-i5800 as an USB Drive

Today I wanted to sync some of my music files with my new GT-i5800. Unfortunately, it didn't worked with MissingSync via Wi-Fi, so I tried USB. Well, how do I mount my GT-i5800 as a USB drive on OS X? By default, USB settings are "Samsung Kies", which I do not need on OS X (and with MissingSync). This setting has to be changed to "Mass storage" before connecting the USB cable!
Settings > About phone > USB settings > (X) Mass storage (default: Samsung Kies)
or in german:
Einstellungen > Telefoninfo > USB-Einstellungen > (X) Massenspeicher
Only after changing this setting, you can connect the GT-i5800 as described in the Missing Sync manual: "pull down the notification window (aka ‘window shade’) and tap USB connected."

Well, and thanks to bTunes ($1.49), my Android device almost feels like an iPod :-D


Thursday, September 16, 2010

Android on Samsung GT-I5800 and Mac OS X

Eventually I had to admit being a geek. As a consequence, I'm an owner of a Samsung Galaxy 3 i5800 (or simply GT-I5800) now. I'm extremely impressed: This Android phone costs 200€ only, and frankly I don't know why to spent 1000€ for an iPhone. Moreover, to me the iPhone is a little bit too big. The i5800 is a little bit smaller, thus it better fits in my trouser pocket. OK, the camera (3.2 MP) is just good enough for funny apps such as the Barcode Scanner, but I do not really need a camera in my phone. As I'm an Mac OS X user, the most important thing is syncing with my MacBook Pro. This is really easy thanks to Missing Sync: Address Book contacts (with photos), iCal calendars, iTunes, iPhoto , arbitrary folders, SMS logs, phone logs, and other things (and in future versions bookmarks) are easily synced via WLan. It can be configured in order to sync automatically every n minutes via WLan or manually. IMHO, this app is worth it's 39$. Most of my friends have iPhones. So I knew about some great apps they demonstrated me on their gadgets. I'm really surprised finding all these apps available for Android as well and nicely working on my GT-I5800:
  • Dropbox for file syncing
  • 1Password password manager, can be used in combination with Dropbox!
  • Call-a-Bike, great for finding a free bike nearby.
  • Shazam to find out which song is currently played
  • DB Railnavigator
  • Remote for iTunes: With this app I have remote access to my iTunes library on my mac (via WLan), and thanks to my Airport Express I can now listen to my music w/o having to jump back to my computer (in another room) for selecting a new album. I can even select the speakers via this app.
Other applications for the daily information overkill:
  • I'm still not that happy with the browser (I tried the build in browser and Dolphin, and I probably will have to spend some time getting along with the latter one as it provides an ad-blocker and reader plugin).
  • For RSS, I installed gReader Pro. It uses my Google Reader settings, so that I do not have to configure all RSS feeds on the phone. Actually, it is one of the rare things I'm using my Google account for on my phone.
  • As a twitter client, I have installed Twidroyd Pro. Seems as if you have to pay a few bucks for good apps.
  • As I have mulitple mail accounts, I installed the K9 mail reader. It is free, and it does what it says.
However I'm not feeling comfortable with having my mail account passwords (and others) stored on the phone. Actually, the mail account password is one of the most sensible passwords. If one cracks the mail account, it is quite simple to change other passwords of web applications as most web apps sends you a new password if you have forgotten your old one. The lock method of Android 2.1 (which is not too secure, see this paper, however, PINs wouldn't solve that problem, would they?) may help, but I'm not really convinced about that issue. I definitely have to investigate further into that topic.

Monday, May 24, 2010

LaTeX: Listings and labels

I have blogged about the listing package here several times (nicely formatting, and hyphenations). This time I will write about creating labels inside a listing. First of all, the listing package allows to define a caption and a label for a listing, e.g.:
\begin{lstlisting}[caption={myListing},label={lst:myListing}]
void foo(int x) {
 doSomething();
 doMore();
}
\end{lstlisting}
Now the listing can be referenced via \ref{lst:myListing}. The listing package also nicely supports line numbers, there are a whole bunch of settings for that. But why do we need line numbers? In most cases, line numbers are used to refer to a certain line within a listing. E.g, we maybe want to write something like
In line 2 of the listing 1 we call method 'doSomething'.
Well, "listing 1" will look like "listing \ref{lst:myListing}" in the LaTeX source code, but how do we reference the line? Fortunately, the listing packages allows us to escape to latex inside a listing and add a label which can then be referenced:
\begin{lstlisting}[caption={myListing},label={lst:myListing},numbers=left,escapeinside={@}{@}]
void foo(int x) {
 @\label{lst:myListing_2}@doSomething();
 doMore();
}
\end{lstlisting}
Now we can reference the line: In line \ref{lst:myListing_2} ... Actually, you can use any label text, however I usually use the listings label with the line number or a small marker, in order to avoid conflicts with duplicate labels. As I do not want to write "line..." and "listing ..." over and over again, I use the autoref command from the hyperref package:
In \autoref{lst:myListing_2} of \autoref{lst:myListing}
autoref automatically adds a name to the reference counter. As there is no name defined for line numbers, it has to be defined previously:
\providecommand*{\lstnumberautorefname}{line} 
If you need names in a another language, you can add a translation:
\addto\extrasngerman{% 
\def\lstlistingautorefname{Quellcode}% 
\def\lstnumberautorefname{Zeile}% 
}
OK, we can add a line label and easily create a reference to that label. However, writing line labels means a lot of work, especially if you use a listing relative name pattern. So, let's add a macro to TeXShop, which uses some shell commands (mainly sed) and AppleScript in order to automatically create the label, even adding the line number to the label:
--Applescript direct
--
-- Create a label inside a listing, must be invoked at the position at which the label is
-- to be created.
-- Precondition: the listing is defined inside a lstlisting environment and 
--   a label is defined in the parameter list of the environment (label={..}).
--
-- New newly created label consists of the label of the listing with the line number
-- appended to the label. You can configure escape characters (as specified in
-- escapeinside={..}{..}) and the separator between listing label and line number.
--
-- E.g. label={myListing}, on line 5 leads to the following output:
-- @\label{lst: myListing!5}@
--
-- (C) 2010 Jens von Pilgrim, http://jevopi.blogspot.com

property texapp : "TeXShop"
property escapeLeft : "@"
property escapeRight : "@"
property separator : "_"
property maxLength : 2000

try
 tell application texapp
  
  if texapp = "TeXShop" then
   tell application "TeXShop" to set pos to the offset of the selection of the front document
   tell application "TeXShop" to set currentSelection to the content of the selection of the front document
  else if texapp = "iTeXMac" then
   -- ??
  end if
  
  set start to 1
  if (pos > maxLength) then
   set start to pos - maxLength
  end if
  
  set preceeding_text to (characters start thru pos of (the text of the front document)) as string
  set preceeding_text to my findAndReplace(preceeding_text, "\\", "_")
  
  set lineNumbers to do shell script ¬
   "echo " & the quoted form of preceeding_text & ¬
   "| sed -n '/label[:space:]*=[:space:]*{[^}]*}/=;$ {x;=;}'"
  
  
  
  set theLines to my splitLines(lineNumbers) -- as list
  set currentLine to last item of theLines as integer
  -- set startLine to item ((length of theLines) - 1) of theLines as integer
  -- length is not working when executed as macro... workaround:
  set startLine to first item of (rest of (reverse of theLines))
  
  set lstLine to currentLine - startLine
  
  set lastLabel to do shell script ¬
   "echo " & the quoted form of preceeding_text & ¬
   "| sed -n '/label[:space:]*=[:space:]*{[^}]*}/h;$ {x;p;}'" & ¬
   "| sed -n 's/.*label[:space:]*=[:space:]*{\\([^}]*\\)}.*/\\1/g;p'"
  
  set newSelection to escapeLeft & "\\label{" & lastLabel & separator & lstLine & "}" & escapeRight & currentSelection
  
  
  if texapp = "TeXShop" then
   tell application "TeXShop" to set the selection of the front document to newSelection
  else if texapp = "iTeXMac" then
   --tell application "iTeXMac" to insert new_section in the text of the front document
  end if
  
 end tell
on error errmesg number errn
 beep
 display dialog errmesg
 return
end try


on findAndReplace(strInString, strFind, strReplace)
 set ditd to text item delimiters
 set text item delimiters to strFind
 set textItems to text items of strInString
 set text item delimiters to strReplace
 if (class of strInString is string) then
  set res to textItems as string
 else -- if (class of TheString is Unicode text) then
  set res to textItems as Unicode text
 end if
 set text item delimiters to ditd
 return res
end findAndReplace


on splitLines(strInString)
 set ditd to text item delimiters
 set text item delimiters to "
"
 set textItems to text items of strInString
 set text item delimiters to ditd
 return textItems
end splitLines
Now things are really easy: Simply activate the macro at the appropriate location in the listing, and a new label will automatically be created. Note: The listing must have a label defined! You can configure the script by changing the properties at the beginning of the macro.