1. Looking at the wider picture
2. Custom commands
3. Bibliographies
4. A short example

I’ve recently been experimenting with writing my CV with emacs ORG mode to allow pdf and html versions to be kept in sync. This is one of many ways you might try maintaining multiple in-sync formats of your CV. Others include:

• A TeX version and using htlatex to generate the html version
• Writing in markdown and using pandoc to generate tex and html versions

Each way has advantages and disadvantages. I hope to write up my experiences of trying out each method soon.

I’m using the cli tlmgr, so I installed each of these via sudo tlmgr install PACKAGE-NAME:

• xifthen
• ifmtarg
• changepage (for the chngpage package)
• paralist
• saurj (for the optparams package)
• placeins

Install all those (plus tufte-latex!) and you are good to go. Oh yea, and if you haven’t checked out the Tufte-book and Tufte-handout classes that come with Tufte-LaTeX, I highly recommend them.

Like LaTeX, you begin by editing a text file. This text file consists firstly of a header or preamble, which is used to load libraries and set initial parameters. Next comes the body of the document, with special mark-up tags or commands for special elements. In Lout, these typically begin with @, much like LaTeX’s backslash. Finally, there is a command to end the document.

This text file is processed by lout to generate the typeset document. By default, lout creates a PostScript file and sends it to stdout, though you can redirect it into a file, or send it directly to a printer:

lout my-document.lout > my-document.ps

With ghostscript installed, you can pass the result to ps2pdf to create a PDF instead:

lout my-document.lout | ps2pdf - my-document.pdf

I’ve mainly been testing with simple documents, but it seems to do its work very fast, and generates far less “noise” on the command-line compared to LaTeX.

Here is a sample lout file:

@SysInclude { doc }
@SysInclude { eq }
@SysInclude { graph }
@Document 
    @InitialSpace { tex }
    @InitialFont { Palatino Base 12p }
@Text @Begin
@Display @Heading { Sample Lout Document }
@PP
This is a sample paragraph. It is really just intended as filler, not as anything special. I should probably put in things like ``scare quotes'', and shouldn't avoid things like apostrophes so everyone can get a better sense of how things look. Maybe a sentence with a lot of different letters? How about: grumpy wizards make toxic brew for the evil Queen and Jack. I stole that from Google web fonts.@FootNote { You've heard of Google right? } What do you think?

@PP
Here is a new paragraph. Let's add words in @B bold and @I italics, shall we? How about @S { Small Caps }? We can even do a @ShadowBox { Shadow Box } if we like.

@QuotedDisplay {
This is a sample paragraph in a quotation display. It is really just intended as filler, not as anything special. I should probably put in things like ``scare quotes'', and shouldn't avoid things like apostrophes so everyone can get a better sense of how things look. Maybe a sentence with a lot of different letters? How about: grumpy wizards make toxic brew for the evil Queen and Jack. I stole that from Google web fonts. What do you think?
}

@Heading { A Numbered List }
@NumberedList
    @ListItem One
    @ListItem Two
@EndList

@Heading { Displayed Mathematics }
@Display @Eq { T(n) = big sum from i=0 to n-1 2 sup i = 2 sup n - 1}

@LeftDisplay @Heading { A Sample Graph }
@Graph
abovecaption { New South Wales road deaths
(per 100 million vehicle km) }
{
@Data points { plus } pairs { dashed }
{ 1963 5.6 1971 4.3 1976 3.7 1979 3.4
1982 2.9 1985 2.3 1988 2.0 }
}

@End @Text

The generated output looks like this:

The first three lines load specific libraries and commands. As you can see, there are special libraries for typesetting equations and complex mathematics, as well as for making graphs and figures. The next four lines represent the rest of the “preamble”; here I do little more that set spacing to emulate TeX in putting extra space between sentences, as well set the base font to Palatino. (The default otherwise is Times.)

Lout’s paragraph layout algorithm is based on TeX’s, and so should generate typographically pleasing results in most cases. It has a built in functional programming language, and so is highly extensible in all sorts of ways. It has built in mechanisms for lists, footnotes, citations, and most other routine tasks you’d expect.

I can think of the following advantages for learning Lout:

1. It’s lightweight! You could carry it around on a floppy disk, and the typical installation is less than 1% of a medium sized (La)TeX installation. That’s neat.
2. It’s fast! Typesetting a small document at least seems to take less time than it does with LaTeX.
3. It can be extended easily.
4. It’s free and open source, and can be used with any text editor. (I was pleased to discover that vim has syntax highlighting for Lout!)
5. There are far fewer external packages to remember the ins and outs of, and maintaining a Lout system is far easier than maintaining a TeX system.
6. A single comprehensive user’s guide is available: here.
7. It’s fun to learn something new.

But that’s not to say there aren’t significant disadvantages.

1. It’s not widely used, so you have trouble sharing with colleagues, and an impossible time submitting to journals.
2. You’re far less likely to find pre-made bibliography styles or templates for various journals or publishers.
3. You won’t be able to make use of the many specific and powerful packages that have been created for the (La)TeX ecosystem.
4. Conversion tools and other specialized software is harder to find.
5. The community of users with expertise you can drawn on is much smaller.
6. Sometimes it’s not so fun to (have to) learn something new.

That said, I’ve really only begun scratching the surface of learning Lout, and am by no means an expert. I welcome your feedback. For experienced users, what have you found to like or dislike about it? For inexperienced users, what are your first impressions?

I won’t be too judgemental in what follows, but just remember: only make what modifications are necessary. White space is normally a good thing.

The easiest and quickest way to fit more on a page is to go to a two column approach.

\documentclass[twocolumn]{article}
\setlength{\columnsep}{2em}

This makes your whole document two columns. For more control you might want to use the multicol package to only have some parts in two columns. You can adjust the \columnsep length to suit. I find anything less that 2em a little cramped, but if you’re really pushed for space you could change this.

\usepackage[margin=1in,top=1.5in]{geometry}

Here’s another easy trick that’s easily abused: change the document’s margins! The geometry package allows you to modify LaTeX’s default generous margins in a very simple way. For example, here I have set all margins to one inch, and then modified the top margin to be slightly larger. You can likewise change left,right,bottom margins separately. This is a powerful package that allows much more involved changes, but for now, let’s leave it at that. If you use the KOMA script classes, they have their own package with much the same functionality as geometry called typearea

\usepackage{enumitem}
\setlist{leftmargin=*,itemsep=0pt,parsep=0pt,topsep=.5\baselineskip}

Are your itemisations and enumerations taking up too much room? enumitem to the rescue! This package allows you to change many details of your list environments. Here I’ve just made spacing very minimal. Personally, I think this is too cramped, but if you really need the space, this is one way to do it.

Now, that pesky title is taking up altogether too much room. We can use the titling package to fix that.

\usepackage{titling}
\pretitle{\noindent\Large\bfseries}
\posttitle{\\}
\preauthor{\itshape}
\postauthor{}
\predate{\itshape}
\postdate{}
\setlength{\droptitle}{-1in}

This package completely redefines the way the titles are done. So we can just make a very minimal looking title by specifying what code we want before and after each of the title elements (title, author and date). The above example just sets the title large and bold, and the author and date on the next line in italics. Takes up much less space now. The \droptitle is the length of space above the title. I’ve made in one inch less than the default to save more space.

Finally, and this is by far the least intrusive and damaging modification, we can change the amount of space the section headings take up.

\usepackage[small,compact,sc]{titlesec}

The titlesec package has already cropped up in a previous post of mine. But this time, we’re just using its package options method for modifying things. This is much easier than getting into the nuts and bolts of how to change the section headings individually. The small option makes the section heading text smaller than normal. The compact option reduces the vertical space the headings take up. The sc option sets the section headings in small caps. I did this just to differentiate them from the title text, which is now of a similar size.

OK. That concludes this brief primer on breaking LaTeX’s sensible rules on how much stuff you should fit on a page.

Post script

Since writing this, boumol pointed out that the savetrees package does a lot of the same things I achieve, and indeed goes further. For instance, it modifies the letter spacing and leading (the space between lines). To quote Bringhurst: “in the world of digital type, it is very easy for a designer … with no regard for letters to squish them into cattle trains and ship them to the slaughter. When letters are maltreated in this way, their reserve of legibility is sapped. They can do little in return except shortchange and brutalise the reader”. savetrees does some other clever things like making LaTeX try harder to not have a paragraph end with a single word. You can, of course turn off the genuinely brutal things the package does, and keep the less brutal ones.

I think the above tutorial serves, in part, as one way to achieve some squishing. But more broadly, it serves to point to some good packages for modifying the style and layout of the page more generally.

1. pdflatex/xelatex/latex
2. bibtex
3. texdoc
4. kpsewhich and friends
5. tlmgr
6. other tools

pdflatex/xelatex/latex

pdflatex [options] filename.tex

Or

latex [options] filename.tex

Or

xelatex [options] filename.tex

Let’s start with the most obvious one, LaTeX itself! These days, most of us use pdflatex, which will take a LaTeX source file and directly output a PDF. If your code contains PostScript commands such as those from the pstricks package, you may need to use simple latex, which outputs a DVI file, which would then need to be converted first to .ps using dvips filename.dvi and then to pdf with ps2pdf filename.ps (which requires GhostScript). Another reason you might need plain latex could be that you’re using an older LaTeX system and need to use .eps graphics (although newer LaTeX systems can handle .eps using pdflatex directly). xelatex is like pdflatex in that it generates a PDF directly, but uses the XeTeX engine, which is necessary mainly if you want to use system fonts through, e.g., the fontspec package.

Important Options to Know About

There are quite a few options you can pass to (pdf)(xe)latex when you compile. Here are some of the ones I think it is important to know about.

-interaction=nonstopmode

Or

-interaction=batchmode

If you run LaTeX without options, and it encounters errors, it will give you an interactive prompt asking what to do. I don’t personally find it very user-friendly, and I think it hasn’t changed since the early days of TeX, when compiling could take much longer, and it sometimes made sense to fix problems on the fly rather than recompile from scratch. These days, it’s better to learn about all errors and fix them in the source file. Using nonstopmode or batchmode to compile will suppress the interactive prompts. The difference between them is that nonstopmode will ignore errors and do its best to build a PDF anyway, whereas batchmode will suppress PDF output if errors are encountered.

-halt-on-error

Using this option will cause LaTeX to quit after the first error it finds. This can be a time saver if you want to focus on fixing them one by one.

-file-line-error

This option affects the way errors are printed in the .log file, putting them in the format filename.tex:line_number:Error message, which can be useful for parsing the log.

-synctex=1

When this option is used, a file named filename.synctex.gz is created, which contains information about what parts of the PDF were created by what parts of the source file. Advanced editors and PDF viewers can use this information to conduct forward and reverse searches from one to the other (click on a spot in the PDF and jump to the corresponding part of the file, and vice-versa). You can also use the synctex program from the command line. E.g., synctex view –i 25:15:filename.tex –o filename.pdf would return information about what part of filename.pdf corresponds to line 25, row 15 of filename.tex. Type in synctex view help or synctex edit help (for the other direction) for more details.

-shell-escape

Activating the –shell-escape option allows LaTeX to execute other commands on your computer, and make changes to files other than the usual ones. This is mainly necessary if you need to call upon external commands such as a graphics conversion program to handle uncommon image formats, or the like. The option should be used cautiously, however, since poorly written or malicious code inside a LaTeX document could lead to trouble. On MikTeX systems, you need –enable-write18 instead.

bibtex

bibtex filename.aux

When you run (pdf)(xe)latex on a source file containing citations, it creates an auxiliary file, filename.aux, which, among other things, contains a list of those citations and information about the bibliography style chosen. The BibTeX program is run with this auxiliary file as input and uses it to create a file named filename.bbl, a bibliography file. Since it needs this auxiliary file, (pdf)(xe)latex must be run before running bibtex, and then run again at least once, typically twice, after bibtex, in order to incorporate the .bbl file bibtex creates into the document.

texdoc

texdoc [options] NAME

This is LaTeX’s equivalent to the UNIX man command. When you simply type in texdoc NAME, the most pertinent LaTeX documentation having to do with whatever you typed in for NAME will be launched. Usually, you’ll enter the name of a package or document class, e.g., texdoc enumitem, and the manual for that package will be opened. If you use the –l option, you’ll get a list of documents to choose from, if more than one relevant document can be found.

kpsewhich and friends

kpsewhich filename

Or

kpsewhere filename

Do you have more than one version of a certain package installed on your system, and are uncertain which version will be used? Or do you simply want to know where a certain file (package, document class, BibTeX style file, etc.) is located? Calling kpsewhich filename will tell you the exact location of the file that would be used with a given filename. For example, for me, typing in which enumitem.sty returns /usr/local/texlive/2011/texmf-dist/tex/latex/enumitem/enumitem.sty. If you want to see all the places where it is installed, use kpsewhere instead.

kpsepath FILETYPE

If you instead want a list of all the places LaTeX (or related program) searches when looking for a certain type of file, you can use kpsepath. The FILETYPE can be things like tex for TeX source, bib for BiBTeX bibliographies, bst for BibTeX style files, pict for images/figures, and several others. The result is a list of directories separated by colons. If a directory name ends with a double slash //, this means subdirectories are also searched. If a directory name is preceded by !! this means it doesn’t actually search the directory itself, but relies on an index of files (an ls-R) file, which can be updated by running:

mktexlsr /path/to/folder

(This may need to be run as root, or with sudo, to update the ls-R for folders you don’t have write-access to as a user.)

tlmgr

[sudo] tlmgr [action] [options] [target]

The TeX live manager, or tlmgr, is a powerful tool for managing your entire LaTeX installation. Its chief uses are installing, removing and updating packages. (Be warned, however, that if you’re using a Linux distribution that has its own package manager, and used it to install TeXlive, you may not have tlmgr in addition.) Since it makes changes system-wide, it must usually be run as root, or with sudo. For example, to install a package from CTAN:

sudo tlmgr install pgf

This would install the PGF/TikZ package if you didn’t have it already and get it ready to be used. To uninstall, use:

sudo tlmgr remove pgf

By far the most common use, for me personally anyway, is to update all the packages I have installed:

sudo tlmgr update -self -all

This will sync your list of packages with a CTAN repository. You can also use tlmgr to query which package a certain file belongs to:

tlmgr search --file tikz.sty

And tlmgr has dozens of other uses too. Type man tlmgr for a list of commands. I should also mention that if you have Perl/Tk installed, you can also use a GUI to access tlmgr, launched with:

sudo tlmgr gui

Though that defeats the purpose for this particular blog post.

other tools

texcount filename.tex

texcount, sometimes called texcount.pl is a sophisticated and customizable Word Count utility for LaTeX files, with many options, and comes with TeXlive. Run it without argument to get a help screen, and see its webpage for more information.

pdfcrop filename.pdf

PDFCrop, another perl script that ships with TeXlive, will crop a PDF to the smallest possible page size. This is useful if you use LaTeX to either create, or include, PDF images which need to be smaller than a full piece of paper.

pdfjam [options|actions] filename1.pdf [filename2.pdf]

PDFJam is actually a collection of tools that make use of the pdflatex pdfpages package to manipulate, combine, rotate and split PDF files. In fact, it is often used not with the above command, but with more specific commands that rely on it: pdfflip, pdfnup, pdfjoin, etc. See its homepage for more info.

detex filename.tex

This command will remove LaTeX commands and options from a file, leaving only the plain text behind. This can be useful for passing to a text to speech system, a spell checker, or in a variety of other ways.

Feel free to share your favorite LaTeX related commands and tricks in the comments below.

I’m also developing a package that allows you to print the input file line numbers in the margin. This is useful if you want to print off a copy of your draft for someone, and then be able to quickly incorporate their feedback. This is very much a work in progress (there’s no documentation to speak of and some of the options don’t work). But here is the github page for draftinputlines for the interested.

What is the cause of all this LaTeX related productivity? Why, it’s structured procrastination at its finest! I have a paper to finish drafting and am desperately trying to avoid it.

A sample

I need a sample to work with, so I picked a small section from a paper I’ve been working on.

\section{Introduction}
\label{introduction}

Peter van Inwagen \citeyearpar{vanInwagenDAUP} first formulated the 
Doctrine of Arbitrary Undetached Parts (DAUP).  Here is his 
presentation of that thesis:
\begin{quote}
  For every material object M, if R is the region of space occupied by 
  M at time t, and if sub-R is any occupiable sub-region of R 
  whatever, there exists a material object that occupies the region 
  sub-R at t.  \citeyearpar[123]{vanInwagenDAUP}
\end{quote}
DAUP says that if some arbitrary region of space sub-R is a part of 
the region occupied by an object, then there is another object that 
exactly occupies sub-R.  To make this more clear, consider an example: 
call the region occupied by my left hand `Left'.  Left is a part of 
the region I occupy.  So, according to DAUP, there is an object that 
exactly fills Left.

DAUP is an odd thesis in that its name tells us the thesis is a 
doctrine about \emph{parts,} but no synonym of `part' appears in the 
thesis.  Why think it is a thesis about parts at all?

[This part added]

Three reasons:
\begin{enumerate}
  \item First reason.
  \item Second reason.
  \item Third reason.
\end{enumerate}

[End addition]

Consider this definition of \emph{part}:
\begin{description}
  \item[Part as Overlap (PAO).] ``[O]ne thing is part of another if 
    and only if whatever overlaps the former also overlaps the 
    latter.'' \citep[44]{GoodmanSA}\footnote{Goodman uses the notion 
      of \emph{overlap} to define all the other mereological notions.  
      This means that, for example, \emph{identity} gets defined as 
      ``a and b are identical if and only if they overlap exactly the 
      same individuals,'' and \emph{sum} as ``that individual which 
      overlaps just those individuals which overlap at least one of 
      the two'' \citeyearpar[45--46]{GoodmanSA}.

    But as many have pointed out, there are a handful of mereological 
    notions one could take as primitive, defining the others in terms 
    of that one; for example, \emph{part, proper part,} and 
    \emph{disjoint} could work equally well.  See \citet{SimonsP} for 
    more on this.}
\end{description}

I had to add some to make sure I demonstrated how ordered lists worked, otherwise, this sample covers the basics: plain text, emphasized text, citations using Natbib, description lists, footnotes, and inline and block quotations.

On Pandoc and Markdown

Pandoc is an extension of Markdown. I’m going to be using those extensions here, so I’ll call what I’m writing ‘Pandoc’. You could do some of this using plain Markdown. Alternatively, you could use MultiMarkdown for a different extension of Markdown. But since I’m using the extensions provided by Pandoc, I’ll say I’m writing in Pandoc. But my file has a .markdown (or .mkd, if you prefer) extension.

Rewriting in Pandoc

I’m not so much interested here in converting from LaTeX to Pandoc, but in writing in Pandoc, then converting to LaTeX. So I’m starting with the following text, written in Pandoc (this is a manual translation of the above, so I can write it the way I naturally would, not the way Pandoc would translate it).

# Introduction

Peter van Inwagen [@vanInwagenDAUP] first formulated the Doctrine of Arbitrary
Undetached Parts (DAUP).  Here is his presentation of that thesis:

> For every material object M, if R is the region of space occupied by 
> M at time t, and if sub-R is any occupiable sub-region of R 
> whatever, there exists a material object that occupies the region 
> sub-R at t.  [-@vanInwagenDAUP 123]

DAUP says that if some arbitrary region of space sub-R is a part of the region
occupied by an object, then there is another object that exactly occupies
sub-R.  To make this more clear, consider an example: call the region occupied
by my left hand 'Left'.  Left is a part of the region I occupy.  So, according
to DAUP, there is an object that exactly fills Left.

DAUP is an odd thesis in that its name tells us the thesis is a doctrine about
_parts_, but no synonym of 'part' appears in the thesis.  Why think it is a
thesis about parts at all?

[This part added]

Three reasons:

1. First reason.
2. Second reason.
3. Third reason.

[End addition]

Consider this definition of _part_:

Part as Overlap (PAO)

:    "[O]ne thing is part of another if and only if whatever overlaps the
     former also overlaps the latter." [@GoodmanSA p. 44][^goodman]

[^goodman]: Goodman uses the notion of _overlap_ to define all the other
mereological notions.  This means that, for example, _identity_ gets defined as
"a and b are identical if and only if they overlap exactly the same
individuals," and _sum_ as "that individual which overlaps just those
individuals which overlap at least one of the two
[@GoodmanSA pp. 45-46].

    But as many have pointed out, there are a handful of mereological notions
    one could take as primitive, defining the others in terms of that one; for
    example, _part, proper part,_ and _disjoint_ could work equally well.  See
    @SimonsP for more on this.

# References

One thing I’m excited about here: I can hard wrap within paragraphs in Pandoc. I write my blog posts using Textile and you can’t do that. I don’t know if that is standard Markdown or not, but I like it!

Pandoc to LaTeX

I’m leaving out the header information that Pandoc generates, but when I run pandoc --bibliography ~/Library/texmf/bibtex/bib/mybib.bib -s -o tmp/pandoc_sample.tex pandoc_sample.markdown, here is the LaTeX I get back:

\section{Introduction}

Peter van Inwagen (Inwagen 1981) first formulated the Doctrine of
Arbitrary Undetached Parts (DAUP). Here is his presentation of that
thesis:

\begin{quote}
For every material object M, if R is the region of space occupied by M
at time t, and if sub-R is any occupiable sub-region of R whatever,
there exists a material object that occupies the region sub-R at t.
(1981, 123)

\end{quote}
DAUP says that if some arbitrary region of space sub-R is a part of the
region occupied by an object, then there is another object that exactly
occupies sub-R. To make this more clear, consider an example: call the
region occupied by my left hand `Left'. Left is a part of the region I
occupy. So, according to DAUP, there is an object that exactly fills
Left.

DAUP is an odd thesis in that its name tells us the thesis is a doctrine
about \emph{parts}, but no synonym of `part' appears in the thesis. Why
think it is a thesis about parts at all?

{[}This part added{]}

Three reasons:

\begin{enumerate}[1.]
\item
  First reason.
\item
  Second reason.
\item
  Third reason.
\end{enumerate}
{[}End addition{]}

Consider this definition of \emph{part}:

\begin{description}
\item[Part as Overlap (PAO)]
``{[}O{]}ne thing is part of another if and only if whatever overlaps
the former also overlaps the latter.'' (Goodman 1951, p.~44)\footnote{Goodman
  uses the notion of \emph{overlap} to define all the other mereological
  notions. This means that, for example, \emph{identity} gets defined as
  ``a and b are identical if and only if they overlap exactly the same
  individuals,'' and \emph{sum} as "that individual which overlaps just
  those individuals which overlap at least one of the two
  \citeyearpar[45--46]{GoodmanSA}.

  But as many have pointed out, there are a handful of mereological
  notions one could take as primitive, defining the others in terms of
  that one; for example, \emph{part, proper part,} and \emph{disjoint}
  could work equally well. See Simons (1987) for more on this.}
\end{description}
\section{References}

Goodman, Nelson. 1951. \emph{The Structure of Appearance}. Cambridge,
MA: Harvard University Press.

Inwagen, Peter van. 1981. The Doctrine of Arbitrary Undetached Parts.
\emph{Pacific Philosophical Quarterly} 62: 123--37.

Simons, Peter. 1987. \emph{Parts: A Study in Ontology}. Oxford: Oxford
University Press.

And here is what the PDF output looks like when I run that through LaTeX:

You’ll notice that some things didn’t work out quite right. But that isn’t a big deal. The big problem is that all the citations weren’t converted to LaTeX at all, they were just processed. If you are planning on working with the LaTeX document, this is no good.

The solution is to just use LaTeX citation markup in your Pandoc file. If I swap out my citations for \citets and \citeps, everything will work out just fine:

Pandoc to HTML

For now, stick with the Pandoc citation style, not LaTeX. If you do that, then when you run pandoc --bibliography ~/Library/texmf/bibtex/bib/mybib.bib -s -o tmp/pandoc_sample.html pandoc_sample.markdown, you get this:

 <h1 id="introduction">Introduction</h1>
<p>Peter van Inwagen (Inwagen 1981) first formulated the Doctrine of Arbitrary Undetached Parts (DAUP). Here is his presentation of that thesis:</p>
<blockquote>
<p>For every material object M, if R is the region of space occupied by M at time t, and if sub-R is any occupiable sub-region of R whatever, there exists a material object that occupies the region sub-R at t. (1981, 123)</p>
</blockquote>
<p>DAUP says that if some arbitrary region of space sub-R is a part of the region occupied by an object, then there is another object that exactly occupies sub-R. To make this more clear, consider an example: call the region occupied by my left hand 'Left'. Left is a part of the region I occupy. So, according to DAUP, there is an object that exactly fills Left.</p>
<p>DAUP is an odd thesis in that its name tells us the thesis is a doctrine about <em>parts</em>, but no synonym of 'part' appears in the thesis. Why think it is a thesis about parts at all?</p>
<p>[This part added]</p>
<p>Three reasons:</p>
<ol style="list-style-type: decimal">
<li>First reason.</li>
<li>Second reason.</li>
<li>Third reason.</li>
</ol>
<p>[End addition]</p>
<p>Consider this definition of <em>part</em>:</p>
<dl>
<dt>Part as Overlap (PAO)</dt>
<dd>&quot;[O]ne thing is part of another if and only if whatever overlaps the former also overlaps the latter.&quot; (Goodman 1951, 44)<sup><a href="#fn1" class="footnoteRef" id="fnref1">1</a></sup>
</dd>
</dl>
<h1 id="references">References</h1>
<p>Goodman, Nelson. 1951. <em>The Structure of Appearance</em>. Cambridge, MA: Harvard University Press.</p>
<p>Inwagen, Peter van. 1981. The Doctrine of Arbitrary Undetached Parts. <em>Pacific Philosophical Quarterly</em> 62: 123–37.</p>
<p>Simons, Peter. 1987. <em>Parts: A Study in Ontology</em>. Oxford: Oxford University Press.</p>
<div class="footnotes">
<hr />
<ol>
<li id="fn1"><p>Goodman uses the notion of <em>overlap</em> to define all the other mereological notions. This means that, for example, <em>identity</em> gets defined as &quot;a and b are identical if and only if they overlap exactly the same individuals,&quot; and <em>sum</em> as &quot;that individual which overlaps just those individuals which overlap at least one of the two .</p>
<p>But as many have pointed out, there are a handful of mereological notions one could take as primitive, defining the others in terms of that one; for example, <em>part, proper part,</em> and <em>disjoint</em> could work equally well. See Simons (1987) for more on this. <a href="#fnref1" class="footnoteBackLink" title="Jump back to footnote 1">↩</a></p></li>
</ol>
</div>

On it’s own, this code might be underwhelming. But when viewed with a browser, it is pretty nice:

Add a good stylesheet and your paper will look great for online viewing. Here is a sample, using a simple stylesheet plus normalize.css.

In my experiments, LaTeX commands (like \citep) were ignored in the translation to HTML.

Pandoc alone

It looks like we have a problem. If you use Pandoc citations with a bibliography, you don’t get a proper LaTeX bibliography. If you use LaTeX citations, they get ignored in your HTML. If you only want one or the other (likely LaTeX), you do have a solution.

This made me curious. What if you didn’t really care about mucking about with the LaTeX? What if you wanted to be able to write your paper in Pandoc and let that be it? Well, we already know you can output nice HTML. What are your other options? On the about page for Pandoc, we’re told Pandoc can output tons of formats: reStructuredText, HTML, LaTeX, ConTeXt, PDF, RTF, DocBook XML, OpenDocument XML, ODT, GNUTexinfo, MediaWiki markup, textile, groff man pages, Emacs org-mode, EPUB ebooks, and S5 and Slidy. Whew.

Let’s face it, most of those formats aren’t helping us much. They might be great for some people, but putting your paper in DocBook XML isn’t going to do anything for you. Your aim, I take it, is to have a printable paper you can share with people and a version you can submit. Let’s start with the printable version.

Pandoc to PDF

Why not let people just read a PDF. That’s what you do with LaTeX anyway. If you have a LaTeX distribution installed, you can use markdown2pdf at the command line to create a PDF directly. So markdown2pdf --bibliography ~/Library/texmf/bibtex/bib/mybib.bib -o tmp/pandoc_sample.pdf pandoc_sample.markdown yields a PDF with all my references in it, just as I’d like. With no customization, you can see what it produces:

That isn’t bad. Can I do better? Well, Pandoc lets me specify a template to be used with my file. If I do that, I can use any prologue I like with my file. Here’s a sample:

 \documentclass{article}
\usepackage{geometry}                
\geometry{letterpaper} 
\usepackage{graphicx}
\usepackage{amssymb}

\usepackage[T1]{fontenc}
\usepackage[utf8]{inputenc}
\usepackage{libertine}
%%%% FANCY HEADER
\usepackage{fancyhdr}
\pagestyle{fancy}
\lhead{}\chead{}\rhead{}
\lfoot{\textsc{$author$}}\cfoot{}\rfoot{\textsc{$title$} | \thepage}
\renewcommand{\headrulewidth}{0.0pt}


%%%% SMALL SECTIONS
\usepackage[compact,sf,small]{titlesec}


%%%% ARTICLE INFO
\usepackage[pdfauthor={$author$},
    pdftitle={$title$},
    bookmarks=false]{hyperref}
\title{$title$}
\author{$author$}
%\date{$date$}

\begin{document}
\maketitle
\tableofcontents

$body$

\end{document}

You’ll notice the variables ($title$, $author$, and $body). Those get filled in with your content and front matter. Read the link above if you want to know more about this. But by saving this as template.tex and then running markdown2pdf --template=template.tex --bibliography ~/Library/texmf/bibtex/bib/mybib.bib -o with_template.tex pandoc_sample.markdown, I was able to generate a PDF with my template (note you can pass the --template argument to pandoc, too, but only if you use the -s flag for a standalone LaTeX file).

One thing worth noting here: for some reason (perhaps through some fault of mine, I don’t know) markdown2pdf kept throwing errors on my original markdown source. It thought I was missing an \item in my ordered list for some reason. I ended up swapping out

1. First reason.
2. Second reason.
3. Third reason.

for

#. First reason.
#. Second reason.
#. Third reason.

It turns out that #. is a shorthand for a basic ordered list (the period keeps this from being a new section!), and for some reason this didn’t cause the same errors.

Pandoc to RTF, ODT, or DOCX

Converting Pandoc to Rich Text Format or Open Document Format was easy enough via the command line, but I can’t tell you how it looked. I don’t have Word installed on my Mac, and while Pages and TextEdit both opened the .rtf file, apparently neither shows footnotes in such a file. I looked at the files in Vim and the footnotes were there, they just weren’t showing up in Pages. So that is inconvenient. Here’s what Kevin had to say about footnotes and these formats in his post:

Because it can convert directly to OpenOffice (.odt) and Office Open XML (.docx) formats, it might serve as a useful tool for getting a LaTeX document into a Word Processing format for a stubborn editor. I personally don’t use either MS Word or Open Office, but for importing into AbiWord in general I preferred the .odt for mat it generates because LaTeX footnotes are preserved as footnotes, rather than converted to end notes (which was the result for .docx format). Unfortunately, the .odt files it generates could not be opened directly in Google Docs (though GDocs could open the .docx files it created).

To be honest, I’m not sure if this is a deal breaker for me or not. I think not. I do have a system with LibreOffice on it that I could use to look at the footnotes. I’m not planning on doing any actual editing in that file anyway, so this might not be a huge deal. If the footnotes show up in that format and someone who demands an RTF or DOC file can read them, then that might be good enough for me.

But besides the issue with footnotes, the output looks passable:

An Ebook?!

If you go to http://www.amazon.com/gp/feature.html?ie=UTF8&docId=1000234621, you can download KindleGen, a command line utility to turn .epub format books (also HTML, but I only tried epub) into Kindle formatted books. To do this you have to specify the title of the document, so don’t forget to do that. (See below for more on this.)

I didn’t specify a stylesheet, so the look isn’t as good as it could be, but here is a sample of the output:

Something I missed

One thing that troubled me when I was creating my Kindle book was figuring out how to set the title and author. I resorted to an epub-metadata file for that, but later learned that you can set this all in a title block. To do that, you start the file like so:

% title
% author(s) (separated by semicolons)
% date

So this paper:

% A Sample Title
% Charlie Tanksley

# Title

Here is the first line.

Will produce a PDF that looks like this when processed with the -s (standalone) flag:

(Note that you don’t need said flag if using markdown2pdf, and that if you neglect that flag, the title block will just be ignored, so including it doesn’t hurt.

A verdict

I haven’t tried writing a paper in Pandoc/Markdown in a very long time. I’m pretty comfortable using LaTeX and don’t mind the syntax I have to type (I rely on lots of SnipMate snippets in Vim to automate lots of that). But Markdown is easy to write. Very easy. So that is kind of compelling.

I’m torn on the issue of having HTML versions to put on the web. I’ve never read a philosophy paper in an HTML version (or if I did, I just printed it off), so my guess is that this isn’t terribly useful, at least for me. So the main consideration is with the experience of writing. If you’d rather write *bold* than \textbf{bold} and [@lewis:on] instead of \citep{lewis:on}, then it might be worth giving Markdown/Pandoc a spin.

I’m genuinely torn on the question of using Markdown for my next paper. I might give it a shot; but I might be too stuck in my ways. I’d love to hear what you think of the idea and/or what your experiences are with Markdown.

Caveats

I don’t write much math or logic. Some people use LaTeX because they write lots of symbols. If that is you, you’ll need to write all your math inside LaTeX markup. Then you’ll have to figure out how to convert it to HTML and RTF. I think it can be done (there are command line options for it), but I don’t know how well it works. So try before you buy.

Appendix: Installing Pandoc

Pandoc is notoriously difficult to install. The problem is that Pandoc is written in Haskell, so you have to install a ton of stuff just to install Pandoc. And that is the kind of complicated part. At least, it used to be complicated, but it isn’t so bad anymore. (If you are on a Mac; if you use Windows, I don’t know what to tell you; if you use a Linux distribution, you’ll do something similar to what I describe below, but you’ll use your package manager for everything.)

If you are using a Mac, you have to start out by installing Xcode. This is easy. If you have an install disc from Snow Leopard (or Leopard, I imagine), you can use that to install the ‘Developer Tools’. That’ll install everything you need. If you want to do things the easy way, go to the App Store and pay the $4 for Xcode. You need it.

With Xcode installed, you need to install the Haskell Platform. Thanks to Homebrew, this is a simple brew install haskell-platform away. If you don’t use Homebrew, see my post on installing Homebrew. You need Xcode to install Homebrew, too. Not only does Homebrew make lots of programs very easy to install, but it makes updating the Haskell-Platform a simple brew install haskell-platform, when the time comes. This is a fairly huge download, so be prepared to wait. (If I recall correctly (which I doubt), on Arch Linux this was a fairly simple sudo pacman -S haskell-platform.)

With the Haskell-Package installed, you’ll have a new installer called cabal installed. That can be used to install any Haskell packages you like. I’ve only ever installed Pandoc on my Mac, but you could install more if you like. So cabal install pandoc to install pandoc. (Note that you may need to put ~/.cabal/bin in your path.)

Sometimes this need can be covered by version control. For example, if you need to change how a paper looks for submitting it to a journal. I recently had to remove all my lovely BibLaTeX citations and use a thebibliography environment. (Oh I should write a post about how to do that too.) Now these sorts of changes you don’t want to propagate through all your versions, so VCS seems the reasonable way to do that.

But say you are writing a beamer presentation and you want a presentation version and a handout version. Merging all the content changes between each version every time you make a change seems like a big hassle. The actual functional differences will likely be very minimal. Obviously the handout version will have the handout option to the documentclass call, and you might have a couple of other minor changes (I use pgfpages to print 4 on 1 for my beamer notes).

Let’s consider another simpler problem. Let’s say you want two versions of an article: one normal and one two column and landscape, to save paper when printed. The content will be the same in each, the only thing different will be a couple of lines to get the right layout.

One way you could do this is to have several files. One file (say “content.tex”) would contain the content. Then there would be another file, the basic version that contains the preamble part for the basic file and then a line that says \input{content}. Then you’d need a third file which contains the relevant preamble for the two column landscape version with a similar \input{content}.

Now, I’ve used this system in the past and it works fine. However, what if you wanted to have different options passed to the hyperref package? This package likes to sit at the end of the preamble, so you can’t put it in each of the container files without including all of the preamble in each container file. But then you need to make sure that you keep the two preambles in sync otherwise. You could put the preamble in a different file and input it into each container before calling hyperref, but this is not ideal. Also what if you wanted to do more versions, say a 10pt version and a 12pt version? Now you’d need five or six files to sort all this out.

There is a better way, and it involves breaking rules that you might have been taught about LaTeX. The not so short introduction to LaTeX contains the claim that “every input file should start with \documentclass”. This is a lie! You can put some sorts of things before the document class, and it’s very useful to do so sometimes.

We’re going to see how we can use LaTeX’s conditional statements to maintain several versions of the same file with just one file! Here’s a simple example of the start of a beamer presentation:

\newif\ifhandout\handoutfalse
% \handouttrue % Uncomment this line to switch on the handout option
\ifhandout
\PassOptionsToClass{handout}{beamer}
\fi
\documentclass{beamer}
...

What this does is define a conditional that can be true or false. We set it to false for now. We can then build our beamer slides as normal. Now let’s say we want to print a version of the slides, we don’t want to print every slide if we’re using lots of overlays. So we can pass the handout option to the document class by switching the conditional to true. This seems a complicated way of adding an option to beamer. Surely just adding the option by hand whenever you want a handout version is easy enough? True, but this way, you can easily make extra modifications for each version. For example, you could have a colourful presentation, but a greyscale colour theme for the printed handout:

\newif\ifhandout\handoutfalse
% \handouttrue % Uncomment this line to switch on the handout option
\ifhandout
\PassOptionsToClass{handout}{beamer}
\fi
\documentclass{beamer}
\usetheme{Rochester}
\ifhandout
\usepackage{pgfpages}
\pgfpagesuselayout{4 on 1}[a4paper,landscape,border shrink=5mm]
\usecolortheme{seagull}
\else
\usecolortheme{beaver}
\fi
...

Note the use of else to specify what to do if the conditional is false (that is, use a colourful theme.) We’ve also taken the opportunity to print the slides 4 on 1 page for the handout. Now you can begin to see that the conditional is saving you some work!

The awkward thing about this set up is that the handout version will be written to the same pdf file as your original presentation version. This means that you’ll have to copy the presentation version to a different file before compiling with handout turned on. You can get around this problem, but that’s a topic for another day. (tex.stackexchange has the answers, if you can’t wait…)

Another thing I use this sort of trickery for is adding comments to my documents. I define an mnote command which prints a comment in the margin if a particular switch is true:

\ifmarginnotes
\KOMAoptions{mpinclude=true}
\newcommand\mnote[1]{\marginpar{\footnotesize\raggedright #1}}
\recalctypearea
\else
\newcommand\mnote[1]{}
\fi
\setlength\marginparwidth{1.67\marginparwidth}

What this is doing is checking whether the marginnotes switch is on. If it is true then we define the mnote command to put a comment in the margin (and we mess about with KOMA script’s margins to allow the comment some room). If the switch is false, then we just define mnote to ignore its argument and thus the comment doesn’t appear in the final version. There are packages for handling notes like this, but really, all you need is some basic TeX conditionals…

I’m sure there are lots more sophisticated things you could do, but these few tricks alone have saved me some time…

Pandoc supports many different formats. Conversion input formats include:

• plain text
• HTML
• LaTeX
• textile
• reStructuredText (rst)
• others such as native Haskell and, JSON

And conversion output formats:

• plain text
• HTML
• LaTeX
• ConTeXt
• OpenOffice (.odt)
• OpenDocument XML (e.g., MS Word .docx)
• emacs Org-mode
• ebook formats (ePub and DocBook)
• slideshow formats (slidy or S5)
• and others including native Haskell, JSON, MediaWiki, groff man page,

Many features seem especially geared toward markdown aficionados (which, alas, don’t include me), including pandoc-specific markdown extensions for additional power.

I am myself most interested in its conversion to and from LaTeX format. The most important change for me personally is that the new version now processes user-defined LaTeX commands using the definitions given in the LaTeX document, rather than leaving all such commands as codes in the output. Since I am a custom-command junkie, this has made a world of difference. There is also limited support for using BibTeX bibliographies.

Because it can convert directly to OpenOffice (.odt) and Office Open XML (.docx) formats, it might serve as a useful tool for getting a LaTeX document into a Word Processing format for a stubborn editor. I personally don’t use either MS Word or Open Office, but for importing into AbiWord in general I preferred the .odt format it generates because LaTeX footnotes are preserved as footnotes, rather than converted to endnotes (which was the result for .docx format). Unfortunately, the .odt files it generates could not be opened directly in Google Docs (though GDocs could open the .docx files it created).

There are special modes for handling LaTeX math mode, including generating MathML or mark-up to use with jsMath, gladTeX and MathJax. I experimented most with the MathML setting, but my expectations weren’t high, since I doubt anything can handle math typesetting as well as LaTeX itself, and so conversion is bound to result in a net loss. It sometimes did a good job, but there are certain math mode codes which I use often, such as \text, \mathrel and similar spacing commands, which it did not handle. Yet, I was not disappointed all in all, given my expectations.

Some other small gripes.

• (Most annoying:) Smart quotes and apostrophes were mishandled in converting from HTML to LaTeX: ’ or ” for smart quotes in HTML are converted into character codes LaTeX does not know how to handle, even with the ucs package loaded. (On the other hand, smart quotes were handled well when converting in the other direction, yielding the appropriate UTF-8 characters.)
• Simple LaTeX tables were not converted to HTML tables, though the program does support conventions for table mark-up when converting from MarkDown.
• Sometimes LaTeX mark-up which it can partially but not fully handle leaves unwanted effects. Just to give one example, if you use the syntax \\[10pt] or similar to insert a linebreak of a nonstandard length in LaTeX, the “[10pt]” part is not removed in the output, even though the linebreak is processed.

With the newer version, pandoc is something I plan on incorporating in my conversion tool kit, alongside my old stand-bys such as AbiWord, latex2rtf, rtf2latex2e, and TeX4ht. It is currently the program I use to convert my LaTeX documents to plain text, which I use to pass them to a text2speech program (I use festival) to have the computer read them out loud, which I find useful when proofreading.

The idea with ThePhilosopher.me is simple enough: it is an application that makes it as easy as possible for philosophers to create a page that lists all their publications (with links). I think I’ve done that. You can log in and add a biography, a photo, your email, etc., but the default is to create a page by simply entering your name (the exact name you published under) and clicking a button. The site should do all the heavy lifting and give you what I think is an attractive page you can point people to if they want to know about your publications (this is a really simple way to make a professional webpage your department webmaster can link to).

You can see some example pages here:

• www.thephilosopher.me/charlietanksley
• www.thephilosopher.me/christophergrau
• www.thephilosopher.me/kevinklement

This is the first web app I’ve created, and it still has some rough edges. I’m announcing the site here as part of a slow rollout. Since readers of this blog are (mostly) philosophers and are at least technologically inclined enough to care about LaTeX, I figured this was a good first place to announce the site. Please let me know if you run into any problems as you poke around the site. Your feedback is invaluable to me. I’m planning on rolling the site out to a little bit wider audience on Monday of next week, so if you run into any problems, please let me know!