Command Line

Overview

Questions

• How can I make my results easier to reproduce?

Objectives

• Introduce Zipf’s Law project.
• Introduce git branches.
• Illustrate pain and fragility of building with editor and sequences of command line commands.

Let’s imagine that you are writing code for a research project to test Zipf’s Law.

Callout

Zipf’s Law

The most frequently-occurring word occurs approximately twice as often as the second most frequent word. This is Zipf’s Law.

We have set up a git repository with a sequence of branches to step through the tutorial today. You should start by cloning the repository

BASH

$ git clone repository work_dir

OUTPUT

Cloning into 'work_dir'...
done.

Change to the new directory, checkout the branch 06-documentation, and list the branches

BASH

$ cd work_dir
$ git checkout 06-documentation
$ git branch -a

OUTPUT

* 06-documentation
  remotes/origin/01-command-line
  remotes/origin/02-first-makefile
  remotes/origin/03-no-hands
  remotes/origin/04-testing
  remotes/origin/05-standards
  remotes/origin/06-documentation
  remotes/origin/HEAD -> origin/06-documentation

Today, we will start with the branch 01-command-line and step through the numbered branches arriving at the branch 06-documentation which uses all of the tool we will introduce.

First let’s peek at the final results

BASH

$ make

View the result with (depending on your OS)

BASH

$ evince build/report.pdf

BASH

$ make docs

View the result with (depending on your OS)

BASH

$ firefox build/docs/html/index.html

Let’s take a couple of minutes to skim the document.

Now clean up and start with the 01-command-line branch

BASH

$ make clean
$ git switch -c my-01-branch remotes/origin/01-command-line
$ git branch -a

The output of the last command should be

OUTPUT

  06-documentation
* my-01-branch
  remotes/origin/01-command-line
  remotes/origin/02-first-makefile
  remotes/origin/03-no-hands
  remotes/origin/04-testing
  remotes/origin/05-standards
  remotes/origin/06-documentation
  remotes/origin/HEAD -> origin/06-documentation

Look at the files the files that git provides and in the directory

BASH

$ git ls-files

OUTPUT

.gitignore
README
abyss.txt
analyze.py
isles.txt
local.bib
report.tex

BASH

$ ls

OUTPUT

README     analyze.py  local.bib   src
abyss.txt  isles.txt   report.tex

The directory src is left over from using the 06-documentation branch for the preview. Let’s remove it

$ rm -r src

Now build the document pdf by following the instructions in the README file.

BASH

$ cat README

OUTPUT

To build report.pdf we need the following:

1. Insert data from abyss.dat into report.tex

2. Insert into report.tex counts of the two most frequent words and
their ratio for abyss.txt and isles.txt.

3. The figure files abyss.pdf and isles.pdf

One can generate the required information and build the document as
follows:

1. From the command line, run

    $ python analyze.py abyss.txt abyss.dat abyss.pdf
    $ python analyze.py isles.txt isles.dat isles.pdf

2. Enter the top_two counts reported above into the report.tex source
with the calculated ratios.  It should look like this:

    Book & First & Second & Ratio\\ \hline
    abyss & 4044 & 2807 & 1.44 \\
    isles & 3822 & 2460 & 1.55 \\
    \hline

3. Copy and paste the first two items in each of the first ten lines
from abyss.dat into report.tex.  Those lines should be:

    the 4044
    and 2807
    of 1907
    a 1594
    to 1515
    in 1221
    i 974
    was 695
    it 680
    for 675

4.Run latexmk to build the document:

    $ latexmk -pdf report.tex

If you are not sure you did it right, you can start over by running:

    $ rm *.dat *.pdf *.aux *.bbl *.blg *.fdb_latexmk *.fls

or if you have clobbered some source files:

    $ rm * ; git checkout .

Key Points

• We hope to improve on executing instructions from a README.