Pseudocode in LyX Revisited

This post is strictly for users of LyX.

In a previous post I offered up a LyX module for typesetting pseudocode. Unfortunately, development of that module bumped up against some fundamental incompatibilities between the algorithmicx package and the way LyX layouts work. The repository for it remains open, but I decided to shift my efforts to a different approach.

LyX has built-in support for "program listings", insets that use either the listings (default choice) or minted LaTeX package. The listings package supports a lengthy list of programming languages, but not pseudocode. This makes sense because pseudocode has no fixed syntax; everyone writes it their own way. So I cobbled together a LyX module that adds my take on a pseudocode language to the listings package, allowing users to type pseudocode into a LyX program listing inset.

The module is available (under a GPL3 license) from a GitHub repository. The repository includes a user guide (both a LyX file and a PDF version) explaining both installation and the nuances of using the module. (Yes, there are some finicky bits.) The user guide also spells out what words are treated as keywords and formatted accordingly. I also built in a (somewhat clumsy) way to insert vertical lines to help the user recognize the span of a block of code.

The listings package provides (and LyX supports) a number of nice formatting features, including options for color-coding keywords, numbering lines and such. In addition, you can modify the list of recognized keywords by editing the module file in a text editor. If you are familiar with the listings package, you can customize the pseudocode language definition even further (for instance, by changing the delimiters for comments), again by hacking the module file. If you use the module, feel free to suggest changes to the language definition via the issue tracker for the repository.

Here is a small sample of the output, to give you an idea of what I am talking about. (I had to convert the PDF output to an image, which explains the slight fuzziness.)

While we're on the subject of LyX, I also have a layout file for the standalone LaTeX class, which is useful for generating PDF output of just one table, image or whatever without the wasted space of page margins. That layout file has its own GitHub repository, if you are interested.

Pseudocode in LyX

Fair warning: This post is for LyX users only. When I'm writing a paper or presentation in LaTeX (using LyX, of course) and want to include a program chunk or algorithm in pseudocode, I favor the algorithmicx package (and specifically the algpseudocode style). There being no intrinsic support for the package in LyX, I have to enter the various commands as raw LaTeX (or, in LyX parlance, "ERT" -- "Evil Red Text", so named for historical reasons). Unfortunately, I do this seldom enough that I do not remember said commands, so each sojourn into pseudocode involves finding and opening the documentation file for algorithmicx.

I finally decided to fix that by writing a pseudocode module for LyX. The beta version (which seems pretty stable to me) is available under a GPLv2 license from my Github repository. Besides a "gitignore" file (which you should, as the name suggests, ignore), there is the module file and a combination user guide/demonstration LyX document. Installation instructions are included in the latter. You will, of course, need to install the algorithmicx package before using the module.

Should you decide to try it, there's an issue tracker in the repository where you can report bugs or feature requests. I hope someone else can get some use out of this, but even if not, the development time will pay itself back the next time I need to write some pseudocode.

Grouping Rows of a Matrix

I spent a large chunk of yesterday afternoon doing something I thought would be simple (relatively speaking) in LaTeX. I wanted to group rows of a matrix (actually, in my case, a vector) with right braces, and label the groups. An example of what I wanted is in the image below.

This seems to me to be a fairly common thing to do, and LaTeX has been around over 35 years (TeX even longer), so by now it must be pretty easy. Right? Um, not so much. I wore out Google looking for packages that would do this. Curiously, it's easy to put braces over and under things:

• $\overbrace{[x_1,\dots,x_n]}$ [\overbrace{[x_1,\dots,x_n]}];
• $\underbrace{[x_1,\dots,x_n]}$ [\underbrace{[x_1,\dots,x_n]}].

There are packages to let you surround matrices, arrays etc. with a variety of delimiters (not just parentheses or square brackets). Nowhere, though, could I find a command or package to do the above.

Fortunately, something pointed me in the direction of the PGF/TiKZ package, which I've used in the past for doing drawings. It's an incredible tool in terms of both what it can do and the outstanding quality of its manual. Because it does so many things, I've never really gotten to know all its capabilities, and in particular its ability to do matrices in a picture environment.

Here is the code to do my illustration. You need to load the TiKZ package and two of its libraries in your document preamble, as follows:

\usepackage{tikz}
\usetikzlibrary{matrix, decorations.pathreplacing}

The code for the drawing is:

\begin{tikzpicture}
 \matrix (vec) [matrix of math nodes, left delimiter = {[}, right delimiter = {]}] {
f_1 \\
\vdots \\
f_{a} \\
f_{a + 1} \\
\vdots \\
f_{b} \\
f_{b + 1} \\
\vdots \\
f_{c} \\
};
\node (a) at (vec-1-1.north) [right=20pt]{};
\node (b) at (vec-3-1.south) [right=20pt]{};
\node (c) at (vec-4-1.north) [right=20pt]{};
\node (d) at (vec-6-1.south) [right=20pt]{};
\node (e) at (vec-7-1.north) [right=20pt]{};
\node (f) at (vec-9-1.south) [right=20pt]{};
\draw [decorate, decoration={brace, amplitude=10pt}] (a) -- (b) node[midway, right=10pt] {\footnotesize something};
\draw [decorate, decoration={brace, amplitude=10pt}] (c) -- (d) node[midway, right=10pt] {\footnotesize something else};
\draw [decorate, decoration={brace, amplitude=10pt}] (e) -- (f) node[midway, right=10pt] {\footnotesize something silly};
\end{tikzpicture}

The name of the matrix ("vec") is arbitrary. The amplitude for the brace (10pt) and the offsets (10pt and 20pt) are matters of taste.

If you happen to know a faster way of doing this, please do share in a comment.

Adventures with TeX Live

Since I use the Linux Mint operating system, the obvious (if not only) choice for a LaTeX distribution is TeX Live. (If you are not familiar with, or are not interested in, the LaTeX typesetting system, you have already read too far in this post.) On Mint, Ubuntu and other Debian-type operating systems, you typically install TeX Live by downloading and installing a number of fairly large files from a repository (in my case, mainly repositories for Ubuntu). Sometimes, though, you just want to install one or two small LaTeX packages without bothering with one of the large TeX Live files (which will contain a zillion other LaTeX packages you do not want or need). For this purpose, TeX Live includes a package manager (tlmgr).

Today, I found myself trying unsuccessfully to install something using tlmgr. The first problem was a missing compression/decompression program that was easy to install. After that, I continued to get cryptic error messages. Eventually, I decided to update tlmgr to see if that would help.

The Canonical (Ubuntu) repositories are fairly far behind the curve when it comes to TeX Live; they still provide the 2015 version, which is incompatible with newer versions (including the newer version of tlmgr). So updating tlmgr alone was not an option. (I had what appeared to be the most recent, and presumably final, incarnation of the 2015 version of tlmgr.) Following instructions I found on the Tips on Ubuntu site, I added a PPA containing the latest (I think) version of TeX Live, running the following in a shell:

sudo add-apt-repository ppa:jonathonf/texlive
sudo apt update 

After that, I used the software updater to update my TeX Live packages. (The "Tips on Ubuntu" instructions have you install TeX Live from the PPA, which presumes you do not already have a version installed, as I did.)

Before using tlmgr to do much of anything, you need to initialize the user tree by running

tlmgr init-usertree

in a shell. I had already done that, but I repeated it, confirming that the user tree was still intact. I then ran

tlmgr --gui

to open a graphical user interface, told it to load the default repository (there's a button in the "Repository" panel of the display), and tried -- unsuccessfully -- to install a LaTeX package.

So what was wrong now?  The error message contained the following snippet:

Tk::Error: /usr/bin/tlmgr: open(/usr/share/texlive/tlpkg/texlive.tlpdb)
failed: No such file or directory ...

I checked /usr/share/texlive/tlpkg, and sure enough there was no file texlive.tlpdb ... but there was a file named texlive.tlpdb.9ed73e8174b03a21aa0d40ebbcaac97f. It's a text file (around 12 MB) with configuration information and what looks like a directory structure. Why it had the rather funky hexadecimal extension, I have no idea. I symlinked it by running

sudo ln -s texlive.tlpdb.9ed73e8174b03a21aa0d40ebbcaac97f texlive.tlpdb

and tlmgr started behaving itself.

I later deleted the file with the scary looking hex extension, reran tlmgr and had it load the default repository again. It reproduced the file, but with a different (equally scary) hex extension. I again symlinked the file to texlive.tlpdb.

I have no idea why loading a repository produces what appears to be the correct file with the wrong extension and does not symlink it, but at least this fix seems to work.

Updating JabRef

I rely on JabRef to created and edit bibliographic databases (for use with BibTeX in LaTeX documents). For whatever reason, the supported version in the Canonical repositories for Ubuntu (and Linux Mint) is lagging further behind than is usual for the repositories (which is saying something). The current stable version (as of this writing) is 2.9.2, while the current beta version is 2.10 beta 2. The "official" version in the repositories is 2.7 beta 1, which I estimate to be between 12 and 18 months old.

I looked around for more current Debian packages but ultimately decided the easiest way to update is manually. Most of the files from the official version do not need to be changed. Here are step-by-step instructions for installing a new version. They worked for me and should work for anyone else using a Linux distribution that employs the Debian packaging system. I assume here that you already have the "official" version of JabRef installed. Do not uninstall the old package, since we're going to retain a lot of its files.

1. Download the latest version (stable or beta, your choice) from the SourceForge project page. Henceforth I will refer to the file (whose name should be JabRef-<version information>.jar) as <new jar>.
2. Open a terminal in the download directory.
3. Run the command

   sudo mv <new jar> /usr/share/jabref

   which will install the new version in parallel with the old one.
4. Optional but recommended: run

   java -jar /usr/share/jabref/<new jar>

   just to make sure the downloaded version works. Once you're sure it works, exit JabRef.
5. Still in the terminal, run the commands

   sudo rm /usr/share/java/jabref.jar
   sudo ln -s /usr/share/jabref/<new jar> /usr/share/java/jabref.jar

   This switches the version of JabRef being executed from the old one to the new one.
6. Test JabRef by running it from the application menu and/or by double-clicking a .bib file.
7. Optional: run

   sudo rm /usr/share/jabref/<old jar>

   to delete the old version. 

I'm not sure whether Synaptic will identify JabRef as a "broken" package as a result of this. We'll see.

Arrowheads in TiKZ

For most publication graphics (including drawings used in blog posts), I favor the TiKZ package for LaTeX. Many of those drawings have included lines with arrowheads, and the arrowheads never posed any problems ... until recently. Consider the following small chunk of TiKZ code:

\begin{tikzpicture}
   \draw[->] (0,0) -- (1,1);
\end{tikzpicture}

and the similar chunk

\begin{tikzpicture}[>=latex]
   \draw[->] (0,0) -- (1,1);
\end{tikzpicture}

Both should draw a diagonal arrow, with the arrowheads differing only in terms of their style. (The optional argument in the first line of the second version specifies the use of LaTeX-style arrowheads.) Indeed, when compiling the document with latex (producing DVI output), ps2pdf (producing PDF output by way of an intermediate Postscript file) or XeTeX, I get the expected output:

On the other hand, when I compile the document with pdflatex (the program I normally use) or LuaTeX, the arrow head in the first version goes missing:

(As a sidebar, compiling with dvipdfm, which I never use, produces a PDF file with a single blank page.)

This occurs on a Linux Mint 14 (Nadia) system with the TeXLive 2012 LaTeX distribution. As I said, the problem is new to me. I've previously drawn arrows in TiKZ using TeXLive (perhaps the 2011 or 2010 version) without specifying LaTeX-style arrowheads and compiled successfully using pdflatex. The workaround is at least straightforward. I just have to remember to specify the arrowhead style.

On an unrelated note, if anyone is curious how I converted the PDF output to the PNG images above, I took a somewhat circular route. For whatever reason, the ImageMagick convert utility, which on a good day requires specification of various command line options to produce  decent looking PNG, insisted on producing empty image files from my PDF files. So I opened each PDF file in a viewer, took a screen capture by pressing Control-PrtScn, and pasted the image into IrfanView (running under WINE). In IrfanView, which has excellent image manipulation tools, I just cropped the image and saved it to a PNG file.

Scalable Images in Blogger

Questions about a recent post containing a couple of flow charts made me regret the fact that Blogger does not support SVG graphics.  Although I made the charts using the excellent TiKZ LaTeX package (which produces vector output in the form of a PDF file), I had to convert the PDF output to PNG for Blogger, and the images are a tad fuzzy (and do not scale well when zoomed), which may have led to some confusion. So I was on a mission today to find a workaround.

The first thing I discovered that SVG is not nirvana.  I generated the images as separate PDF files from the TiKZ source.  (Hint to people doing this: use the LaTeX standalone document class and the output file will automatically be cropped to the smallest rectangle containing the image.)  I then used ImageMagick to convert the PDF files to SVG files ... which blew them up from around 54 KB to about 8+ MB. Each. Oops!  I tried a tool I found to convert the SVG files to "canvas" files, which got me another 5x or so increase in size.  So back to PDF files.  Blogger does not consider PDFs to be images, to the plan now is to use a PNG file as the image and link it to the corresponding PDF, allowing readers to click on the image and at least get a scalable version in a new window or tab.

Blogger does not allow you to upload arbitrary files, only images in formats it recognizes (which are actually stored in Picassa, another Google product/service). I thought about putting the PDFs on a personal server somewhere, but I worry about moving things (including them) to a new server at some future date and not remembering to update the links.  Enter Google Documents.  I just have to upload the PDFs to Google Docs, make them public, grab the URLs and set the links on the PNGs (which by default point to the PNG files in Picassa) to point to the PDFs in Google Docs instead.

I did this with the aforementioned post, and I think it's working. The one question mark for me is whether everyone can see them.  I can, but Google knows I'm the owner.  If either of my loyal readers runs into problems, or wants me to convert images from earlier posts, please drop a comment here.

Fixing TiKZ/PGF to Work with Gnuplot

While working on a new presentation today (in Beamer), I grabbed a slide from a previous presentation (one I reuse annually). The slide contains PGF code that uses Gnuplot to plot functions (which I then annotate using PGF commands). Small problem: the transplanted slide didn't work (no curves on the plot) ... which led me to attempt to recompile the original presentation and discover that it, too, no longer worked. Grrr!

Poking in the files in the /tmp directory showed me that Gnuplot was crabbing about a command (set terminal table) that PGF uses to tell it to create a text file with the points to be plotted. A bit of searching led me to a blog post by
Toine Bogers containing the fix. Instructions for Linux follow (I haven't tried it on Windows yet):

1. Open a terminal and run 'kpsewhich pgfmoduleplot.code.tex' to locate the file you need to edit. (The location varies with the LaTeX distribution you use; this takes the work out of finding it.)
2. Issue 'sudo gedit <path>/pgfmoduleplot.code.tex' (where <path> is the path you found in the previous step) and give your password when prompted. (Feel free to use a different editor if gedit is not your cup of tea.)
3. Find the line containing 'set terminal table' and delete the word 'terminal', so that it becomes 'set table' (the rest of the line staying unchanged).
4. Save the modified file, and you should be good to go

In LyX, you also have to go to Tools > Preferences... > File Handling > Converters, locate the converter for LaTeX (pdflatex) -> PDF (pdflatex), and tweak the Converter: entry to read 'pdflatex -shell-escape $$i'. Then click Modify and Save. If you use other formats besides PDF (pdflatex) to view/export Beamer presentations, you may have to add the -shell-escape flag (or something similar) to them as well. The flag allows pdflatex to run an external program (in this case gnuplot) in a shell.  Users of other other LaTeX editing software will likely need a similar tweak.

I love open source software, but one of the challenges of using lots of separate pieces of software is that developers will change something in the latest version of one program or library, and that change will break some interaction with another program/library from an entirely separate developer. To modify a saying from my misspent youth: "You pays your money [or, in this case, you don't] and you takes your chances."

Mixed Case Titles

Writing pointless academic papers requires citing other pointless academic papers.  Thus do academicians, in a symbiotic process eerily similar to those of lawyers and nuclear weapons manufacturers, keep each other in business.  Since I write in LyX and generate the documents with LaTeX, it is unsurprising that I process bibliographies using BibTeX.  My preferred tool for maintaining BibTeX databases is JabRef, which is cross-platform, has a decent feature set, and just plain works.

When I add references to by BibTeX databases, I'm careful to capitalize most of the words in the title.  Anyone who has had the misfortune to deal with journals  knows that every journal publisher employs at least one or two people with obsessive/compulsive disorder, who are tasked with ensuring that this journal formats various things (possibly tables or figure captions, but always, always references) in a way that visually distinguishes it from every other journal in the galaxy. Thus I have to find (or cobble together) a BibTeX style file specific to whatever journal makes the mistake of accepting of my paper.  BibTeX style files can "downshift" titles to lower case, but as far as I know they do not "upshift" to what I'll call "title" case (nouns, verbs, adjectives, adverbs and initial articles capitalized, other articles and conjunctions not).  So it behooves me to insert the reference into the database in "title" case.

On the other hand, I'm a firm believer in copying and pasting to avoid retyping.  So I frequently copy article information from a web page or PDF file and paste it into JabRef.  Small problem: as far as I know, JabRef does not have an editing feature to adjust cases.  That led me to some searching, which in turn led me to discover that gedit (my primary editor on Linux) comes with a preinstalled plug-in to shift cases.  Said plug-in can shift to lower, upper or (drumroll) "title" case. On Windows, NoteTab (including the free "Light" version) has a similar feature.  If I recall correctly, NoteTab's converter is available with no configuration.  In gedit, though, it needs to be turned on (Edit > Preferences > Plugins > Change Case), a revelation to which I have recently (and belatedly) come.

Updating TeX Live on Mint

Linux Mint is built on Canonical's Ubuntu distribution, and Canonical is, shall we say, a tad conservative about updating packages in their repositories.  Thus Ubuntu 9.10 (Karmic Koala), which I believe was released in the fall of 2009, still had the 2007 version of the TeX Live distribution of LaTeX. (The recently released Ubuntu 10.04 Lucid Lynx distribution apparently comes with TeX Live 2009; meanwhile, TeX Live 2010 is out and about.)

For various reasons, it became incumbent upon me to update my laptop (Mint Helena, built on Karmic Koala) to a later version of TeX Live.  So I zapped the old installation and followed the quick install instructions, including the comment that they recommend installing as a normal user rather than as root.  This made sense, since when TeX Live is installed as root you have to sudo to do some maintenance operations, such as updating the file name database.

Yeah, except ... if TeX Live is installed as root, it can write anywhere, so it gets itself on the system command path effortlessly and automatically.  Not so if it's installed in user mode.  I had to point it to a different folder than where it normally installed (I picked a folder under /opt -- which I then had to sudo to create) and got it installed, but it was not on the system command path.  So now I had to add the location of the new TeX Live bin directory to the system command path.

Rarely do I pay Windows a compliment, but it's pretty darned easy to add something to the Windows path (maybe too easy, from a security perspective), and it's equally easy to distinguish between the overall path (that every user gets) and the supplemental path that only the user making the changes gets.  Not so with Linux.  As best I can tell, there are no helper tools to make path changes in Linux.  So I added the path to my ~/.bashrc file (where I've made other path changes in the past), and that seemed to work ... until I tried to use my favorite document writing program, LyX.  Started from a terminal (where I was logged in as myself), it required a reconfiguration (which came as no huge shock), after which it ran fine. Started from the Mint program menu, though, it insisted that all document classes had gone missing, which is a sure sign that it can't find the LaTeX distribution.

Mind you, if I started LyX from a terminal with sudo (so that it was running under the root account), I could get it to work. But no way would it run from the menu. So I guess the ~/.bashrc file is not read by programs run from the menu. Fine, be that way.  I eventually solved the problem by appending the path export to /etc/profile, the system-wide profile. It works -- now -- but if some system upgrade down the road rewrites that file, I hope I remember to look here for how to get LyX working again. :-(

Using Impressive on Mint/Ubuntu

I've earlier mentioned Impressive, a very handy program for presenting slide shows done as PDF files (e.g., using the LaTeX beamer class).  Today I finally managed to get a couple of features working on my laptop (Linux Mint "Helena") that had eluded me until recently.

• The tab key toggles an overview mode where you can see (and jump to) any slide in the show. Beamer's method of displaying bullets etc. incrementally on a slide is to create a new PDF page for each "overlay"; so a slide ("frame") with five bullet items would occupy five pages in the PDF file. That's fine until you use the tab key in impressive and see a few bazillion "slides" listed. The answer is to run impressive with the option -O first in the command line. Well and good, except who wants to open a shell in order to run impressive. So the answer was to right-click a PDF file, select Open With > Other Application > Use a custom command and set the command to /usr/bin/impressive -O first.  Simple enough.

• Theoretically, with the right helper software installed (pdftk), you can click on a hyperlink in a PDF file while displaying it with Impressive, and Impressive will jump to the designated page (if within the document) or open the target in a browser (if the URL points outside the document). Small problem: it has never worked for me. A web search revealed that the version of pdftk (1.41+dfsg-1) included in recent Ubuntu repositories (and thus also available in Mint's package manager) is the culprit. Downgrading to 1.41-3ubuntu1 solves the problem. This requires three steps: uninstall 1.41+dfsg-1; download and install 1.41-3ubuntu1; and, in the Synaptic package manager, mark pdftk as not to be updated (otherwise Synaptic will try to upgrade it back to 1.41+dfsg-1 every time it finds updates, and it would be easy to forget to uncheck it in some mass update).