Monday, September 12, 2011

Feature of the week: access your posts in Emacs (with RefTeX)

This week's feature of the week is something for our more experienced users but I guess that applies to many Emacs users anyway. ;-)

For all of you that write their LaTeX files using GNU Emacs I present a small script that simplifies its interaction with BibSonomy.
First, if you don't know and use RefTeX yet, I highly recommend that you give it a try, it's really awesome! I won't go into detail how to activate it, typically something like
; load reftex                                                                                                
(require 'reftex)
; turn reftex on                                                                                             
(add-hook 'LaTeX-mode-hook 'turn-on-reftex)   ; with AUCTeX LaTeX mode
in your Emacs configuration file ~/.emacs should be sufficient.
Adding citations to your LaTeX file with RefTeX is as easy as typing C-c [. Then you can search for appropriate entries using a regular expression.

What I want to show you in this feature of the week is how you can add a script to RefTeX such that each time RefTeX is initialized your BibTeX references are downloaded from BibSonomy. For this to work you must follow the following steps:

  1. Find out which posts you want to use from BibSonomy.
  2. Add an appropriate \bibliography{} command to your LaTeX file.
  3. Write a small shell script.
  4. Tell RefTeX about the script.
  5. Try it!

Find out which posts you want to use from BibSonomy


Let us assume that I am writing a paper about formal concept analysis (fca). So I want to reference publications from my list of fca-related publications that I can get at http://www.bibsonomy.org/user/jaeschke/fca. Since I want all publications in BibTeX format, the file I finally want to have is http://www.bibsonomy.org/bib/user/jaeschke/fca?items=1000. Notice the modifications in bold print.

Add an appropriate \bibliography{} command to your LaTeX file


Since the script presented later is rather simple, this is related to the posts I want to download, i.e., to the tag fca:
\bibliographystyle{plain}
\bibliography{fca}
That means the BibTeX file will be named after the tag(s) used to query BibSonomy.

Write a small shell script


Of course, we have done this for you. :-) Nevertheless, you should adopt it to your needs, in particular change the variable BASEURL (e.g., insert your BibSonomy username):
#!/bin/sh

FILE=$1
RESULTFILE=`pwd`/$FILE.bib
BASEURL=http://www.bibsonomy.org/bib/user/jaeschke
PARAMS="?items=1000"
QUERYURL=$BASEURL/$FILE$PARAMS

# the file is downloaded on each call of the script - 
# typically on the first call of reftex-citation
wget -q -O - $QUERYURL > $RESULTFILE

# the result for RefTeX: the path to the downloaded file
echo $RESULTFILE
The script gets as input from RefTeX the string from the \bibliography{} command (if you have several files specified, the script is called for each file). Then, it downloads your posts from BibSonomy using the input as tag of the user jaeschke. The downloaded file is put into the current directory (named after the tag(s)) and its name is returned to standard output (this is what RefTeX expects).

Place the script at some convenient location, let's say /usr/local/bin/find_file_from_bibsonomy.sh.

Of course, the script can and should be adopted to your needs. If you have suggestions for improvements, just let us know!

Tell RefTeX about the script


Add the following lines to your ~/.emacs file:
; connect RefTeX with BibSonomy                                                                        
(setq reftex-use-external-file-finders "yes")
           
(setq reftex-external-file-finders 
   (cons '("bib" . "/usr/local/bin/find_file_from_bibsonomy.sh %f") 
      reftex-external-file-finders)
   )

Try it!


Well, just open the LaTeX file and press C-c [ on your keyboard (for non-Emacs users: Pressing the Ctrl-Key together with "c" and then releasing both keys and pressing "["). Then search for some author name or keyword (e.g., "fca")

and be surprised about the results

You can choose any of the matching posts and the corresponding \cite{} command is automatically added to your document. And the best thing is: all the posts are coming from BibSonomy!

Further reading


Improvements


The script above always tries to download the entries from BibSonomy - even if you already have one with that name. Here is an updated version that acts only if the requested file name starts with a configurable prefix, in this case bibsonomy_.
#!/bin/sh                                                                           

# All files with publications from BibSonomy should have
# this prefix - to not overwrite other files.
PREFIX="bibsonomy_"
# query                               
BASEURL="http://www.bibsonomy.org/bib/user/jaeschke"
PARAMS="?items=1000"

# the first parameter is the file name from the \bibliography{}
# command                                  
FILE=$1

# check for prefix
if [ $(echo $FILE | grep "^$PREFIX") ]; then
    # prefix found -> work on

    # remove prefix for tag query
    TAG=$(echo $FILE | sed "s/^$PREFIX//")
    # build path for result file and query URL
    RESULTFILE=`pwd`/$FILE.bib
    QUERYURL=$BASEURL/$TAG$PARAMS

    # the file is downloaded on each call of the script - typically on
    # the first call of reftex-citation
    wget -q -O - $QUERYURL > $RESULTFILE

    # the result for RefTeX: the path to the downloaded file
    echo $RESULTFILE

else
    # just return the file name in case the file is in the current
    # directory                                
    echo $FILE.bib
fi
That means that in the example above we must change in our LaTeX document \bibliography{fca} to \bibliography{bibsonomy_fca}. That's it!

Further improvements will be added to this section.
at