Category Archives: LaTeX

Using \raggedbottom To Identify Where To Reword

Say you are preparing a camera-ready submission and you are running a little low on space, maybe by a few lines. At this point, hopefully you are willing to put in the time and try rewording some of your sentences. A usual way to start is to identify a paragraph with a very short final line and try rewording a sentence within so that the paragraph uses one less line.

But if you have tried this route, you may notice that TeX has “optimized away” your effort by subtly padding the pages with more vertical spaces, thereby keeping the page count constant…

Long story short, you want to use \raggedbottom. Put it in the preamble and recompile. With this, LaTeX will keep the breaks at the same places, but it will not pad and hence the bottom of the pages will be ragged (duh!). Now you can usually see why your effort did not produce the desired effect: the space that you just freed up does not allow the current page/column to absorb enough material from the next.

With the ability to find a short page/column by inspection, now you can identify the earliest place where rewording is more likely help. Repeat the reword-recompile cycle a couple times, and the page count will go down. Just be sure to take out \raggedbottom when you are done! :P

P.S. The two-page mode in your previewer can make the inspection more effective.

PGF Version 2 is Released

From the project homepage:

PGF is a TeX macro package for generating graphics. It is platform- and format-independent and works together with the most important TeX backend drivers, including pdftex and dvips. It comes with a user-friedly syntax layer called TikZ.

I have been a happy user of PGF ever since 2006. For certain types of graphics like data structures and geometry, it really makes more sense to “code it” then to “draw it” (interactively). The package is very rich in features, as you can witness just by flipping through the 560 page manual.

560 pages for a package? I know it’s long, but of course you don’t need to learn every single option of every single feature before you can use PGF productively. (Actually, you will use a high-level abstraction layer called TikZ as explained in the manual.) The manual provides several tutorials to help you start.

Lastly, I note that the package is written by fellow Theory researcher Till Tantau. Thank you Till!

P.S. Version 2.0 is in the MiKTeX distribution already. Just do an automatic update.

Protect Your Email Address in PS and PDF

The randtext package is a great random find in CTAN. Here is its description in full, but with an emphasis added by me:

The package provides a single macro \randomize{TEXT} that typesets the characters of TEXT in random order, such that the resulting output appears correct, but most automated attempts to read the file will misunderstand it.

This function allows one to include an email address in a TeX document and publish it online without fear of email address harvesters or spammers easily picking up the address.

The author is Charles Duan.

While you most certainly want to use this package for some protection, you should not rely solely on it. For a historical reason(*) , Adobe’s PDF library can easily extract an email address protected by this package. I don’t know about the top search engines, but I would expect their extractors to perform no worse.

(*) Basically, space characters need not exist after the TeX phase. They may instead exist as kerning and spacing information. Therefore, Adobe have an extraction routine that guesses the word breaks based on how the characters are spaced. In other words, the routine is literally “reading” the text from the rendering, just like any human!

Changing PDF Margins With The pdfpages Package

Sometimes I am given a PDF and I wish I could change its margins. For example, when I print out a conference version of a paper to study in detail, usually there isn’t much space on the sides to write my own ideas. I heard Fermat had a solution for this type of issue :P , but in the modern days, I use sticky notes. The same situation surprisingly arises even if you use PDF annotating softwares. Free or not free (no link for them), they simply do not support the “enlarge canvas” feature yet. All you can do is to insert electronic sticky notes. So much for the metaphor!

Now there is actually a technology called “reflowable PDFs”, which are PDFs that contain enough information to support reflowing its content to fit any width. You can see this page for a screenshot of a reflowed document. Reflowing works wonder for text-dominant documents like novels, but the PDF has to be specially prepared for reflowing to really work well. (Try View->Zoom->Reflow in Adobe Reader 8.)

But if the given PDF is not reflowable, we can still use some graphics editor and edit the PDF interactively. After all, a PDF is mostly a vector graphics file, modulo some potential embedded bitmaps, and so you can edit it like any vector graphics file. I’ve seen it done in Illustrator, and I guess some of the free software competitors like Inkscape or Scribus can do this kind of editing too. But using a command line tool would be far easier.

For a long while, I actually know how to change the margins of a PDF. (Turns out lawyers have essentially the same problem.) The trick is to use the pdfpages package with pdfLaTeX. You may recall that this package allows us to include specific pages of a PDF into our own document. Magically, it has a scale option (that is really inherited from graphicx)… This gives us the first batch file: pdf-rescale.bat. Execute

pdf-rescale.bat foo.pdf 0.8

and you will get foo-0.8.pdf, which is foo.pdf shrunk to 80%. I’ve found that 80% is a good default and so the third argument is actually optional. You can also specify a scale of larger than 1 for some journal articles formatted for smaller paper sizes. I can also imagine fancier applications in which you combine this idea with the geometry package (see this post) to control of the final outcome.

But since we are not changing the actual size of the paper, shrinking the content for a larger margin actually means, well, shrunk content. Conference proceedings are already typeset in a small enough font. Since the proceedings are in two columns, I had the idea to print each column on its own page. That will definitely give us ample space. After a lot of different attempts since last year, I finally managed to get the second batch file: pdf-1c.bat. Execute

pdf-1c.bat foo.pdf

and you will get foo-1c.pdf, which is foo.pdf but with one column per page. No kidding.

The following PNG illustrates these scripts using the title page of an old paper. The upper-left shows the original, and the upper-right is after shrinking to 80%. The lower-left and lower-right are the two pages from the one-column version. I have also attached the source PDF from which I generated the PNG. The key feature is that this PDF retains the text of the original—try search for the word “degree” and you will see. (At one point my solution was to assemble a bunch of PNGs representing each single column into a huge PDF. Although you can annotate on it electronically, you cannot search in it. It also prints slowly.)

Finally, I also note that it is in fact possible to prepare reflowable PDFs using pdfLaTeX or dvipdfm (there seems to be trouble if going through a PS), but I will save it for a later story. For now, you can experience reflowing a LaTeX PDF with this PracTeX article, which is actually on the use of the pdfpages package. Having played with reflowing for a while, I would say that the real deal-breaker for reflowable PDFs lies in the mathematical expressions. You can see this TUGboat article for some excellent macros on fine-tuning mathematical expressions. Now, try to reflow it… :P

P.S. If you write the corresponding bash scripts, please send them to me so that I can, with full acknowledgement, post them here. The only reason why I stick to batch files is to avoid extra dependencies.

Change PDF Margin Scripts: pdf-rescale.bat pdf-1c.bat

Update: Joshua Dunfield has ported the rescaling script to Linux. See the comments.

Continuous LaTeX Compilation Using latexmk

Now that we know how to precompile the preamble to cut down the running time of latex, here is a tool that furthers the goal of saving time in the document production process—latexmk.

As its name suggests, latexmk is a “make” utility for LaTeX files. In particular, it understands when a particular document requires varying number of runs to resolve all references, with a bibtex and/or makeindex throw in at the right moment in-between the runs. Recent versions even support multiple bibliographies and the like. In short, assuming no source errors, if you execute latexmk foo.tex, you will get a fully compiled foo.dvi without any manual intervention. (PDF users: add the -pdf option. nomencl(ature) and glossaries package users: see below.)

Now latexmk would be a great piece of software to recommend just for the features I have mentioned above. Indeed, over the years I have seen various Makefile solutions using the make utility, some of which are fairly sophisticated. There are also direct competitors like texify and the like. (See this article in EmacsWiki.) While I find that latexmk fits my workflow in terms of ease of use and customizability, you may also want to check out these other intelligent options too. They all beat the “latex, latex, bibtex, latex, latex” batch script.

But latexmk is better than that—it has support for continuous/automatic compilation: if you run latexmk -pvc main.tex, then whenever it detects that one of the dependent source files of main.tex has been changed—be that a TeX, bib, an included graphics, or any file you declare to be a source, latexmk will automatically recompile it for you. That means you don’t need to start the compilation manually after changes and an oven-fresh dvi/pdf will be delivered to your previewer as soon as it is ready.

Finally, here are some notes on latexmk:

  • You really want the latest version, even though the version number may say “beta”. The script is very mature. Also note that MiKTeX ships with latexmk.exe, which is a wrapper to call Perl on TEXROOT\scripts\latexmk\perl\latexmk.pl
  • , which is the script you want to replace.

  • You can set up your .latexmkrc to override defaults or even define new dependencies. Below I have attached some interesting bits of my .latexmkrc just for an example. For instance, you can avoid launching a previewer even though you are using the -pvc option, and you can support the nomencl package and the like by declaring a custom dependency. And since this is a Perl script, you can use any Perl constructs. You can read the documentation for more possibilities.

    $latex = 'latex -src-specials -parse-first-line -c-style-errors';
    $pdflatex = 'pdf' . $latex;
    $dvi_previewer = 'exit'; # don't start a previewer for me
    @default_files = ('main');
    $clean_ext = # space separated string
    join(' ', qw( fmt acn acr alg gls glo glg ist nls nlo nlg brf out pdfsync rel));
    push @cus_dep_list, "nlo nls 0 nlo2nls"; # nomenclature
    sub nlo2nls { system("makeindex $_[0].nlo -s nomencl.ist -o $_[0].nls -t $_[0].nlg"); }
    push @cus_dep_list, "acn acr 0 acn2acr"; # glossaries and acronym hack
    sub acn2acr { system("makeindex $_[0].acn -s main.ist -o $_[0].acr -t $_[0].alg"); }
    push @cus_dep_list, "glo gls 0 glo2gls"; #MiKTeX 2.6 has a broken makeglossaries.exe
    sub glo2gls { system("makeindex $_[0].glo -s main.ist -o $_[0].gls -t $_[0].glg"); }

  • The -silent option suppresses the output of latex and show you only the errors in a succinct format. Here is an example transcript when I run latexmk -silent foo.tex with two planted errors.

    No specific requests made, so default to dvi by latex
    Latexmk: Run number 1 of rule 'latex'
    Latexmk: Running 'latex -src-specials -parse-first-line -c-style-errors -interaction=batchmode -c-style-errors "foo.tex"'
    This is pdfTeX, Version 3.141592-1.40.4 (MiKTeX 2.6)
    entering extended mode
    foo.tex:3: Undefined control sequence
    foo.tex:4: Undefined control sequence
    Latexmk: Use the -f option to force complete processing.

Have fun with latexmk!

P.S. I should note one fine point: if you have the habit of saving your file after every single sentence, then perhaps continuous compilation can be a bit counterproductive. Emacs users can consider tuning their auto-save-timeout and auto-save-interval instead.

Precompiled Preamble for LaTeX

If you can save six seconds every time you run LaTeX, would you do it?

Indeed, I have been pondering on this issue for quite some time now. Every time I compile “a large document that shall not be named”, I notice that the first six seconds are used to process the code before \begin{document}. But this code—known as the preamble—hardly sees any changes between runs. The preamble for this particular document may be a bit longer than usual, but considering that I am usually working on a chapter at a time using the \includeonly facility (see a tutorial here), these six seconds actually represent over 50% of the running time. Computationally and environmentally, this is horribly inefficient.

But a few days ago, I have finally stumbled upon a solution—it’s called “custom format file”. However, let me call it precompiled preamble, borrowing the concept from C compilers that support precompiled headers. Assuming your source file is main.tex, here is how you may use this method:

  1. Rearrange your preamble so that its static part precedes any dynamic part. What in the preamble can be “dynamic”? For example, if you use \includeonly, you probably want to change its argument rather frequently and so it is not static. Another example is the svninfo package, which introduces a command \svnInfo whose arguments get updated every time you commit. While you can certainly load svninfo.sty in the precompiled preamble, you also want the \svnInfo to remain in main.tex. Finally, some packages read and write auxiliary files when you issue a command that you should put in the preamble (eg, nomencl uses \makenomenclature). Clearly, you have to run these commands in every run.
  2. Extract the static part of the preamble into, say, preamble.tex. At this point, main.tex no longer contains the static part. It should start with the dynamic part, or simply \begin{document} if you have nothing dynamic.
  3. Execute latex -ini -job-name="main" "&latex preamble.tex\dump". You will notice that a new file main.fmt has been generated in the same directory, along with other auxiliary files. PDF users can replace latex with pdflatex in both occurrences and the same applies to the steps below. Also, in some distributions, the options could be “-jobname”. Make sure you get main.fmt and not preamble.fmt in this step.
  4. Edit the first line of main.tex so that it starts with %&main. There can be other stuff on that line too, for example

    %&main -*- mode: latex; TeX-master: "main.tex"; -*-

    works for me. (See this post if you are not familiar with Emacs local variables.)

  5. (Drum beats) Execute latex main.tex as usual. You may get an error about the class file immediately, or you may notice that latex finishes as usual. But if you have paid attention to the output, or if you inspect the the log file, then you will see that the preamble gets processed in “no time” at all. At this point, cheers!
  6. If you happen to hit an error, you will need to run latex -parse-first-line main.tex instead. The extra option will force latex to parse the first line of main.tex where we have asked for main.fmt to be used instead of the default format. (In Linux, you can try to locate texmf.cnf and change the option parse_first_line from f to t.)

To make things slightly fancier, here is an modification of my own. First, add this to the end of preamble.tex:

\def\preambleloaded{Precompiled preamble loaded.}

Then, before the dynamic preamble (or \begin{document} if there is none) of main.tex, add:

\def\ifundefined#1{\expandafter\ifx\csname#1\endcsname\relax}
\ifundefined{preambleloaded}\input{preamble}\else\typeout{\preambleloaded}\fi

The idea is to define a macro in the precompiled preamble and use it to detect if the precompiled preamble has been loaded or not. If not, \input{preamble} will be used to pull the static preamble back in and you will not see any error at all.

Of course, the actual amount of time saved will depend on your computer and your preamble. But in my case of long preamble and short document, the saving has been truly tremendous. (Hence I took some time to write this post in the hope that it would help someone down the road.)

Updated 2007/11/04: Changed the format file name to main.fmt and expanded on the dynamic preamble note.

File 2007/11/11: Attached beamer preamble test files in a zip, as referred to in my comment.

Updated 2007/11/11: Added comments for Linux users, after resolving the issue raised by Suresh’s comment.

How to Install MiKTeX 2.5 Today

(Updated on 2007-10-31 with simpler steps. This post assumes you are running Windows, but it’s actually applicable to Unix users if you replace the MiKTeX terms with their TeX Live counterparts. )

The most recent release of MiKTeX is 2.6 and it ships with pdfLaTeX 1.4. Unfortunately, it is incompatible with Ipe‘s latest release 6.0pre28 because this version of Ipe cannot cope with the PDF generated by pdfLaTeX 1.4. As the next version of Ipe is not coming very soon (Otfried says “Certainly not before spring 2008.”), one solution would be to downgrade to MiKTeX 2.5 so that Ipe can use the pdfLaTeX 1.3 that ships with MiKTeX 2.5. But if you have upgraded to pdfLaTeX 1.4 with a reason (like having fun with microtype), then you can also keep the two installations side-by-side with some storage overhead (~100MB). Assuming that your MiKTeX 2.6 is installed in C:\texmf-2.6, here is how you might do the MiKTeX 2.5 installation:

  1. Get a copy of basic-miktex-2.5.2580.exe. It’s the self-contained “basic installer” for MiKTeX 2.5 and contains some basic packages. This file does not seem to be available at the official MiKTeX download page any more, but Google can help you find a copy, or you can get a local copy hosted on this server.
  2. Launch the basic installer and install MiKTeX 2.5 to, say, C:\texmf-2.5.
  3. After the installation finishes, remove C:\texmf-2.5 from the PATH environment variable. That way, whenever you run latex, you are still running pdfLaTeX 1.4.
  4. Run Yap 2.6 once and you will be prompted to associate .dvi files with it. (The 2.5 installer associates .dvi files with Yap 2.5, of course. And frankly, I recommend dviout over Yap.)
  5. Set up an environment variable called IPEPDFLATEX to override IPE’s default pdflatex command, eg, IPEPDFLATEX=C:\texmf-2.5\miktex\bin\pdflatex.exe if that’s where you installed it to. At this moment, you may also be interested to set up something like IPELATEXDIR=C:\temp\iperun to control where Ipe generates the temp files.
  6. If you don’t use any special packages in your Ipe files, then you can skip this step. But for completeness, we can let MiKTeX 2.5 know about the extra packages installed in MiKTeX 2.6. From the Start menu, run MiKTeX 2.5->Settings. In the Roots tab, add C:\texmf-2.6 to the bottom of the search list. Click OK and the filename database will be refreshed. (Unix users: this is the Kpathsea step. See here.)

At this point, the side-by-side installation is complete. Have fun!

Current Ipe and pdfLaTeX Incompatibility

I upgraded my MiKTeX installation to version 2.6 because I want to use pdfLaTeX 1.4 for microtyping. But it turns out that upgrading to MiKTeX 2.6 breaks the current release of Ipe:

Ipe cannot currently cope with the PDF output generated by the new version 1.40 of Pdflatex. This version is included in MikTeX 2.6 and in TexLive 2007. Therefore, Ipe does not currently work with MikTeX 2.6 or TexLive 2007. This will be fixed in Ipe 7.0.0, but since I’m changing many other things at the same time, do not expect this version before September 2007.

Thankfully, I also have an older laptop and with Subversion, it is not difficult to work on both simultaneously.

The Microtype Package

The short of this post is: if you use a recent LaTeX distribution, then by simply adding \usepackage{microtype} to the preamble, your document will look subtly nicer and the number of overfull/underfull hboxes will go down. In two-column publications, this package is really wonderful.

The tricks implemented in this package are called “microtypography”, which refers to techniques that enhance typography at a very small scale. (Tweaking \baselinestretch doesn’t count. :P )

One such technique is character protrusion—the ability to slightly extend certain characters, like punctuations, into the right margin. When used properly, the right margin will actually look “more justified” than justified. (The example above protrudes the hyphens completely. See below for a more moderate protrusion example that demonstrates the “more justified” look.)

Another technique is font expansion—the ability to dynamically tweak the width of the fonts within a line very slightly. The effect of this technique is more even density across a page due to better line breaking, but it is by design meant to be virtually imperceptible. (You can see it in before-after comparisons below.)

Aesthetics aside, these two techniques can cut down on the number of bad hboxes because they give extra flexibility to the line-breaking algorithm in TeX. Their effectiveness clearly varies from document to document, but the extra elbow room cannot hurt and so you may as well use it in every document. I especially like it in two-column publications based on my experiments.

A whole thesis has been written about the techniques that lead to this package, and the package also comes with an extensive manual that describes other microtypographic techniques implemented by the package. I must note that if you use a PDF viewer that supports PDF 1.5 (current Foxit and Sumatra fans may need Adobe Reader), you can even interact with a “live demo” of character protrusion and font expansion on page 4 of the manual. This is a highly recommended exercise. The manual itself is, of course, typeset with both features turned on as an example of the package, and so at least you get to see character protrusion in action if you look for it.

Finally, system requirements: first of all, the package is smart and simply adding \usepackage{microtype} will “just work”. But you really want a recent pdfTeX backend, and you can upgrade to version 1.4 to reap all the benefits in your PDFs. Note that pdfTeX can also generate DVIs. I know, it sounds weird, but for instance, recent versions of MiKTeX actually generate DVIs via pdfTeX. (microtype was a big part of the reason I upgraded from 2.4, and that led me to undergo the conversion from Yap to dviout.) Font expansion is not available in DVI though, but character protrusion does work.

Debugging Bad \hboxes with AUCTeX

When you use AUCTeX to compile a LaTeX document that contains an error, the compilation will fail and AUCTeX will remind you in the minibuffer area: LaTeX errors in `*foo output*'. Use C-c ` to display. By pressing C-c `, which invokes the next-error function, you can navigate to the source locations of the errors and fix them one by one. It surely is one of the most convenient features of AUCTeX.

But AUCTeX also has a lesser known feature in this regard: by pressing C-c C-w, which by default binds to TeX-toggle-debug-boxes, you can tell AUCTeX whether the debugger should consider underfull/overfull \hboxes as errors too. When preparing for the final(*) revision of a document, this feature really makes locating the bad \hboxes a breeze!

(What’s remaining are of course the \vboxes, but there doesn’t seem to be any good way to locate them using the output messages alone.)

(*) It is usually not a very productive idea to fix bad boxes before the document content is finalized.

Switching From Yap to Dviout

(Most recently updated on 2008-02-08, but I have kept the referenced MiKTeX version at 2.5. As far as I know, none of the changes in MiKTeX 2.6 and 2.7 matters to the topic of this post.)

I have recently upgraded my MiKTeX to the latest version 2.5 for some reason. And as much as I love MiKTeX, I have switched from YAP (Yet Another Previewer, the DVI previewer in MiKTeX) to Dviout.

Dviout may not be very familiar to non-Japanese users because, to my understanding, it is primarily developed to deal with Japanese usage (think about fonts). However, it works equally well in English too. I can recommend Dviout over YAP 2.5 for several reasons:

  • Dviout pretty much does everything YAP is capable of: color specials, HyperTeX jumps (you use the hyperref package, don’t you?), and perhaps most importantly, round-tripping using source specials (but see the note below).
  • Unlike YAP 2.5, it does not seem to have any DVI locking issue, at least not in my daily usage of working on a large document. (To me, this alone is worth the switch until YAP eliminates the lock issue.)
  • In my experience, Dviout is much faster than YAP ever since it had a major change in version 2.5. Unlike YAP, Dviout does not make you choose between “dvips” vs “pk font” rendering—the former is slow, and the latter cannot be used when your document has any graphics. There is really no good choice in YAP.
  • The particular document I am working with is also somewhat graphics intensive. Like YAP, Dviout is able to call Ghostscript to show the included graphics in the DVI preview. But it also caches the generated bitmaps and use them later for unmodified figures. This saves me a lot of time. (And this is the primary reason why I expect to stick with Dviout for a while. I sprinkle \parpics and wrapfigures quite liberally on my spaghetti.)
  • Dviout allows you to customize the shortcut keys. I like to exercise my left hand more often and so I set some shortcuts on my left hand.
  • Dviout can do a text search directly inside DVIs. This can be handy if all you have is a DVI file. (Package documentation comes to mind. And yes, you could have converted it to PS and then do the search in the PS…)

(Note: there is an issue that I am still puzzling on. In the forward search, sometimes Dviout will land on a few paragraphs earlier than the intended destination. I will update this post once I figure out the solution.

Update 2007-03-07: Nailed it. First, recall that source specials are implemented by inserting tags that specify the source file and the corresponding line number into the DVI file. The problem is that sometimes the line numbers in the tags are not in increasing order. Here is how the stream of tags might look like: {src:1003main.tex}{src:1055main.tex}{src:1015main.tex}{src:1019main.tex}. In this case, if you ask the DVI previewer to go to line 1015 of main.tex, a simple scan algorithm will hit the second tag and then incorrectly conclude that no further reading is necessary. This is exactly what happened. Workaround? I guess I will have to wait until I finish my current project and patch the source directly.)

Below I will show how to get Dviout working with MiKTeX 2.5. (Update 2007-11-15: The same instruction works for MiKTeX 2.6 because there is no change in directory layout.)

  1. Remove the directory C:\localtexmf\fonts if you have one. It contains your existing PK font files. We can afford to regenerate them. MiKTeX 2.5 by default put PK files in a different location too.
  2. Create a new file dviout.par and put it in the same directory with dviout.exe. It’s the preference file for Dviout.
  3. I have included the non-default parameters that I use at the end of this post. You can use it as your first dviout.par and start from there. As you can see, there are some hard-coded path names that you will need to change. The following is a list of parameters that you want to pay attention to, in the order of appearance in my dviout.par below:
    GS
    This means “On” with “Direct PS” turned off in the Graphic tab. Keeping Direct PS off can mitigate a class of problems due to dvi files prepared with source specials containing postscript. For instance, you can generate such a dvi file by using hyperref with the dvips driver, which is usually the default. The right driver for dviout is hypertex, used like this \usepackage[hypertex]{hyperref}.
    gsx
    You may have installed Ghostscript somewhere else. I note that MiKTeX comes with Ghoscript these days, but I usually keep an installation of the most recent Ghoscript so I don’t use the one that comes with MiKTeX.
    gdat
    All my documents store their figures in a figure subdirectory. The current setting tells Dviout to cache the preview bitmaps in the same subdirectory instead of the parent directory where the DVI is located.
    gen
    I installed my MiKTeX there. The default for 2.7 would be `C:\Progra~1\miktex~1.7\bin\makepk.exe ^s ^d ^D ^M. There should be no space in the path name and so you must use short path. Also, be careful with the backquote character.
    key
    I have added four shortcut keys to my config. “z” and “x” are for back and forward, “-” and “=” are for zooming out and in. Also, note that “space” is by default mapped to next-page, and so the pair “z” and “space” is all I use most of the time. Remember, the shortcuts are fully configurable in the Option->Set Parameter->Key tab.
    BMP and scale
    I have made an unusual choice here because of my late-night TeXing. The negative numbers represent negative gamma, which is to say that the DVI text is displayed in white on black. If you want the normal black on white, change the -400 to 1100. The particular number depends largely on the font you use and your monitor, but 1100 is in the ball park. (This answers rmcd’s comment.)
    TEXROOT
    For MiKTeX 2.6, the current setting is a sensible choice. This is what ^r in the TEXPK option expands into.
    TEXPK
    If you have installed MiKTeX 2.6 at its default destination, use TEXPK=”^r\fonts\pk\\dpi^d\^s.pk;C:\Program Files\MiKTeX 2.6\fonts\vf\\^s.vf” instead. You can read my comment on 2007-03-23 to understand what it does and how you can come up with the right setting for your machine with the help of YAP.
    TEXFONTS
    According to the Dviout manual, this option is needed when you cannot generate a PK font but you want to replace the missing characters with spaces of the correct size, hence the need to locate the TFM (font metric) files. I would say that if you cannot generate an English PK font, then you want to resolve the issue completely instead of relying on this feature.
    src
    I use GNU Emacs on Windows since a long time ago and I am still at version 21. That explains why I picked gnuclientw as my src editor. In the comments, rmcd explained how to use emacsclient instead. Dviout supports DDE as well and so you can use many other editors. See the help file for instructions.
    gsrc
    I use Ipe for most of my graphics. That explains the path in gsrc.
    isp
    With the GS option above, we have turned off Direct PS. This “ignore some source specials” setting further suppresses a whole bunch of (mostly harmless) warnings. There are pros and cons, but I think this together with the GS setting above is a sensible default.
    file
    This is where you put dviout.par. Of course, you don’t really change this setting by changing it inside dviout.par, but this is a non-default setting with a hardcoded path. :P
  4. Finally, to make AUCTeX use Dviout instead of YAP, here is a snip from my tex-site.el. Note that I am showing you Emacs Lisp here and as rmcd pointed out in his comment, you do not want to enter the backslashes before the two inner double-quotes if you are using Emacs’s customize-variable command to change your TeX-view-style. The backslashes are only necessary in Emacs Lisp so that we escape the two inner double-quotes.

    (setq TeX-view-style
    '(("^a5$" "yap %d -paper a5")
    ("^landscape$" "yap %d -paper a4r -s 4")
    ("^epsf$" "gsview32 %f")
    ;;("." "yap -1 -s%n%b %d")
    ("." "dviout -1 %d \"# %n %b\"")))

Here are some usage tips on Dviout:

  • As much as I prefer not to ask you to touch the registry, you want to know that Dviout remembers some of its settings in HKCU\Software\SHIMA\DVIOUT. For instance, it stores the window dimensions there. (I set my xPos, yPos, Height and Width in the registry once and for all.) I believe that all options set outside of Option->Set Parameters, such as Option->Continuous Renew, are stored in the registry.
  • You may also want to disable Options->Check color specials from the menu in case Dviout complains about your DVI file. It happens when your color specials have certain issues as explained in the manual. I meet these issues too frequently.
  • Make sure you enable Options->Setup Parameters...->System->Auto Renew. (It’s on by default, but it’s worth checking in case you turned it off by accident.) It forces a update check when you switch into Dviout from another application. This behavior is shared among most, if not all, DVI previewers.
  • Options->Continuous Renew is a good thing if you have a large monitor or a dual monitor to let you see both your text editor and Dviout without overlap. This option will cause Dviout to pop into foreground when the DVI file is updated. Using Microsoft’s Tweak UI, in General->Focus, enable Prevent applications from stealing focus and set it to flash the taskbar button one time. That will make Dviout always show you the latest DVI without stealing the focus from your text editor. (I use this with the continuous mode in latexmk.)
  • Most importantly, once you have customized the options using Option->Setup Parameters to your own liking, select Option->Non-default Parameters. A small text box will pop up and you can copy and paste its content into your dviout.par. (That’s how I get the file below.)

Have fun with Dviout!

Finally here is my current dviout.par (last updated 2008-02-08). I have also uploaded it as a file to avoid line wrapping and other funny things due to quotes.

br=0x800000
bf=0x800000
bb=0x1d4c000
multi=4
button=+
dpi=600
GIF=5
GS=17
gsx=C:\Progra~1\gs\gs\bin\gswin32c.exe^-IC:\Progra~1\gs\fonts;C:\Progra~1\gs\gs\lib;C:\Progra~1\gs\gs\Resource^-dTextAlphaBits=4^-dGraphicsAlphaBits=4
gdat=./figures
gsize=+
search=448
sdpi=600
hyper=0x1d030
hbuf=0x400000
ToEdit=^c^V
FB=2
varf=+
gen="`C:\texmf\miktex\bin\makepk.exe ^s ^d ^D ^M"
y=F614.295pt:794.96999ptP
key=DR=-:DM==:JL=x:JF=z
log=C:\temp\dviout.log
BMP=6:6:-400
scale=2:2:-400:4:4:-400:2:2:1100:4:4:1100
TEXROOT="C:\Documents and Settings\All Users\Application Data\MiKTeX\2.6"
TEXPK=^r\fonts\pk\\dpi^d\^s.pk;C:\texmf\fonts\vf\\^s.vf
TEXFONTS=C:\texmf\fonts\tfm\\
src='gnuclientw^s+%d "%s"'
gsrc=.eps.pdf=C:\UnixHome\ipe\bin\ipe.exe^s"%n.ipe"
isp=ps:SDict;!
file=c:\unixhome\dviout\dviout.par

P.S. I should mention that staying with MiKTeX 2.4 would not be a bad choice if I could… You should also be reminded of potential issues if you decide to upgrade to Vista before MiKTeX 2.6 comes out.

Subversion Keywords and LaTeX

Update 2008-05-08: Please note that this post was written before I started using svninfo, and I highly recommend it if you are dealing with multiple source files. You still need to set the Id keyword property on each source file, but the double dollar trick is not really needed. See the \svnInfo command.

For each file in a Subversion repository, we can specify a list of name-value pairs which are called “properties”. Properties can be used for any purpose (useful for automation scripts), and they are versioned just like the content of the files.

Some properties, however, have special meanings in Subversion. For example, the automatic end-of-line conversion feature relies on the svn:eol-style property. And in this post, we will look at another one: svn:keywords.

To use the svn:keywords feature, you insert special tags like $keyword$ into your file. There are currently five keywords in Subversion: Date, Rev, Author, URL, Id. The idea is when you commit a file, Subversion will automatically expand the keywords inside the file.

To use this feature, first add the svn:keywords property to the files that you want keyword expansion. For example, svn propset svn:keywords "Date Rev" *.tex will add two keywords to all the TeX files in the current directory.

Then, inside the TeX files, you can insert text fragments like:

Last committed as $ $Rev$ $ on $ $Date$ $

(The extra pairs of dollar signs are added to “eat” the dollar signs that surround Subversion keywords.)

The five keywords are more or less self-explaining. But if you want to dig deeper into advanced features like fixed-width keywords, you can read it here.

P.S. Again it is very convenient to have the properties set automatically for all TeX files in your repository. To do so, here is an example config file that you can use. Any file added after you changed the config file will automatically have their properties set.

LaTeX Source Specials

As I have hinted in this post about pdfopen, it is possible to do some sort of round-trip LaTeX editing with the right tools. There are two directions to make the round-trip complete.

The forward jump is editor-to-previewer: given the current cursor location in the editor, jump to the corresponding paragraph in the previewer. The backward jump is symmetrical. The magic behind this is called “source specials”.

While it sounds somewhat like a Chinese dish with special sauces, it really isn’t. :P Instead, when you generate the DVI file, you ask latex to tag the DVI file with “source specials”. Imagine each word in the DVI file is tagged with the source filename and the line number of the word.

The forward jump is to ask the previewer to display the location that is right after the editor’s cursor location (filename and line number). The backward jump is to ask the editor to put the cursor closest to the current location in the previewer (usually the location of a double-click).

Let’s get to the example. I will show how to get round-tripping to work in Windows using MiKTeX distribution 2.4 and GNU Emacs. Other configurations are similar.

(Round-tripping between LaTeX and PDF is similar in principle, but the tools are not very mature yet. I will save this for a later post.)

  • Install the AUC TeX package into Emacs.
  • To enable tagging in latex, invoke it with the --src-specials option. Say the primary LaTeX source is main.tex, AUC TeX invokes it this way, :
    latex --src-specials \nonstopmode\input{main.tex}

  • To do the forward jump with YAP (the DVI previewer in MiKTeX), say when the cursor is on line 65 of hetero.tex, AUC TeX will execute:
    yap -1 -s65hetero.tex main.dvi

  • To enable the backward search, install the gnuserv package. Google can help you locate many links, like this and the rest.
  • Assuming you have gnuclientw installed on your path, in YAP, go to View->Options->Inverse Search. Inside Program combo, you should see “GNU Emacs (Single Instance)”. Example command line:
    gnuclientw.exe -F +%l "%f"

  • Note that installing gnuclientw addresses the problem in this comment. In general, you rarely want to invoke emacs directly. Use gnuclientw instead.

Have fun!

TexPoint is now Shareware

Long story short: harddisk crashed, go to download TexPoint again and notice that it’s now shareware, costing 25 dollars, with a Mac version too. See this post for a tiny bit of history.

(Back to harddrive recovery mode.)

Creating an Annotated Bibliography

Today I learned a new LaTeX trick. If for whatever reason you want a citation to appear in the bibliography of a document without actually citing it in the document, you can use the command \nocite to force BibTeX to include the item in the bibliography.

Now you may ask why on earth one may want to do this. Wouldn’t such not-exactly-cited citations confuse the readers? Hmm, well, you may be right. But anyway, Google has shown me a perfectly reasonable use of it: you can use this command to make annotated bibliography quite easily.

http://www-math.cudenver.edu/~billups/courses/ma5779/annotated_bibliography.html

Numerical Constants are Math

Suppose we want to input the following sentence in LaTeX:

Therefore, the approximation ratio is 42.

Here is the obvious way:

Therefore, the approximation ratio is 42.

It works well, hmm, until that one day when you decide to change your math font. The correct way should be:

Therefore, the approximation ratio is $42$.

The dollar signs have a semantic meaning: “42″ is in the mathematical context, just as how we would input $x^2$. So if you intend to change the math font, then you want this occurrence to use that new font as well.

In case you want to see it in effect, here is a small example that you can try:

\documentclass{article}
\usepackage{ccfonts}
\usepackage[euler-digits]{eulervm}
\begin{document}
\begin{enumerate}
\item 1 $1$ -1 $-1$ one
\item 2 $2$ -2 $-2$ two
\end{enumerate}
\end{document}

This example also shows the importance of the dollar signs when dealing with negative numbers. Without the dollar signs, the minus sign is actually a hyphen. This difference is very noticeable in the output. You can refer to this post if you want a reminder on hyphens (-), number ranges(–) and dashes(—).

A Fractional Tip

What do you expect if you run LaTeX on the following?

\documentclass{article}
\begin{document}
This is a $(\frac13, \frac23)$-separator.
\end{document}

Hint: it works.

P.S. In my experience, this “trick” is most useful for constant fractions with a one-digit numerator and a one-digit denominator. When in doubt, just use the braces, or you can learn why and how this works once and for all.

TeX for the Impatient

I just discovered that there is another book about TeX that has been “freed”:

TeX for the Impatient
ftp://ftp.tug.org/tex/impatient-1.0/book.pdf

I have not found time to read it yet, but flipping through the PDF suggests that this is a pretty good book.

As for why you would want to read about TeX? Well, at least you can tell confidently which one of the following five gives a different (probably unintended) output:

1. H{\aa}stad
2. H\aastad
3. H\aa
stad
4. H\aa{}stad
5. H\aa stad

and perhaps even explain the (visually non-existent) differences between the other four. :P

P.S. I feel obligated to make sure you really know 2 is wrong unless you really have defined \aastad. 1 and 4 are better because they are less confusing. A control word “eats” the spaces and also the end-of-line after it, hence 3 and 5 both “work” but for a less obvious reason.

Emacs Local Variables

If you use Emacs to edit your LaTeX files, then you want to know about Local Variables. They are “comments” that you write at the end of a file, say in this example:

blah blah

% Local variables:
% mode: latex
% TeX-master: "main.tex"
% End:

The purpose of local variables is to allow you to give Emacs extra customization when you load a file. In this example, we want Emacs to switch to latex mode and set the TeX-master variable to “soda.tex”. mode is actually a special variable controlling the major mode of the file. The TeX-master variable is used by AUCTeX so that when you invoke LaTeX on the current buffer (Ctrl-C Ctrl-C), it will instead invoke LaTeX on the “master” file. This is crucial when you break the paper into multiple files and use \input to string them together because this alleviates the need to switch to the master file before you invoke LaTeX.

There is also another way to specify local variables by putting them in the beginning of a file. Here is how our example would look like:

% -*- mode: latex; TeX-master: "main.tex"; -*-

blah blah

There is also a special local “variable” call eval. The value for that variable is simply evaluated as an expression, and hence it can actually be somewhat dangerous. Fortunately Emacs also provides enable-local-eval to let you catch the evals.

Happy TeXing in Emacs!

Extended List Environments

In some publications(*), space is at a premium. While I do not recommend tuning your baselinestretch in the main body of a paper, I believe there are other reasonable things to tweak. In particular, I often find the space used by itemized lists to be a bit more than desirable. But how can we cut the space down without inserting \vspace*{-1ex} before every \item?

Well, I just figured it out last week: you want to use the paralist package. What it does is to provide several new list environments that consume no space between list items by default. You can add some space back in, but this time you can control the amount. Here is an example:

\usepackage{paralist}
\setlength{\pltopsep}{0.5ex} % space before first item
\setlength{\plitemsep}{0.25ex} % space between items
\newenvironment{itemizeC}{\begin{compactitem}}{\end{compactitem}}

The last line in the example is really just for convenience if you happen to want to switch between normal lists and compact lists easily.

Also note that paralist is quite a feature-rich package. Among other things, it can let you customize the item bullets and margins, as well as providing an enumerated list environment inparaenum that wraps its items in a paragraph like: (i) blah; (ii) blah blah. Be sure to check out its documentation!

(*) You know I really meant conference proceedings, don’t you? :P