Reading the Text and Secret Handshakes

The computer is exact, authors are not. Authors are lazy and sloppy, so mistakes slip though. We hope these common text conventions and text idioms will help you understand what the authors probably meant.

# this is a comment, in bash, python, and many other languages.
# comments can be multiline

/* in some languages, comments look like this */

# '$' implies a 'unix/terminal/bash' prompt
$ mycommand  # <- you would type [mycommand] at your prompt.

# typically, if a line starts with '$ ' (note the space!)
# you type the rest of the line *as is*.
# and the output is given without a $....
$ pwd

# note that the '$ ' is shorthand for *your prompt*,
# and you don't actually type the '$ '
>>> # remember, '#' is a comment line in python too
>>> # the 'triple chevron' implies a 'python command line'
>>> # you might get this line from your prompt by
>>> # typing ->  $ python
>>> "a string"
'a string'
>>> # don't type the chevrons!
keyboard font
type the command as written, substituting in for things like mydir as appropraite.
foo, bar, /some/path, some_function, some_var
standard ‘fake’ or ‘generic’ variables, methods, variables
your_function, yourname, mylogin
your and my tend to imply whatever it is you chose.
> File > Print Preview
Typically single chevron implies heirarchical nesting. Most commonly, this is used when describing GUI (graphical user interface) commands.
Can mean either the python promt, or command line prompt
unix / bash / terminal / shell / command line / CLI
For the purposes of these tutorials, these all mean ‘the command line bit where you interact with the system. Authors tend to be sloppy and conflate these.
home directory

On UNIX-like systems, where ‘your stuff’ lives. Typically written with the tilde ~ character. Often, the cd command will take you to your home directory.

Ex: ~someuser might expand to /Users/someuser (on OSX).

Learn the Keyboard!

symbol   name (in programming)
=======  ==============================
#        octothorpe, hash, pound
()       parens, parentheses
{}       left and right brace
[]       left and right bracket
<>       greater than, less than
~        tilde
`        backtick, backquote
''       quote
""       double quote
-        dash,hyphen (for programmers)
/        slash, forward slash
\        backslash
!        bang, exclamation point
|        pipe (vertical bar)
*        star, asterisk
=======  ==============================

Common Actions

navigate (or ‘go to’)
  1. in a web context: open a url in your browser, or follow some link by clicking.

    ex.: Navigate to localhost -> (open http://localhost/ )

  2. at the prompt: cd or change directory to some path.

    ex.: “Go to your project directory” -> $ cd ~yourname/yourproject

open the file in your text editor of choice (Gedit, Vim, TextEdit, XCode, etc.)
save the file to the file system.

add and commit the files (or equivalent) in your source control system. (git, mercurial/hg, svn and friends)

# in git, for example
git add yourfile
git commit -m "some message"
  1. in a web context: look around at the page, see what links are there. Alt., view source (often by ‘right-clicking’ on a web page).
  2. In a CLI context, use commands like pwd, ls and friends to see what files are in a directory, how large they are (using ls -l), etc. When doing so, one should be thinking about why those files are there, what they do, etc.
  3. In a Python context, use dir(mything), help(mything), print mything and the like to discover its properties and values.

Check your Understanding

  1. Which of these are unix commands, and which are Python commands?

    1. $ ls
    2. >>> import time
    3. # I don't know what is going on here!
    1. unix (bash).
    2. python. it imports the time module.
    3. could be either :). It’s a comment, in any case!
  2. Explain what this instruction means:

    Go to http://some/url. Save the source as somedir/source.html.

  3. “Explore your home directory.” What might the author expect you to do?

    $ # on unix
    $ cd ~
    $ ls
    $ ls -alF  # shows *all* files, in *long* format