Got Errors?

Are you getting LaTeX errors when compiling the Open Logic Project files?  If you get this one:

LaTeX Error: \memendofchapterhook undefined.

it means you have an old version of the memoir class installed. Get a new version from CTAN, or update your TeXLive or MacTeX distributions.

If you get another one, make sure you have the most up-to-date version of OLP installed.  If it persists, please file an issue on GitHub, and attach the .log file of the file you’re trying to compile.

Getting Your Book to Print

As I explained yesterday, making a custom text from the OLP source using LaTeX is relatively easy.  But, I’d also like to get an attractively printed version with covers and everything.  So I’m trying out two print-on-demand services: lulu.com and blurb.com.  The challenge is now to (a) format the book so that the can print it and (b) to find a way to produce a cover.  Both Lulu and Blurb let you upload PDFs for this, and they give you the specs to format your books for print.  All the files are on GitHub (this version, most current version), but I’ll walk you through the process.

First, we have to choose a size. I went with Royal for Lulu (that’s the size, e.g., your standard OUP book comes in. It’s slightly larger than US Trade, which is 6″ by 9″).  Blurb doesn’t offer Royal, so there I’m using US Trade.

First, let’s go through the Lulu process. After you pick your binding (perfect-bound paperback), size (Royal), and color (B&W on White paper), and clicking “make this book,” Lulu will tell you what the page dimensions of the PDF should be: 15.593cm x 23.389cm.  Setting up the book design can be a long process, but for now I’m just interested in the print quality, speed of delivery, and pricing.  Since I use the memoir class, setting up the design is relatively easy. [Update: A. Mani pointed out that you can also use the bookcover LaTeX class, and for more involved covers, esp. dust jackets for hardbound copies, this is probably the way to go.]

First, we set the stock size, i.e., the size of the paper the thing will be printed on, and the trim size, i.e., the area on the stock that will remain after the pages are trimmed. For a Lulu PDF, you ignore the trim. So:

\setstocksize{23.389cm}{15.593cm}
\settrimmedsize{\stockheight}{\stockwidth}{*}
\settrims{0pt}{0pt}

Since this is a non-standard size, we’ll also have to tell memoir where to put the text on that page.  For this, we’ll first have to determine the size of the typeblock, the are that will hold the running text.  That of course depends on the stock size, but also on the typeface and the type size.  For optimal readability, the typeblock should be dimensioned so that a line of text contains not more than 70 characters.  So you have to determine how long a line with, say, 65 characters in your typeface/type size is, and that’ll give you the width of the typeblock.  That would be a pain to find out, but memoir has a macro for it: \setlxvchars will set the length \lxvchars to that length.  Then we can set the size of the typeblock to be that width, and whatever height makes the ratio of height to width the golden ratio.

\setlxvchars
\settypeblocksize{*}{\lxvchars}{1.618}

The next step is to determine the margins and the positioning of the header and footer.  You can set these by hand, and it’ll depend on, e.g., if you want to have space in the margin for notes, etc. For now, let’s keep it simple: Make everything in the golden ratio too, and start the typeblock 60pt from the top edge.

\setlrmargins{*}{*}{1.618}
\setulmargins{60pt}{*}{*}
\setheaderspaces{*}{*}{1.618}

Now you tell memoir to fix the layout to these specifications using \checkandfixthelayout. This will also make some slight adjustments, e.g., guaranteeing that the height of the type block is an even multiple of the line height.

That’s it. Run it through LaTeX and you have a PDF for the book interior to upload to Lulu.

For Blurb, the procedure is almost the same, except that they want you to include the trim.  In the book size calculator on their site, you select the options (trade book, 6″ by 9″). Now the stock size is 6.125″ x 9.25″ with 0.125″ trim, so:

\setstocksize{9.25in}{6.125in}
\settrimmedsize{9in}{6in}{*}
\settrims{.125in}{.125in}

Everything else stays the same.

After you upload the PDF to Lulu, you’ll click “make print-ready PDF”. Lulu might now warn you about type that’s too small to print clearly (e.g., subscripts).  I haven’t worried about it and will wait for the printed copy to check if that’s a problem.  Then you get to design a cover. There’s a cover “wizard” that lets you do that, but we’re nerds and want to make our own PDF using LaTeX. So click on “one piece cover creator” to go to the PDF upload page. Here it’ll tell you what your cover PDF should look like.  (Blurb tells you up front in the book size calculator, but you need to know the number of pages in the book, since the width of the spine depends on that).

I made a separate LaTeX file for the cover, also using memoir.  Now the stock size is larger (same height, but twice the width + the width of the spine).  Lulu gives these dimensions in “PostScript points” which correspond to the LaTeX measure “bp”.  Lulu says:

Spine width: 23.351 Postscript points wide (0.824 cm) (97 px)
Spine begins 451 Postscript points (15.908 cm) (1879 px) from the left
Total cover width: 925.351 X 681 Postscript points (32.640 cm X 24.021 cm) (3856px X 2838px)

My file will do some calculations for you, so you just have to put those measurements in. You can also do it by hand, of course using \setstocksize etc.

\setlength{\coverheight}{681bp}
\setlength{\coverwidth}{925.351bp}
\setlength{\spinewidth}{23.351bp}
\setlength{\spinepos}{451bp}

Now we have to place the front cover, back cover, and spine text into the right place.  Absolute positioning is not something LaTeX is designed to do, but there is the textpos package that lets you do it. After you load it:

\usepackage[absolute,overlay]{textpos}

you can place stuff onto the page with absolute positioning. For instance, our spine will be a box of width 23.351bp positioned at 451bp from the left margin:

\begin{textblock*}{23.351bp}(451bp,0bp) ... \end{textblock*}

Of course, the text on the spine should go along the spine, so we have to use the \rotatebox macro from the rotating package. This code in my file centers the text on the spine, horizontally and vertically:

\begin{textblock*}{\spinewidth}(\spinepos,0bp)%
\noindent\hfil\rotatebox{-90}{%
\hbox to \coverheight{\hfil
Text that goes on the spine
\hfil}\hfil
\end{textblock*}

You’ll probably want the text to be styled properly (e.g., larger size, etc).

The front and back cover are handled similarly. The width of the front and back cover is the same as the spine position, and the front cover begins at \spinepos + \spinewidth.

This will make a boring black & white cover, but of course you can play around with colors and/or put images on the cover.  To keep things simple, I just set the background color to Ice Blue and the text and logos in Reflex Blue (the colors of the OLP logo). You do this using the xcolor package, define the colors and set the page background and text color in the preamble:

\usepackage{xcolor}
\definecolor{OLPiceblue}{RGB}{179,199,227}
\definecolor{OLPreflexblue}{RGB}{12,28,140}
\color{OLPreflexblue}
\pagecolor{OLPiceblue}

For Blurb, the procedure is the same.  In my test, I tried something a bit different with the colors: invert the colors on the spine and add a 1cm edge on the front and back (textpos lets you set the background color on each positioned textblock using \textblockcolor).  Blurb also automatically adds a (free) ISBN to the back cover, so you’ll have to take that into account.  Lulu also gives you a fee ISBN, but it’s required only if you want to sell the book through retail services (Amazon, Barnes & Noble, and the Ingram network).

That’s it. Upload the cover PDF and enter whatever Lulu and Blur want in terms of metadata, license info, etc., and then order the book.  For this 143-page test, Lulu charged $6.77 and Blurb $3.89 (Canadian).  However, Blurb’s cheapest shipping option was $5 more than Lulu’s regular mail option. In the end, I paid Lulu $13.40 and Blurb $14.61 for a single copy, but if you order a bunch (e.g., for your class), Blurb will be cheaper.  I’ll let you know how delivery speed and quality of the finished product compare.

[Update: See this post for how it turned out in the end!]

 

Making a New Logic Textbook in Seven Easy Steps

I’ll be teaching the University of Calgary’s second logic course, imaginatively titled “Logic II,” next term.  It’ll be the first time for me to use the Open Logic Text for this course.  I used it for McGill’s “Intermediate Logic” earlier this year, and Nicole Wyatt has been using parts of the text the last time she taught it a year ago.  Lots has changed, and I’m aiming to provide a nice, self-contained book.  I’ll document the steps to make this happen.

To start, I have to pick the material to include. Logic II is supposed to cover “Introduction to the metatheory of logical systems. Completeness, compactness, Löwenheim-Skolem, and undecidability theorems for first-order logic.”  In previous iterations, I’ve used Boolos, Burgess, and Jeffrey’s Computability and Logic as a textbook, and that’s also what my colleagues who also teach it have used.  In part because of this, I’ve previously covered set theory, then Turing machines, first-order logic, undecidability, completeness and Löwenheim-Skolem theorems in that order: it’s the order BBJ covers it. But with an open text, I can rearrange things if I want to. And I think I do.  Once you cover relations, it’s sort of natural to continue with first-order semantics, definability, and expressibility.  So I’ll go with set theory, metatheory of first-order logic, Turing machines, and undecidability. (Right?)

To make a new book, you have to start by setting up a driver file that does all the setup and loads the parts and chapters you want in the right order.  Of course, I’ll use Git also for that driver file and anything else I’ll need to pull things together. So,

Step 1: set up a GitHub repository [You can skip this step if you don’t want to use Git to keep track of changes.].

create-repo

Step 2: Clone the repository, so I have it on my local drive.  The Git URL is git@github.com:rzach/phil379.git.  I use SSH, but there’s also an HTTS URL: https://github.com/rzach/phil379.git.  Where do you put it?  It’s probably easiest if it lives with the other courses in the OLP directory.  So I go to where my OLP clone lives, then to the subdirectory holding the courses, and clone there:

$ cd ~/tex/openlogic/courses/
$ git clone git@github.com:rzach/phil379.git
$ cd phil379

[If you don’t want to use git, just make a new subdirectory of the /courses directory.]
Step 3: We have to start somewhere, so I’ll copy the files courses/sample/open-logic-sample.tex and courses/sample/open-logic-sample-config.tex from courses/sample to my new directory, renaming them to phil379.tex and phil379-config.tex, respectively. I’ll also add a license and a Makefile, but you wouldn’t have to.

Step 4: The main file, phil379.tex contains the instructions for what to include and in what order.  I’ve changed it so that only what I need is included.  Here is what it looks like at this point, and here are the changes I made to the original open-logic-sample.tex file.  I haven’t yet done anything to the formatting or layout, just changed the title page and what chapters are included.

Step 5: I do want to do a few things a bit different from the default.  First of all, I’ll make the text unpretentious: no Greek formulas, no Fraktur letters for structures.  I haven’t yet made up my mind about terminology, but I think I might want to use “countable” instead of “enumerable”.  (I wouldn’t if I were going to talk about “computably” or “recursively enumerable” sets, but I think I won’t.  And when you’re talking about sizes of sets, “countable” and “uncountable” is a bit more conventional and easier to say. Maybe. I might change my mind later.)  There are some switches I can adjust, too: e.g., I’d like to have everything but biconditional and “true” be primitive symbols: That way there are more cases to prove, but I’ll get all the cases for the conditional and the universal quantifier as exercises.  Lastly, the first-order-logic part includes both sequent calculus and natural deduction as proof systems, but I’ll cover only one.  Maybe natural deduction.  Might change my mind on that too.  Anyway, all these things can easily be specified in phil379-config.sty.

Step 6: Run phil379.tex through LaTeX, get a nice PDF.

Step 7: Commit everything and push to GitHub, so it’s saved (and I can link to the source files here).

[UPDATE: (a) The current version has phil379.tex containing only the content, and the layout and setup is done by phil379-screen.tex and phil379-print.tex, which generate a version for on-screen reading and a version for printing, respectively. See also this post.]

Open Logic Quick Start Guide

[Chad and Samara have documented the steps required to download and compile the Open Logic Text, and written a “quick start” guide for people who aren’t experienced with Git or may not even have LaTeX.  The most up-to-date version of this document can be found on the OLP wiki here.]

This page describes all the steps required to install and compile the Open Logic Text on your computer, including installation of LaTeX (the typesetting program OLT uses) and Git. Please see the pages on LaTeX and Git for more information on what those are if you don’t know already. You can avoid using Git by downloading OLT directly, but it makes it harder for you to keep up-to-date with changes to the text, and us to incorporate any contributions you make.

Installing LaTeX and Git

A LaTeX environment is necessary for both building a version of the Open Logic Book and contributing to the project. While it is possible to build the book without [Git], the project is currently hosted on Github, and you will need Git to contribute to the project.

Linux

The easiest way to get a working LaTeX environment on the majority of Linux systems is to install TeX Live through the package manager. The name of the package varies (texlive for Debian and Ubuntu with aptitude, texlive-most for Arch Linux with pacman, texlive and texlive-latex for OpenSUSE with libzypp). If TeX Live is not available through your distribution’s package manager or your distribution does not use a package manager (Gentoo), follow the instructions on the website to download and install TeX Live. To compile a .tex file into a .pdf file, use the pdflatex command at the command prompt.

Similarly, install git through your package manager. For an introduction to git specific to the Open Logic Project, see below.

Windows

Download the TeX Live installer for windows and run the executable. The installer will guide you through the installation process. Do not be alarmed if it takes a long time for the installer to download all the required packages. After installation is complete, you should be able to double click on latex source files to open them in the editor, from where you can click the green “play” button in the upper left hand corner of the interface to compile the document.

If you only want to build a custom version of the book, you don’t need to install Git on your system, it is enough to click the “Download ZIP” button on the right hand side of the Github interface on the project page, and extract the contents to a convenient location. If you want to contribute to the project, the easiest way is probably to install Github for Windows.

OSX

Install MacTeX to obtain a LaTeX environment. If you’re comfortable with the command line, install Git. If you choose the command line most of the instructions and advice for Linux systems will apply to you also. If you prefer a GUI, install Github for Mac. Ideally you will install both, allowing you to try typing the git commands as they appear for Linux users, with the GUI as a fallback if something isn’t working for you.

Git Primer: “Fork” and Other Verbs

Git is the distributed version control system used by the Open Logic Project. It allows multiple people to work on the project at the same time, and makes creating your own version of the project and incorporating your changes into the main project easy. A collection of files managed with Git is called a repository. The Open Logic Project repository is hosted on Github, a hosting service for Git repositories with a nice web browser interface. Git is a somewhat complicated system, and can be intimidating for new users. The aim of this section is to help you become comfortable with what Git is and get you started using it.

To contribute to the Open Logic Book, you will probably want to register an account with Github. While this is not necessary if you are looking only to use the text, and not strictly necessary if you would like to contribute to the project, it will make both of these things far easier. During the account creation process you may be asked to choose a payment plan. The free one will suffice.

Once you have a Github account, the first thing you should do is create a copy of the the OpenLogic repository tied to your account. To do this, log in to your Github account, and click the “Fork” button on the page for the repository (In the upper right hand corner of the web interface). A copy of the repository should now be displayed on your Github profile page at https://github.com/<yourusername>. Any changes you make to this repository will not be reflected in the main OpenLogic repository. You can request that your changes be added to the main repository by issuing a “pull request”, covered here.

Now that you have your own copy of the project files on Github, the next step is to get those files on your computer. If you’re using git from the command line, navigate to the directory you want the files to be in and enter

git clone https://github.com/<yourusername>/OpenLogic

at the command prompt.

If you’re using the Github GUI interface for Windows (or the similar application for OSX), you need to link your Github account to the instance of the software on your computer. If you are not prompted to do this when you first start it up, you can do it by clicking the gear icon in the upper right corner of the main window of the application. Once you have linked your account, you will be able to clone your fork of the OpenLogic repository by clicking the plus sign icon in the upper left corner of the main window, and selecting “clone”, and finally selecting your fork of the repository. You will be prompted to enter a save location, and it doesn’t matter what this is as long as you remember it. Once you have done this, the copy of the files on your computer will behave much the same as for Linux and OSX users, with the difference that you will have to use the Github for Windows application instead of the command line to do the things described below. The Github for Windows application comes with a low-powered “shell” that will act a bit like a Unix command prompt, and makes it easier to perform more complex operations should the need arise. Please consult the documentation for more information on the Github for Windows application.

There are three sorts of basic changes you can make to the repository, adding new files, changing old files, and removing old files. To add a new file called file.ext to the repository, move the file to the OpenLogic directory on your computer and type git add file.ext. This tells git to keep track of file.ext. To make changes to a file that git is already keeping track of (such as the files that were in the repository when you cloned it), simply edit the file. To remove a file called file.ext from the repository, type git rm file.ext at the command prompt. This not only tells git to stop tracking the file, but deletes it. To record changes you have made, type git commit -m "summary of changes" at the command prompt. If you don’t want to record your changes, you can type git reset to restore the repository to the state it was in immediately after the last commit. Finally, to synchronize the changes you have made with the version of the repository on Github, type git push at the command prompt (after committing your changes).

If you are using Github for Windows it easy to commit and push changes. Once you have edited a document that Git is currently tracking, or added a new document to the OpenLogic directory on your computer, it will pop up in Github for Windows as an uncommitted change. You can select/deselect files to commit at this point. You must write a summary of the commit, and are given the option to add a short description. Once you have done so, hit the commit button. At this point, the changes you have made will not be reflected in the version of the repository on Github. You should see that the sync button at the top of the application now has a number beside it, reflecting the commits that have yet to be pushed to Github. When you are ready to push your changes, click the sync button.

To request that your changes be reflected in the main Open Logic Project repository, submit a pull request.

The pull request can be done directly from Github for Windows, but the application does not have a compare and review feature. If you’d like to do a comparison of the changes you’ve made before submitting a pull request, follow the instructions linked to above. If you’d like to do the pull request directly from Github for windows, you can do so by clicking the pull request button to the left of the sync button. The program will show you which branch the changes are being taken from, and where you are sending the updates to. The default options for the pull request should be correct, but you may want to double check that the pull request is being sent to the correct place (in most cases, this should be from your master branch into OpenLogicProject/master). You’ll have to enter a title, and if you’d like, a description. Then click “Send pull request”, and you’re done!

If you want to update your copy of the repository to include changes in the main repository that have happened since you made the copy, read this. Alternatively, and if the “upstream” changes can be synced into your fork without manual intervention, you can use the Github web interface to sync changes from the main repository into your fork. To do this, proceed as if you were sending a pull request, but switch the “base fork” and “head fork”. (The base for should be “yourid/OpenLogic”, the head fork “OpenLogicProject/OpenLogic”; and in each case the branch should be “master”). Github will tell you if an automatic merge is possible. If it is, you will have sent yourself a pull request that you can merge.

Building the Open Logic Book

Once you have a working LaTeX installation and a copy of the Github repository on your computer, you can compile a custom edition of the Open Logic Book. To build the complete book (all chapters included), compile the open-logic-complete.tex file. The open-logic-debug.tex file also produces a complete PDF, but with extra debugging information that helps to keep track of labels of theorems and the like, and which files which parts of the final PDF come from.

The files in the main directory should not be changed. To make a customized version of the book, instead go to the courses directory, and copy the sample subdirectory. Your copy should contain two files, open-logic-sample.tex and open-logic-sample-config.sty. You may rename these files, e.g., to myversion.tex, myversion-config.sty (where “myversion” can be any string). You can make any changes to the layout, fonts, page style, etc., in myversion.tex you like. You can also rearrange the order of the parts and chapters or leave out parts you do not want included. For instance, to exclude the part on computability theory, change the line

\olimport[computability]{computability}

to

%\olimport[computability]{computability}

in myversion.tex.

To change the OLT-specific configurations, e.g., how formulas are printed or whether formulas are called “formulas”, “formulae”, or “wffs”, open myversion-config.sty in a text editor. The configuration options are explained in open-logic-config.sty in the main directory. Copy any configuration option you would like to change to myversion-config.sty and make your changes.

Finally, generate a PDF of your custom textbook by compiling the myversion.tex file with pdflatex.

You can keep different versions of the text in different directories by following the same steps as before.

Open Logic Project Special LaTeX Syntax

The Open Logic Book is configurable, you can choose which word you want the book to use for a number of technical terms, and more! To achieve this we preface configurable elements with a special syntax in the .tex files of book chapters. This makes writing chapters for the text a bit more complicated that it would have otherwise been, but not by too much. In addition to this section, you will have to read the open-logic-config.tex file in the top level of the OpenLogic repository, which contains a complete listing and explanation of the syntax.

The pattern common to all of the special syntax is that instead of using the standard LaTeX macros for a particular symbol, you use a specific Open Logic Project macro, e.g., \lif for a conditional symbol instead of \rightarrow. When the document is compiled, the special macro is replaced with text according to the configuration of that instance of the book. Sometimes the OLP uses the standard macro, e.g., \land. For example, one of the configuration options allows you to choose between the Greek and Latin alphabets for the symbols used to represent formula metavariables. For this to work, when you write material for the book you must use the syntax !A, !B, and so on for formula metavariables. Other configurable things include the symbols used for various sets of numbers (natural, real, integer, and so on), logical connectives (including quantifiers), and the syntax for relations like provability and entailment.

“Tokens” are slightly different than the rest of the configurable syntax. The idea is that in addition to using different symbols for the same thing across book instances, we might also want to use different words. This is done by treating some words, like “formula” and “variable” differently, as Tokens. When you use a tokenized word in material for the Open Logic book, instead of typing it, you have to enclose it in braces and place two exclamation points in front of it. That is, instead of typing

formula

type

!!{formula}

instead. To typeset the (configurable) plural form of a token word, type

!!{formula}s

and to typeset the token word with a (configurable) article, type

!!a{forumla}

The complete list of tokenized words and instructions for customizing tokens can be found in the configuration file open-logic-config.tex

Git for Philosophers (pt. 1)

What is Git?

When software developers work on complex programming projects, they use something called a revision control system. A revision control system allows them to keep track of changes in their code — it stores a history of changes, and allows them to quickly and easily take back (“revert”) changes that turn out to break things. It also makes is easy to collaborate with others: multiple contributors can edit and add code, and the revision control system automatically integrates changes when possible, and alerts contributors to conflicts when it isn’t. Software code is just text, and revision control systems work just as well with LaTeX code, or Markdown text, as they do with Java or Haskell programs.

Git is such a revision control system. It is distributed, which means that the entire history of your code lives not just on a server somewhere, but on your own computer and any other computer that uses the same shared code. Thus, you do not have to be connected to the internet to use Git to make changes, add material, or revert to a previous version. In order to collaborate with others, it is of course necessary to make code maintained by Git available over the internet. There are a number of websites which provide this service, the most popular ones are GitHub and GitLab. Both are free. GitHub is bigger, but GitLab is open source and allows you to have private projects without paying.

You are no doubt familiar with the history function in Word, and with automatic backup services like Dropbox. Git is a little bit like these, and so it might be useful to compare them as we go along. You can use Git as a backup solution, but it is not an automatic tool.

How does Git work?

A collection of files managed by Git are called a repository. A repository may be a single text document, or an entire collection. It is essentially a folder (possibly with subfolders) for which Git keeps track of changes to (some of) the files in it.

A particular state of a repository is called a revision. In contrast to automatic versioning (e.g., track changes in Word, or automatic updates in Dropbox), a Git revision must be explicitly created. If you have a file on your computer that is tracked by Git, you can make any changes you like to it, but you have to tell Git when you want your changes to “stick,” i.e., to count as a new revision. This is called committing. When you commit changes in a Git repository, Git creates a new revision of your repository. A revision may include changes only to a single file, or it may include changes to files, new files added to the repository index, files renamed, moved, or deleted. Each revision is assigned a unique 40-digit hexadecimal “hash” code (often abbreviated to a 10-digit code). When you commit changes to create a new revision, the identity of the committer (i.e., you) as well as a commit message describing the changes is recorded.

One of the differences between Git and, say, Dropbox, is that any new Git revision has to be created manually by committing, while Dropbox just checks if a file has changed on your disk, and makes a new revision whenever that happens. Another difference is that Git only tracks those files it has been asked to track, while Dropbox tracks every change in every file in the Dropbox folder. To ask Git to track a file, you add that file to the repository index. A third difference is that Git works locally until you tell it to save or load changes from the cloud, whereas Dropbox not only records your changes automatically, it also saves those changes to the cloud, and any change in the cloud automatically is mirrored on your own computer without you having to do anything — but also without asking you first!

To save the revisions in your Git repository over the internet, your Git repository must be linked with a version of the repository on a server somewhere (e.g., on GitHub or GitLab). This server repository is called a remote. Think of it as the cloud copy of your local Dropbox folder. However, the remote repository is not automatically synced with your local version. You have to tell Git to copy the changes in your local repository to the remote. This is called pushing your changes. In the other directions, to incorporate changes to the remote copy into your local repository, you pull changes from the remote. It’s in this case, when the remote repository has been changed (by you, from a different computer, or by a collaborator), that Git is most useful. If a file is changed in your Dropbox folder at the same time you’re editing it on your own computer, Dropbox will make a new copy of the entire file and leave you to figure out if there are conflicting changes and what to do about them. If you pull changes from a remote Git repository, Git will try very hard to compare your local version with the remote version of each file. If it is possible to merge changes automatically, Git will do so. If not — e.g., when both you and your collaborator have changed the same sentence — Git will alert you to a conflict that has to be reconciled manually. In practice, you will find a version of the file with both lines marked; you delete the line you want don’t want to keep, save the file, and commit the change to creat a revision that reflects both your and your collaborator’s change.

How do I use Git?

In order to use Git on your computer, you have to install the Git software. The bare-bones “command line” Git client is available for all operating systems, but there are a fair number of graphical interfaces available as well. The best place to start is on the Git download page. For Windows, there is TortoiseGit, which will make all the Git commands available via the Windows Explorer right-click menu. If your repositories are or will be hosted on GtHub, you can use GitHub’s own graphical tools for Windows and Mac.

Once you have Git and possibly a graphical Git tool installed, you have to set up a repository. There are two ways to do this. The first is using the git init command: in the folder/directory you want to track using Git, just say git init. Most of the time, however, you want your repository to have a matching remote version on a server. Then it will be a lot easier to first create the repository on the server and create a local copy of that repository, which will then be linked to the remote. Creating such a local version of an existing repository is called ‘cloning.’

So go to GitHub or GitLab and create a repository. In both GitHub and GitLab, when you are logged in, there is a little ‘+’ next to your username in the top right corner which lets you add a new repository (GitLab calls them “projects”). Once your repository/project is created, you can clone it to a repository living on your computer using the clone URL at the bottom of the right sidebar in GitHub or at the top of the projct page in GitLab. There are HTTPS and SSH versions of those URLs. HTTPS always works, but you will have to give your GitHub/GitLab user ID and password whenever you push or pull. SSH can be set up to avoid that, so it’s preferable, but it is a bit of a hassle to set up on Windows.

You can of course also use Git to clone repositories not created by you. For instance, the Open Logic Text is a logic textbook project that uses Git, and you could use the clone URL on its GitHub page to download a copy using Git. This very document can be cloned from its GitHub page as well. In the same way, you can clone a repository set up by a collaborator for a document you are planning to work on together. However, only in the latter case will you have permissions to change the repository on the server. Instead of cloning, e.g., the Open Logic repository directly, you can first ask GitHub to make a copy of it, which you then own. This is called a fork. A fork of a repository is a snapshot of the original, which you have complete control over. In particular, you can clone it to your own computer, and push any changes you make back to GitHub or GitLab. Both GitHub and GitLab display a “fork” button in the top right corner of the repository page which allows you to do this.

Once you have a clone URL, you can create your local version of the repository with the command
git clone URL
To track your own work, you’ll start with a new, empty repository and clone it. Suppose you are ‘user’ on GtHub and have started a repository ‘project’. You make a local version of this repository using
git clone https://github.com/user/project.git
and this repository will live in the directory/folder ‘project’ on your local drive. You can add a new file to that folder, but to have it tracked you also have to add it explicitly to the Git index:
git add new-file.tex
Now Git knows that new-file.tex should be tracked. To create a new revision of your ‘project’ repository which records all the changes to your tracked files, say
git commit -a
The switch “-a” is for “all”: Git will ‘stage’ all changes for all tracked files in the repository.

Then to sync your local changes to GitHub/GitLab, you say
git push
(Cross-posed from Richard Zach’s blog.)

Making your own Open Logic Textbook

I’ve started teaching Phil 310 (Intermediate Logic) at McGill, and am using the OLP for the first time myself.  Here’s what I’ve done so far to adapt it for my class.

The standard, complete compile is of course intended just as a record of what’s in the text, and isn’t meant to be used by itself. So I’ve made separate “driver” LaTeX files that includes only what I want to be in the text, in the order I want it, and with the conventions, notation, formatting I want.  It’s on my github. In order to compile, it has to be placed in the right location. If you want to follow along, find the courses/ subdirectory of your own clone of the complete OLT, and then clone/download to phil310 repository there.  There should now be a subdirectory courses/phil310/ that contains the files.

phil310-letter.tex is the file you want to run through pdflatex to produce a PDF of the book.  There’s also a version phil310-ebook.pdf formatted for on-screen reading. It’ll change as I add more content to it, and clean it up as I go along.  But it’ll always have the following ingredients:

Layout setup. I’m using the memoir class with letterpaper option, and then some font selection packages (mathpazo for Palatino and Palatino math fonts, helvetica for Helvetica sans-serif). You could include all kinds of customization using memoir’s commands here, from the way chapter headings are styled, to page layout, etc.

You have to tell OLP where to find all the texts, in this case, two directories up:

\newcommand{\olpath}{../../}

You also have to include all the OLP commands.

\input{\olpath/sty/open-logic.sty}

The file open-logic.sty also includes the definitions of all theorem and other environments (it lives in \olpath/open-logic-envs.sty). If you wanted to change these, you would copy the entire file into this directory and name it phil310-envs.sty. If this file exists in the current directory, it will be loaded instead of the default.

Right now the mechanism for making problems appear not in the text, but at the end of a chapter isn’t working right yet.  Until it does, I have a bunch of commands in here that move problems to an appendix, with headers per chapter.

Then comes the content itself, after \begin{document}. First, a title page, a table of contents, and a preface (which is essentially the content of my course outline) which is included from preface.tex.

The actual content of the book goes between \mainmatter and \endmatter. For now, I’m just including entire parts, but I’ll probably be more selective as the course goes on.  Instead of including an entire part

\olimport*[first-order-logic]{first-order-logic}

you could include just a chapter

\olimport*[computability/recursive-functions]{recursive-functions}

or even every section individually. If you do that, you might also include your own \part and \chapter commands. You can add you own content here as well, either directly in the file or using simple \include‘s if your files live in this directory, or \olimport if you’ve added files to the directory tree of your local OLT clone.  You can also put the \olimport‘s into separate files which you then \include in the main file. This way, you can use \includeonly in the preamble to produce a PDF of only part of the book, but with page numbering etc. consistent with a full version–useful if you want to pass out reading materials as the course progresses.

Customization of tokens, symbols, and setting up selective compilation is done in phil310-config.sty, which is loaded in addition to, and after the default \olpath/open-logic-config.sty.  So here, only include things you want to be different from the defaults.  So far I’ve just changed the truth values to T and F from 1 and 0, made ↔ a defined operator, and set it up so that when there are proofs by induction on formulas, the cases for ∧ and ∀ are left as exercises.