Paper or Plastic?

Most consumers used to think the environmentally friendly option at the grocery store checkout was paper bags. Paper bags are made out of natural materials after all, whereas plastic bags are made from non-renewable petrochemicals. But this decision doesn’t matter much in the context of all the purchases that consumer make. And in general, some people focus too much on product-level decisions when they should focus on product-category decisions.
A product-level decision usually means deciding between two brands of a product (e.g., a Honda Accord versus a Toyota Camry). A product-category decision means deciding between entirely different ways of getting a product or service. For example, all of the following are different ways of getting transportation: driving a personal automobile, biking, walking, and mass transit. Driving a Camry won’t change your overall environmental impact nearly as much as biking to work would.
An assessment in Finland compared various types of grocery bags, including plastic bags, recycled plastic bags, paper bags, and biodegradable (starch) bags, and it found that recycled plastic bags actually had the lowest life cycle CO₂-eq. emissions¹ (Mattila et al. 2011). But the more important finding is the range of CO₂-eq. emissions per bag: at least −7 g CO₂-eq./recycled plastic bag and at most 60 g CO₂-eq./biodegradable bag. For context, the per capita emissions of CO₂-eq. in Finland are somewhere in the range of 9.0 tonnes to 12.5 tonnes (Heinonen and Junnila 2011). So if you purchase, say, 50 bags of groceries per month, and you switch from the most polluting bag to the least polluting bag, you save
$$\left( \frac{60 g CO_{2} eq.}{bag} - \frac{{-7} g CO_{2} eq.}{bag} \right) \times \frac{50 bags}{month} \times \frac{12 months}{year} = \frac{40,200 g CO_{2} eq.}{year}$$
If we take 10 tonnes CO₂-eq. as a nice, even number for annual per capita emissions of CO₂-eq., the savings from this one decision amount to about
$$\left( \frac{40,200 g CO_{2} eq.}{year} \times \frac{kg}{1000 g} \right) \times \left( \frac{year}{10 tonnes CO_{2} eq.} \times \frac{1 tonne}{1000 kg} \right) = 0.00402$$
or 0.402%.
This is a rough calculation, but I used generous assumptions, and choosing a different grocery bag still only makes less than half a percent difference in per capita greenhouse gas emissions.

What Decisions Matter

It turns out that three broad areas of consumption are responsible for the bulk of people’s environmental impact, at least in developed countries:

• construction and housing (e.g., heating and air conditioning),
• food (especially eating meat), and
  
• transportation (especially driving and flying).

When researchers study the broad areas of consumption that cause environmental impacts, these three sectors are at the top of the list, again and again (e.g., Brower and Leon 1999; Spangenberg and Lorek 2002; OECD 2002). One study found that these three sectors account for roughly 70% of consumers’ annual greenhouse gas emissions (Jones and Kammen 2011). So why worry about paper-versus-plastic when it’s far more important whether you rode your bike to the store and whether you’re buying meat or not?
I am not arguing that people and companies should stop caring about product-level improvements. Environmentally friendly laundry detergent, for example, helps, but the benefits are more obvious for the company that sells the product than for consumers who purchase the product. And it’s often difficult for consumers to know which detergent is better, in any case.

Confusing Messages

Messages about products that are better for the environment are dangerously close to becoming like messages about foods that are more healthy. Are eggs actually healthy? Should I really make an extra effort to drink the occasional glass of wine? Is the low-fat alternative actually better for me?
All of these questions have had different answers in recent years, and as the confusion mounts, the general public decides that health experts don’t really know what’s best. Or if they do, they’re not communicating it well, so the average person eventually says, “Forget it: I’m eating eggs, bacon, and buttered toast for breakfast and washing it down with a cup of coffee. It can’t be that bad if there’s this much confusion.” Similarly, those of us who tell consumers what’s best for the environment need to make sure that our messages are clear, accurate, and (ideally) easy to implement.
In my example about grocery bags, you might have been surprised to read that the bag with the highest greenhouse gas emissions was the biodegradable one. This type of bag has been developed specifically to be environmentally friendly, and I’m sure it’s marketed as such. Wouldn’t you be annoyed if you spent extra on the environmentally friendly option, only to find out later that it’s the least environmentally friendly option? And wouldn’t that make you less likely to purchase “environmentally friendly” products in the future? That would certainly be my reaction. So researchers and marketers need to be extra careful about their messages to consumers; otherwise, consumers will just stop caring.

Clear Messages

The best recommendation that I can give consumers is to trying making changes in the big three areas of consumption (housing, food, and transportation), and don’t worry so much about other decisions. Ride a bike when you can. Take public transit. Eat less meat (or at least less beef and pork). Turn up the thermostat in the summer. This list is not exhaustive, but these are examples of recommendations that are clear and will definitely reduce your environmental impact, even if they aren’t always easy to do.

I originally wrote this post for Aaron Redman’s Achieving Sustainability blog.

References

Brower, Michael, and Warren Leon. 1999. The Consumer’s Guide to Effective Environmental Choices: Practical Advice from the Union of Concerned Scientists. New York: Harmony.

Heinonen, Jukka, and Seppo Junnila. 2011. “A Carbon Consumption Comparison of Rural and Urban Lifestyles.” Sustainability 3 (12): 1234–49. doi:10.3390/su3081234.

Jones, Christopher M., and Daniel M. Kammen. 2011. “Quantifying Carbon Footprint Reduction Opportunities for U.S. Households and Communities.” Environmental Science & Technology 45 (9): 4088–95. doi:10.1021/es102221h.

Mattila, Tuomas, Marjukka Kujanpää, Helena Dahlbo, Risto Soukka, and Tuuli Myllymaa. 2011. “Uncertainty and Sensitivity in the Carbon Footprint of Shopping Bags.” Journal of Industrial Ecology 15 (2): 217–27. doi:10.1111/j.1530-9290.2010.00326.x.

OECD. 2002. “Towards Sustainable Household Consumption? Trends and Policies in OECD Countries.” Paris: OECD Publishing. http://www.ine.gob.mx/dgipea/descargas/towards_sust.pdf.

Spangenberg, Joachim H., and Sylvia Lorek. 2002. “Environmentally Sustainable Household Consumption: From Aggregate Environmental Pressures to Priority Fields of Action.” Ecological Economics 43 (2): 127–40. http://www.sciencedirect.com/science/article/pii/S0921800902002124.

---

1. CO₂-eq. (or carbon dioxide equivalents) is a measure of greenhouse gas emissions. CO₂ is the most well-known greenhouse gas but not the most potent. In order to describe global warming impact in a single unit of measurement, researchers often convert all greenhouse gas emissions associated with a particular activity into the equivalent amount of CO₂ emissions.↩

Constructive Criticism

Copyediting is one of the services that I provide through Kutter Consulting, and this work necessarily involves reviewing others’ writing and making occasional recommendations. Part of a copyeditor’s job is recommending different words, asking for clarification, and pointing out weak arguments. There will be more or less of these depending on what the author wants from the copyeditor (in terms of how deep a copyedit to make), but basically, copyeditors include these kinds of comments along with corrections to grammar and style. And whenever I make such comments, I always formulate them as constructive criticism. Constructive criticism is not so much criticism as it is making recommendations on how to improve a piece of writing. It should come from a fundamentally positive place and aim to help the author improve his or her work.

In one of my recent projects,¹ I saw the ugly flip-side of constructive criticism: cutting someone off at the knees. This project involved editing a chapter of a student’s dissertation, and the version sent to me included comments from the student’s advisor. I am not reproducing exact quotes here, but the advisors had made comments like the following:

Okay, you are introducing the theory of the framing effect, but this is the results section. Assuming this actually is the results section, Dave, why haven’t you discussed this earlier in the literature review???

The following is another example of a short comment:

Still in the results section? Really???

(Some of the comments were actually followed by three question marks!!!)

My main objection to these comments is the tone, and I have a more minor complaint about the content. The tone is condescending; the comments seem to be asking the student, “How could you be so incompetent???” (Yes, with three question marks.) And that tone is not only unhelpful, it is harmful, especially when directed at someone building confidence as a professional in a new field. Moreover, comments should focus on how to improve what’s on the page, not what’s wrong with it. These comments only implicitly tell the student how to improve his chapter. They say, “Do not do this,” rather than “Do this,” so the student only knows what the problem is, not how to fix it. Identifying solutions rather than problems is not only more clear, direct, and concise but also more positive and supportive.

One could argue that the advisors might be trying to prepare the student for getting these kinds of comments in peer review on future academic journal article submissions. And to be honest, I could see some merit in that strategy if the advisors were indeed employing it, but based their other comments, I doubt their commenting style is intentional. An advisor who would go to the effort of changing their natural commenting style to prepare a student for the peer-review process would be a fantastic, supportive advisor, and I would expect to see some hint of that in the comments. Or I would have expected the student to rebut my interpretation of the comments when I mentioned to him that they seemed incredibly rude.

In any case, whether these particular comments are intentionally or accidentally condescending does not really matter; there’s no question that many people use the same style when commenting on others’ writing. So to people who comment on others’ writing (whether as copyeditors, academic advisors, or any other position), please consider the tone and content of comments that you make on others’ writing. Is the goal to feel smart (i.e., ego inflation) by pointing out all the flaws in a given piece of writing? Or is the goal to improve the piece of writing and help the author communicate with his or her audience?

Of course, I have also copyedited poorly written articles and become frustrated, but regardless of the quality of writing, comments should be tactful and respectful. Poor writing is harder to copyedit for a couple reasons. First, poor writing has more errors, so the volume of work is simply greater. Second, poor writing is confusing, so it takes longer to understand and, therefore, longer to fix. But poor writing needs and usually deserves more help than good writing. “Poor” writing often comes from people speaking and writing English as a second language. Having lived abroad and learned a foreign language myself, I empathize with those trying to produce technically correct prose in a foreign language. I have not only experienced the frustration of making simple grammatical errors over and over but I have also felt as though my voice was muffled because I could not communicate in a nuanced way. Everything became simply “good” or “bad.” I either “liked” something, or I did not. Because English is a global lingua franca, I feel fortunate to be a native speaker, and I appreciate that I am in a position to help people bring their own thoughts to life.

My argument in this post is that criticism should be constructive rather than negative, not that criticism in general is bad. This post itself is critical of others’ writing (other commenters’ writing), so I would be a hypocrite if I argued that criticism in general is bad. My goal with this post is to point out a problem (overly negative comments on others’ writing) and to provide a solution (constructive criticism). To that end, the comments quoted above would be better rendered as follows:

The first mention of the framing effect appears in the results section. It would be better to introduce the reader to this concept in the literature review (to provide context) and then refer to it as you already have in the results section here. Also, I’m not sure whether this is the results section, so I recommend to delineate the sections more clearly with headings that are numbered and have distinct formatting (e.g., bold text).

The shorter comment could be rendered as follows:

There is a great deal of content in the results section that belongs in the literature review section. (This content is mostly about existing studies rather than the results of your own research.) I will highlight and mark text throughout that I think belongs in the literature review.

These versions communicate the same points but without the vitriol. Notice that these versions do not ascribe problems to the author himself. The original version of the comment criticizes Dave directly for writing the chapter out of order (“Dave, why haven’t you discussed this earlier in the literature review???”) In the versions I have recommended, the problems are in the text (“The first mention of the framing effect appears in the results section”). Then, it’s up to Dave to decide if he takes criticism of the text personally. As an author myself, I know how easy it is to interpret criticism of text that I have written as criticism of me personally, but as long as comments are only about the text, the fault for doing so lies with me. Additionally, the versions that I recommend clarify what is wrong with the current text and, more importantly, how to fix it.

---

Notes:

---

1. I have changed some details and the quotations because I have not requested permission to write about my work with this student publicly.↩

ASU Dissertation Template Now on ShareLaTeX

I have already posted about the LaTeX template that I developed for Arizona State University (ASU) theses and dissertations. I was and am highly motivated to help ASU grad students get through format review quickly and painlessly. In my view, the template is a great step in that direction.

In the README for the GitHub repo for the dissertation template, I invite users to contact me if they need help using the template. Most of the messages that I have gotten are actually requests for help setting up TeX rather than resolving problems with the template. It seems that people that struggle to use the template are stumbling on the first step: getting a TeX distribution up and running on their computers.

Troubleshooting these problems is incredibly difficult from a distance. There are so many things that could be going wrong on the user end. The problem could be with the TeX distribution or my dissertation template; it could be the particular TeX editor that the person is using; or it could be something else entirely. I have to admit I’m not sure how to troubleshoot these problems unless I’m sitting at the user’s computer and able to try it out for myself, but in-person support is not a practical solution.

So I have turned my dissertation template into a ShareLaTeX template. ShareLaTeX is an online LaTeX editor. Anyone can write or upload LaTeX code, and ShareLaTeX will convert it into a PDF—no need for installing TeX on your own computer. I’ve tried it out over the past couple days, and it seems like quite a fast, stable site with some cool features. Creating an account is painless; it just takes an email account and password. I don’t think you even need to confirm your email address.

Once you have an account, you can start a new project based on the ASU dissertation template. Go to the page for the ASU dissertation template, and click “Open in ShareLaTeX”. ShareLaTeX will automatically create a new project for you based on the template.

I have tested the template on ShareLaTeX, and it runs great. So ASU grad students rejoice! You now have an even more user-friendly way to format your dissertations and theses.

ShareLaTeX also provides some tutorial information for people new to LaTeX:

• ShareLaTeX Beginner’s Tutorial
• ShareLaTeX Documentation

The second point, the documentation page, contains a wealth of information about LaTeX basics, such as making text bold and inserting tables, and more advanced topics, such as integrating R code into your LaTeX documents. (By the way, I’m sort of blown away that ShareLaTeX supports R. This is an incredibly handy feature.)

To recap, the basic steps for using the ASU dissertation template on ShareLaTeX follow:

1. Create a ShareLaTeX account.

2. Start a new project based on the ASU dissertation template:
   1. Visit the template page.
   2. Click the “Open in ShareLaTeX” button.

3. Update the template with your own dissertation information (e.g., author name) and content. (The README file and the template file itself walks you through where and how to update the template.)

4. Click the “Compile” or “Recompile” button to make your document.

Using ShareLaTeX should make dissertation and thesis formatting easier than it was before. For people who want an entirely painless formatting experience, I offer a typesetting service through my consulting company. I’ll take your LaTeX files and update them so that your thesis or dissertation passes format review. I have found that many people end up coming to me after going through a couple rounds of revisions with the format reviewers at the grad office as graduation deadlines are fast approaching. Please don’t wait to get in touch if you’re stuck on formatting. I’ll help however I can, whether answering questions by email (for free) or doing the typesetting myself (for a fee).

Literature Review: Citing Sources That Cite Sources

General Advice

The overriding idea behind providing citations is proper attribution. Work (i.e., analysis, ideas, interpretations, and so forth) that is not your own should be attributed to the people that actually did the work. The general advice to undergraduates and graduate students often boils down to the following:

1. Information that comes from sources needs to be correctly attributed to those sources.
2. Word-for-word reproductions from sources need to be correctly attributed and accompanied by a location identifier—usually a page number.

In the first situation, you are paraphrasing a source, and in the second situation you are providing a direct quotation.

That advice covers most of the territory that students and other authors are likely to encounter. But concrete advice on the finer points of citing sources can be scarce. For example, what if you are citing a source that cites another source?

Citing Sources That Cite Sources

Direct Quotations

If you are reproducing a direct quotation, you should find the original source with the quotation and cite from it. If the original source is unavailable, you can still provide the direct quotation and indicate that the quote is from a secondary source. The correct format for citing from a secondary source varies according to style guide. In Chicago style, for example, authors should “mention the original author and date in the text, and cite the secondary source in the reference list entry. The text citation would include the words ‘quoted in’” (University of Chicago 2010, §15.52).

Paraphrasing

A common situation that involves paraphrasing sources that cite other sources is paraphrasing academic journal articles, which themselves contain many citations. Literature reviews in these articles can be great sources of information about a given topic. But when you paraphrase from the literature review of such an article, should you cite the article or the sources cited in the article? It depends on what the article says and why you’re citing it.

Consider the following scenario: Paper 1 cites papers A, B, and C. You have read paper 1, but you have not yet read papers A, B, or C.

If you are paraphrasing paper 1’s analysis of papers A, B, and C, then cite paper 1. For example, paper 1 might say, “Researchers in the field have struggled to develop a valid and reliable instrument for this variable of interest (Paper A, Paper B, Paper C).” Your paraphrase of paper 1’s analysis of the state of the field should be made directly to paper 1. You’re not reproducing paper 1’s analysis of the field, and you didn’t come up with that analysis of the field on your own (presumably). So paper 1 should get the credit for that analysis. You might even cite paper 1’s analysis and then argue that it’s incorrect.

However, if you are discussing the contents of papers A, B, or C, it is your responsibility to read those papers and cite them directly. For example, paper 1 might say, “Participant recall improves when [some condition] is true (Paper A, Paper B, Paper C).” Assuming all three papers (A, B, and C) directly address this point (that [some condition] improves participant recall) and paper 1 is simply gathering and citing the sources that have shown this to be the case (i.e., no additional analysis is done in paper 1), then you should read and cite papers A, B, and C.

Remember that by citing a source, you are indicating to the reader that you have obtained and reviewed the source. There are at least two reasons for taking this approach: (1) honesty and (2) accuracy. First, an in-text citation indicates that you are paraphrasing from that source, and it does not make sense to paraphrase from a source you have not read. You should not grab citations out of a source, like an academic journal article, and use them in your own work unless you have reviewed the cited works yourself. Second, sometimes authors misinterpret or even misrepresent the sources that they cite. I have often found that I disagree with the way that authors characterize sources that they cite after I have found and reviewed the original sources. And unless authors are rigorous about reviewing the sources that they cite, misinformation about original sources can easily propagate.

References

University of Chicago. 2010. The Chicago Manual of Style. 16th ed. Chicago; London: University of Chicago.

Zotero + Word Tutorial

I mentioned Zotero in my first academic workflow post. Zotero is a great citation manager with many great features. And if you write your documents in Word, Zotero is a no brainer. A Zotero plug-in for Word lets you insert citations from your Zotero database in your Word documents, and then Zotero automatically formats in-text citations and the reference list at the end of the document. Plus, it’s free!

Most students, whether graduate students or undergrads, use Word to write their school essays, term papers, and manuscripts, so Zotero is a great, free option for easily handling citations in these documents.

In this post, I provide a tutorial for getting citations into Zotero and getting citations from Zotero into your Word documents. At the end of the post, I provide links to some additional tutorials (including screencasts) on installing and using Zotero.

Installation

Basic Installation

You can download and install Zotero from this page. There are two ways to install Zotero:

• Standalone
• Zotero for Firefox

The stand-alone option installs Zotero like any other application that runs on your computer. Note that if you install the stand-alone version, you should also install the plug-in for whichever browser you use when you do academic research (Firefox, Chrome, or Safari). Using a browser with Zotero makes it much easier to get citations into your reference database. Install the browser add-on after installing the stand-alone version.

If you install Zotero for Firefox, you will need to have Firefox open to use Zotero (including putting references into Zotero and citing references from Zotero).

Zotero Plug-in for Word

You definitely want to install the plug-in for Word so that you can create citations automatically in Word documents. If you install the stand-alone version of Zotero, the Word plug-in is included. If you install Zotero for Firefox, you need to manually add the Word plug-in (available here).

Getting Sources into Your Reference Library

There are four main ways to get citation information into your Zotero database. I give step-by-step instructions here plus a few exercises, so you can try them out.

Web Page with Embedded Metadata

The browser that is integrated with Zotero (e.g., Firefox) can quickly and easily import sources into the Zotero library. Many web pages embed metadata into the web page itself (e.g., the web pages for academic journal articles hosted on ScienceDirect). Zotero can recognize this information and import it.

Other useful websites with embedded metadata include Amazon, Google Books, and most newspapers. So, for example, when I have a hard copy of a book, I often look it up on Amazon and grab the citation information from there, so I don’t have to type it in manually.

Exercise

Open the web browser that is integrated with Zotero, and go to this random academic journal article hosted on ScienceDirect: http://www.sciencedirect.com/science/article/pii/S1053811902913303. (Note that it does not matter if you have access to the full text of the article.) Look at the right-hand portion of the address bar of your web browser. There should be a small icon that looks like a single piece of paper. If you click on that icon, Zotero will automatically import the citation into your reference library. It’s hard to imagine how it could be any easier.

External Citation Files

Citation information can also exist in external files. I usually only resort to importing from external files when importing from metadata embedded in a web page does not work. There are several citation file types (with extensions, such as *.bib and *.rdf). Fortunately, their details don’t really matter. Zotero should be able to import all of the ones you are likely to encounter. You can usually download these files from academic journal article databases (such as ScienceDirect and Google Scholar).

Exercise

Search for a famous journal article called “The Tragedy of the Commons” on Google Scholar. (Or click this link to navigate straight to the search results.) When I wrote this post, the second result was the correct article (by Garrett Hardin). Click on the link titled “Cite”. A dialogue will pop up with text that you can copy and paste for MLA, APA, and Chicago-style citations. Click on any of the links at the bottom of the dialogue: BibTeX, EndNote, RefMan, or RefWorks. The format doesn’t really matter, but RefMan is Zotero’s native format, so I recommend clicking that one. Another dialogue will pop up asking you where to download the file on your hard drive. Select a location, and download the file. (If you clicked on the RefMan link, the file will have a *.ris extension.)

Next, open Zotero, click on the gear button (which should reveal a drop-down menu containing items like “Import ...” and “Import from clipboard”). Click on the item labeled “Import ...”. Zotero will pop up a dialogue, so you can select the file from your hard drive. Do so, and Zotero will import the citation information for “The Tragedy of the Commons” by Garrett Hardin into your library.

PDF with Embedded Metadata

Just like web pages, PDFs of recent academic journal articles often contain embedded metadata. Zotero can extract this data and write a new entry in the Zotero database for the PDF. Note that this usually only works with PDFs of relatively recent academic journal articles, but you can try it with any PDF.

Exercise

Download the full text of the first result from the Google Scholar search in the previous exercise. This is an article written by Elinor Ostrom, a Noble Prize winner, who has written extensively about the tragedy of the commons and common-pool resources. Or you can directly retrieve the PDF by clicking here.

Open Zotero, and drag the PDF into the main window (which should also list other references, usually according to title and author). After doing so, the PDF will appear with an Adobe Acrobat symbol next to it, but the citation information for the PDF has not been properly entered into the database, yet. Right-click on the title of the PDF. A menu will pop up; select “Retrieve Metadata for PDF”. Another dialogue will pop up showing Zotero’s progress. If Zotero is able to retrieve the metadata for the PDF, it will automatically create a new entry and save the PDF as an attachment to the entry.

Note that you can select multiple PDFs at the same time, right-click on them, and retrieve metadata as described above for a single PDF.

Shared Libraries

Zotero comes with an amazing feature that lets Zotero users share references with each other via Zotero Groups, again, for free. See the link for instructions on setting up Zotero Groups and syncing your Zotero collection.

If you have a shared library (whether the library is owned by you or another person), sources that are added or edited by any member of the shared library will appear in your local copy of the library. If you have enough storage for the library (currently everyone gets 300 MB for free), attachments (including PDFs) will sync, as well. These sources are available to you like any other source in your library.

Using Your Reference Library to Make Citations

In Word for PC, Zotero commands appear in their own toolbar. In Word for Mac, Zotero appears under the script icon between the “Window” and “Help” menus. To insert a citation, click “Add citation”. The first time you use this command in a Word document, Zotero will ask which citation format you want to use in that document. Select your preferred citation format from the pop-up menu, and I recommend to leave the “Store references in document” option checked. Doing so ensures that when you share your document with others, they will also be able to see and work with your Zotero citations.

Anytime you insert a citation from Zotero, a Zotero search bar will pop up, or Zotero will bring you to a window of your Zotero library. If the search bar pops up, type in the author or title of the source you want to cite. If the window of your Zotero library pops up, click on the source(s) you want to cite. Zotero will automatically insert a properly formatted in-text citation.

You may need to edit your citations as you draft your document or to format them properly (e.g., to add a page number for an in-text citation after a direct quote). You can modify in-text citations by clicking on them (so the cursor is in the in-text citation) and then selecting “Edit citation” from Word’s Zotero menu. A Zotero dialogue will pop up. Right-click on the citation you want to modify, and select the options you want.

At any time, you can use the “Add bibliography” command in Word’s Zotero menu to insert the full reference list. The reference list will appear in the same citation format as the in-text citations.

To change the citation format for both in-text references and the reference list, use the “Set document preferences” command in Word’s Zotero menu.

Using More Citation Formats

Zotero has many citation formats (7,449 at the time of writing)—far more than the basic APA, MLA, and Chicago styles. See the Zotero Style Repository for a list. If you’re writing a manuscript for an academic journal, Zotero might even have a custom citation style for the journal you’re submitting to. Zotero does not automatically download all the available citation styles. The most popular ones are preloaded, and others need to be downloaded and installed manually. (See here for instructions.)

Additional Resources

Of course, this tutorial is not exhaustive, so here are some additional resources for your further edification:

• This page includes a tutorial for installing Zotero.
• Here is a video tutorial on installing and using the Zotero plug-in for Word.
• This page has a video tutorial that goes over the basics of using Zotero.
• Finally, this page contains links to a variety of more specific topics on using Zotero.

Automating Sente Exports

In this post, I’ll provide some guidance on getting and using Sente’s reference library without opening the application itself. In last week’s post, I wrote about fixing Sente’s export to BibTeX. Being able to fix up the *.bib file that Sente exports helps with writing documents in LaTeX. Using the fix that I demoed in last week’s post, you could also make your reference metadata more consistent (e.g., removing internal periods from US state abbreviations) and ensure the metadata conforms to your style guide (e.g., capitalization of source titles). However, the fix that I demoed requires opening up Sente and exporting the reference library both as SenteXML and as BibTeX. Doing so is not an unbearable burden, but it obstructs fully scripting (i.e., fully automating) parts of the workflow.

Sente Library Basics

The Sente reference library is an SQLite3 database. SQLite is a implementation of SQL, and, according to its website, “the most widely deployed SQL database engine in the world.” In my experience, it is lightweight and relatively easy to use.

To access Sente’e SQLite database, you first have to find it. Sente library files have the extension *.sente6lib. This file is actually a folder that contains several files including the SQLite database and PDFs for articles (if you have elected to include them in the Sente library file).

Open a terminal and navigate to the folder containing the Sente library file. Then, navigate into the sub-folder with the SQLite database. One of my library files is called ASU-References or ASU-References.sente6lib in full, so to get to the folder containing the SQLite database, I enter the following in the terminal:

cd ASU-References.sente6lib/Contents

As far as I can tell, the SQLite database is always called primaryLibrary.sente601, although it may differ in other versions of Sente. To get into the database, enter the following in the terminal:

sqlite3 primaryLibrary.sente601

This command opens SQLite and allows you to get information about the database and its tables and to perform SQL queries on the database. To get a list of tables in the database, enter

.tables

To get the schema for a given table, enter

.schema TABLENAME

For example,

.schema Reference

To get just the column headings, enter

.indices TABLENAME

For example,

.indices Reference

These are some helpful basics. For a full list of SQLite commands, simply enter

.help

To exit SQLite, enter

.q

Sente Citation Identifier

One of the most valuable pieces of identifying information about a source is its Sente citation identifier. The citation identifier is the tag that Sente reads when it scans text documents (e.g., Word documents). An example in-text citation follows:

This is a made up sentence for display purposes only {Arnstein 1969}.

The tag is “{Arnstein 1969}”. So if you’re using Sente to cite sources, your documents are full of Sente citation identifiers. And if you want to do something automatic with citations, there is a good chance you will want to retrieve information about a source based on its citation identifier.

The citation identifier appears in the SparseAttribute table, which contains a lot of other additional information about each citation, too. The table has three columns:

• ReferenceUUID
• AttributeName
• AttributeValue

Here are the table contents for one reference in the SparseAttributes table:

C914FC95|EndNote reference number|116
C914FC95|publicationCountry|
C914FC95|publisher|Routledge
C914FC95|Primary contributor role|Author
C914FC95|DOI|10.1080/01944366908977225
C914FC95|BibTeX cite tag|arnstein1969ladder
C914FC95|Citation identifier|Arnstein 1969
C914FC95|publicationStatus|Unknown
C914FC95|ISSN|0194-4363
C914FC95|Web data source|Google Scholar

In the output above and throughout the rest of the post, I have abbreviated the entry in the first column, which is the ReferenceUUID, from C914FC95-5EE5-4C2D-BC80-1621EC22C2EC to C914FC95.

This particular reference is a well-known article on community participation. Its full citation is

Arnstein, Sherry R. 1969. “A Ladder of Citizen Participation.” Journal of the American Planning Association 35 (4): 216–224. doi:10.1080/01944366908977225.

Sente References’ ReferenceUUID

As far as I can tell, the ReferenceUUID is Sente’s true key for each entry in the database. In database terms, the ReferenceUUID is the unique, primary key for a reference.

Aside from being the primary key for a reference, the ReferenceUUID is also important because Sente will serve it up to other applications that request information about highlighted Sente references. For example, to use Robin Trew’s AppleScript (which exports Sente reference notes to DevonThink), you highlight references in Sente and then run the script. The script gets the ReferenceUUID for highlighted references, uses it to grab more information (including notes) about each reference, applies some formatting, and then ships the results to DevonThink. I recommended using this AppleScript in my original post on academic workflows.

It should be possible to pull the citation identifier out of the AttributeValue column by looking up the ReferenceUUID for a given reference, selecting the row that contains “Citation identifier” in the AttributeName column, and pulling the value in the AttributeValue column for that row. For the Arnstein reference, the goal is to retrieve the seventh row from the output above. The seventh row is

C914FC95|Citation identifier|Arnstein 1969

I would expect the following SQL query to retrieve the citation identifier:

select AttributeValue from SparseAttribute 
where AttributeName='Citation identifier' 
and ReferenceUUID='C914FC95'; 

But this query fails. To figure out why it fails, I examined the schema for the SparseAttribute table, which is

CREATE TABLE SparseAttribute 
    ( ReferenceUUID varchar, 
    AttributeName varchar COLLATE SenteLocalizedNoCase, 
    AttributeValue varchar COLLATE SenteLocalizedNoCase );
CREATE INDEX SparseAttributeByName 
    ON SparseAttribute ( AttributeName );
CREATE UNIQUE INDEX SparseAttributePK 
    ON SparseAttribute 
    ( ReferenceUUID, AttributeName );

Note that this table has a collation sequence. I have to admit that I don’t know what that is or what it does, but it causes the SQL query to throw an error. The following is a corrected version of the SQL query:

select AttributeValue from SparseAttribute 
where AttributeName='Citation identifier' COLLATE NOCASE 
and ReferenceUUID='C914FC95' COLLATE NOCASE;

This SQL query gives the following result:

Arnstein 1969

This is the correct citation identifier for the reference.

Next Steps

When I was working on my dissertation, I found that Robin Trew’s AppleScript stopped working. I was relying on the script to export Sente reference notes to DevonThink, and it was a key part of my workflow. The AppleScript makes SQL queries to Sente’s reference database, processes the information it retrieves, and then sends it to DevonThink. So I used all this information about Sente’s SQLite database to update the script and get it working again. If people are interested, I can post my version of the script, although mine may have become out of date by now, too.

In general, I hope this post helps other people who want to write scripts that retrieve information about their Sente references. With access to Sente’s SQL database, it’s possible to do … pretty much anything with metadata about references in your Sente library. You could even reimplement Sente’s export commands (e.g., to fix errors in the way Sente exports to BibTeX).

Fixing Sente's Export to BibTeX

I recommended Sente as a reference manager and tool for reviewing literature in a previous post. And Sente is great for both of those tasks (assuming you have a Mac). However, Sente does a poor job when exporting a library to BibTeX format—something you would want to do if you were writing an article using LaTeX. For example, Sente leaves the title field blank for web pages. Fortunately, I have found that I can solve these kinds of problems with a bit of coding.

Outline of the Solution

Sente accurately exports data to its own SenteXML format, so my solution uses the following steps:

1. From Sente, export the reference library to SenteXML format.
2. From Sente, export the reference library to BibTeX format.
3. Using a script,
   1. Read in the SenteXML file.
   2. Read in the BibTeX file.
   3. Loop through each entry in the BibTeX file and
      1. Check if the entry is a web page;
      2. If it is a web page, retrieve the title from the same entry in the SenteXML file and save the new title for the BibTeX entry;
      3. Save the BibTeX entry.

First, note that you must start with a library of references in Sente and then export your library to the two formats listed in steps 1 and 2. Second, note that this procedure could be used to check and modify any field, but in this blog post, I address missing titles for web pages.

Solution Details

Getting Perl

I implemented the solution using a perl script. If you don’t have perl, I recommend installing it using perlbrew. I strongly recommend using perlbrew if you’re using a Mac or a Linux machine because you avoid modifying the version of perl that’s installed by default on your operating system. Some system utilities and other applications might rely on the default perl installation, so if you modify it, these utilities and applications might break. See perlbrew’s web page for installation instructions, but you can likely install it with the following command:

\curl -L http://install.perlbrew.pl | bash

Then, to install the latest stable version of perl, enter the following command:

perlbrew install perl-5.16.0

Setting Up Perl

The script uses a few external perl modules, which need to be installed. Assuming that you’re using perlbrew with version 5.16.0 of perl, enter each of the following lines on the terminal (and wait after each finishes before entering the next):

perlbrew exec --with perl-5.16.0 cpanm XML::Simple

perlbrew exec --with perl-5.16.0 cpanm Text::BibTeX

perlbrew exec --with perl-5.16.0 cpanm Getopt::Long

Using the Script

You can retrieve the script and some example files here:

• The script
• An example SenteXML file
• An example BibTeX file

The GitHub repository is here, and you can download the entire repository as a ZIP file here.

To use the script, put all three files in the same folder. If you’re using your own files (instead of the example files above), make sure to move your files into the same folder as the script. You need to either rename your own files to the default file names used in the script or use command-line arguments to specify the file names that you are using (see below). The default file names are the ones used in the example files:

• SenteXML file: references.xml
• Original BibTeX file: references.bib
• Updated BibTeX file: references_new.bib

Next, open a terminal and run the script with the following command (again, assuming that you have used perlbrew to install version 5.16.0 of perl):

perl5.16.0 repair.pl

The script will generate a file called references_new.bib which contains all the same references as the original file and correct titles for web page entries.

The script also accepts the following command line arguments:

--sente-file  FILENAME     Name of the SenteXML file

--bib-infile  FILENAME     Name of the original BibTeX file
                           
--bib-outfile FILENAME     Name of the updated BibTeX file
                           

For example, if you want to save the updated file as bibliography.bib instead of references.bib, enter the following command in the terminal:

perl5.16.0 repair.pl --bib-outfile bibliography.bib

You could also directly overwrite the old BibTeX with the updated one:

perl5.16.0 repair.pl --bib-outfile references.bib

But be careful because the old BibTeX file will be gone forever.

Next Steps

The script is a straightforward procedural script that loops through entries in a BibTeX file and makes changes according to some simple instructions. It’s not sophisticated, and for a simple task such as this, it doesn’t need to be. But there are many other ways in which an author might want to fix up a BibTeX file.

When I wrote my dissertation, I used a more elaborate version of this script to do all of the following:

• convert titles to headline-style capitalization according to the Chicago Manual of Style,
• correctly indicate the translator(s) of sources,
• correctly alphabetize institutional authors with hyphens in their names (e.g., “UN-HABITAT”),
• clean up the edition field, which inconsistently contained ordinal numbers, “ed.”, and “edition” in my reference library,
• clean up US state names (e.g., by removing internal periods), and
• insert missing titles for laws and statutes.

With these tasks, it might make sense to create some more general methods—for example, a general method that retrieves the contents of a field (such as the title field), sends it to a regex, and then updates the field with the result.

Advantages of Scripting

In general, I found that using perl to fix up the bibliographic database was very efficient. I did not want to manually update the BibTeX database because it was very large (over 2,000 entries) and because I was using Sente as the actual reference manager. If I had updated the BibTeX file manually, I would probably have to re-export to BibTeX any entries from the Sente library that I modify, overwrite the old versions in the BibTeX file, and then manually update those entries in the BibTeX file as needed (e.g., entering titles for websites). That is way too much manual work because I was constantly adding new entries to my Sente reference library and occasionally updating older entries.

This approach is also more flexible. If I were to manually update my entire database so that (for example) all titles conform to Chicago-style headline capitalization, I would have to edit everything again to use those same entries in a document that needs to conform to a different style guide. By implementing these changes with a script, I left myself a relatively easy way to change the formatting for different documents.

Using Macros with "titlecaps" in a LaTeX Document

The LaTeX template that I wrote for Arizona State University’s dissertations and theses makes use of the titlecaps package. The titlecaps package has commands for selectively capitalizing words, so that titles can be correctly capitalized in what is often called headline style. Titles of chapters and sections, for example, should usually appear in headline style.

Style guides vary a little bit on the particular rules for headline style, but in general, the rules are the following:

• Always capitalize the first and last word.
  
• Capitalize all remaining words unless they are:
  • articles (i.e., a, an, the),
  • prepositions (e.g., of and for), or
  • conjunctions (e.g., and, but, and or).

Any particular style guide should give more details about exactly which words should not be capitalized.

In any case, the titlecaps package can be used to perform this capitalization on a string of text. Here is an example of a memoir class document that shows how to use the titlecaps package:

\documentclass{memoir}
\usepackage{titlecaps}
\Resetlcwords
\Addlcwords{a an the} 
\Addlcwords{and but for or nor} 
\Addlcwords{aboard about above across %
  after against along amid among anti %
  around as at before behind below %
  beneath beside besides between %
  beyond but by concerning considering %
  despite down during except excepting %
  excluding following for from in %
  inside into like minus near of off %
  on onto opposite outside over past %
  per plus regarding round save since %
  than through to toward towards under %
  underneath unlike until up upon %
  versus via with within without}

\renewcommand{\cfttableaftersnumb}% 
  {\titlecap}%                      
  
\begin{document}

\listoftables
\clearpage

\begin{table}[h] % Table float
\caption{Here is a table caption ending in ``of''}
\label{table1}
\begin{tabular}{l c c} \\ \hline
Column1 & Column2 & Column3 \\ \hline
Row1 & 2.0 & 3.0 \\
Row2 & 2.0 & 3.0 \\
Row3 & 7.0 & 8.0 \\ \hline
\end{tabular}
\end{table}

\end{document}

This setup will send the \titlecap command to all the table captions in the list of tables, which should appear after the table of contents. The table captions in the running text will not be changed.

As far as I can discern, the titlecaps package is relatively new; it appears that it was written in 2013 or maybe 2012, so it still has some rough edges. (Then again, LaTeX is pretty old by now, and it’s full of rough edges.)

One problem with titlecaps is that it does not ignore the last word in a title. In the example above, the last word of the table caption of will not be capitalized in the list of tables because of is in the list of words to leave lowercase (defined by the \Addlcwords command). This behavior contradicts some style guides (such as the Chicago Manual of Style), and there does not seem to be a way to change this behavior.

Another problem is that macros in text sent to \titlecap are likely to break. In the above example, all captions are sent to \titlecap. Users might want to refer to another figure or table in a caption (e.g., with the \ref command) or put a citation in a caption (e.g., with \cite). But these macros will break if they’re sent to \titlecap. (By the way, I am not scolding the package author here. Capitalization in LaTeX is tricky, and when text gets sent to a macro for capitalization, odd things can happen.)

So I started searching for solutions. \textnc is a macro from the titlecaps package that causes \titlecap to ignore text within, so it seemed that wrapping a macro with \textnc would be a way to get \titlecap to skip over the macro. Unfortunately, that strategy did not work.

To (sort of) fix this problem, I read through the titlecaps documentation to see how its \textnc macro was defined. The other clue from the titlecaps documentation was that wrapping text with {{}} can also cause \titlecap to leave the text alone. Between this tidbit, the definition of \textnc, and a bunch of trial and error, I arrived at the following macro:

\newcommand{\macrocapwrap}[1]{% 
  {\bgroup\bgroup{{#1}}\egroup\egroup}%
}

Below is an example of this macro in action:

\documentclass{memoir}
\usepackage{titlecaps}
\Resetlcwords
\Addlcwords{a an the} 
\Addlcwords{and but for or nor}
\Addlcwords{aboard about above across %
  after against along amid among anti %
  around as at before behind below %
  beneath beside besides between %
  beyond but by concerning considering %
  despite down during except excepting %
  excluding following for from in %
  inside into like minus near of off %
  on onto opposite outside over past %
  per plus regarding round save since %
  than through to toward towards under %
  underneath unlike until up upon %
  versus via with within without}

\renewcommand{\cfttableaftersnumb}%
  {\titlecap}%

\newcommand{\macrocapwrap}[1]{% 
  {\bgroup\bgroup{{#1}}\egroup\egroup}%
}

\begin{document}

\listoftables
\clearpage

\begin{table}[h] % Table float
\caption{Here is a table caption ending in %
  ``of'' with number \macrocapwrap{\ref{table1}}}
\label{table1}
\begin{tabular}{l c c} \\ \hline
Column1 & Column2 & Column3 \\ \hline
Row1 & 2.0 & 3.0 \\
Row2 & 2.0 & 3.0 \\
Row3 & 7.0 & 8.0 \\ \hline
\end{tabular}
\end{table}

\end{document}

Why does this macro work? I honestly have no idea. As I said, I arrived at it mostly through trial and error. It’s not ideal, and it seems a bit fragile, but I hope it can help other people until something more robust comes along.

Academic Workflow for the Ages (Part 2)

Over two years ago, I wrote a post about an academic workflow, mostly for literature review. I did not focus on writing, although I did recommend that people to use Scrivener to draft their documents (dissertation chapters, journal articles, and so forth). In this post, I discuss an alternate way to draft documents, which I think is much better.

Pandoc

Natural Writing

I recommend that people write their documents in pandoc markdown. Pandoc’s author describes it as “your swiss-army knife” for documents because it can convert between many document formats (e.g., HTML to MS Word).

Markdown is a syntax for plain-text documents that aims to be readable in plain text but also have enough structure that it can be parsed and translated into other formats. (Markdown’s original authors aimed to generate HTML documents from markdown.) For example, the following is a list in a markdown document:

Here is a list written in markdown: 

* Here is an item in the list.
* Here is another item in the list. 
* Here is the final item in the list. 

Even in a plain-text file, it’s clear that this is a list, so it’s easy to read this document in plain text and understand the intended formatting. Additionally, because the syntax is very simple, it’s easy to just write your thoughts, arguments, and whatever else you need to without pausing to deal with formatting. If I wanted to make a list in an e-mail, I would write it exactly as written above. At least for lists, there’s nothing new to learn, and in general, writing in markdown is very natural. Markdown achieves a tremendous separation between content and formatting. Pandoc converts the list above into the HTML shown below.

<p>Here is a list written in markdown:</p>
<ul>
<li>Here is an item in the list.</li>
<li>Here is another item in the list.</li>
<li>Here is the final item in the list.</li>
</ul> 

When writing in pandoc markdown, you can also use HTML comments to make notes to yourself and keep them right next to the material they refer to. For example, you could write an outline of a journal article you’re drafting and enclose it in an HTML comment, so it’s excluded from the output (for most formats) but still at the top of your own markdown document.

<!-- This is an HTML comment. --> 

<!-- 
Comments can also 
span 
several lines. 
--> 

Here is a list written in markdown: 

* Here is an item in the list.
* Here is another item in the list. 
* Here is the final item in the list. 

And because pandoc markdown is stored in plain-text files, you can use a variety of text editors to write them. Personally, I prefer a minimalist writing environment because there are less distractions. MS Word, for example, has so many formatting tools immediately available that it’s tempting to write something and then immediately fix up how it looks. With a plain-text editor, there are virtually no distractions. My favorite at the moment is Text Wrangler on Mac with the font set to display 24pt Helvetica. It’s free and simple, and it does what I need it to.

More Features

Pandoc expands traditional markdown with new features, such as different kinds of lists, different kinds of tables, in-text citations and reference lists, footnotes, and metadata. For example, you can make a table with the following pandoc markdown:

-------------------------------------------------------------
 Centered   Default           Right Left
  Header    Aligned         Aligned Aligned
----------- ------- --------------- -------------------------
   First    row                12.0 Example of a row that
                                    spans multiple lines.

  Second    row                 5.0 Here's another one. Note
                                    the blank line between
                                    rows.
-------------------------------------------------------------

Table: Here's the caption. It, too, may span
multiple lines.

If you want to cite a source, you can write the following:

Blah blah [@smith04; @doe99].

smith04 and doe99 are BibTeX keys in a BibTeX database.¹ Pandoc will replace them with proper in-text citations and generate a reference list at the end of the document. You can even use Zotero’s citation styles, so there are a lot of options for automatic formatting, including Chicago, APA, MLA, and formats for many academic journals.²

For all the features and how to use them, spend some time on pandoc’s readme page, and try them out for yourself. Note: The table and citation examples in this section were copied verbatim from pandoc’s readme.

More Formats

Pandoc can convert markdown into formats other than HTML, including LaTeX. Pandoc converts the markdown list above into the following LaTeX:

Here is a list written in markdown:

\begin{itemize}
\itemsep1pt\parskip0pt\parsep0pt
\item
  Here is an item in the list.
\item
  Here is another item in the list.
\item
  Here is the final item in the list.
\end{itemize}

And as I mentioned above, pandoc can also convert markdown to an MS Word document (*.docx file). Do you see where this is going? If you write your documents in pandoc markdown, you can easily convert them to other formats as needed. Lists, tables, and citations will all appear correctly in a variety of formats. If you’re a PhD student and your advisors want to review your work in MS Word (usually because of its handy track changes feature and comments feature), you can just take the current version of your markdown file, convert it to MS Word, and send it out. And when it’s time to make a final version, you can still convert your markdown to LaTeX and apply whatever template you want to (your school’s template, a journal’s article template, or your own custom template). You don’t have to change your source file at all; just apply a new template to get the formatting you need.

A Simple Example

Returning to the list example above, if I have a markdown file named temp.md with the following contents:

Here is a list written in markdown: 

* Here is an item in the list.
* Here is another item in the list. 
* Here is the final item in the list. 

I can open a terminal and convert it to HTML with the following command:

pandoc -r markdown -w html -o temp.html temp.md

Pandoc will create an HTML file called temp.html with the following contents:

<p>Here is a list written in markdown:</p>
<ul>
<li>Here is an item in the list.</li>
<li>Here is another item in the list.</li>
<li>Here is the final item in the list.</li>
</ul>

Reproducible Statistics

But wait. There’s more!

If your work involves statistics and you’re familiar with R, you can write something called R Markdown. R Markdown files can contain both markdown and R code (and R code that writes markdown). So you can write an R Markdown file with your entire statistical analysis that writes out fresh statistics, tables, and figures every time you process the file. If you find an error in your work or you want to update the way a figure looks, just change the code in the R Markdown file and reprocess it. Everything else will be the same plus your changes will have been included.

I won’t get into the details of setting up an R Markdown file here, but basically, you create a file with the *.rmd extension and write in your markdown and R code. Then, you “make” the file by running R on it. There are different ways to do this. You could call R from the command line with Rscript, for example. In any case, the result will be a pandoc markdown file (with a *.md) extension, which you can then convert to other formats (e.g., MS Word, LaTeX, etc.) as you would any other pandoc markdown file. In addition, you can easily share your R code with anyone who wants to check your work.

Disadvantages

A Command-Line Tool

For some people, the fact that pandoc is a command-line tool will be a disadvantage. Some graphical user interfaces (GUIs) for pandoc are listed here. I haven’t tried them, so I can’t make any recommendations.

The LaTeX Writer

One of the footnotes in this post discusses my complaints about the way pandoc handles citations. Another problem is the way pandoc writes out tables in LaTeX. Pandoc automatically writes out tables as longtables in LaTeX and sometimes inserts minipages in the middle of tables. For example, the following table is written in pandoc markdown and saved in a file called temp.md:

-------------------------------------------------------------
 Centered   Default           Right Left
  Header    Aligned         Aligned Aligned
----------- ------- --------------- -------------------------
   First    row                12.0 Example of a row that
                                    spans multiple lines.

  Second    row                 5.0 Here's another one. Note
                                    the blank line between
                                    rows.
-------------------------------------------------------------

Table: Here's the caption. It, too, may span
multiple lines.

Pandoc will convert the document to LaTeX with the following terminal command:

pandoc -r markdown -w latex -o temp.tex temp.md

The above command creates a file called temp.tex with the following contents (although I added some line breaks for formatting):

\begin{longtable}[c]{@{}clrl@{}}
\toprule\addlinespace
\begin{minipage}[b]{0.15\columnwidth}\centering
Centered Header
\end{minipage} & %
\begin{minipage}[b]{0.10\columnwidth}\raggedright
Default Aligned
\end{minipage} & %
\begin{minipage}[b]{0.20\columnwidth}\raggedleft
Right Aligned
\end{minipage} & %
\begin{minipage}[b]{0.31\columnwidth}\raggedright
Left Aligned
\end{minipage}
\\\addlinespace
\midrule\endhead
\begin{minipage}[t]{0.15\columnwidth}\centering
First
\end{minipage} & %
\begin{minipage}[t]{0.10\columnwidth}\raggedright
row
\end{minipage} & %
\begin{minipage}[t]{0.20\columnwidth}\raggedleft
12.0
\end{minipage} & %
\begin{minipage}[t]{0.31\columnwidth}\raggedright
Example of a row that spans multiple lines.
\end{minipage}
\\\addlinespace
\begin{minipage}[t]{0.15\columnwidth}\centering
Second
\end{minipage} & %
\begin{minipage}[t]{0.10\columnwidth}\raggedright
row
\end{minipage} & %
\begin{minipage}[t]{0.20\columnwidth}\raggedleft
5.0
\end{minipage} & %
\begin{minipage}[t]{0.31\columnwidth}\raggedright
Here's another one. Note the blank line between rows.
\end{minipage}
\\\addlinespace
\bottomrule
\addlinespace
\caption{Here's the caption. It, too, may span multiple lines.}
\end{longtable}

Notice that it’s a longtable containing minipages. This looks to me like a bit of madness. My understanding is that longtables are used by default because if they’re not, tables that are longer than a single page will not appear correctly. And I assume that authors complained about this problem in the past leading to the current setup. However, longtables could at least be implemented more elegantly with the tabu package. In general, it seems that more LaTeX formatting should be left to the LaTeX template (which can be changed easily by authors) than the pandoc writer (which cannot be changed easily by authors).

Git

Another benefit of writing documents in markdown—or really any plain-text format—is the ease of using version control. Version control systems, such as git, track changes to files, and with websites like GitHub, it’s possible to keep a remote backup of your files and their changes. Version control is especially useful on long projects, such as books or dissertations, where you may want to keep separate chapters in separate files. And if you’re collaborating with tech-savvy people, you can all work on the same set of files and track changes collectively.

I won’t give a tutorial on git here, and unfortunately, there’s a bit of a learning curve. But here are some useful resources:

• A pretty good, brief introduction: http://rogerdudler.github.io/git-guide
• A more detailed introduction: http://gitolite.com/gcs.html
• A very detailed guide book: http://git-scm.com/book
• Some interactive exercises on git branching: http://pcottle.github.io/learnGitBranching

The Setup

In summary, the setup I recommend is writing documents in either pandoc markdown or R markdown (depending on whether they contain statistics) and using git to track changes to documents. This setup works very well with long works, such as books and dissertations, where it makes sense to separate chapters into individual files.

---

Notes:

---

1. You need to tell pandoc the name of the BibTeX file when you execute the pandoc command on the command line, and the file needs to be in a folder where pandoc can find it (i.e., in the same folder as the markdown file or in the folder indicated by the --data-dir flag). Again, see the readme for details.↩

2. I actually have some gripes with the syntax for pandoc’s in-text citations. It’s convenient for quick documents, but for a formal academic work, pandoc’s citation commands are somewhat lacking, and BibLaTeX’s in-text citation commands are much more powerful. This is a tricky situation because while you can write BibLaTeX macros directly in pandoc markdown, pandoc won’t use them unless it’s converting that document to LaTeX. So if you want to create an MS Word document instead of a PDF, you’ll lose your citations. Personally, my solution was to write a parser in perl that could find pandoc citations and replace them with BibLaTeX citations, so I could still output LaTeX documents containing BibLaTeX formatting. But that might not be a solution for everyone. If there’s enough interest, I will polish and publish my perl code for others to use.↩

Arizona State University Dissertation/Thesis Template in LaTeX

Arizona State University (ASU) is one of the largest universities in the US. It must have tens of thousands of graduate students in attendance at any given time, many of whom need to write and submit a thesis or dissertation. All theses and dissertations need to following the formatting guidelines of ASU’s Graduate College (latest revision [July 2013] available here).

So I was surprised to see that ASU’s current LaTeX template is fairly basic. By writing this, I do not mean to criticize its author, who (as I understand the situation) was a graduate student who created a template that worked reasonably well and decided to make it available to others. ASU then adopted this student’s work as the template it would officially distribute to students. But as far as I know, the student who created the template did not invest a great deal of time or effort into it, and as a result, the template is rather shallow. It has the correct margins, and the table of contents will come out more or less correct, but what if you want to include appendices, for example? Or use biblatex for citations instead of natbib?

I did the formatting for my PhD dissertation on my own and created a new LaTeX template, which is available on GitHub here. (If you’re not familiar with git, you can grab everything simply by clicking the “Download ZIP” button to get the template and supporting files in a ZIP archive. Or just click here.)

Sample title page of dissertation template; click for image full sample PDF

The biggest (and, in my opinion, the most beneficial) difference between the official template and this new one is that the new template uses the memoir document class. The memoir document class is designed for formatting book-length works. For example, it has commands for indicating divisions between front matter, main matter, and back matter and adjusts formatting accordingly. So it’s a natural choice for formatting theses and dissertations which are book-length works. memoir is also a very large document class that natively supports many features without having to load other packages. It can natively format footnotes and endnotes, for example, and the table of contents can be highly customized using only memoir commands. The template I created definitely loads other packages, but I would guess that memoir is probably the most complete document class out there. And finally, memoir has excellent documentation, which is currently over 600 pages long. If there’s some confusing code in the template I created or if someone wants to add a new feature to their own thesis/dissertation, there’s a better chance that the documentation for memoir will provide the answer than for other document classes.

Some of the other improvements over the official template include the following:

• Includes all required and optional sections, including a copyright page, dedication, acknowledgements, preface, endnotes, and biographical sketch.
• Correct formatting for main matter (chapters) and back matter (appendices), which makes it easy to organize your entire document.
• For the typesetting engine, works with either pdftex or xetex. (xetex makes it easy to use any of the approved fonts.)
• For references, works with natbib and biblatex. (biblatex makes it easy to use Chicago, MLA, and APA style references.)
• Better separation of content and formatting. For example, write your table captions however you want and they will appear correctly in the list of tables. This arrangement makes it much easier to produce another (much better-looking version) of your dissertation/thesis in case you want to share a better-looking version with colleagues.
• Internal document references work. For example, clicking on an in-text citation jumps down to that citation in the references list.
• Bookmarks work, so there is a navigation side menu in the PDF that contains the major document elements (e.g., table of contents and each chapter heading), so the PDF is easier to navigate.
• Writes PDF metadata (including the title, name, and keywords) automatically.
• Uses the memoir document class, so it is easier to change formatting and create a book-length work in general.

There were challenges to getting all these features working together. Strangely enough, one of the most difficult challenges was getting chapter-level and part-level headings to appear uppercased in the table of contents. It turns out that the typical commands for uppercasing text in the table of contents conflict with the hyperref package. (I’ve written a separate post on my solution here.) But overall, I think I’ve found reasonably elegant solutions for implementing the formatting requirements in ASU’s style guide.

I have intentionally not created a style file, yet. In my experience, troubleshooting a document with a custom style file leads to headaches because it requires hunting through the style file and the preamble to figure out where problems are. I think it’s better to have all the potentially problematic code in one lengthy preamble. If there is enough interest in either a style file or packaging everything in a class, I will create them, but at least initially, I am just making a simple template file available to everyone.

Formatting a dissertation or thesis is often one of the less pleasant parts of the graduate student experience. It’s the last thing students need to do before they’re finally done with an often long and difficult graduate school experience, and formatting is usually tedious and time-consuming. Hopefully, this template can take some of the pain out of that experience for ASU graduate students.

Again, the template is available on GitHub here. You can grab everything simply by clicking the “Download ZIP” button to get the template and supporting files in a ZIP archive. I did the formatting for my PhD dissertation on my own and created a new LaTeX template, which is available on GitHub here. If you’re not familiar with git, you can grab everything simply by clicking the “Download ZIP” button to get the template and supporting files in a ZIP archive, or just click here.

Uppercasing in a "memoir" Table of Contents with "hyperref"

memoir is one of my favorite document classes in LaTeX, but uppercased headings in a memoir table of contents conflict with the hyperref package. Uppercasing headings the table of contents in a memoir document can be achieved in at least two basic ways. The first uses the \cftKfont font commands to send formatting instructions to the table of contents. The K in \cftKfont stands for the heading level,¹ so to modify the chapter headings, for example, you would use the \cftchapterfont macro as shown below:

% Uppercase chapter headings in TOC
\renewcommand*{\cftchapterfont}%     
  {\normalfont\MakeUppercase}

Because \MakeUppercase is sort of brutal in the way that it uppercases, it can cause errors. The memoir documentation recommends using another macro \MakeTextUppercase, which would be used in the following way to uppercase chapter headings in the table of contents:

% Uppercase chapter headings in TOC
\renewcommand*{\cftchapterfont}%     
  {\normalfont\MakeTextUppercase}

These methods are simple, but—as noted above—they both conflict with the hyperref package.

This conflict is aggravating because hyperref makes PDFs better in many ways. For example, hyperref will automatically make internal document links active. So if you have citations throughout your work, those in-text citations will turn into links that jump down to their entries in the list of citations at the end of the document. Similarly, when the document refers to a table or figure (e.g., “see table 2 for more information”), the number becomes an internal document link that will take the reader to the table or figure. And entries in the table of contents also become internal document links. So there are a lot of benefits to simply using the following line in a preamble:

\usepackage{hyperref}

With specific commands, hyperref can do a lot more, such as write out PDF metadata and use another package, called bookmarks, to create a PDF navigation bar.

The conflict between these two uppercasing commands and hyperref are a known problem, so memoir provides another method, \settocpreprocessor, for sending uppercase formatting to headings in the table of contents (see p. 158 of the memoir documentation). The code below shows how to use this macro to uppercase part and chapter headings in the table of contents:

\makeatletter
\settocpreprocessor{part}{%
    \let\tempf@rtoc\f@rtoc%
    \def\f@rtoc{%
      \texorpdfstring{\MakeTextUppercase{%
        \tempf@rtoc}%
      }{\tempf@rtoc}%
    }% 
}
\settocpreprocessor{chapter}{%
    \let\tempf@rtoc\f@rtoc% 
    \def\f@rtoc{%
      \texorpdfstring{\MakeTextUppercase{%
        \tempf@rtoc}%
      }{\tempf@rtoc}%
    }% 
}
\makeatother

This code will uppercase part and chapter heading entries in the table of contents, but it does not uppercase part-level or chapter-level headings in the table of contents. The difference is important because entries, such as the “List of tables,” won’t be uppercased by these commands. Doesn’t it make more sense for entries with the same level to have the same formatting? Users can get around this problem by manually uppercasing table-of-contents entries, such as for the name of the list of tables:

% Manually uppercase name of the list of tables
\renewcommand{\listtablename}
  {LIST OF TABLES}

But users would need to go back and manually change this and other commands if they want to produce a new version of their document without uppercased part-level and chapter-level headings. This approach violates the supposed strength of LaTeX—separating content from formatting. Instead, users need a way to uppercase part-level headings and chapter-level headings in memoir documents.

Fortunately, I have discovered a way to produce uppercase part-level and chapter-level headings by patching certain macros in the memoir document class. In the preamble, enter the following:

% Load 'etoolbox' to get the '\patchcmd' macro
\usepackage{etoolbox}

% Patch the command that writes part-level entries
%   to the table of contents, so they are in 
%   'normalfont' and uppercase
\makeatletter% 
\patchcmd{\l@part}%                     
    {\cftpartfont {#1}}%                
    {\normalfont \texorpdfstring{%      
      \uppercase{#1}}{{#1}} }%
    {\typeout{Success: Patch %
      'l@part' to uppercase %
      part-level headings in the %
      table of contents.}}%
    {\typeout{Fail: Patch %
      'l@part' to uppercase % 
      part-level headings in the %
      table of contents.}}%
\makeatother%

% Patch the command that writes chapter-level 
%   entries to the table of contents, so they are 
%   in 'normalfont' and uppercase
\makeatletter% 
\patchcmd{\l@chapapp}%                  
    {\cftchapterfont {#1}}%             
    {\normalfont \texorpdfstring{%      
      \uppercase{#1}}{{#1}} }%
    {\typeout{Success: Patch %
      'l@chapapp' to uppercase %
      part-level headings in the %
      table of contents.}}%
    {\typeout{Fail: Patch %
      'l@chapapp' to uppercase %
      part-level headings in the %
      table of contents.}}%
\makeatother%

% Load 'hyperref' to get the \texorpdfstring
%   command
\usepackage{hyperref}

This solution uses a similar approach to the one provided in memoir documentation with the \settocpreprocessor macro in that both use the \texorpdfstring macro from the hyperref package. The \texorpdfstring macro lets users send different text depending on whether the text will be typeset by LaTeX or not. Chapter headings are an example of content that gets typeset by LaTeX in the table of contents and in the PDF as PDF bookmarks, so \texorpdfstring is a great way to avoid these kinds of errors.

---

Notes:

---

1. See table 9.3 on p. 150 of the memoir documentation for the other values of K.↩

Pander Tables with No Emphasized Columns or Rows

Pander is a great R package for writing pandoc markdown from R, for example, from an R markdown (*.rmd) document. (R is an open-source statistics platform; pandoc converts documents to different formats [e.g., markdown to HTML or HTML to LaTeX].) Pander is great because it makes it easy to integrate statistical analyses (conducted in R) into reports written in pandoc markdown, which pandoc can then easily convert to nearly any other format you would want.

Default Behavior

Pander can write paragraphs, lists, and tables out to pandoc markdown—all very useful. But its table-writing functions have at least one problem: they automatically emphasize (i.e., bold) row labels, and pander provides no option to change this behavior.¹

Here is an example to illustrate the default behavior. Create an R markdown document with the following contents:

# Load pander
library(pander) 

# Get a small dataframe for demonstration purposes
df <- subset(mtcars, select=c("mpg","hp","wt"))[1:5,] 

# Print out the dataframe as a markdown table using pander
pander(df)

If you process the file with R, it creates a markdown file with the following contents:

----------------------------------------
                    mpg   hp   wt  
----------------------- ----- ---- -----
     **Mazda RX4**       21   110  2.62 

   **Mazda RX4 Wag**     21   110  2.875

    **Datsun 710**      22.8   93  2.32 

  **Hornet 4 Drive**    21.4  110  3.215

 **Hornet Sportabout**  18.7  175  3.44
----------------------------------------

The double-asterisks enclosing each term in the first column will bold those terms when converted to another format, such as HTML. If the file above is called demo.md, it can be converted to HTML with the following command in a terminal:

pandoc -r markdown -w html -o demo.html demo.md

And here are the contents of the file the command generates (called demo.html):

	mpg	hp	wt
Mazda RX4	21	110	2.62
Mazda RX4 Wag	21	110	2.875
Datsun 710	22.8	93	2.32
Hornet 4 Drive	21.4	110	3.215
Hornet Sportabout	18.7	175	3.44

It’s an HTML table (with no border), all the columns are center-justified, and all the row labels appear in bold.

I’m not sure why this behavior is the default, let alone why it can’t be changed. Two of the style guides that I am most familiar with, APA and the Chicago Manual of Style, do not recommend setting row labels in bold. (These are also two of the most popular style guides for writing in American English.) In fact, I can’t think of any style guide that recommends setting row labels in bold. Such style guides could exist, but they’re clearly in the minority on this element of formatting. So without some kind of workaround, pander produces tables that can’t be used in most professional documents.

The Fix

It happens that I need to produce professional-looking tables using pander, so I wrote the following function in R:

no.emphasis.table <- function(df){
  the.row.names <- rownames(df) 

  # For some reason, when 'pandoc' writes the markdown 
  # table to LaTeX, it doesn't make the first column 
  # wide enough unless some padding is added to the row 
  # names
  add.space <- function(x){
    return(paste0(x, "&nbsp;"))
  }
  the.row.names.m <- as.vector(sapply(the.row.names, add.space))
  rownames(df) <- NULL
  df <- cbind(the.row.names.m, df)
  colnames(df)[1] <- '' 

  # Set horizontal justification for columns
  v.justify <- vector()
  v.justify[seq(1, length(df))] <- 'center'
  v.justify[1] <- 'left'
  set.alignment(v.justify) 
  return(df)
}

This function can then wrap data frames before being called by pander as shown here:

pander(no.emphasis.table(df))

When the original table is processed with this new command, the output is:

 ----------------------------------------
                     mpg   hp   wt  
 ----------------------- ----- ---- -----
 Mazda RX4           21   110  2.62 
 
 Mazda RX4 Wag       21   110  2.875
 
 Datsun 710         22.8   93  2.32 
 
 Hornet 4 Drive     21.4  110  3.215
 
 Hornet Sportabout  18.7  175  3.44 
 ----------------------------------------

Pandoc converts the above markdown to the following HTML:

	mpg	hp	wt
Mazda RX4	21	110	2.62
Mazda RX4 Wag	21	110	2.875
Datsun 710	22.8	93	2.32
Hornet 4 Drive	21.4	110	3.215
Hornet Sportabout	18.7	175	3.44

Notice that the row labels are no longer in bold, but everything else is the same.

---

Notes:

---

1. Note that pander’s author fixed this problem after I submitted a bug report. However, the solution presented in this post can still be used with older versions of pander.↩