Last week I explained, among other things, how to generate “many different calendars, each customized for a different friend or relative, almost automatically”. I also mentioned that adding different pictures to each of those calendars would be quite easy.

This week I’m going to show you how to do just that, that is, how to insert photographs or any other graphic file inside LaTeX files. The first thing I’ll explain is why I want to do that, and why I think that every Linux user wishing to automate as much as possible his or her computing activities should know a trick like this.

This technique has much more general usage than you may think at first sight. LaTeX files produce professional, really beautiful printouts and PDF files — in ways much more sophisticated and powerful than any desktop office suite can do.

There are a lot of Free Software programs of all kinds that can output their data in LaTeX format, and many more LaTeX templates available online. Knowing how to put your own pictures in them (or any other data) means to be able to customize those programs and documents without being a programmer.

This is possible because LaTeX (and TeX, on which LaTeX is based) are open, plain text based formats. Consequently, automatic insertion of images into an already existing LaTeX file is as simple as finding and replacing the right ASCII strings with sed, awk, Perl or whatever text processing tool you like best.

Let’s see how the trick works by adding a picture to the LaTeX calendar I showed last week.

Figure A

What the pal program generates looks like Figure A, and this is the snippet of LaTeX code that generates the “Alice’s Birthday” entry:

  \textbf{\textit{\Large 20}} {\raggedright
  $\cdot$Alice's birthday
  }\vspace{.3in} &
  \textbf{\textit{\Large 21}} {\raggedright
  }\vspace{.9in} &

The basic procedure to add an image in a LaTeX file is very simple and consists of two steps. The first is to add the command to use the graphicx package, right after the declaration of the document class:


The second is to insert, in the right place of the code, the command that actually loads an image. This single extra line added after “Alice’s Birthday”:

  $\cdot$Alice's birthday

modifies the corresponding page of the calendar as in Figure B.

Figure B

You’ll notice immediately that the insertion modified the height of one row of the calendar. I’ll talk about that in a moment. Before that, let’s see how to make the process of inserting generic code automatic. There are lots of ways to do it. What I use, half for personal taste and half for laziness (one of the great virtues of each programmer) are one-liner Perl commands:

  perl -pi.bak -e 's/^(\\document.*)/$1\n\\usepackage{graphicx}/' template.latex
  perl -pi.bak -e 'undef $/; $A = <>; $A =~ s/(Alice.*birthday\s*})/$1\n\\includegraphics[scale=0.30]\{tux.png\}/m; print $A;' template.latex

The several command line switches tell Perl (see details here) to execute the code between quotes, directly inside the file passed as last argument. The first one-liner adds the usepackage command, right after the line beginning with the \\document string. The second one is more complicated, because it must edit a multiline string. That’s why it undefines the record separator ($/) to load the whole file in one $A variable, and uses the “m” modifier to find the string to which it must append the second LaTeX command.

What about the modified row height?

Personally, when I prepare calendars in this way I just leave the higher rows as they are, since I happen to prefer the irregular layout. If you can’t stand it, instead, you have two solutions. One is to learn much more LaTeX than I’ve shown here, and create your custom template (which is absolutely fine, just outside the scope of this particular post). Another solution is to give your pictures different sizes (see Resources below) and/or play with the horizontal and vertical spacing commands (hspace and vspace), to move each picture inside its cell and modify the space around it.

Figure C

Figure C shows what happened (compare it with Figure B) when I manually edited the LaTeX code around the picture in this way:

$\cdot$Alice’s birthday



\includegraphics[scale=0.20]{tux.png}\vspace{.02in} &

Scaling it up

Of course, if you only had to edit one file, just once, you should ignore scripting and just modify your file, as explained above, with any text editor or (much better) with LaTeX frontends like Kile. Adding scripting to the picture is a must when you need to generate many different files, many times, each with different pictures, out of the same initial template. In such a situation, a simple shell loop like this:

  for FRIEND in Ted Alice Bob
    echo perl -pi.bak -e "'"'undef $/; $A = <>; $A =~ s/('$FRIEND'.*birthday\s*})/$1\n\\includegraphics[scale=0.30]\{'$FRIEND'.png\}/m; print $A;'"'"  >> make_calendars

creates and saves in make_calendars all the commands that your Linux box must run to do the work for you. Finally, text strings can be literally anything. Therefore, processing LaTeX files with shell scripts is worth learning because it can do much more than insert pictures. I, for example, used the same general technique explained here to transform plain text files in PDF files.