OER Publishing with LaTeX and GitHub

Size: px

Start display at page:

Download "OER Publishing with LaTeX and GitHub"

Gervais Anthony
5 years ago
Views:

1 OER Publishing with LaTeX and GitHub Samara Burns 1 Overview LaTeX is a document preparation program that allows for full customization of documents. LaTeX uses a program called TeX to compile document coding into a document that can be distributed. LaTeX documents are written in a markup language (like HTML or Markdown - essentially a coding language) that defines the formatting of the document and turns it into a readable.pdf or.dvi file. LaTeX provides several advantages for collaboration on OERs. Because the software is non-proprietary, anyone on any type of computer can access and edit the files. The markup formatting also allows extra flexibility in terms of customization, which is advantageous as you begin to build your OER, and if others wish to adopt and remix your OER. This guide presents some basic commands for building LaTeX documents but is by no means comprehensive. You can use LaTeX via a local installation (visit for downloads and installation instructions) or through an online LaTeX editor like Overleaf or ShareLaTeX. 1 2 Basic Formatting In this section we ll describe some commands that will allow you to create a basic LaTeX document. Document Class: Begin your document by defining the document class, like this: \documentclass{article}. In this case, the document class is ar- 1 Note that these two online editors will soon be joining forces. 1

2 ticle, which will give you a basic document like the one you are reading. Title, author and date: Below the document class, you can specify the document title, author and the date. \title{document Title} \author{your Name} \date{the Date} For no date, delete The Date and leave the field empty. Document Body: Everything you have done up to this point is part of the document preamble - your document so far has no output text. In order to get some output, you must define the body of the document, below the title information. \begin{document} Document Body \end{document} Anything you want to appear in the body of the document appears in between the begin and end document tags. Text Size: Text size across the whole document can be changed by adding the font size (10pt, 11pt, 12,pt, etc.) to the document class. \documentclass[size]{article} Italics: \textit{italic text} typesets italic text. Boldface: \textbf{bold text} typesets bold text. Underline: \underline{underlined text} typesets underlined text Line Spacing: In order to get text on the next line, use a double return. If you would like a white space between two lines, use a double slash at the end of the first line \\. 2

3 This formatting produces two lines of text, where one is stacked on top of the other. This formatting produces two lines of text, where one is stacked on top of the other. Whereas, This formatting produces two lines of text,\\ with a line of white space between them. This formatting produces two lines of text, with a line of white space between them. Lists: There are two basic ways to create lists in LaTeX: enumerate and itemize. The former creates a numbered list; the latter creates a bullet list. \begin{itemize}, \item First bullet, \item Second bullet \end{itemize} First bullet, Second bullet \begin{enumerate}, \item First item, \item Second item, \item Third item \end{enumerate} 1. First item, 2. Second item, 3. Third item 3

4 3 Using Packages In this section we ll see how packages can be used to customize a LaTeX document. Much of the formatting you would like to do requires additional scripts for LaTeX to use, called packages. In order to import a package, add the following to the preamble of your document: \usepackage{package name} Where package name is the name of the package you d like to import. 3.1 Adding Hyperlinks Relevant Package: hyperref If you want to link a url use the url command: \url{ If you want to create clickable text, use the href command: \href{ Commons website} 3.2 Adding Graphics Relevant Package: graphicx Flickr has an archive of Creative Commons licensed photos available at Once you have found an image that you want to import into your document, you can either save it in the same folder as your document, or create a new folder called images (or something similar). Keeping all your images in one folder creates a more organized project. First, add \graphicspath{ {images/} } 4

5 To your document preamble. This will tell LaTeX to look in the images folder. Note that this folder is relative to where your LaTeX document is stored; it will look for a folder called images in the same location where your LaTeX document is stored. The simplest way to import an image is to use the command \includegraphics{file name}. Place the command wherever you want the image to appear; it can be in-line with the text or on a separate line. Another option for inserting images is the figure command. This allows you to define where you want the image to appear, add a caption, and give the picture a label. \begin{figure}[h] \centering \includegraphics[width=\textwidth]{image name} \caption{caption} \label{fig:label} \end{figure} Beside the figure tag, you can specify where you want the image to appear. h tells LaTeX to put the image here (or somewhere close if the image is oversized for the space). There are multiple other options, including t for the top of the page, and b for the bottom of the page. The width field sets the width of the image, currently it set to the width of the text space. You can change this as you like. Replace image name with the name of your image - do not include the extension, and make sure your file name has no spaces. Underneath the picture is a good place to give appropriate credit and add a caption. Make sure to mention who the author is, provide a link back to the source, and mention which license the image is licensed under. Use the hyperref package to link back to where you found the image. Below is a template for giving credit for an image. \href{url of image}{title of image} by \href{link to author s profile (if applicable)}{author s name} is licensed under \href{link to license deed}{type of copyright} 5

6 Finally, the label field allows you to give your image a label. although this is not covered in this document, you can use this label whenever you refer to the image using the ref command. You now have all of the tools to insert an image and give proper attribution. More about inserting images can be found at ShareLaTeX guides. 3.3 Adding Bibliographies Relevant Packages: natbib, bibtex There are two main packages you can use for bibliography management: natbib and bibtex. Natbib is probably your best bet for traditional looking citations, and this guide will give a brief demonstration of citation using natbib. Within each package, you are able to choose from multiple styles of citation. In LaTeX, bibliographies are stored in a separate file. Each entry in the bibliography is given a name (or a key) which LaTeX uses to print the correct citation. Each component of the citation (i.e., author name, date, journal, etc.) is tagged appropriately, so you can change the bibliography style without having to change each entry. Below is an example bibliographic entry. author = "Gila Sher", title = "The Formal-Structural View of Logical Consequence", journal = "The Philosophical Review", volume = "110", number = "2", pages = " ", year = "2001" In the above, sher2001 is the citation key. Google scholar, and other scholarly resources, have Bibtex citation exporters and will give this code to you. If you d like to add a bibliography to your document, import the natbib package. In addition to importing the package, you want to tell natbib what style to print the citations and bibliography in. Add the following to the preamble: 6

7 \usepackage{natbib} \bibliographystyle{unsrtnat} This example uses the unsrtnat style. A list of natbib styles can be found at styles. Now create a new bibliography file and call it bibliography.bib (or anything you want, with the extension.bib). Paste your bibliography entry in the file and save. Now, switch back to your main file. In order for the bibliography to be printed, the entry needs to be cited. Cite the document by adding the following somewhere in the document: \cite[page number]{citation key} Where citation key is the name you gave your bibliograpy entry. In this case, I ll put sher2001 in the curly braces, and cite page 250. The \cite[]{} command prints the citation at the end of the sentence, like this: [Sher, 2001, 250]. To import the bibliography, use the following command: \bibliography{bibliography} If you used a different name for your bibliography, simply change the text in the parentheses to that name. It should print wherever you put the command. More on citation using natbib on ShareLaTeX guides. References Gila Sher. The formal-structural view of logical consequence. The Philosophical Review, 110(2): ,

8 4 Using GitHub GitHub is an online version control respsitory system. GitHub uses the Git software to track changes to a specific set of documents (the documents that you want it to track) - this is called a repository. In this document, we give a high-level overview of the basic properties of the online GitHub platform. In order to use Git and GitHub locally from your computer, you must install the Git software. You can find instructions to do so here: https: //gist.github.com/derhuerst/1b15ff4652a867391f03. Git can be run from the command line, or through a graphical user interface (GUI). GitHub has its own GUI called GitHub Desktop, available here: github.com/. If you have written or produced your OER in LaTeX, GitHub is a wonderful place to store the files so that others can easily access them. By default, GitHub repositories are public, and others are able to download the files or create their own fork of your repository. This guide will outline some of the very basic features of GitHub for sharing your work in the open and collaborating with others. If you have written your document in another format, you can also upload your files to GitHub. Any format can be shared, but some of the collaborative features work best with plan text documents, as document history and changes are provided on a line-by-line basis. In order to find this document helpful, you will have to sign up for GitHub at and verify your address. 4.1 Creating a Repository When you first open a GitHub account, you will be prompted to create a new project. You might also see a green New repository button on the home screen. Click this button to get started. A page will pop up that looks like figure 1. You must fill out the required fields in order to create your repository. Your repository name should be relevant to the content of your project, and you description should describe the content so that those searching on GitHub for your topic will be able to find it. If I were creating a textbook for a class, I would make the repository name the name of the textbook, and give a brief description of the content covered in the book. By default, your repository will be public. GitHub offers private repositories as a paid feature. Next, you ll want to initialize your repository with a README. This 8

9 Figure 1: Creating your first repository will create a basic file (written in the markdown language) and add it to your repository. The two dropdown menus give you options to add.gitignore and to add a license..gitignore tells git to ignore certain types of files (i.e., unnecessary auxiliary files). You can leave this for now. GitHub has several built in licenses for you to choose from. The standard for OERs is to use a Creative Commons license, but this is not available as a preset license on GitHub. We will refrain from putting in a license now, but will add a license in a later step. Click Create repository when you re ready. When you create a repository this way, your README will appear in your list of files. If you (or anyone else) wishes to copy the files from your online repository to your computer, you can download a zip file from the clone or download 9

10 menu. However, unless you have Git installed on your computer, there will be no link between the files on your computer and the online repository. 4.2 Creating a README Once you ve successfully created your repository, you ll see a screen like the one below in figure 2. Currently, your repository only contains your README file. The text of your README appears at the bottom of your repository page by default. Figure 2: Your repository Your README is an important document when sharing your work openly; now is a good time to update your README file so it is informative to those who are viewing, using and collaborating on your OER. Click on 10

11 README.md to open the text editor; click the pencil icon to edit the text in your README file. Here are some ideas of what content should appear in your README: A description of your OER and its main features, Who the collaborators are, Who the contents of the repository are for, How to use your OER, Rules for contributing to your OER, What kind of help you need for future development. This is also a good place to put a clickable image for your repository license. This is explained in the next section. Note that your README file (and other text files on GitHub) use markdown formatting. A simple tutorial on how to use markdown can be found on GitHub guides: Commits Unlike collaborative platforms like Dropbox, GitHub does not immediately upload changes to your repository. In order for a change to be reflected in your repository, you need to commit it. GitHub will ask you for a summary and an optional description. It s good form to make your summary descriptive of the changes you ve made; if you re committing a change to a single document, include the name of the file you re changing and an adjective describing your changes (i.e., updating README.md or restructuring README.md ). You re also given the option to add a description. If you feel like others would benefit from a more detailed description, add it in the larger box. Every time you commit a change, GitHub tracks the changes for you and others in the commit history of the document. When you click on a file, like your README file, at the top of the text editor is a History button. Clicking on this button will show you all of the versions that the file has gone through (figure 4). 11

12 Figure 3: Commiting Changes Figure 4: Document History Clicking on each commit brings up a detailed outline of the commit, including a line by line comparison of the changes (additions and deletions) that were made to the document. 12

13 4.4 Adding a License When uploading your OER to an online repository, it is important that you let others know what kind of license your work has; this lets others know how they can use your work. On your main repository page, click the Create new file button. Name this file LICENSE.md. Most OERs are licensed under a Creative Commons license. For more information about these licenses, check out licenses. The most liberal license available via Creative Commons is the Creative Commons attribution license (also known as the CC BY license). Sharing your OER under this license means that others may use, distribute, remix and create derivatives of your work as long as they give appropriate credit to you. Once you ve decided what kind of license best suits your project, you want to add the license information to your LICENSE.md file. You have a few options for how to do this. You may wish to copy and paste the legal code of your license into your LICENSE.md file. The legal code for your license can be found on the Creative Commons website. It is also a good idea to note what license your OER has in your README file. The Creative Commons license chooser at org/choose/ gives you the HTML code for a clickable license button. You have the option for reformat this code into markup language and place this in your README file. 4.5 Issues and Milestones When collaborating with others, GitHub has features that allow you to plan out the future of your OER and any planned changes or additions to your project. Click on the issues tab on your main repository page to access these features. Milestones are larger events or goals for your project. When you re in the issues tab, click the Milestones button to access your milestones. An example milestone would be a first draft of your OER textbook, or a finished version of your OER for an upcoming semester. When you create a milestone you are given a few different fields to fill out, as in figure 5. Give your milestone a descriptive title, and a brief description. You can also add a deadline to your milestone so everyone knows when it 13

14 will (or should) be completed. Figure 5: Creating a Milestone Issues are more specific projects to get done, or issues to fix with your OER.You can create a new issue from the main issues tab. Give your issue a descriptive name: what needs to get done? In the side bar, you can also assign this issue to a specific person, give it a label for organization, and associate it with a specific milestone. 4.6 Forking a Repository One collaborative issue that GitHub has is called forking. Once you upload your files to a public repository, others may want to create their own 14

15 Figure 6: Creating an Issue GitHub repository to keep their version of your OER. They can do this by forking your repository. When a repository is forked, it means that someone who is not the owner of the original repository has created a copy on their own GitHub account. This can be someone who wants to remix or use your OER, or it could be one of your collaborators. In order to fork a repository, simply click the fork button on the top right of the main repository page. The great thing about forks is that any changes made to the forked repository do not affect the main repository. Others can remix your OER while you maintain or continue to work on the original version. 15

16 4.7 Pull Requests Pull requests allow others who have forked your repository to suggest that you pull their changes into your main repository. For instance, if one of your collaborators has added a section to your OER in their fork, they can submit a pull request so the new section can be incorporated into the main repository. You can submit a pull request from the pull request tab on your main repository. Similarly, if someone has submitted a pull request to you, it will appear under this tab. When creating a pull request, you must designate the head and the base fork. The head is the repository where the changes are coming from, and the base fork is where you want the changes to go. The pull request will compare the original repository to your fork and detail the changes that have been made. If someone has submitted a pull request to you, you can view the details by clicking on the request in the pull request tab. You can view the suggested changes and comment on the pull request. In addition, in the right-hand sidebar you can assign someone to the pull request, give it a label, and assign it to a milestone. You can incorporate the changes by clicking the merge pull request button. If there are any conflicts, GitHub will ask you to resolve them before you can incorporate the changes. You also have the option to close the pull request without incorporating the changes. 4.8 GitHub Vocabulary Branch: A branch is a copy of your repository that is contained within the repository itself. You can modify this branch as you like without affecting the main (or master) branch. When you re ready, you can merge the changes from your branch to the master. Clone: You can clone your repository so that you have a copy of it on your computer. The files on your computer can be changed without affecting files stored online on the GitHub repository. When you re ready, any local changes can be pushed to the online respository. Commit: When you make changes to a file, they aren t automatically incorporated into your repository. In order to have the changes reflected in 16

17 the repository, you commit them. Each commit shows what changes were made, who made them, and a brief description of the changes. Fork: If your repository is public, users can create a copy of your repository called a fork. Any changes they make to their fork do not affect the main repository. Issue: Issues can be filed for any changes, improvements or projects that are planned for the repository. Users can contribute issues and discuss open issues. Pull: When someone makes a change to a file in the GitHub repository, you can pull those changes and merge them to your local repository (the files on your computer). Pull Request: If someone makes changes on a fork of your repository, they can make a pull request to suggest that you merge those changes with the main repository. Push: When you change a file on your computer, you can push those changes so that they are represented on the GitHub server. Repository: Your repository is the main folder on GitHub that holds all of your files and their revision history. This would be similar to a Dropbox folder, or other cloud-based storage. 5 Further Resources Comprehensive TeX Archive Network (CTAN): LaTeX on Wikibooks: GitHub guides: GitHub for Collaboration: 17

Tips on how to set up a GitHub account:

Tips on how to set up a GitHub account: 1. Go to the website https://github.com/, you will see the following page: Figure 1: The GitHub main webpage (before you create an account and sign in) Then choose