using pub.pl

the pub.pl tool is what is called a command line application, a terminal program, or a shell program. this means that it has no graphical interface, and operates simply by reading and writing text to and from files and the keyboard.

to interface with command line tools, we need to use a terminal emulator. on Mac OS X this is the Terminal app in the Utilities folder (/Applications/Utilities/Terminal.app). on newer versions of the OS, the Utilities folder is sometimes hidden; you can reach it by switching to the Finder, holding down Command and Shift, and pressing the U key. on Linux, this is a tool such as gnome-terminal, mate-terminal, or urxvt.

once you've opened the terminal, there are a few core concepts you need to understand.

the shell

the shell is the command-line application that starts running as soon as you load the terminal. it displays a prompt (by default, usually a string ending in $) and accepts commands. the shell handles basic file management tasks and launching other applications.

you enter a command into a shell by typing it into the window and pressing the Return or Enter key. the command performs a task like moving a file or launching a program. when the command finishes, another prompt will be displayed. many commands do not print anything while they are running, so you will simply see a cursor sitting on a blank line until they terminate.

running pub.pl

the only commands you need to understand in order to run pub.pl is the cd command. the shell can be thought of a bit like a Finder window. a Finder window displays a view of a single folder and lets you take actions on the contents. in the shell's case, this folder is known as the working directory.

the cd command changes the working directory. it's the analogue of double-clicking on a folder. in order to run pub.pl, we need to change the working directory to the one that pub,pl is located in. the precise command needed varies depending on where you've put the folder containing your website. if it's in your home folder, you can reach it with the command cd ~/evergreen; if it's on your desktop, you can reach it with cd ~/Desktop/evergreen. if you've changed the name from evergreen, you should write that new name instead.

(a useful trick is shell autocomplete -- once you typed part of a name, you can press the Tab key and the shell will try to figure out what file or folder you meant.)

once you've reached the right directory, you can run pub.pl and generate your site. you do this by entering ./pub.pl at the prompt and pressing Enter. if you receive an error, try running chmod +x pub.pl and then trying again.

as pub.pl runs, it will display its current status, printing a list of the files it is operating on. once it has finished, it will display the text ok and then return you to your shell.

it might be useful to keep a shell open while you work on your website so you can quickly regenerate it. if you do this, it might be useful to know that you can re-run the last command simply by pressing the up arrow and then pressing Enter as usual.

output

the compiled forms of the input files are stored in the out folder. you can double-click on them to open them in a browser. to upload them to your web host, see uploading.

technical details

pub.pl is not a binary. as the name suggests, it is self-contained script written in the Perl programming language with no external dependencies besides the Perl interpreter. it should be broadly portable to any POSIX-compliant operating system, and it's possible it runs on Windows, at least under Cygwin. i don't know, haven't tried, and don't care.

pub.pl ignores all files and folders whose names begin with ., keeping out profligate nonsense like the .DS_Store files OSX so enjoys spamming all over every filesystem it gets its greasy hands on, and allowing you to place metadata of your own choosing inside the source tree.

the source code of pub.pl is poorly commented and thorny as hell; it in general should be edited only with extreme care and looked upon only as a source of horrified amusement.