plaintext_paper_tutorial.md

#MVC Tutorial: a PlainText paper on GitHub

How to use Markdown, BibTeX, and Pandoc to efficiently write and publish an academic paper on GitHub.

G. E. Saretto - December 17th, 2014

GitHub is an excellent platform to store, access and edit your academic writing: it is an online database that allows you to track your notes and drafts, quantify your daily labor, and showcase or share your progression. The habit of recording and publishing every stage of your work quickly improves your sense of productivity, and the documents that you produce will always be easily accessible. Nevertheless, the integration between the various components that participate in the redaction of an academic text - notes, drafts, bibliography, polished work - can pose some problems. Here is a tutorial that will accompany you in every step of your work, from the collection of ideas to the final presentation of your paper.

##1. Setting up the environment

1. From your GitHub home page, create a new repository by clicking on the dedicated link. Use a simple, catchy name, so that the page will be easily accessible by your peers as well (e.g.: sonnets_print for a paper about Shakespeare's Sonnets as a reaction to the advent of printing), and provide a brief and clear description. Click on Create Repository when you are done.

2. Create a working folder on your hard drive; open the terminal and access the folder where you usually store your work (e.g.: /home/user/Documents/) by using the cd (change folder) and cd .. (go up one folder) commands; here type mkdir sonnets/ to create the folder (substitute sonnets with the working title for your project).

3. Access the folder by typing cd sonnets (substitute sonnets with the working title for your project).

4. Here create three files (substitute sonnets with the working title of your project):

   1. a notes file, where you will keep track of ideas and impromptu provisional passages - type touch sonnets_notes.md;

   2. an outline file, to start working on the structure of your paper - type touch sonnets_structure.md;

   3. a draft file, which will become your paper - type touch sonnets.md.

5. Initiate a Git repository in this folder: it will constantly keep track of your changes to every file. Type git init in the terminal to do so.

6. To verify that your folder has become a Git repository, type git status; as you will be able to read, the repository is waiting for something to commit.

7. Add each of the three files contained in the folder (you can always check what's in it by typing ls) to the current stage of your work by using the command git add, followed by the name of each file:

   1. for the notes, type git add sonnets_notes.md;

   2. for the outline, type git add sonnets_structure.md;

   3. for the draft, type git add sonnets_draft.md.

      • Tip: if you want to add every file in a folder to the folder's repository, you can simply type: git add -A; remember, however, that this is not always necessary.

8. Now commit your changes: the state of every file that you have added to the current stage will be saved as part of a single set of changes, to which you will be able to add a brief annotation. In order to do so, type the command git commit -m, followed by your comment placed between quotation marks " comment ". This initial commit, for instance, might be something like: git commit -m "Setting up the files for my paper on the Sonnets".

9. Finally, push your changes to the online repository: the package of changes that you have committed (in the form of the individual files that you have added) will be uploaded on the GitHub platform, so that it will be accessible from any device. Our first push is special: we have to tell our local repository where to locate the remote repository with which each change will be constantly coordinated. The empty online repository that you have created during step 1 will probably contain a detailed set of instructions; in any case, only two commands are required for your first push:

   1. define the remote origin of your repository by typing the line git remote add origin followed by the https:// web address of your online repository (e.g.: git remote add origin https://github.com/gesaretto/sonnets_print.git);

   2. upload your current committed stage by typing git push -u origin master.

10. All set! We have a local repository, containing our draft, our structure, and our notes, and a mirroring remote repository that will track every step of our work.

##2. Writing and tracking

1. The format that you will use for writing your paper is an accessible and versatile language called Markdown; you can find plenty of software to redact your .md files online: MarkdownPad for Windows and ReText for Linux are user-friendly, free options that are appropriate for beginners, given their straightforward GUI. A few hints to get started (more info can be found on the language's official page):

   • to emphasise your text, encompass it with one (for italics) or two (for bold) *asterisks* or __underscores__;

   • for titles, use #hashtags: the main titles of the paper will be preceded by one #hashtag, the title of each smaller section by ##two hashtags, the title of each paragraph by ###three hashtags and so on;

   • for lists use either numbers followed by a dot and a space (1. list item), or asterisks (* list item) and dashes followed by a space (- list item);

   • for footnotes, use square brackets to create a label that will follow the word requiring a note (e.g. word[^note]) - then, in a different paragraph, use the same label, followed by a colon, to write your actual note (e.g. [^note]: This is a note.)¹;

   • if you need to quote pieces of code in your paper, simply use ticks (e.g.: `code`) to encompass them.

2. After each writing session, remember to add, commit, and push your changes:

   1. add each file that you have worked on to the current stage by using the command git add, followed by the name of the file;

   2. commit your changes with the git commit command, followed by a comment on the progression of your work placed in quotation marks after the flag -m (e.g.: git commit -m "This is a comment on my work.").

   3. push your changes to the remote repository by using the command git push; you will have to enter your username and password.

      • Tip: you can check the status of your repository (tracked and untracked changes and files) by typing git status at any time.

3. Follow and share the development of your work through the GitHub dashboard.

##3. Managing your bibliography

1. The standard that you will use to manage your references, BibTex, is an effective and flexible bibliographic system; the information needed for your paper will be stored in a single .bib archive, a human-readable, adaptable format, compatible with several programs and textual file types. Download a manager for BibTex online: Zotero is a powerful option, although slightly overwhelming for beginners; we suggest the simple GUI of JabRef, available for most operating systems.

   • The use of JabRef is very intuitive: create a new record for each reference, specify the appropriate type, fill in the required fields, add an abstract and a review whenever you feel it may be necessary (I find it useful to store relevant quotations and page numbers here, so that I don't have to rush to the library later).

     • Tip: entering each proper name in the format "LastName, FirstName" (e.g. "Vargas Llosa, Mario") will avoid confusion.

     • Tip: the BibTex Key that we will discuss later is always visible as the last entry in each record; a "Generate BibTex key" command is available (the small wand on the left column, in the lower section of the window).

     • Important: in order to easily use your bibliographic archive across different systems, set the Default encoding as UTF8 from the Options - Preferences panel; please note that this is an essential requirement to let your .bib file work with Pandoc.

2. Keep your bibliographic archive constantly updated. The .bib file where your references are stored should be placed inside of your working folder (e.g.: sonnets.bib), so that you may easily add, commit, and push your bibliographic data and notes together with the rest of your documents.

3. Learn to recognize the BibTex Key of each entry: it is usually a combination of the author's last name and the book's year of publication (e.g.: VargasLlosa1975 for Mario Vargas Llosa's La Orgía Perpetua); this functions as a label to identify the entire set of data related to a reference.

4. To insert a reference to an entry of your .bib archive within your .md document, simply use the corresponding BibTex Key, preceded by the at-sign @ (e.g.: @VargasLlosa1975).

   • Tip: the standard Pandoc output will produce a Name (Year) output for a simple @BibTexKey reference, and a (Name Year) output for a [@BibTexKey] reference between square brackets; once you have started using Pandoc, try experimenting with these options:

     • @VargasLlosa1975 will result in "Vargas Llosa (1975)";

     • [@VargasLlosa1975] will result in "(Vargas Llosa 1975)";

     • [as in @VargasLlosa1975] will result in "(as in Vargas Llosa 1975)";

     • [@VargasLlosa1975 page 16] will result in "(Vargas Llosa 1975, 16)".

5. To include an index of your references at the end of your paper, simply insert a #References or ##Bibliography empty section; Pandoc will compile one for you.

##4. Presenting your paper

1. Once you are done with your work, use Pandoc for a quick conversion of your .md file into the format of your choice (.doc, .html, .docx, .pdf). Install Pandoc by following the instructions presented on its web site; the software is available for most operating systems.

2. Verify that you have correctly installed Pandoc by typing the command pandoc --version in your terminal; if you get information about the version currently installed, you are all set.

3. Prepare your .md file by adding a YAML block at the beginning; this small object will provide Pandoc with the necessary information for the conversion. Here is an example of how it will look like:

   title: Shakespeare's Sonnets and the Advent of Printing
   author: G. E. Saretto
   date: January 17, 2015
   bibliography: sonnets.bib
   

   • Tip: the crucial part of this step is identifying the path to the bibliography: file; remember that it has to be located in the same folder as the main .md file - otherwise Pandoc won't be able to find it.

4. Run Pandoc by invoking it in the terminal; your command line will look like this: pandoc -oS sonnets.odt --filter pandoc-citeproc sonnets.md. Notice that the output precedes the input in the program's syntax, which is as follows:

   5. pandoc is simply the invocation of the program;

   6. the two combined flags -o and -S (resulting in -oS) tell Pandoc to:

      • -o - write the o__utput to the specified file (the one that immediately follows), and in the format of our choice (.doc__, .pdf, .html, etc.);

      • -S - operate __s__mart choices in determining the format of the layout, detecting typographical correspondences between the format of the input and that of the output;

   7. sonnets.odt is the output, with an extension corresponding to the format of my choice;

   8. --filter pandoc-citeproc asks Pandoc to use one of its secondary implementations, a devoted CiteProc program, in order to identify and match our references and produce a bibliography;

   9. sonnets.md is the input, the original file on which you have been working on.

      • Tip: Pandoc requires an piece of software, a LaTeX engine, in order to work; MiKTeX is the standard option for Windows, TeXLive the one for Linux.

5. Good job! The final file, a printable version of your paper featuring a clear layout and a complete bibliography, is in your working folder, ready to be distributed. Remember to provide a link to your GitHub repository!

Footnotes

1. It is easier than it sounds! ↩