en.search-data.min.4611b8a4de9f01e9f4aa9b67509c508bcea111a910e4214317371b7cb45cf898.json

[{"id":0,"href":"/docs/book/chapter-1/","title":"What? Why? Who? How?","section":"Book","content":" What? Why? Who? How? # What? # Academic writing in general, and scientific and social scientific writing in particular, requires that we use empirical data to mount an argument. There are many conventions that have become sacrosanct that we both need to use and find quite helpful for fulfilling the task of providing convincing data and a tight argument, grounded in a long line of other worthwhile research. Citations, figures, tables, equations, proofs, diagrams and prose are all key to this endeavor. Most undergraduate and graduate students, post docs, early, mid and late career faculty do most of their writing in What You See is What You Get style programs like Word or Google Docs. They are easy to use and you already know how to use them but they were not made with scientists and social scientists in mind. Anyone who has had to format a bibliography, update their in-text citations, re-number figures, or properly format a table in a Word document will quickly realize the limitations of Microsoft’s flagship Office program.\nIn this document, I am going to give you an introduction to some of the most helpful tools for adopting a plain text tool kit for conducting and writing your research, which was designed with researchers in mind who need to leverage all these conventions in their work. It will require that you actually write code, install programs, manipulate text and images to compose documents and then typeset them. If you are familiar with a programming language like python or R, you will be well positioned to take advantage of these tools. If you are not familiar with how your computer works, you will have to do a little extra work but I will attempt to make the burden of learning how to use these tools a little less onerous. But what is plain text?\nA plain text file is a file where the contents are human readable, and do not contain any information other than the alphanumeric characters in the file itself. Plain text is primarily distinguished from a formatted text file, such as a Word Document. For example, if you open a Word Document that has italicized, bolded, underlined, different type faces, and margins, the instructions for how that text is formatted is not immediately rendered to you, just the formatted text is. In a plain text file containing the same information, the styling conventions are readable to you as they are encoded in the text along with the prose. The distinction is not easy to immediately capture but will become clear very quickly, the more important question to address is why would you be interested in learning anything about plain text files and software.\nWhy? # I have colleagues who really don\u0026rsquo;t understand my obsession with plaintext software. Most think it is the product of a desire for esoteric and complicated things, a severe and somtimes productive neurosis. They think that it is actually just harder to use Markdown, \\(\\LaTeX\\) , and pandoc, that Word is enough, and that when something is poorly formatted or not particularly pretty then the words and argument have to speak for themselves. I used to be willing to concede the point that just using Word is easier, but it actually isn\u0026rsquo;t easier. Yes, you already know how to use Word, but Word wasn\u0026rsquo;t designed with scientists and social scientists in mind, people who have to communicate very complicated things in concise and elegant ways, taking advantage of all the contemporary tools we have at our disposal.\nIt is in fact easier to do what I will teach you in this document. No one wants to emulate a document that looks like it was written in Word. What more, one day the people who read your work and take it seriously might just want to replicate it. Maybe they\u0026rsquo;ll ask you how a particular figure was made, or what process you adopted to generate a particular regression table. If you have a PDF file for the submitted article version called my_fabulous_paper_vFINAL_2.pdf and 20 different Word documents all with slightly different versions of the same name you will lament the times you thought writing in Word was \u0026ldquo;easier\u0026rdquo;.\nTo give just a brief introduction to why you should make the effort to switch to plaintext tools for research and writing I will say there are three reasons:\nThey Are Free: All the things I will outline here are things that are free to use, have a wide user base, and keep your data and writing in an accessible and non-proprietary format.\nThey Encourage Good Practices: Working with plaintext tools makes you interact with your data and writing files in a way that encourages good practices at the expense of bad ones. I will say more about these shortly so you will have to have sufficient faith in the project to get through chapters 1 and 2 to be truly convinced but convinced you certainly shall be.\nThey Make Your Work Accessible: You\u0026rsquo;ll make documents that are reproducible and allow you to distribute the means to replicate your work with ease.\nThese tools are not just for quantitative scientists and social scientists. They were originally written for scientists who needed to use a lot of math, but they are now quite useful to scientists and social scientists of any methodological commitment, particularly considering the other important feature of a plain text workflow, its synergy with reproducibility and openness.\nTrivia\nYou might be surprised to learn that I am actually a qualitative sociologist who specializes in interviews and ethnographic data collection. Several other social scientists have noted the usefulness and superiority of plaintext tools for research and writing. My extended introduction is hardly a substitute for some canonical texts on the subject. I myself became an acolyte when I found Kieran Healy\u0026rsquo;s The Plain Person\u0026rsquo;s Guide to Plain Text Social Science in my second year of graduate school. I recommend reading it as it outlines in a far more parsimonious and convincing way the why of why make the switch to a set of software that is a little more onerous at first to use but rewarding once it is mastered. The document you are looking at here is superior in only one regard: it takes you step by step through some of the more dizzying steps in the process of switching to this tool-kit, and is geared toward the graduate student who knows how to use their computer but hasn\u0026rsquo;t made a lot of effort to learn the more archaic and powerful tools already available to them.\nWho? # Adopting this work flow and taking advantage of this book in particular to do so, will be most helpful to undergraduate and graduate students as well as post docs and early career professors or researchers. Especially those students who are taking courses in computation, statistics, or higher level methods courses will find this work helpful. But I do not think that the benefits of the plain text tool kit should be solely confined to scholars and students in the quantitative side of the social sciences as this software will help you not only get things done, and make things look beautiful, but it will also help enhance your skills in scientific communication. Along the way, I imagine you will also learn a few things about data and project management as well that are applicable across the sciences and social sciences.\nHow? # For complete beginners, people who are proficient at using their computer but have never opened up a terminal, review Chapter 1, \u0026ldquo;The Terminal\u0026rdquo;, and Chapter 3, \u0026ldquo;Project Organization\u0026rdquo;, before going to Chapter 4, \u0026ldquo;Installation\u0026rdquo;. If you are familiar with how to use the terminal then you can briefly checkout Chapter 3 before going to Chapter 4 to install the software that we are going to be using. Installing the software is the first big jump to adopting plaintext software for your research and writing and it is a little complicated.\nOnce you have the software installed you will be ready to start learning how to actually use it in Chapter 5, \u0026ldquo;Document Composition\u0026rdquo;,, where I will show you all the most important conventions in LaTeX and Markdown before showing you how to typeset your first document. After that you can proceed to Chapter 6, \u0026ldquo;Dynamic Documents\u0026rdquo; to learn how to use dynamics documents and RMarkdown in particular. At that point you will be ready to learn how to keep a record of everything you\u0026rsquo;ve done and make it available to others using git and Github in Chapter 7, \u0026ldquo;Version Control\u0026rdquo;.\nNext "},{"id":1,"href":"/docs/book/chapter-2/","title":"The Terminal","section":"Book","content":" The Terminal # Switching to a plain text workflow requires that you adjust the way you interact with your computer. Rather than pointing and clicking and navigating through different windows we will be using what is a primitive technology in computing: the Terminal. It was once the case that all interactions with a computer were done with nothing more than a keyboard, not even a mouse. Of course computing has come a long way and most of your interactions with your computer take place with a mouse, touch pad, or touch screen, and it can be intimidating to approach the terminal.\nUsing the terminal has some distinct advantages over navigating through the file explorer that comes with your operating system and will help to get you familiar with how to control the software we will be working with. For one, the terminal is actually quite easy to use and straight forward after learning just a few basic principles. Further, navigating your computer with the terminal helps to instruct you in the file structure upon which the programs you interact with relies. Understand this file structure will then help you to both organize your project and typeset documents. Here I will provide a quick tutorial on how to use the terminal with some of the most basic and essential commands.\nFigure 1: The Terminal in macOS\nWindows and macOS use different kinds of terminals, and even in macOS there are slightly different versions of the same terminal. This means that you will have to learn commands for your operating system. Also, they are called slightly different things. On Windows it is called \u0026ldquo;Command Prompt\u0026rdquo; and there is a specific program called PowerShell. Don\u0026rsquo;t use PowerShell, use Command Prompt, sometimes referred to as CMD which can be found in the \u0026ldquo;Accessories\u0026rdquo; part of the Start Menu. On macOS you will find the terminal under \u0026ldquo;Other\u0026rdquo; in your Launchpad. Once you have found it and launched it, you\u0026rsquo;ll have something on your screen that looks like Figure 1. Here is a table with commands across operating systems:\nWindows CMD Task macOS Terminal dir List files and folders ls cd Full path of current folder/directory pwd cd \u0026lt;path to directory\u0026gt; Change folder/directory cd \u0026lt;path to directory\u0026gt; cd .. One directory up in directory tree cd .. mkdir newFolder Create new directory in current directory mkdir myFolder rmdir myFolder Remove a directory* rmdir myFolder ren oldFolderName newFolderName Rename a directory mv oldFolderName newFolderName robocopy myFolder \u0026lt;path to destination directory\u0026gt; Copy a directory cp -r myFolder \u0026lt;path to destination directory\u0026gt; move myFolder \u0026lt;path to destination directory\u0026gt; Move a directory mv myFolder \u0026lt;path to destination directory\u0026gt; ren oldFileName newFileName Rename a file mv oldFileName newFileName copy myFile \u0026lt;path to destination directory\u0026gt; Copy a file cp myFile \u0026lt;path to destination directory\u0026gt; move myFile \u0026lt;path to destination directory\u0026gt; Move a file mv myFile \u0026lt;path to destination directory\u0026gt; cls Clear the terminal screen clear Table: Equivalent commands for the terminal in Windows and macOS.\nA Short Tutorial # When working in the terminal you will be dealing with Files and Directories. A directory is what is usually called a \u0026ldquo;folder\u0026rdquo;, a container for files. A file is the basic unit for holding data in your computer. A file is the thing that you typically open with your cursor (like a text file, Word document or an image file) by double clicking on it. We will be dealing with programs on the terminal but not in the way you are familiar. We will get there eventually, but just remember files go in directories and directories can themselves have sub-directories with files in them. This is the hierarchical folder structure that is ubiquitous in computing.\nWith the terminal open go ahead and type in ls and hit Enter. In macOS you should see something like this print out:\n(base) MacBook-Pro:~ timothyelder$ ls Applications Desktop Documents Downloads Library Movies Music Pictures Public The ls or \u0026ldquo;list\u0026rsquo; command in macOS lists the contents of the current directory you are in. To determine which directory you are in type in pwd and hit Enter.\n(base) MacBook-Pro:~ timothyelder$ pwd /Users/timothyelder pwd stands for \u0026ldquo;present working directory\u0026rdquo; and prints out the path to the directory you are in. The \u0026ldquo;working directory\u0026rdquo; just means whatever directory your terminal is open in. On macOS, whenever you open a terminal it automatically opens in what is known as your \u0026ldquo;Home\u0026rdquo; directory which has the files that appear on your Desktop, in your Documents directory and other directories associated with Videos, Music, etc.. A path is the generic way of referring to the address of a directory or file on your computer. Let\u0026rsquo;s start to navigate your computer and manipulate directories and files from the terminal.\nTo navigate to another directory from your working directory use the cd or \u0026ldquo;change directory\u0026rdquo; command and specify which other directory you want to change to. Let\u0026rsquo;s change to the Documents directory by typing in cd /Users/timothyelder/Documents. This is the path for me, as my user name on my machine is \u0026ldquo;timothyelder\u0026rdquo;, so you\u0026rsquo;ll have to use your username or whatever is in the path when you use the pwd command. After using the cd command to get to the Documents directory let\u0026rsquo;s create a sub-directory there to store the files related to the PlainText Working Group. To do this you will use the mkdir or make directory command. Type mkdir plaintext into the terminal and hit Enter. Check to see that the new directory has been made by typing in ls again and see that the directory has been made.\nNow, when using the cd command (or any other command that takes in a path as an argument) you can use either absolute or relative paths to specify where you want to go or what file or directory you are specifying. An absolute path uses the full amount of information to describe the address of the file or directory you are referring to (think of them as latitude and longitude), such as /Users/timothyelder/Documents/plaintext. That is the absolute path of the plaintext directory. Using the absolute path makes everything explicit, but takes up a lot of time when you have to type it in over and over again into the terminal. To save yourself time you can use a relative path which is relative to wherever your terminal is open on your computer (think of these as generic indexical directions, \u0026ldquo;around the corner\u0026rdquo;, \u0026ldquo;take a left at the light\u0026rdquo;, or \u0026ldquo;across from the 7/11\u0026rdquo;). For instance, if you did the last set of instructions correctly, you created a directory called plaintext in the Documents directory and we noted the absolute path above. The plaintext directory is immediately accessible to the Documents directory because the former is a sub-directory of the latter, so simply typing in cd plaintext will move your terminal into the plaintext directory.\nGo ahead and cd into the plaintext directory and type ls again. As you\u0026rsquo;ll see, nothing is printed out from the list command because it is a brand new directory with no files or subdirectories. Next thing to do is to create an example text file. To do this we are going to use a built-in text editor to create a new file using the vim command. vim is an ancient text editor that is pretty much built into all machines that are based on UNIX which includes macOS and Linux. Into the terminal type vim my_text_file.txt. The command vim is used to open a text editor in your terminal and you have just used it to open a file called my_text_file.txt, and because the file doesn\u0026rsquo;t yet exist, you are creating it at the same time. This can be very confusing because it looks like an empty terminal window, as can be seen in Figure 2.\nFigure 2: An instance of an empty file opened with `vim`\nThe terminal is now open in an empty text file, and if you start tapping away at your keyboard nothing will happen, which is also pretty mysterious behavior. To edit the file and add content you need to press the i key on your keyboard. This activates \u0026ldquo;insert\u0026rdquo; mode in the vim text editor meaning you can actually type in the window and put content into the file. This will look like Figure 3. Type in \u0026ldquo;Hello World!\u0026rdquo; then hit the esc or escape key on your keyboard and you will exit the insert mode, then type in :wq (that is hit Shift - ; and then type wq). Typing in wq means \u0026ldquo;write-quit\u0026rdquo; which is \u0026ldquo;write the file contents to memory and exit the editor\u0026rdquo;. To exit without saving use :q! instead of :wq. Once back to the normal terminal type in ls to check that the file is there, and then type in cat my_text_file.txt and the file contents will print out. The cat command (besides being a cute reminder of our Feline friends) stands for \u0026ldquo;concatenate and print file contents\u0026rdquo; and allows you inspect plain text files from the command line.\nFigure 3: Insert mode in `vim`\nThough we are not going to be using vim extensively it is good to know how to use it, particularly considering how disorienting it can be when a program pops you into a vim terminal and you\u0026rsquo;ve never seen one before. All digital writing was once conducted in things like vim, and other text editors, a class of programs that allows the user to create and edit plain text data. You could do nearly everything we are going to do in the working group with vim or an equivalent terminal based text editor. You could write a whole book in it if you wanted, or the documentation that you are looking at now (see Figure 4).\nFigure 4: Composing this documentation in `vim`\nLastly, the terminal lets us take a look at hidden files in a directory. Do the exact same thing as you did above (where you created a text file called my_text_file.txt with \u0026ldquo;Hello World!\u0026rdquo; inside it) but this time when you first type in the vim command, instead of my_text_file.txt, type .hidden_file. Make the file contents the \u0026ldquo;Hello World!\u0026rdquo; phrase, same as before and write quit out of the file. Back at the normal terminal type ls again to make sure the file you just created is there. Curiously, you will not see a file called .hidden_file but the my_text_file.txt will be there! You can even check in a normal Finder window or File Explorer and the file will not be there.\n(base) MacBook-Pro:plaintext timothyelder$ ls my_text_file.txt This is because files that begin with a period are hidden and do not appear without using a special flag or option for the ls command. Typing in ls -a will printout all the files in the directory, even hidden ones.\n(base) MacBook-Pro:plaintext timothyelder$ ls -a .\t.hidden_file ..\tmy_text_file.txt There is nothing special about any given directory that you can navigate to on your computer. They are all generic containers that store generic files and so you can take what you have applied here and move up and down the directory tree, listing out the files and creating files as you please.\nA Few Helpful Hints and A Warning # When using the terminal if you ever need help with a command you can look up what\u0026rsquo;s called a man page, or manual page simply by typing in man \u0026lt;command of interest\u0026gt;. So if you want to read about everything the ls or cd commands can do simply type in man ls or man cd and the terminal prints out information that you can navigate through with the directional keys. If you need to exit a man page hit the q key on your keyboard.\nWindows Users\nUse help instead of man Also, for the cd command, you can navigate into the parent directory of your working directory by typing in cd ... For example, above we created a sub-directory called plaintext in our Documents directory with two files in it. If you were in the plaintext directory and typed cd .. that would take you one level up to the Documents directory. Doing the cd .. command one more time takes you up another level into your home directory where we started out.\nWarning\nWhen you delete things on the terminal, be certain you won’t ever need them again. Lastly, the terminal is intimidating but hopefully some of its mystery has been resolved now that you can navigate around it, list files out and make them all from the terminal. But, the terminal was made by computer scientists and engineers who were very technically capable and knew what they were doing, so when they typed in a command they knew what it meant and what it would do. Sometimes we can get ourselves into trouble on the terminal because we are not computer scientists and engineers and we don\u0026rsquo;t always know what we are doing. For example, the rm and del commands (in macOS and Windows respectively) delete files, and when you run them they don\u0026rsquo;t ask you to confirm that you really want to delete the file only_copy_of_my_thesis_do_not_delete_no_backups.tex and it doesn\u0026rsquo;t go to the Trash folder for you to restore it later. It just gets deleted. So use caution on the terminal but for the most part you can\u0026rsquo;t get into too much trouble.\nPrevious Next "},{"id":2,"href":"/docs/book/chapter-3/","title":"Project Organization","section":"Book","content":" Project Organization # Working with the terminal requires and instructs you about the file structure of your computer, knowledge of which is important for keeping things organized while you do your research and writing. Project organization refers to two separate and sometimes competing tasks: one is organizing the material you need to learn about the world in a way that is conceptually coherent and helpful to you. The second task is organizing actual computer files in such a way that they are accessible to you and to the software you are working with. These are distinct tasks and sometimes they compete with one another, as the first is meant to help you think better and the second is meant to help you do things faster. For example, it makes sense to keep distinct activities related to your research in different directories (sort of like keeping one notebook of notes for one class, and another notebook for another class). This organization is in part a matter of taste but there are certain organizing principles you should almost certainly avoid. For example, you could just have one directory that has all the files for your project in a flat structure, which makes remembering the paths to each file pretty simple (it would just be /Users/timothyelder/Documents/project-dir/FILENAMEHERE.txt). That makes everything accessible but doesn\u0026rsquo;t help to keep conceptually or practically separable parts of your project organized. On the other extreme, you could have a byzantine file structure, where edits to documents are organized by activity (such as having folders for interview_transcripts, field_notes, field_notes_reflections, interview_notes, draft_papers), and then subdirectories organized by the date in which the files in that directory were edited or created. That would certainly heep thins organized but fairly messy when it came time to put them altogether in a write-up.\nFinding a healthy compromise between the conceptual ordering of research material and the organization of computer files will be a matter of personal preference. With that said, I have a few principles that I find helpful and encourage you to emulate:\nEach project should have its own directory. # A project can be as small as a side-project that goes nowhere, or your dissertation or even your magnum opus. A rule of thumb that I use is that once something takes on a distinct character, and is relying upon more than 5 or so files to be coherent, it probably needs its own directory.\nEach Area of a Project should have its own Sub-Directory. # Again what constitutes an \u0026ldquo;Area\u0026rdquo; is ambiguous and you have to use your own judgement and the final rule of thumb is if you are making progress and getting things done. I usually end up having the same directories at the top of my project directory. These include the following:\ntimothyelder@MacBook-Pro project-dir % ls README.md research_log.md analysis data drafts figures memos misc scripts The two files at the top of this list are what are called Markdown files, a simple markup language. The README.md file includes an explanation of what the project is, what data it uses, and any required software while the research_log.md includes entries about what is going on in the project and my laments about the world and my own research. The rest are sub-directories that contain different parts of the project. In the data directory naturally is all my data (both quantitative and qualitative), while the drafts directory has all the drafts for the different formal pieces of writing coming from the project. Informal pieces of writing that are likely only to be seen by myself, my advisors, or collaborators are stored in the memos directory. figures includes all the images that are generated from the data or that might be included in papers, slides, etc.. Whether the project is purely qualitative or not, I inevitably write some scripts in R, python or shell and they go in the scripts folder and misc is a garbage can of all the things I don\u0026rsquo;t need now but am not confident I will never need again.\nHierarchical is Better than Horizontal # This goes hand in hand with the first two points but I want to emphasize that creating directories and sub-directories is helpful for keeping everything organized and that nesting directories is particularly helpful as it allows for more and more fine grained conceptual categorizations.\nLiteral is Better than Symbolic # There are only two hard things in Computer Science: cache invalidation and naming things.\n\u0026mdash; Phil Karlton\nWhen you are naming directories and files, it is always best to make things explicit. If the directory holds data call it data. If the directory contains images of documents from the Florida Office of Insurance Regulation in Tallahassee, call the directory images_florida_insurance_regulation. If the file is your dissertation latex file call it dissertation.tex. Choosing symbolic names, or anything cryptic makes parsing files difficult, particularly if you take a break from a project for a few weeks and need to get back to it.\nIMPORTANT NOTE: It is really important that when you are naming things, including files and directories, that you don\u0026rsquo;t use spaces or slashes in the names. This is because spaces and other characters like slashes are read by your computer as meaningful to how it reads different files. If you use them then errors will be raised and things won\u0026rsquo;t work.\nSome Examples # Here are some examples that exemplify and defy the paradigm I articulated above. All of these are examples from my own computer and time in graduate school. Figure 1 is the directory that contains all the files for my Qualifying Paper, my first independently researched and written paper from graduate school. You will note two things: I was doing all my writing with Word and didn\u0026rsquo;t abide by my rules about keeping different directories for different areas of the project. I do this a little bit having a drafts directory but I am not certain what the Print and Material directories are and the Writing Seminar Submission directory should probably be in drafts. Clearly, I was not being very thoughtful when it comes to how I organized my work, but this is a lot better than the directory in Figure 2.\nFigure 1: A poorly organized directory.\nThis is a directory for class prep for a sociology course I helped to design along with Profs. Jenny Trinitapoli and John Levi Martin. It is a complete mess with obscure directory names and files that are all at the top of the directory without much organization at all. Files are misspelled and there is a particularly egregious organizational error. I have two files that are indistinguishable in their name except for the suffix \u0026ldquo;.v2\u0026rdquo; being included in the file name. A short anecdote will heighten the importance of the naming conventions I articulate here.\nFigure 2: A very poorly organized directory.\nI have a colleague who has had a paper under review for a couple of years now due to a variety of factors related to the pandemic. On the second R\u0026amp;R, after months of working on other projects and getting ready for job talks, he went back to the project files to address the concerns of a particularly scrupulous Reviewer #3. The reviewer was asking that they re-run some analyses with a different method and so my colleague needed to go back and figure out how a few figures were generated and how the original analyses were specifically conducted. Opening the directory with his code he had endless files all with nearly indistinguishable names like:\npol_gss_multiimput.R pol_gss_multiimput_v2.R pol_gss_multiimput_v2_1.R pol_gss_multiimput_v2_2.R pol_gss_multiimput_v2_2_THIS_ONE.R pol_gss_multiimput_v2_2_No_REally_THIS_ONE.R pol_gss_multiimput_v2_2_No_REally_THIS_ONE_final.R He spent weeks and lots of tireless hours figuring out what was what. Instead of being like my friend, be more like me and do something like you see in Figure 3. This is a directory for a project that I am working on that includes lots of different scripts and data. Code for processing the data is kept separate from code for doing analyses and files are given explicit and non-redundant names. Certainly, this takes some amount of effort and energy to do and my project directories don\u0026rsquo;t always look like this while working on them, but it is worth cultivating good habits like this to do your research and writing. You will thank yourself later if you are ever in the same position as my poor sweet friend being harassed by pesky Reviewer #3.\nFigure 3: A more orderly directory.\nSummary # The wisdom then for organizing a directory in a way that successfully achieves the two different goals of organization (conceptual clarity and organizational productivity) can be condensed into:\nProject in Every Directory and a Directory for Every Project A Sub-Directory for every Area of a Project Hierarchical is better than horizontal organization Literal names are always favored over cryptic or symbolic names This is an area that is going to be much more dependent on your particular disposition to doing work, but at a certain point you will run up against the need to typeset documents and keep conceptually distinct areas actually digitally distinct, so if you don\u0026rsquo;t buy into my dogma that is fine, but adopt some other regular process of your own and stick to it as you do your work.\nPrevious Next "},{"id":3,"href":"/docs/book/chapter-4/","title":"Installation","section":"Book","content":" Installation # In this chapter I will guide you through a tedious and error prone step in the process of adopting plaintext software: installing all the bits and pieces that we are going to be using. When you use something like Word to write, all you need is Word, but the workflow we are going to be using relies upon different pieces of software that all work together. The good thing about this process is that you only have to do it once, and you won\u0026rsquo;t have to fiddle around with it endlessly.\n\\(\\LaTeX\\) # LaTeX, typically pronounced lay-tek or lah-tek, is a program for typesetting documents developed in the late 70s. It allows you to create really pretty documents and in particular, documents that include mathematical notation, figures, and tables. It can be used to typeset pretty much anything that needs typesetting.\nLaTeX is a pretty big program (around 5GBs) so you will need sufficient space on your hard drive to accommodate it. Depending on your system you will need to navigate to the install page and pick the version that is appropriate for your OS. Follow the installation instructions as you would any other program. This takes a little time due to its size.\npandoc # pandoc bills itself as a \u0026ldquo;universal document converter\u0026rdquo; and can be used to convert files into different formats. It was primarily developed to take documents written in Markdown and convert them into other, prettier formats. When combined with LaTeX, pandoc is a pretty powerful tool and we can use it to write in Markdown and then simultaneously convert that document into Word, PDF, Tex and HTML. It is this software that allows you to integrate your work with your colleagues that might not want to make the shift to a plain text workflow. Further, you can actually take in documents in a common format like Word and convert them to plain text.\nJust like for LaTeX above, navigate to the install page, and download the installer appropriate to your OS. pandoc is significantly smaller than LaTeX so you should not have an issue installing it.\nGit and Github # Git is a version control system which monitors a directory for changes. Think of it as the \u0026ldquo;Track Changes\u0026rdquo; option for a Word Document, but it tracks all the changes that occur to a group of files in a directory. Git is a program with a command line user interface so you will need to know your way around a terminal to use it. It also allows you to take advantage of open source software freely available on Github.\nGitHub is a website that hosts repositories of software, and if you sign up for a free account, acts like a cloud backup for your projects when they are in plaintext. All the software hosted on GitHub can be installed using git, and we will use it to install the templates we are going to be using for our documents. Install Git here.\nVisual Studio Code # One of the advantages of plain text is that you can open your files on any computer with the native programs installed on it from the factory. Every computer will have a basic text editor (macOS has TextEdit and Windows has Notepad++) and you could do everything we are going to do in this working group with the command line and one of these text editors (in fact you could do everything just with the command line). I highly recommend you install a more advanced text editor to do your work in.\nThere are a few excellent options to choose from including Sublime Text, Emacs, Atom, Notepad++ and RStudio. By far the best, and the one I use is Microsoft\u0026rsquo;s Visual Studio Code (or VS Code for short). The advantage to using a text editor regardless of which specific one you choose is that they highlight the syntax of whatever programming language you are writing in (including Markdown and LaTeX) enhancing the readability of your code to help writing and debugging. What more, you can typically run everything directly in the text editor so you never need to navigate away from a single window to get all your work done. You can run R, python, and keep your \\LaTeX document open all at the same time toggling between the different tasks as you need.\nYou should install VS Code as it is what I will be using to demonstrate how to use these plain text tools. You can install it from here. One of the nice things about VS Code is that it is extensible and has all sorts of extra features designed and implemented by users to help you get things done. One of the most important extensions is a LaTeX helper that we will be using when we do have to edit or write in LaTeX. After you install VS Code go ahead and install the extension here. There are also other helpful things for writing like a spell checker, a tool for auto-completing citations, a word counter, and support for your favorite (or not so favorite) statistical software. And don\u0026rsquo;t worry, installing these extensions is just a matter of clicking a button.\nDocument Templates, Class Files, and Fonts # There are a few more bells and whistles that you can install that will help you customize the look of documents. I have packaged these together for your use, but installing them will be different between macOS and Windows users. Instructions for both are included below.\nWhat are we installing? # We are going to be installing two collections of files: the first is a set of templates that we use to take in our raw plain text files and typeset them into beautiful PDF, HTML, and (to satisfy your Word dependent colleagues) Word Documents. These templates are what pandoc uses to make pretty output, but the templates themselves rely upon what are called LaTeX class and style files. These are the second collection of files we are installing. A quick preview of how to use this software: when you are done writing your document or you want to see what it ultimately will look like, you will go to your terminal and tell pandoc essentially \u0026ldquo;take my plain text Markdown file and make it into a PDF document\u0026rdquo; by typing in a few commands.\npandoc then converts the plain text data (the prose, tables, and figures you\u0026rsquo;ve written and created) into a PDF using LaTeX as the software to typeset it. It isn\u0026rsquo;t the case that LaTeX understands what Markdown is, but pandoc is super nifty and actually does an intermediate step that you don\u0026rsquo;t see where it converts your Markdown formatted plain text file into a LaTeX file before then typesetting it. Because these are, strictly speaking, two different processes which are done by two different pieces of software that are talking to one another, we need to install the templates into two different places on your computer, where LaTeX and pandoc, respectively, look for files.\nWe are going to be installing the two collections of templates for typesetting documents from my GitHub page using Git. This is actually a very straight forward and easy process but feels really overwhelming at first. All you need to do is open a terminal, cd to the place that we want the template files to be and tell Git to download them.\nThe first set of templates is in a repository called pandoc-templates and includes the templates that take in our Markdown files and convert them into LaTeX files. The second is a set of document class and style files that include all the details for how the software will typeset our documents with LaTeX. These can be found in the repository latex-custom-te. Finally, we will also install a template directory, pwg-template, which includes template Markdown and Make files which you can use for pretty much any document. Don\u0026rsquo;t worry about what these are yet, we will cover that shortly when we start using them.\nmacOS Ensure that the software you need is installed by running the following code in a terminal:\npandoc --version latex --version git --version Each of these commands, if the software is installed, will print out version information. If you the software is not installed then your terminal will say something like python: command not found or latex: command not found which means something has gone wrong and you will have to attempt to install the software again. NOTE: Go to the appendix below for learning out how to add to your PATH variable which could solve your problem for you.\nYou need to make sure that you create a directory and a sub-directory the custom LaTeX templates, class and style files. Run the following code (changing the paths for your machine):\nmkdir -p ~/Library/texmf/tex/latex This creates a directory where you install the custom class and style files for LaTeX. With those directories made you can install the templates into their proper locations with the following code (again, make sure you change the paths for your machine):\n# pandoc templatea cd ~ git clone https://github.com/TimothyElder/pandoc-templates/ mv pandoc-templates .pandoc # Class files cd ~/Library/texmf/tex/latex git clone https://github.com/TimothyElder/latex-custom-te/ # starter projects cd ~/Documents git clone https://github.com/TimothyElder/pwg-template Next there are a few fonts that you might want to have that are referenced in some of these templates. You can download and install them using this code:\ncd ~/Documents git clone https://github.com/TimothyElder/open-fonts.git cd open-fonts chmod +x install_fonts.sh ./install_fonts.sh Cross-Referencing and Text Editors # You will likely be mounting an argument or writing in an area of your discipline that requires you reference past works. So you will need a bibliography, and you will probably want to include tables, figures and diagrams that you will reference in the body of your text. It is a pain having to format a bibliography yourself or to number each table and figure. What more, it is particularly annoying when you decide to rearrange your paper and then have to rearrange the number of all the tables and figures in the text. You wll also want a nice interface to actually write and code in.\npandoc-xnos # pandoc-xnos is for cross-referencing figures, tables, equations, sections and pretty much anything else that can be written in a Markdown file. This helps for automatically handling the labelling of different parts of your document, so you can move the position of a figure or table or equations without having to change the reference to it in the body of your text. Install with:\npip install pandoc-fignos pandoc-eqnos pandoc-tablenos \\ pandoc-secnos --user If you get an error that pip can\u0026rsquo;t be found, make sure you have python installed on your computer, which should be the case for macOS and Linux users. You then use this suite of helper functions in documents with some conventions that we will cover in Chapter 4.\nWindows Ensure that the software you need is installed by running the following code in a terminal:\npandoc --version latex --version git --version Each of these commands, if the software is installed, will print out version information. If you the software is not installed then your terminal will say something like python: command not found or latex: command not found which means something has gone wrong and you will have to attempt to install the software again. There is help below doing this.\nYou need to make sure that you create a directory and a subdirectory the custom LaTeX templates, class and style files. Run the following code (changing the paths for your machine):\nmkdir C:\\texmf\\tex\\latex This creates a directory where you install the custom class and style files for LaTeX. With those directories made you can install the templates into their proper locations with the following code (make sure to change the paths to match your computer):\ncd %HOMEPATH%\\AppData\\Roaming git clone https://github.com/TimothyElder/pandoc-templates.git ren \u0026#34;pandoc-templates\u0026#34; \u0026#34;.pandoc\u0026#34; cd C:\\texmf\\tex\\latex git clone https://github.com/TimothyElder/latex-custom-te.git cd %HOMEPATH%\\Documents git clone https://github.com/TimothyElder/pwg-template Windows has an extra step which includes you adding a directory to your LaTeX installation so it knows where to look. To do that do the following steps:\nStart MiKTeX Console (either find it in the Start menu or search for it in the search bar) and open the Settings page. Click the Directories tab. Click the Add button and browse to the texmf root directory created earlier (C:\\texmf). Make sure that you change all the paths to match your machine otherwise you get lots of errors and nothing will work. If you did everything above right, Congratulations! You are one step closer to making beautiful and reproducible documents in plain text.\nThere are a few key pieces of software that Windows does not come installed with that you will need to take the extra step of installing.\nwinget Package Manager # winget is a command line based package manager for Windows that helps with installing other pieces of software. It is part of App Installer which you can download and install here.\nMake # Make is a tool that handles the creation of files from some source material and is super helpful when you need to repetitively run the same programs in the same order over and over again, such as when you are editing and typesetting your next paper. With winget installed, Make is super easy to get, just run this line of code in a command prompt on your computer:\nwinget install GnuWin32.Make Python # Python is a modern general computing language that is very common in the sciences and social sciences. Though we are not going to be actively using it in the working group, some of the software that we use relies upon it. It doesn\u0026rsquo;t take up much space and can be downloaded and installed here.\nAlternatively, you can install python with winget using the following command:\nwinget install python If you do use winget you may have to update your PATH variable manually, so the command prompt can find it (See below for help adding to PATH in Windows).\npandoc-xnos # pandoc-xnos is for cross-referencing figures, tables, equations, sections and pretty much anything else that can be written in a Markdown file. This helps for automatically handling the labelling of different parts of your document, so you can move the position of a figure or table or equations without having to change the reference to it in the body of your text. Install with:\npip install pandoc-fignos pandoc-eqnos pandoc-tablenos \\ pandoc-secnos --user And then use it with --filter pandoc-xnos as a flag for the pandoc command in your Makefile recipe. NOTE: Whenever using pandoc-fignos or pandoc-xnos, they need to be invoked before the --citeproc filter as they both use the @ symbol to identify references and they will get confused otherwise.\nIf you did everything above right, Congratulations! You are one step closer to making beautiful and reproducible documents in plain text.\nAdding to PATH # A lot of the work of typesetting is going to be taking place in the terminal and sometimes you will get an annoying an inexplicable error like \u0026ldquo;this software is not on the PATH\u0026rdquo; or \u0026ldquo;I can\u0026rsquo;t find this software\u0026rdquo;, which means that your computer is searching the location where executable programs are located (the PATH variable) but it is not finding whatever software you are telling it to run. Why this happens is a mystery. Sometimes the software has installed onto your computer, but the terminal program doesn\u0026rsquo;t know where to look for where the programs are installed. I know this is a little confusing but here is a quick lesson. When you invoke a command on the terminal the first thing the computer does is check an index of the available software, which it does by examining what is called the PATH variable. If it finds whatever you are asking it to use like pandoc or LaTeX or R or python or whatever, it runs the command. If it doesn\u0026rsquo;t find what you tell it to look for it returns an error.\nBefore giving up completely try updating the PATH variable so the terminal knows where the software is. Depending on what specific command line or terminal you are using the instructions are slightly different but they will be pretty portable across platforms, and operating systems. This is one of those things that you really only have to learn once and then you\u0026rsquo;ll be able to improvise a lot better later. To find out where the files for a program are on macOS, run the which command followed by what your looking for, such as which pandoc, and it will print the path to where the executables of these files are installed. Sometimes the data files for a program get installed onto our computer without the PATH variable getting updated to tell the terminal that the software is installed.\nmacOS There are two different kinds of terminals on macOS. Run this line of code in your terminal and it will tell you which terminal you are using: echo $0. Check below for relevant information about how to add to the path:\nzsh # To add a directory to your path in zsh:\nRun path+=('/path/to/dir') in an open terminal where the path is to where the executables for the program are. For me pandoc is located in /usr/local/bin/pandoc and LaTeX is in /Library/TeX/texbin/latex. Then run export PATH in the same terminal. Restart the terminal and check that it works by typing in latex --version or pandoc --version or whatever else was giving you trouble. bash # Remember when we learned how to use vim from the command line and what a hidden file was? Well now that knowledge will actually come in handy. To add something to the PATH in bash you need to edit your .bash_profile which is located in your home directory. The home directory is where your terminal opens up and is located at /Users/your-user-name.\nOpen the .bash_profile file in your home directory (for example, /Users/your-user-name/.bash_profile) in vim by running vim .bas_profile in your home directory in a terminal. Add export PATH=\u0026quot;your-dir:$PATH\u0026quot; to the last line of the file, where your-dir is the directory you want to add. Save the .bash_profile file by exiting vim with :wq. Restart your terminal. Windows The first step depends which version of Windows you\u0026rsquo;re using: If you\u0026rsquo;re using Windows 8 or 10, press the Windows key, then search for and select \u0026ldquo;System (Control Panel)\u0026rdquo;. If you\u0026rsquo;re using Windows 7, right click the \u0026ldquo;Computer\u0026rdquo; icon on the desktop and click \u0026ldquo;Properties\u0026rdquo;. Click \u0026ldquo;Advanced system settings\u0026rdquo;. Click \u0026ldquo;Environment Variables\u0026rdquo;. Under \u0026ldquo;System Variables\u0026rdquo;, find the PATH variable, select it, and click \u0026ldquo;Edit\u0026rdquo;. If there is no PATH variable, click \u0026ldquo;New\u0026rdquo;. Add your directory to the beginning of the variable value followed by ; (a semicolon). For example, if the value was C:\\Windows\\System32, change it to C:\\Users\\Me\\bin;C:\\Windows\\System32. Click \u0026ldquo;OK\u0026rdquo;. Restart your terminal. Summary # Congratulations! You have actually just done a lot of the work of getting started using plain text for your research and writing. This is an onerous task and you should be commended for your effort. If you have managed to get this far then you are likely somewhat invested in adopting the plain text paradigm but if this effort has inspired skepticism or reticence about diving deeper I think it is important to note that installing the software is something that you only have to do once on any given computer. So you won\u0026rsquo;t have to endlessly tinker with things. Once these tools are installed they are very dependable\nPrevious Next "},{"id":4,"href":"/docs/book/chapter-5/","title":"Document Composition","section":"Book","content":" Using LaTeX, Markdown, pandoc # Now that you are familiar with the Terminal and have installed the software we are going to be using you are ready to begin addressing the core competencies of working with plain text software for your research and writing. The essential workflow that we are adopting here is writing in Markdown, a simple markup langauge with a few extra bells and whistles, and then using the pandoc program to convert these into HTML, PDF, ad Word files. To establish why this is the appropriate workflow to adopt I will outline what markup langauges are and how they work, as well as the conventions used in LaTeX and then Markdown.\nLaTeX # Though you won\u0026rsquo;t need to write with LaTeX you will need to know what a LaTeX document looks like and how to work with one. Once you have a feel for the LaTeX document setup, you will be able to create your own document templates for pretty much any use. For example, I have LaTeX templates for memos, letters with my contact and university affiliation, article drafts, class handouts, single columned general prose, double column general prose, and even the documentation you are looking at right now was created using this workflow.\nLaTeX at bottom is something called a markup language, or a means of encoding text where different characters are used to designate structure, formatting and style. In a Word document, all that appears on your screen is the text you are composing, and its style and structure are handled by the program. If you want to change the type face, or the margin, or the line spacing, you go to the top bar and click through menus to change the style. There is a lot of behind the scenes action going in a Word file as the means by which document is styled is hidden from you. In a markup language, all that information is present in the document itself as you explicitly declare the style and structure using the conventions of that particular language. To give a specific example, where in Word you would click the italics button to make text italics, in a markup language like LaTeX you wrap the text you want to be italicized with the command \\textit{}. There is a lot more that goes into it, and diving into practical examples will help to give you an idea of how markup languages work and LaTeX in particular.\nLaTeX is notorious for being unintuitive and hard to pickup and is the bane of any graduate students existence when they take STATS102 for the first time. The thing about LaTeX is that it is complicated and unintuitive but there are only a few complicated and unintuitive conventions to understand before LaTeX seems a lot clearer. Below is an example of the simplest LaTeX document you can make, and examining it helps us to begin to understand how markup langauges are different from something like Word and what LaTeX in particular looks like:\n\\documentclass{article} \\begin{document} Hello World! \\end{document} In LaTeX, anything that begins with a backlash \u0026ldquo;\\\u0026rdquo; is a command, and commands usually have brackets at the end to take in some arguments. You can think of working with a LaTeX document like working in narrower and narrower environments. In any file, you first need to declare the kind of document you are creating with \\documentclass and then declare the beginning of the document with \\begin{document}. The \\documentclass command creates the underlying environment with some associated styles in which you will be composing prose, before the \\begin{document} command creates the environment in which the prose and content of your document go.\nThe convention of open and closing environments applies to most features of a LaTeX document. We open a document with \\begin{docuemnt} declare the end of the document with \\end{document} while figures or images in your document need to be between the commands \\begin{figure} and \\end{figure} and the same is true of tables, which go between\\begin{table} and \\end{table}. The body of your document can be 2 words or 200 pages worth of content, and I simply use the \u0026ldquo;Hello World!\u0026rdquo; document as an example. You could make that document your self in a matter of seconds.\nThe \\documentclass command specifies how the document will be formatted and loads a set of default settings. There are a variety of options to choose from depending on your need including article, book, report, slides, and letter. A very common document class that you\u0026rsquo;ll see is memoir which is used for general prose writing. This command can take in arguments to further specify the formatting of your document and usually includes things like the paper size, whether it is one or two sided, font size, line spacing, among many other things. Here is an example where we are setting a document to have 11pt font, to be one sided and use formatting for an article type document, using all the bells and whistles from the memoir document class:\n\\documentclass[11pt,article,oneside]{memoir} Another convention in LaTeX is to declare metadata and other information in the preamble of the document. The preamble is the part of the file that is above the \\begin{document} command. In the above example the preamble includes only the \\documentclass command but you can do a lot more here including telling LaTeX about all the formatting of your document as well as loading any packages that you will be using to create your document. Also, you can declare metadata in the preamble that then will appear in your document such as the author name, title of the document, abstract, date, and pretty much anything else. Here is another simple example:\n\\documentclass{article} \\title{My First \\LaTeX Document} \\date{1/1/1597} \\author{William Shakespeare} \\begin{document} \\maketitle Hello World! \\end{document} The \\title, \\date and \\author commands are components of the \\maketitle command that you can invoke after you begin the document to create a well formatted title block for your document. The above code renders a document that looks like Figure 1.\nFigure 1: A document made with LaTeX.\nAs mentioned above, the body of the document (here it is just \u0026ldquo;Hello World!\u0026rdquo;) can be as long as you want and encompass all sorts of different things that are particularly helpful to social scientists who write documents that use data to make an argument. For example, and we will cover all of these shortly, you can include tables, figures, citations, theorems, proofs, equations, diagrams, code blocks, and any number of other information that you want typeset in a beautiful way.\nTo summarize here are the important parts for understanding a LaTeX document and markup languages in general. Remember to:\nDeclare the beginnings and ends of environments in which different formatting or content is located. Include metadata and package calls in the preamble of the document. Render formatting using commands like \\textit{} or \\textbf{} Learning the exact conventions of LaTeX is a task that is worth exploring. If you want to be a truly autonomous plain text writer and researcher, you will have to learn more about LaTeX so you can create your own templates. But, if you want to stick to thinking and writing then you\u0026rsquo;ll need to know more about the accessible alternative to LaTeX: Markdown.\nMarkdown # Markdown is a much easier to learn and intuitive markup language than LaTeX and is becoming more and more ubiquitous. In Markdown, italicized text is created by wrapping the text in *asterisks*, while bold is done with **two asterisks**. There are certain limitations to Markdown; for instance there is no underlining in Markdown so you have to get by with the other ways of styling text. Here is an example of some text in Markdown before being typeset:\n# Header 1 You might have some introductory comments ## Sub-Header Some text with different styling such as *italics* and **bold**. Remember there is no underlining which is old fashioned anyways, but you can insert [Hyperlinks](https://en.wikipedia.org/wiki/Hyperlink) and create tables: | Movie | Actor | |----------------|---------------| | Apocalypse Now | Marlon Brando | | Wizard of Oz | Judy Garland | | Sound of Music | Julie Andrews | There are also other important aspects of academic writing.^[Like footnotes that are rendered at the footer of the page in which they appear.] ![Here is a figure inserted into a Markdown file.](figures/healy_plaintext_vis.png) The good thing about Markdown is that it is much easier to use than LaTeX so instead of messing around with a document preamble, document classes, and style files you can get straight to writing your document. I am not going to cover all the different Markdown conventions in this documentation but you can find them here. Markdown is pretty straight forward but you will still want to take advantage of all the fancy features of LaTeX while maintaining the usability and ease of Markdown. Luckily, someone already thought up this idea and created the program pandoc.\npandoc # pandoc is a command line based program that allows you to convert files between different file formats. It is a pretty powerful program because it will take the markup conventions from one format and translate them into another. So, when you write your next article in Markdown and really emphasize some part (\u0026ldquo;And to reiterate again, it is the Lumpenproletariat that ultimately must be motivated by a vanguard party to seize the means of production from the Petty bourgeoisie.\u0026rdquo;) pandoc will convert the text surrounded by *asterisks* (which indicates italics) and converts them to an \\textit{} command. pandoc is the key link in the workflow that allows us to convert our simple Markdown files into LaTeX files and then into PDFs and how we are able to accommodate the different resources we need for academic writing, like bibliographies, footnotes, tables, figures, and diagrams.\nThe basic usage of pandoc looks like the following:\npandoc my_doc.md -o my_doc.pdf On the left, directly after pandoc is the Markdown file that we want to convert to a PDF file. The -o flag indicates that the my_doc.pdf file is in fact the intended output document from the input. That is pretty simple, but so too will be the output PDF. Compare the line above to this one:\npandoc my_doc.md -o my_doc.pdf --from=Markdown --template=/Users/timothyelder/.pandoc/templates/eisvogel.latex --listings --filter pandoc-xnos That is the command for rendering the document your are looking at right now. It does the same thing that we saw above, specifying an input file and then an output file, but it includes all sorts of extra flags that indicate how to handle different attributes of your document and the proper formatting for the output. The --from= flag makes it perfectly explicit to the software what the input format is (in this case it is Markdown), while the --template= flag tells the software where to look and which template to use when rendering the output. The final two flags (--listings and --filter pandoc-xnos) indicate the style for code blocks (those shaded areas that display computer code throughout this document) and how to cross reference different parts of the document respectively.\nIt is important to get clear on what is actually going on when we use the pandoc command to create a PDF. What we are doing can be seen in Figure 2.\nFigure 2: Writing in Markdown and typesetting into a pdf with a tex intermediate step.\nWe write our files using the conventions of the Markdown format (indicated by the .md file extension) and then use pandoc to typeset these into a PDF. pandoc is not a typesetting software itself per se but relies upon LaTeX to typeset into PDF. When you invoke pandoc to create a PDF, pandoc performs a quiet intermediate step where it creates a LaTeX copy of the Markdown document (the .tex file in Figure 2) and typesets that into a PDF by invoking the LaTeX program. pandoc is super smart, and understands how to translate the conventions of one markup language into another, and that is how we are able to write in Markdown (with all its simplicity and speed) while still taking advantage of all the power of LaTeX.\nWe are able to add a few bells and whistles to pandoc to define the specific formatting of the document. We do this partly by manipulating the characters and conventions in our document directly, but also outside our document, by invoking templates and style files that you can install. This can be seen in Figure 3.\nFigure 3: There are a few extra little dependencies.\nDocument Composition with Markdown # In this section, I want to explain how you put together the various pieces that we have up to this point only been reading about. We are going to be covering:\nInserting figures Creating tables. Including math, both numbered equations and inline math Writing the Document # This part is pretty self explanatory. You type characters, which form words, words create phrases and sentences, and you keep doing that until you have something that looks like a defensible argument. Once you have that, you put in all the nifty evidence that you have discovered to support your argument and there are all sorts of things that go into that.\nHeaders and Metadata # Where in a LaTeX document you put metadata such as the author name, date, title, abstract, etc. in the preamble of the document, in Markdown you use what is called a YAML (yam-mul) header. Since you don\u0026rsquo;t want the metadata being represented in the document as it is, you need to contain it in special characters (sort of like how you create an environment in LaTeX with \\begin{} and \\end{}). Three dashes opens and closes your YAML metadata header like this:\n--- title: My First Markdown Paper author: Timothy Elder date: February 17th, 2023 --- The information that the YAML header contains is arbitrary though there are a few standard entries like \u0026ldquo;author\u0026rdquo;, \u0026ldquo;title\u0026rdquo;, \u0026ldquo;date\u0026rdquo;, and \u0026ldquo;abstract\u0026rdquo;. Because pandoc translates your Markdown document into LaTeX before typesetting, you have the full arsenal of LaTeX options available to you, which means you can change the font, margins, headers and footers among many many others. Too many to cover here but you can review the full set of options in the pandoc documentation here (see the section \u0026ldquo;Variables for LaTeX\u0026rdquo;).\nFigures # A figure or image in a Markdown file can be included with the following notation:\n![Here is where you put your caption.](/absolute/path/to/image.png){@fig:example-crossref-label} The image will render on the page around where you insert the line but you will not have exact control over it unless you go edit the intermediate .tex file. In our templates we specify some options that help images render in an attractive way and LaTeX uses an algorithm for image placements when not manually placed. Instead of manually numbering figures and referencing them in the body of your paper, you assign them a label, which follows the call to the image, wrapped in curly brackets with the @fig: prefix. Rather than having to keep track of how your figures are numbered, when you want to reference the figure in the body of your paper, you do so like this:\nHere I am explaining the really impressive figure that I made that is going to definitively demonstrate some strong association between two variables. This can be seen in Figure @fig:example-crossref-label. This means of cross-referencing figures is really convenient especially when you decide to reorder your paper, and suddenly figure #5 is where figure #1 was and all the labels would have to be manually changed if you were using something like Word. NOTE: Whenever using pandoc-xnos, include it with --filter pandoc-xnos as a flag for the pandoc command in.\nTables # Tables are pretty easy in Markdown and can be styled different ways. This is a pretty bare bones table:\nTable 1: Some information about Star Wars characters. Character Height (cm) Mass (kg) Homeworld Species Han Solo 180 80 Corellia Human Wedge Antilles 170 77 Corellia Human Yoda 66 17 NA Yoda's species Ackbar 180 83 Mon Cala Mon Calamari Mace Windu 188 84 Haruun Kal Human This table is created with the following code:\n------------------------------------------------------------------------ Character Height (cm) Mass (kg) Homeworld Species ---------------- ------------- ----------- ------------ ---------------- Han Solo 180 80 Corellia Human Wedge Antilles 170 77 Corellia Human Yoda 66 17 NA Yoda\u0026#39;s species Ackbar 180 83 Mon Cala Mon Calamari Mace Windu 188 84 Haruun Kal Human ------------------------------------------------------------------------ Table: Some information about Star Wars characters. {#tbl:id} You will be able to output from most statistical software into the Markdown format or LaTeX. And tables in Markdown can also be labeled, just like figures, so you can reference them without keeping track of what order they appear in.\nMath # If you are a quantitative scholar and need to describe your modeling strategy you can do that in Markdown. This requires a bit of knowledge of LaTeX: as mentioned above, pandoc converts your Markdown to LaTeX before typesetting, you can use LaTeX conventions when we really need to. This is such an instance. So if you want to explain to someone the standard deviation of a population you would write the formula using LaTeX math commands (\\sigma, \\sum, \\frac, \\bar, exponents and subscripts, etc.) on its own line and wrap it in double dollar signs ($$) like this:\n$$ \\sigma = \\sqrt{\\frac{ \\sum (x_i - \\bar{x})^2 } {N - 1}} $$ which renders your math beautifully:\n\\[\\sigma = \\sqrt{\\frac{ \\sum (x_i - \\bar{x})^2 } {N - 1}} \\] You can also insert math inline with your text \\(\\mu = \\frac{ \\sum_{i=1}^{n} x_i} {n}\\) using single dollar signs in line with the rest of your text, like:\nWhen $a \\ne 0$, there are two solutions to $(ax^2 + bx + c = 0)$ and they are $x = {-b \\pm \\sqrt{b^2-4ac} \\over 2a}$. Make # It can be very annoying to continually run the same lines of code over and over again, when you are nearing the completion of working on some document, particularly if you are obsessive and neurotic and messing with some minor part of a paper that you want to get perfect. A very helpful resource that computer scientists thought up was to create a system for handling running code called Make. Make automates the process of, for lack of a better word, making things. This is somewhat advanced when it comes to typesetting documents so if you want to skip this part or skim that is totally fine. I will note that this tool will be particularly helpful if you are a quantitative scholar and have different scripts that handle the creation of data, figures, or tables etc. etc.\nMake is particularly powerful because it has a system for checking whether or not a given output file needs to be changed given some change in the input file. For example, say you have a recipe (recipes in Make are the different commands that you want it to run) that creates your document that looks like this:\n## Location of Pandoc support files. PREFIX = /Users/timothyelder/.pandoc ## Location of your working bibliography file BIB = /Users/timothyelder/Documents/bibs/socbib-pandoc.bib ## CSL stylesheet (located in the csl folder of the PREFIX directory). CSL = asa dissertation.pdf: dissertation.md pandoc -f --pdf-engine=xelatex --template=$(PREFIX)/templates/ucetd.template --top-level-division=chapter --filter pandoc-xnos --citeproc --bibliography=$(BIB) dissertation.md -o dissertation.pdf To typeset the dissertation.pdf file given the recipe in the Makefile, you would simply type into the terminal with the Makefile, make dissertation.pdf and the recipe runs. Make will check to see if any changes have been made in the name of the prerequisite file (the dissertation.md file) which is used to make the PDF. If no change has been made to the Markdown file, then Make will let you know and say make: Nothing to be done for 'dissertation.pdf'.\nWhen you run \u0026ldquo;pdf\u0026rdquo;, a couple of python scripts get run in a particular order, then an R script, and then a pandoc line runs and then a shell command. That would be a lot of keystrokes on your own but make does it auto-magically. This is actually a recipe that I have because I have a project where we generate all the data from optical character recognition of JPEGs, and then carving up big plaintext files with regular expressions. Sometimes the underlying data changes because we notice there is some error in the plaintext file and we have to regenerate a whole bunch of CSVs from the plaintext files. What make does is it checks the various pieces of data that you are asking it to use and that you want it to make, and checks whether or not they have changed at all since you last ran Make, and it only runs precesses to update pieces of data as needed. So if you keep running Make without changing anything it will tell you \u0026ldquo;nothing to update\u0026rdquo;.\nPrevious Next "},{"id":5,"href":"/posts/my_post/","title":"Columns Text","section":"Blog","content":" Acerbo datus maxime # Astris ipse furtiva # Est in vagis et Pittheus tu arge accipiter regia iram vocatur nurus. Omnes ut olivae sensit arma sorori deducit, inesset crudus, ego vetuere aliis, modo arsit? Utinam rapta fiducia valuere litora adicit cursu, ad facies Suis quot vota # Ea furtique risere fratres edidit terrae magis. Colla tam mihi tenebat: miseram excita suadent es pecudes iam. Concilio quam velatus posset ait quod nunc! Fragosis suae dextra geruntur functus vulgata. Tempora nisi nunc # Lorem markdownum emicat gestu. Cannis sol pressit ducta. Est Idaei, tremens ausim se tutaeque, illi ulnis hausit, sed, lumina cutem. Quae avis sequens!\nvar panel = ram_design; if (backup + system) { file.readPoint = network_native; sidebar_engine_device(cell_tftp_raster, dual_login_paper.adf_vci.application_reader_design( graphicsNvramCdma, lpi_footer_snmp, integer_model)); } Locis suis novi cum suoque decidit eadem # Idmoniae ripis, at aves, ali missa adest, ut et autem, et ab?\n"},{"id":6,"href":"/docs/book/hidden/","title":"Hidden","section":"Book","content":" This page is hidden in menu # Quondam non pater est dignior ille Eurotas # Latent te facies # Lorem markdownum arma ignoscas vocavit quoque ille texit mandata mentis ultimus, frementes, qui in vel. Hippotades Peleus pennas conscia cuiquam Caeneus quas.\nPater demittere evincitque reddunt Maxime adhuc pressit huc Danaas quid freta Soror ego Luctus linguam saxa ultroque prior Tatiumque inquit Saepe liquitur subita superata dederat Anius sudor Cum honorum Latona # O fallor in sustinui iussorum equidem. Nymphae operi oris alii fronde parens dumque, in auro ait mox ingenti proxima iamdudum maius?\nreality(burnDocking(apache_nanometer), pad.property_data_programming.sectorBrowserPpga(dataMask, 37, recycleRup)); intellectualVaporwareUser += -5 * 4; traceroute_key_upnp /= lag_optical(android.smb(thyristorTftp)); surge_host_golden = mca_compact_device(dual_dpi_opengl, 33, commerce_add_ppc); if (lun_ipv) { verticalExtranet(1, thumbnail_ttl, 3); bar_graphics_jpeg(chipset - sector_xmp_beta); } Fronde cetera dextrae sequens pennis voce muneris # Acta cretus diem restet utque; move integer, oscula non inspirat, noctisque scelus! Nantemque in suas vobis quamvis, et labori!\nvar runtimeDiskCompiler = home - array_ad_software; if (internic \u0026gt; disk) { emoticonLockCron += 37 + bps - 4; wan_ansi_honeypot.cardGigaflops = artificialStorageCgi; simplex -= downloadAccess; } var volumeHardeningAndroid = pixel + tftp + onProcessorUnmount; sector(memory(firewire + interlaced, wired)); "},{"id":7,"href":"/docs/shortcodes/buttons/","title":"Buttons","section":"Shortcodes","content":" Buttons # Buttons are styled links that can lead to local page or external link.\nExample # {{\u0026lt; button relref=\u0026#34;/\u0026#34; [class=\u0026#34;...\u0026#34;] \u0026gt;}}Get Home{{\u0026lt; /button \u0026gt;}} {{\u0026lt; button href=\u0026#34;https://github.com/alex-shpak/hugo-book\u0026#34; \u0026gt;}}Contribute{{\u0026lt; /button \u0026gt;}} Get Home Contribute "},{"id":8,"href":"/docs/shortcodes/columns/","title":"Columns","section":"Shortcodes","content":" Columns # Columns help organize shorter pieces of content horizontally for readability.\n{{\u0026lt; columns \u0026gt;}} \u0026lt;!-- begin columns block --\u0026gt; # Left Content Lorem markdownum insigne... \u0026lt;---\u0026gt; \u0026lt;!-- magic separator, between columns --\u0026gt; # Mid Content Lorem markdownum insigne... \u0026lt;---\u0026gt; \u0026lt;!-- magic separator, between columns --\u0026gt; # Right Content Lorem markdownum insigne... {{\u0026lt; /columns \u0026gt;}} Example # Left Content # Lorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat stringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa protulit, sed sed aere valvis inhaesuro Pallas animam: qui quid, ignes. Miseratus fonte Ditis conubia. Mid Content # Lorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat stringit, frustra Saturnius uteroque inter! Right Content # Lorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat stringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa protulit, sed sed aere valvis inhaesuro Pallas animam: qui quid, ignes. Miseratus fonte Ditis conubia. "},{"id":9,"href":"/docs/shortcodes/details/","title":"Details","section":"Shortcodes","content":" Details # Details shortcode is a helper for details html5 element. It is going to replace expand shortcode.\nExample # {{\u0026lt; details \u0026#34;Title\u0026#34; [open] \u0026gt;}} ## Markdown content Lorem markdownum insigne... {{\u0026lt; /details \u0026gt;}} {{\u0026lt; details title=\u0026#34;Title\u0026#34; open=true \u0026gt;}} ## Markdown content Lorem markdownum insigne... {{\u0026lt; /details \u0026gt;}} Title Markdown content # Lorem markdownum insigne\u0026hellip; "},{"id":10,"href":"/docs/shortcodes/expand/","title":"Expand","section":"Shortcodes","content":" Expand # Expand shortcode can help to decrease clutter on screen by hiding part of text. Expand content by clicking on it.\nExample # Default # {{\u0026lt; expand \u0026gt;}} ## Markdown content Lorem markdownum insigne... {{\u0026lt; /expand \u0026gt;}} Expand ↕ Markdown content # Lorem markdownum insigne\u0026hellip; With Custom Label # {{\u0026lt; expand \u0026#34;Custom Label\u0026#34; \u0026#34;...\u0026#34; \u0026gt;}} ## Markdown content Lorem markdownum insigne... {{\u0026lt; /expand \u0026gt;}} Custom Label ... Markdown content # Lorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat stringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa protulit, sed sed aere valvis inhaesuro Pallas animam: qui quid, ignes. Miseratus fonte Ditis conubia. "},{"id":11,"href":"/docs/shortcodes/hints/","title":"Hints","section":"Shortcodes","content":" Hints # Hint shortcode can be used as hint/alerts/notification block.\nThere are 3 colors to choose: info, warning and danger.\n{{\u0026lt; hint [info|warning|danger] \u0026gt;}} **Markdown content** Lorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat stringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa {{\u0026lt; /hint \u0026gt;}} Example # Markdown content\nLorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat stringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa Markdown content\nLorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat stringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa Markdown content\nLorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat stringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa "},{"id":12,"href":"/docs/shortcodes/katex/","title":"Katex","section":"Shortcodes","content":" KaTeX # KaTeX shortcode let you render math typesetting in markdown document. See KaTeX\nExample # {{\u0026lt;/* katex [display] [class=\u0026#34;text-center\u0026#34;] */\u0026gt;}} f(x) = \\int_{-\\infty}^\\infty\\hat f(\\xi)\\,e^{2 \\pi i \\xi x}\\,d\\xi {{\u0026lt;/* /katex */\u0026gt;}} \\[f(x) = \\int_{-\\infty}^\\infty\\hat f(\\xi)\\,e^{2 \\pi i \\xi x}\\,d\\xi\\] Display Mode Example # Here is some inline example: \\(\\mu = \\frac{ \\sum_{i=1}^{n} x_i} {n}\\) , rendered in the same line. And below is display example, having display: block \\[f(x) = \\int_{-\\infty}^\\infty\\hat f(\\xi)\\,e^{2 \\pi i \\xi x}\\,d\\xi\\] Text continues here.\n"},{"id":13,"href":"/docs/shortcodes/mermaid/","title":"Mermaid","section":"Shortcodes","content":" Mermaid Chart # MermaidJS is library for generating svg charts and diagrams from text.\nOverride Mermaid Initialization Config\nTo override the initialization config for Mermaid, create a mermaid.json file in your assets folder!\nExample # {{\u0026lt;/* mermaid [class=\u0026#34;text-center\u0026#34;]*/\u0026gt;}} stateDiagram-v2 State1: The state with a note note right of State1 Important information! You can write notes. end note State1 --\u0026gt; State2 note left of State2 : This is the note to the left. {{\u0026lt;/* /mermaid */\u0026gt;}} stateDiagram-v2 State1: The state with a note note right of State1 Important information! You can write notes. end note State1 --\u003e State2 note left of State2 : This is the note to the left. "},{"id":14,"href":"/docs/shortcodes/section/","title":"Section","section":"Shortcodes","content":" Section # Section renders pages in section as definition list, using title and description. Optional param summary can be used to show or hide page summary\nExample # {{\u0026lt; section [summary] \u0026gt;}} First Page First page # Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. Second Page Second Page # Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat. Duis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum. "},{"id":15,"href":"/docs/shortcodes/section/first-page/","title":"First Page","section":"Section","content":" First page # Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\nDuis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.\n"},{"id":16,"href":"/docs/shortcodes/section/second-page/","title":"Second Page","section":"Section","content":" Second Page # Lorem ipsum dolor sit amet, consectetur adipiscing elit, sed do eiusmod tempor incididunt ut labore et dolore magna aliqua. Ut enim ad minim veniam, quis nostrud exercitation ullamco laboris nisi ut aliquip ex ea commodo consequat.\nDuis aute irure dolor in reprehenderit in voluptate velit esse cillum dolore eu fugiat nulla pariatur. Excepteur sint occaecat cupidatat non proident, sunt in culpa qui officia deserunt mollit anim id est laborum.\n"},{"id":17,"href":"/docs/shortcodes/tabs/","title":"Tabs","section":"Shortcodes","content":" Tabs # Tabs let you organize content by context, for example installation instructions for each supported platform.\n{{\u0026lt; tabs \u0026#34;uniqueid\u0026#34; \u0026gt;}} {{\u0026lt; tab \u0026#34;MacOS\u0026#34; \u0026gt;}} # MacOS Content {{\u0026lt; /tab \u0026gt;}} {{\u0026lt; tab \u0026#34;Linux\u0026#34; \u0026gt;}} # Linux Content {{\u0026lt; /tab \u0026gt;}} {{\u0026lt; tab \u0026#34;Windows\u0026#34; \u0026gt;}} # Windows Content {{\u0026lt; /tab \u0026gt;}} {{\u0026lt; /tabs \u0026gt;}} Example # MacOS MacOS # This is tab MacOS content.\nLorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat stringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa protulit, sed sed aere valvis inhaesuro Pallas animam: qui quid, ignes. Miseratus fonte Ditis conubia.\nLinux Linux # This is tab Linux content.\nLorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat stringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa protulit, sed sed aere valvis inhaesuro Pallas animam: qui quid, ignes. Miseratus fonte Ditis conubia.\nWindows Windows # This is tab Windows content.\nLorem markdownum insigne. Olympo signis Delphis! Retexi Nereius nova develat stringit, frustra Saturnius uteroque inter! Oculis non ritibus Telethusa protulit, sed sed aere valvis inhaesuro Pallas animam: qui quid, ignes. Miseratus fonte Ditis conubia.\n"},{"id":18,"href":"/docs/shortcodes/vim/","title":"Vim","section":"Shortcodes","content":" Installing vim on Windows # vim is a command line based text editor that we are going to be using for doing quick edits to files. Unfortunately, Windows does not come with it pre-installed like it is on macOS and Linux so Windows users should do the following steps to make sure you can use vim during our first session.\nDownload the following installer.\nOpen the downloaded file.\nAccept the User Agreement.\nOn the next window (\u0026ldquo;Choose Components\u0026rdquo;) make sure to select the \u0026ldquo;Custom\u0026rdquo; install type from the dropdown menu and that the \u0026ldquo;Vim Console Program\u0026rdquo;, \u0026ldquo;Create .bat files\u0026rdquo; and \u0026ldquo;Create Default Config\u0026rdquo; options are selected with checkboxes.\nLeave the next window (\u0026ldquo;Choose _vimrc settings\u0026rdquo;) as it is. Hit \u0026ldquo;Install\u0026rdquo; on the last window and the program will install. The program should then be installed and ready to use for Friday\u0026rsquo;s session.\n"}]