1 Mazugis

Markup And Markdown Homework Pass

Opener:  As students enter the room, they will immediately pick up and begin working on the opener – Instructional Strategy - Process for openers.  This method of working and going over the opener lends itself to allow students to construct viable arguments and critique the reasoning of others, which is mathematical practice 3

Learning Target:  After completion of the opener, I will address the day’s learning targets to the students.  For today’s lesson, the intended target is, “I can calculate a markup using a percent bar model.” Students will jot the learning target down in their agendas (our version of a student planner, there is a place to write the learning target for every day). 

Thoughts from Me! As a way to dive into percents and create a conceptual understanding, students will utilize a bar model (mathematical practice 5).  They will use the model to represent scenarios conceptually (mathematical practice 4) instead of just punching numbers. Students will also reason abstractly and quantitatively by analyzing what each model represents (mathematical practice 2).  Students will look for repeated reasoning to make connections within percents (mathematical practice 8).

It’s that time of year when students are signing up for study skills classes. One of the skills that science students are likely to be encouraged to develop is the use of LaTeX. Other people may come to LaTeX for other reasons: people who want to typeset their own books; people who’ve heard that LaTeX may have something to do with Digital Humanities; etc. I’ve written this essay as a sort of pre-introduction to LaTeX. It won’t teach you how to use it (I’m not qualified!), but it will try to give non-users a clear understanding of what LaTeX is really for, which may help them to make their minds up about whether the effort of learning it (not to mention simply getting it to work) is really going to be worthwhile. Why such a long essay? Because many of those who evangelise for the use of LaTeX fetishise it to the extent of spreading misinformation about its true benefits and I want to clear some of that up.

1. What is LaTeX?

According to its own website, LaTeX (pronounced ‘lay-tech’) is ‘a high-quality typesetting system’ and ‘the de facto standard for the communication and publication of scientific documents.’ (LaTeX Project n.d., para. 1) I’m not going to argue with that.

Commercial typesetting of books, magazines, etc is typically done using WYSIWYG applications for desktop publishing, such as InDesign, Scribus, or the now-discontinued PageMaker. LaTeX works differently: you set it to work on a file containing text interspersed with code (i.e. markup), and it spits out a Postscript file that another program can convert into a PDF (some variants will generate PDFs directly). If you’ve spent any time reading (a) papers from computer science conferences, (b) open access preprints of scientific articles on arXiv.org, or (c) documentation for R packages, you will be familiar with the look of those PDFs: the titles (but not the headings) are centred, the first line of each paragraph is indented, the lines of type are justified, the margins are usually generous unless a double-column layout is used, the word-spacing is elegant, and everything is (typically) printed in this weird, old-fashioned-looking typeface called Computer Modern.

Technically, LaTeX is built on top of TeX: ‘a special-purpose programming language that is the centerpiece of a typesetting system that produces publication quality mathematics (and surrounding text)’ (TeX Users Group, n.d., para. 8). TeX was created in the late 1970s by the legendary computer scientist, Donald Knuth, who was disappointed by his publisher’s standards of typesetting. Its early adopters were mathematicians, who appreciated its provision of mathematical symbols unavailable on the typewriter as well as the beauty that its typesetting algorithms gave to mathematical formulae. In the early 1980s, another distinguished computer scientist, Leslie Lamport, extended TeX to produce LaTeX (it is the first two letters of his surname that provide the ‘La’ in ‘LaTeX’). Lamport did this by creating TeX macros: that is, programs that write TeX code for you, behind the scenes. Very few people try to write documents directly in TeX. It’s too hard. Writing in LaTeX is easier. But that doesn’t mean that it’s a good idea.

2. A fetish for LaTeX

Many scientists and mathematicians write articles in LaTeX form: as they type the words and punctuation marks of the text that the reader will encounter, they intersperse them with bits of code that instruct the computer on how to typeset the text. The computer interprets these bits of code as instructions such as ‘style this bit of text as a chapter title’ or ‘insert an ellipsis here’. The result is (ideally) a nice-looking PDF that can be submitted to a journal for review; if the journal accepts the article, then the author or authors can upload more-or-less the same PDF to an Open Access repository and send the LaTeX source code to the journal itself, which will typeset it again. LaTeX users often produce other documents using LaTeX too: their PhD theses, conference handouts, and CVs, for example. Perhaps this is just because, having mastered a particular technology for some particular purpose, one may just as well employ it for every other purpose that it can be made to serve. But there may be more positive reasons too. LaTeX-typeset documents are, as I’ve hinted above, for the most part fairly easy to recognise. A LaTeX-formatted CV is the CV of a LaTeX user, and a LaTeX user is to be taken seriously within LaTeX-using academic disciplines. Etc.

Although LaTeX places fewer obstacles in the writer’s way than TeX does, the fact that people write prose in either of them is anomalous. LaTeX is a typesetting system and a markup language. Typesetting systems are not customarily used for writing in, and while markup languages such as XML and HTML often are, this is generally recognised as a bad idea. It has been quite reasonably asserted that ‘making humans edit XML is sadistic’ (Django Project n.d., para. 10), for example, and while it was at one time suggested that the online journal Digital Humanities Quarterly would require all submissions to be in XML (and a unique variety of XML was created specifically for the purpose), it now additionally accepts submissions in the file formats used by popular word processing packages (see DHQ 2016, para. 10). The requirement to use the wikitext markup language when authoring or editing Wikipedia articles has been recognised by the Wikimedia Foundation as a barrier to participation, though its efforts for reform were stymied by the ever-diminishing community of committed Wikipedia volunteers, amongst whom ‘it’s not a fringe opinion that making editing easier is a waste of time’ (Simonite 2013, para. 22). I write this blog using the slightly simplified version of HTML required by WordPress’s ‘plain text’ editor – though every time an essay gets beyond a certain length, I start to wish that I didn’t. Markup’s great for machines to read and write, but for humans, not so much – and this is well understood by the creators of word processors such as Microsoft Word and LibreOffice Writer, both of which store text in XML form, but neither of which ever makes the user deal with the actual XML.

Despite this, much writing is done in LaTeX. What I call the ‘LaTeX fetish’ is the conviction that there is something about LaTeX that makes it good for writing in. As we shall see, arguments in favour of writing in LaTeX are unpersuasive on a rational level: LaTeX is in fact quite bad for writing in (although it could be worse, i.e. it could be TeX). This doesn’t mean that people shouldn’t use LaTeX at all, but it does mean that people probably ought to stop recommending it as a writing tool.

3. The case for writing in LaTeX

LaTeX is better for writing in than TeX, but that isn’t saying much. Some enthusiasts will say a lot more, however, implying – or stating outright – that writing in LaTeX is somehow better not only than writing in TeX but than writing with the use of a word processor. The blog for the ShareLaTeX online editing software for example gives the following advice to PhD students: ‘Your thesis could be the longest and most complicated document you’ll ever write, which is why it’s such a good idea to use LaTeX instead of a common word processor.’ (ShareLaTeX 2013, para. 1) A fuller argument is presented by the LaTeX Project itself:

LaTeX is not a word processor! Instead, LaTeX encourages authors not to worry too much about the appearance of their documents but to concentrate on getting the right content. For example, consider this document:

Cartesian closed categories and the price of eggs
Jane Doe
September 1994

Hello world!

To produce this in most typesetting or word-processing systems, the author would have to decide what layout to use, so would select (say) 18pt Times Roman for the title, 12pt Times Italic for the name, and so on. This has two results: authors wasting their time with designs; and a lot of badly designed documents!

LaTeX is based on the idea that it is better to leave document design to document designers, and to let authors get on with writing documents. So, in LaTeX you would input this document as:

(LaTeX Project n.d., paras 2-6)

The above is a fairly standard explanation of why people should use LaTeX instead of a word processor, and I’ve seen versions or partial statements of the same argument many times. As of the time of writing, the Wikipedia page on LaTeX, for example, says this: ‘LaTeX follows the design philosophy of separating presentation from content, so that authors can focus on the content of what they are writing without attending simultaneously to its visual appearance.’ (Wikipedia 2016, para. 7) In a presentation entitled ‘Writing papers the right way’, staff at the MIT Research Science Institute follow the question ‘Why LaTeX?’ with the unequivocal answer, ‘Presentation shouldn’t get in the way of content’, and then explain this point with a series of comparisons between word processors and LaTex – comparisons each of which sees LaTeX emerges as the winner:

  • With a word processor, you spend valuable time agonizing over what font size to make the section headings.
    With LaTeX, you just tell it to start a new section.
  • With a word processor, changing the formatting means you have to change each instance individually.
    With LaTeX, you just redefine the relevant commands.
  • With a word processor, you have to carefully match any provided templates.
    With LaTeX, you can be sure you’ve fit the template, and switch templates easily.

(RSI Staff 2015, slide 5)

Sound terrible, those word processors, don’t they? And that LaTeX, it sounds great, doesn’t it? Now, I’ll be honest with you. I took these sorts of arguments at face value for a while, and I more-or-less repeated them as part of a published discussion of academic literacy practices:

While it was difficult to change the appearance of letters typed on old-style mechanical typewriters, popular computer operating systems are distributed with a range of digital fonts, giving millions of people access both to modern typefaces such as Helvetica, Gill Sans and Calibri, and to centuries-old typefaces such as those of the Garamond family. Such opportunities can be viewed as a distraction, which is why many scientists reject word processors in favour of LaTeX: a document markup language that encourages the user to forget about what the text is going to look like and concentrate instead on its conceptual structure.

(Allington and Hewings 2012, p. 53)

So this is – officially – why LaTeX is good for writing in. Word processors make you ‘worry too much about the appearance of [your] documents’, which is ‘a distraction’, but writing in LaTeX enables you to ‘focus on the content of what [you] are writing without attending simultaneously to its visual appearance’, usefully ‘forget[ting] about what the text is going to look like and concentrat[ing] instead on its conceptual structure’. Everybody says so. Even me. (My co-author’s innocent, btw: I wrote that paragraph.)

4. The case critiqued

So convinced was I that this was why scientists wrote in LaTeX that I even had a go at writing a LaTeX paper of my own (it never got finished; there was a lesson there). What I eventually realised was that while the argument is (as noted above) widely repeated, it is also wrong. Let’s have a look at that example again. Seriously, anyone who believes that making people type this…

…instead of this…

Cartesian closed categories and the price of eggs
Jane Doe
September 1994

Hello world!

…amounts to ‘let[ting] authors get on with writing documents’ has (at best) a slightly unconventional understanding of the words ‘let’, or ‘writing’, or possibly ‘get on with’. Do any LaTeX users really believe that this is why they use LaTeX? Perhaps a parallel can be drawn with the ‘discursive mantras’ that Matt Hills argues to be prevalent among fans of cult television shows such as Doctor Who. These mantras – standard arguments trotted out again and again by fans – are, in Hills’s analysis, ‘defensive mechanisms designed to render the fan’s affective relationship meaningful in a rational sense, i.e. to… legitimate the fans’ love of “their” programme’ (Hills 2002, p. 67). Try reading ‘fan’ as ‘committed user’ and ‘[television] programme’ as ‘[computer] program’. But it’s more than that. The argument is used in persuading new generations of academic writers – students especially – to take up LaTeX.

So let’s take a still closer look at the full LaTeX Project argument quoted above:

  1. To produce this in most typesetting or word-processing systems, the author would have to decide what layout to use, so would select (say) 18pt Times Roman for the title, 12pt Times Italic for the name, and so on.
  2. In most typesetting systems – yes, arguably. That’s the point of them. But most people who do their writing on computers don’t do it using typesetting systems. They do it using word-processors such as Word, Writer, or Pages. And these have default settings that are (for the most part) allowed to stand. That is why there are so many documents in 12pt Times New Roman (formerly the default font on Word, the market leader among word processors) and 12pt Calibri (currently the default font on the same word processor). If you want to go messing with the font and the margins on your word processor, you can. But you are not made to. And there’s certainly no need for a conscious decision about it before starting to write. It is thus completely false to suggest that one ‘would have to’ select a typeface, font size, etc in order to produce the example document above in a word processor. One would simply have to type ‘Cartesian closed categories and the price of eggs’, etc – which is a lot more intuitive than typing (not to mention ), as in LaTeX one must. Of course, typing the words ‘Cartesian closed categories and the price of eggs’ won’t produce a nicely formatted title, as will (once LaTeX has worked its magic) – but there’s a way around this which is just as effective as the LaTeX way and much less obtrusive (we’ll come to it shortly)

  3. This has two results: authors wasting their time with designs…
  4. Authors have many ways of prevaricating, including messing around with designs. There’s no reason to suppose that authors who use word processors would prevaricate less if they didn’t use word processors. They might prevaricate by perfecting their LaTeX setups. I know a number of academic authors who seem to spend considerable amounts of time doing that. I shan’t say that this is worse, but is it really better? Until there’s empirical evidence that LaTeX authors prevaricate less than other authors, the above is a baseless assertion, expected to be taken on faith

  5. …and a lot of badly designed documents!
  6. Well, maybe. But there are other ways around that problem. For example, the last three universities I have taught at all have formal specifications for the formatting of student work – formal specifications that closely resemble the default settings on popular word processors. When it comes to stopping people from creating documents in purple 28pt Comic Sans, teaching them all to use LaTeX is a lot less efficient than stating that you will refuse to read anything that doesn’t match the style guide. (Teaching them to use word processors properly might also help.)

  7. LaTeX is based on the idea that it is better to leave document design to document designers, and to let authors get on with writing documents.
  8. Think about this for a moment. If ‘How can we let authors get on with writing documents?’ is the question, can LaTeX really be the answer? LaTeX does less to prevent authors from getting on with writing documents than TeX does. But if neither of the two existed, and you had to come up with something, right now, in 2016 – would it really be a markup language?

The MIT Research Science Institute argument isn’t much better. If you look at the three comparisons carefully, what’s actually being contrasted is not LaTeX and word processors, but the effective use of LaTeX and the naive misuse of word processors: all three things that the Research Science Institute staff tell their students can be done with the wonderful LaTeX can in fact be done perfectly well with a modern word processor. I’ll get to the details in the following section, but for now it is enough to observe that people who don’t know how to use a particular tool very well are being told to throw that tool away and learn to use an entirely new one on the grounds that it will enable them to do things that they could have done at least as well with the old one – which is (when you think about it) a little peculiar if the aim is really to help people with their writing, and not (heaven forbid!) simply to evangelise for a community’s preferred way of doing things. The really important thing to teach students is the importance of writing in a structured way and using the features of whichever tool they are using in order to facilitate that, but instead we have LaTeX evangelism and the false implication that word processors don’t facilitate structured writing at all. Someone who indicates section headings in a word processor by emboldening them or enlarging the font size is not using that word processor correctly and will be unable to take advantage of its full range of features, e.g. Microsoft Word’s Outline view, LibreOffice Writer’s Navigator, or the automatically generated tables of contents that both will create at the touch of a button. Comparing good use of LaTeX with poor use of word processors is unfair; the most that can really be said is that you are more likely to be introduced to LaTeX in a class taught by someone who really knows how to use it, and more likely to be introduced to a word processor by playing around with it or under the informal instruction of someone who doesn’t understand it very well, and that, for this reason, the number of people who use LaTeX but don’t use its document-structuring features is probably close to zero while the number of people who use word processors and don’t is enormous.

In sum, the case for writing in LaTeX is more than a little weak. TeX solved a genuine problem for scientists and mathematicians, but it made writing the prose that surrounded their mathematical formulae rather hard; LaTeX partially mitigated that problem at a time when few other reliable computer typesetting systems existed and none were designed specifically for academic use; TeX had behind it perhaps the biggest name in computer science since von Neumann; TeX and LaTeX were already-existing, already-working examples of free software at exactly the time that the free software movement started to kick off and evangelise; things developed from there. None of these was a bad reason for certain academic communities to adopt TeX and LaTeX in the 1980s. But none of them has anything to do with any supposed advantages of LaTeX as a writing medium – and the fact that most people use word processors badly is neither here nor there.

5. The case against writing in LaTeX

To cut to the chase, LaTeX documents are very hard to read until typeset, which is inefficient for both writing and editing. This is a point that programmers ought to understand: if the readability of code is important, then so is the readability of text. LaTeX documents can yield beautifully readable PDFs once typeset, but the experience of editing them might politely be described as sub-optimal.

LaTeX is, as already noted, a markup language. Markup consists of text spattered with code. The code gets in the way of the content. Reading marked up text requires interpreting or filtering out the markup in order to reconstruct the actual text in your head. This is not an advantage when writing or editing prose. I’ll show you what I mean.

Here is a screenshot of some text marked up as LaTeX. The text is taken with slight adaptations from an article I published this June. In the screenshot, I’m editing it using the version of Emacs that comes with OS X, which is my usual text editor when I’m working on a Mac:

You’ll note (click for a full size image) that the title is inside a pair of curly brackets identified as containing the title (), while the section heading is inside a pair of curly brackets identified as containing the section heading (). That is the nature of markup. What the markup is doing is good – unambiguously identifying the section heading as a section heading will help us later (e.g. when the designer wants to apply some particular style to all the section headings) – but doing it through markup (as opposed to doing it in some other way) is disruptive of the text for human readers (including editors and the original author): looking at the screenshot, we see the text mixed up with a lot of symbols that are not part of the text, and it is up to us to figure out what words and punctuation marks the eventual reader will see. That is a distraction from figuring out whether those words and punctuation marks are the right ones for the writer’s purpose. No matter how accustomed you are to the markup language in question, it’s an unnecessary cognitive burden. This is a particular issue with regard to the BibLaTeX markup for automatically generating citations and bibliography, because that markup doesn’t at all resemble the text that it will generate in the finished product.

By the way, one of the words in the screenshot is not right. It’s a typing error that I deliberately inserted. I know where it is because I put it there, but looking for it is hurting my eyes.

The following is a screenshot of the same text being edited with LibreOffice Writer. The same typing error is present, but this time you may find it easier to spot (I should add that the spellchecker didn’t; again, click for the full-sized image):

Spoiler: it’s ‘devotes’ (for ‘devotees’). Maybe you spotted it here, maybe you didn’t, maybe you spotted it in the markup – but I think you’ll agree that looking for it in a document sans markup was an easier mental task. I should point out that the citations and bibliography were automatically generated (with Zotero), but in such a way as to appear on screen in their final (easily readable) form: where the LaTeX version of the text has and , the LibreOffice version has ‘(see Bennett 2002)’ and the actual bibliography.

I’d also like to point out that the title and section heading are no less unambiguously identified as such in this document than they are in the LaTeX document above. At the time when I took the screenshot, the cursor was on the same line as the title – though you can’t see this in the screenshot itself. If you look in the top left of the screen (just underneath the Zotero buttons), you’ll see the word ‘Title’ in a dropdown menu box. By using that dropdown menu, I told LibreOffice that the line on which my cursor was placed at the time contained the title, and in the same way I told it that ‘A past that it could not transcend’ was a top level heading (‘Heading 1’, equivalent to the HTML tag). Just like LaTeX, LibreOffice infers that text following a heading but not designated as anything else is body text belonging to that heading (although one can also explicitly designate text as body text using the dropdown menu just mentioned). Move the cursor from one line to another and the label in the dropdown menu box changes, telling you what the text on that line has been designated as. If you want to change the style of headings or of body text throughout the document, you edit the styles and then the word processor will apply the changes automatically to the actual text. You can also save edited styles as a template, then load them into any document you want, restyling that document to match the template. And of course you can share the template with other users so that everybody’s documents are styled consistently.

So, pace the LaTeX Project’s claims, I didn’t ‘have to decide what layout to use’, nor to choose a typeface, a font size, or a font style. LibreOffice does that for you once it knows what to style as a title, what to style as a heading, etc. And pace MIT Research Science Institute staff claims, I didn’t have to ‘spend valuable time agonizing over what font size to make the section headings’ – I just designated certain bits of text as section headings, and LibreOffice handled the font size. And whatever the Research Science Institute staff may want students to believe, ‘changing the formatting [doesn’t mean] you have to change each instance individually’ – just as you can ‘redefine the relevant commands’ in LaTeX, you can redefine the relevant styles in LibreOffice (though for this screenshot, I’ve stuck with the defaults, as I usually do). Moreover, you don’t ‘have to carefully match any provided templates’, because you can switch templates just as easily in LibreOffice as in LaTeX. And you can do all these things in Word as well. Actually this might be a good time to look back at the above-quoted comparisons between word processors and LaTeX, because we have now seen that they are all false: essentially LaTeX propaganda.

But back to the editing process. Okay, there’s a less eye-watering way to proof-read a LaTeX document than scouring the markup itself. This is to typeset the marked up file, open and read the resulting PDF, look for anything that needs to be changed, edit the marked up file accordingly, typeset it again, rinse and repeat.

If you’re a programmer, that probably makes sense to you by analogy with the code-compile-debug cycle. But that isn’t how most people want to write. Most of us would rather have a piece of paper or a screen that is covered in the words and punctuation marks that are actually going to appear in the finished piece than a screen covered in markup like . Never mind boilerplate code like or at the start of your document – running into something along the lines of in the middle of a paragraph and having to mentally parse it into ‘(Lena and Peterson 2008, p. 706)’ interrupts your train of thought and makes it harder to do what you really need to be doing: reading your punctuated words back to yourself to make sure that they ‘sound’ like what you really wanted to say and don’t have any mistakes in them.

Being able to edit the document that you’re looking at (as opposed to what is in effect the source code to the document you’re looking at) should be taken for granted. In the interests of producing fluent prose and avoiding errors, it’s obviously better to edit a document that has ‘…’ where an ellipsis is intended than a document that has in the same places.

6. So what is LaTeX good for?

Science researchers are the biggest users of LaTeX. There are also some researchers who use LaTeX (or some variant thereof) despite working in the humanities. These people are not using LaTeX simply because it’s the thing to do: they’re going the opposite way from the herd. As a result, they are perhaps more likely to have reflected deeply on the real advantages of LaTeX – as opposed to imagined advantages, such as those pushed by the LaTeX evangelists above.

As far as I can tell, they choose LaTeX for the opposite reason to the stereotypical one about focusing on content and forgetting about design. For example, one argues that ‘The computer should allow an ordinary writer to produce a polished typeset page, but Word makes this extremely difficult to achieve.’ (Goldstone n.d., para. 7) This reverses the above-quoted arguments for writing in LaTeX: that is, such authors use LaTeX (or variants thereof) because they do not believe ‘that it is better to leave document design to document designers’: in fact, they are using it precisely because they want to have a go at being designers (which is in turn because they ‘worry… about the appearance of their documents’).

This is what LaTeX is good for: not helping people to compose text, but helping them to make it look nice. If that is important to you, go ahead and give it a look.

7. LaTeX: a typesetting tool, not a writing tool

As an author, I want to ‘get on with writing documents’, but sometimes I have reason to play at being a designer, and on those occasions I want to think about design.

LaTeX provides one set of options for those occasions. Desktop publishing packages such as InDesign provide others. Actually, they provide a somewhat wider set. Perhaps unnecessarily wide when it comes to typical academic document types such as conference and lecture handouts. Forget all that nonsense about LaTeX being somehow better for writing in than a word processor: it isn’t. But it is better than a word processor for typesetting. And its use requires fewer aesthetic choices and less design expertise than a desktop publishing package, so it’s likely to save you some time in that regard (and give you fewer opportunities to mess up) provided that the kind of document that you want to typeset is the kind of document that people generally use LaTeX for typesetting. The advantages of LaTeX for academics inhere in its having been set up to produce reasonable-looking documents of the kinds that academics most frequently like to self-publish. Outside of its comfort zone, it’s not a lot of use: TeX can be used for almost anything, but the macros that extend TeX to make LaTeX have for the most part been created with fairly scholarly uses in mind. I didn’t use it to typeset the public report from the Valuing Electronic Music project, for example, because that was a public report and I didn’t want it to look like a conference paper.

Here are the PDFs generated by the above LaTeX file (on the left) and by LibreOffice’s ‘Export as PDF’ facility (on the right). I didn’t alter any default settings for either of them (except by enabling smart quotes in LibreOffice). The LaTeX version includes a date as well as section and page numbers automatically because this is default behaviour for LaTeX articles; you can easily do that on most word processors too but it’s not the default on this one so I chose not to have it done here.

I think you’ll probably agree that the LaTeX version looks better than the word processor export version. Whether it looks sufficiently better to justify the additional effort is a judgement call that you’ll have to make for yourself.

8. If we don’t write in LaTeX, how can we make use of the typesetting goodness of TeX?

The obvious approach would be to write your document in some other format, then – when it’s finished – go through it, or have somebody else go through it for you, marking it up. That’s how I created the LaTeX version of the sample paragraph above, for example: the article I published was not written in LaTeX, but I thought I’d have a go at LaTeXifying it for the purposes of this essay. But markup languages are often better used by computers than by people, and these days you can save time by getting your computer to do your LaTeX markup for you. So just because your work is going to be typeset with LaTeX doesn’t mean that you will have to author it in LaTeX.

Here is a range of options for getting your text marked up automatically:

  1. Write using AbiWord, Scrivener, Emacs Org-mode, or Texts. AbiWord (available for Windows and Linux), Scrivener (available for Windows and Mac), and Org-mode (available for just about anything if you can put up with Emacs) can export your work as a LaTeX file; Org-mode and Texts (available for Windows and Mac) can additionally typeset it with LaTeX if you have a working LaTeX installation. You can also use AbiWord to open a file that you wrote using another word processor, then export it as LaTeX. I haven’t used AbiWord for a long time and I haven’t yet tested Texts, but I can vouch for Org-mode. Note that the version of Org-mode that comes with the version of Emacs that comes with Mac OS X won’t do this: you’ll need a newer version.
  2. Write using Word or LibreOffice, then use Pandoc to convert the resulting files into LaTeX files [1]
  3. Write in Markdown using any text editor at all and use Pandoc to convert your Markdown files into LaTeX files (yes, Markdown is a markup language, but it’s one that was designed to be simple and human-readable; also note that while Texts is a word processor, it saves everything as Markdown). Also: Pandoc’s citeproc extension provides Markdown with a more intuitive citation markup syntax than BibLaTeX, and because knitr works with Markdown, this option also enables you to embed automatically generated tables etc if you use R. You might want to check out Kieran Healy’s detailed guide to this general approach.

Not all of these options are equal, all rely on your structuring your text properly, and it still helps to have some knowledge of LaTeX (especially if you want to do something like embedding mathematical formulae). But the fact is that they exist because writing in LaTeX isn’t what it’s cracked up to be. LaTeX was invented so that nobody would have to write prose in TeX, which is too hard for ordinary mortals. The above were created so that nobody would have to write prose in LaTeX – which is not too hard for ordinary mortals, but still a fairly bad idea.

9. Typesetting your own book

You may be thinking of using LaTeX to typeset a book that you are not self-publishing. Academic publishers expect this sort of thing from scientists and may also put up with it from humanities researchers. It’s what Knuth invented TeX for in the first place. But here are three things to consider before trying to persuade your publisher to let you typeset your book yourself:

  1. There’s already somebody whose job it is to do that
  2. If you’re so keen on doing other people’s jobs for them, then maybe you’d also like to pick up the physical copies from the printers, transport them to the publisher’s warehouse (hey, they might let you drive the forklift yourself!), do the marketing using your own telephone, and deliver copies to customers and retailers in your own car. Wait – why stop there? Why not insist on operating the printing and binding machinery yourself? In fact, why not buy a mechanical hand press and print and bind the copies at home, like Virginia and Leonard Woolf?
  3. Even if you only typeset your book and don’t bother with the rest of the above, Ricardo’s theory of comparative advantage still says you’re wasting your time.

Not put off yet? Okay, maybe typesetting your own book is going to give you personal satisfaction, or maybe the typography of your book needs to have some particular look that nobody else in the world but you can provide. Fine; it’s not like it’s going to do any harm. (If it were ever to become standard practice for book publishing outside science monographs, then that would be another matter. All book designers would become unemployed, and most books would end up either looking awful or looking pretty much the same as one another. Not good.)

10. A brief warning about the endless inconvenience of anything that has anything to do with LaTeX

As we have seen, there are few good reasons for writing in LaTeX but some good reasons for typesetting in LaTeX. I have not yet touched upon the technical problems involved. If you’re not currently a LaTeX user but are still thinking of using LaTeX for typographic purposes, you really need to know what you’re letting yourself in for. Before wrapping up this essay, I shall make a few observations for the benefit of people in that position.

Free and open source software has a strong tendency towards being difficult to install and get up and running. TeX and LaTeX are no exception. Also, if you want to do anything really wild and crazy – like using a typeface other than Computer Modern – then plain vanilla TeX and LaTeX won’t do. (Please: you do want to use typefaces other than Computer Modern. Computer Modern is not some sort of universal, all-purpose typeface. It’s just the digital version of the typeface that happened to have been used for the first edition of the book whose second edition Knuth created TeX in order to typeset, and it really isn’t suited to some of the uses to which I’ve seen it put, especially in slide presentations.) And anything other than vanilla TeX and LaTeX is really, really difficult to install. So difficult that most people seem to give up on installing individual packages and instead install the whole of something called TeX Live. Tex Live wraps up almost everything that a TeX or LaTeX user could ever possibly want into a single, handy download. A single, handy unbelievably large download that takes up over two gigabytes on disk: to be exact, 2.4 gigabytes for the Mac version, MacTeX. For comparison, LibreOffice takes up about one and a half gigabytes of disk space on a Windows or Linux machine, and less than one gigabyte on a Mac. And LibreOffice is a word processor, a spreadsheet, a slideshow presentation program, a drawing package, and a database, all in one. LaTeX is just a typesetting program. This is nuts – especially if you’re using old or cheap hardware. And even if you decide to weigh your hard drive down with TeX Live, you still have a lot of work to do in getting things to work properly, and almost nothing ever seems to be clearly explained. Sometimes it feels as if getting LaTeX to work has become a sort of hazing ritual through which the pledge must suffer alone.

Here is an entirely typical wail of despair from somebody trying to get LaTeX to work correctly with BibLaTeX and Biber (two programs included in TeX Live that supplement LaTeX as an alternative to BibTeX, also included in TeX Live, or to BibLaTeX plus BibTeX – confused already? Just you wait!):

‘I get “There were undefined references” errors and [I] can’t fix it after two days of trying. I have tried switching editors from Sublime Text 3 to TeXStudio on a Mac, then trying both on a PC. I am willing to try anything at this point. …

I have read about doing a compilation trick but I’m not sure how to do this in either SublimeText or TexStudio. … I have run into many problems and taken many detours that led to other problems. I’m at a loss. Can someone please give me a few hints or keywords I can search for to fix these problems, or a complete solution? I can’t even get a minimum working example up. I will install anything.

(user2205916 2014, paras 1 & 9)

Every time somebody new tries to get started with LaTeX, that person is set up for hours or even days of this kind of thing – plus a lifetime of fiddling with TeX and LaTeX’s quirks – even if (like this user) that person employs relatively ‘user friendly’ graphical applications such as TeXstudio rather than trying to cope with Emacs or vi and the command line. This particular user has been driven to such distraction that he or she has not only changed LaTeX editor programs but changed computers in the vain hope of getting anything to work. Now the response. The accepted answer carefully outlines a solution and then explains the underlying problem as follows:

it is possible to set up TeXstudio in alternative ways to achieve the same effect. The key is that you have to ensure that the[re] is a sequence[:]

which can be done ‘by hand’ (as I have) or can be automated in various ways. Note that the same general idea applies whatever editor is used: this is a feature of LaTeX and not of the editor.

(Wright 2014, paras 3-5)

Well, how silly of the would-be LaTeX user not to have realised that the only way to get LaTeX running properly with Biber was to run it twice, once before and once after! Now note the grateful response to this (unusually clear) answer: ‘The detail of your answer will be very helpful to other neophytes like myself. Other answers assume a level of computer/LaTeX literacy not all have.’

It’s a typical story. Set foot on the path of LaTeX, and sooner or later you’ll be tearing your hair out. You have been warned.

Footnotes

1. Converting an .odt file with a Zotero-generated bibliography to LaTeX with Pandoc is slightly more difficult than it sounds. In my experience, the best way to achieve it is to open your .odt file in LibreOffice and save it as a .docx file (which turns all the Zotero references and the bibliography into ordinary text), then use Pandoc initially to convert the .docx file to a Markdown file and then to convert the resultant Markdown file to a LaTeX file.

References

Allington, D and Hewings, A (2012). ‘Writing in English‘. In: Allington, D. and Mayor, B. (eds.) Communicating in English: talk, text, technology. London: Routledge. pp. 47-76.
DHQ (2016) ‘DHQ submission guidelines’. Accessed on 11 Sep 2016 from http://digitalhumanities.org:8081/dhq/submissions/index.html
Django Project (n.d.) ‘The Django template language | Django documentation | Django’. Accessed on 11 Sep 2016 from https://docs.djangoproject.com/ja/1.9/ref/templates/language/
Goldstone, A. (n.d.) ‘Producing digital documents’. Accessed on 3 Sep 2016 from https://andrewgoldstone.com/tex/
Hills, M (2002). Fan cultures. London / New York: Routledge.
LaTeX Project (n.d.) ‘An introduction to LaTeX’. Accessed on 3 Sep 2016 from https://www.latex-project.org/about/
RSI Staff (2015) ‘Introduction to LaTeX: writing papers the right way’. Slide presentation, Massachusetts Institute of Technology Research Science Institute. Accessed 12 Sep 2016 from http://web.mit.edu/rsi/www/pdfs/new-latex.pdf
ShareLaTeX (2013) ‘How to write a thesis in LaTeX pt 1 – basic structure’. Accessed on 12 Sep 2016 from https://www.sharelatex.com/blog/2013/08/02/thesis-series-pt1.html
Simonite, Tom (2013) ‘The decline of Wikipedia’. MIT Technology Review, 22 Oct. Accessed on 11 Sep 2016 from https://www.technologyreview.com/s/520446/the-decline-of-wikipedia/
TeX Users Group (n.d.) ‘History of TeX – TeX Users Group’. Accessed on 9 Sep 2016 from https://www.tug.org/whatis.html
user2205916 (2014) ‘Biblatex, Biber, and LaTeX: citations undefined’. Stack Exchange, 12 Jan. Accessed on 10 Sep 2016 from http://tex.stackexchange.com/questions/153647/biblatex-biber-and-latex-citations-undefined
Wikipedia (2016) ‘LaTeX’. Accessed on 10 Sep 2016 from https://en.wikipedia.org/w/index.php?title=LaTeX&oldid=736123000
Wright, Joseph (2014). Answer to ‘Biblatex, Biber, and LaTeX: citations undefined’. Stack Exchange, 12 Jan. Accessed on 10 Sep 2016 from http://tex.stackexchange.com/questions/153647/biblatex-biber-and-latex-citations-undefined

Leave a Comment

(0 Comments)

Your email address will not be published. Required fields are marked *