* Getting rid of old cheat sheets

*   Indenting error output cells
*   Removing explicit 'level' keys from Markdown files
*   Storing the generated files so that people who don't use those tools won't have to regenerate them.
*   Modifying .gitignore to reflect this.
*   Updating the Makefile to run Jekyll exactly once.
*   Command to install on the server
*   No longer worrying about making a page of images
*   Better (more guessable) name for the target that builds the website
*   Fixing image paths
*   Fixing up glossary entries

.gitignore

@@ -1,26 +1,7 @@
-*~
 *.pyc
+*~
 .DS_Store
 .ipynb_checkpoints
 _site
-tmp
-image-page.html
-tmp-book.*
-patched-gloss.md
-*/*/*_files
-lessons/misc-r/full-R-bootcamp/R-basics/01-basics-of-R.md
-lessons/misc-r/full-R-bootcamp/R-basics/rstudio-basics.md
-lessons/misc-r/full-R-bootcamp/R-basics/02-data-structures.md
-lessons/misc-r/full-R-bootcamp/R-basics/03-best-practices.md
-lessons/misc-r/full-R-bootcamp/R-basics/04-seeking-help.md
-lessons/misc-r/full-R-bootcamp/R-basics/05-subsetting.md
-lessons/misc-r/full-R-bootcamp/R-basics/06-vectorization.md
-lessons/misc-r/full-R-bootcamp/R-basics/best-practices.md
-lessons/misc-r/full-R-bootcamp/functions/01-functions.md
-lessons/misc-r/full-R-bootcamp/functions/02-control_structures.md
-lessons/misc-r/full-R-bootcamp/functions/03-scoping_rules.md
-lessons/misc-r/full-R-bootcamp/data-manipulation/00-messy_data.md
-lessons/misc-r/full-R-bootcamp/data-manipulation/01-input-output.md
-lessons/misc-r/full-R-bootcamp/data-manipulation/02-apply-family.md
-lessons/misc-r/full-R-bootcamp/data-manipulation/03-split-apply.md
-lessons/misc-r/full-R-bootcamp/testing-documentation/testing.md
+book.md
+cached/novice/*/*_files

Makefile

@@ -1,191 +1,122 @@
-#-----------------------------------------------------------
+#======================================================================
 # Re-make lecture materials.
-#-----------------------------------------------------------
+#======================================================================
 
 # Directories.
-OUT = _site
-LINK_OUT = /tmp/bc-links
-BOOK = _book
-INSTALL_DIR = $(HOME)/sites/software-carpentry.org/v5
-
-# Source Markdown pages.
-MARKDOWN_SRC = \
-	LICENSE.md \
-	contents.md \
-	bib.md \
-	gloss.md \
-	rules.md \
-	setup.md \
-	team.md \
-	intro.md \
-	$(sort $(wildcard novice/shell/*.md)) \
-	$(sort $(wildcard novice/git/*.md)) \
-	$(sort $(wildcard novice/python/*.md)) \
-	$(sort $(wildcard novice/sql/*.md)) \
-	$(sort $(wildcard novice/extras/*.md)) \
-	$(sort $(wildcard novice/teaching/*.md)) \
-	$(sort $(wildcard novice/ref/*.md))
-
-NOTEBOOK_SRC = \
-	$(sort $(wildcard novice/python/??-*.ipynb)) \
-	$(sort $(wildcard novice/sql/??-*.ipynb))
-
-# Slides.
-SLIDES_SRC = \
-	$(sort (wildcard slides/*.html))
-SLIDES_DST = \
-	$(patsubst %.html,$(OUT)/%.html,$(SLIDES_SRC))
-
-NOTEBOOK_MD = \
-	$(patsubst %.ipynb,%.md,$(NOTEBOOK_SRC))
-
-HTML_DST = \
-	$(patsubst %.md,$(OUT)/%.html,$(MARKDOWN_SRC)) \
-	$(patsubst %.md,$(OUT)/%.html,$(NOTEBOOK_MD))
-
-# Source for book (in order, with some substutitions).
-BOOK_SRC = \
-	intro.md \
-	team.md \
-	novice/shell/index.md $(sort $(wildcard novice/shell/??-*.md)) \
-	novice/git/index.md $(sort $(wildcard novice/git/??-*.md)) \
-	novice/python/index.md $(patsubst %.ipynb,%.md,$(sort $(wildcard novice/python/??-*.ipynb))) \
-	novice/sql/index.md $(patsubst %.ipynb,%.md,$(sort $(wildcard novice/sql/??-*.ipynb))) \
-	novice/extras/index.md $(sort $(wildcard novice/extras/??-*.md)) \
-	novice/teaching/index.md  $(sort $(wildcard novice/teaching/??-*.md)) \
-	novice/ref/index.md  $(sort $(wildcard novice/ref/??-*.md)) \
-	bib.md \
-	tmp/gloss.md \
-	rules.md \
-	LICENSE.md
+SITE = _site
+INSTALL = $(HOME)/sites/software-carpentry.org/v5
+LINKS = /tmp/bc-links
+CACHED = cached
 
-BOOK_TMP = \
-	$(patsubst %,tmp/%,$(BOOK_SRC))
+# Templates for nbconvert and Pandoc.
+IPYNB_TPL = _templates/ipynb.tpl
 
-BOOK_DST = $(OUT)/book.html
+# Temporary book file.
+BOOK_MD = ./book.md
 
-# Mark cached versions of compiled notebooks as SECONDARY so that GNU
-# Make won't delete them after rebuilding.
-.SECONDARY : $(NOTEBOOK_MD)
+# Principal target files.
+INDEX = $(SITE)/index.html
 
-#-----------------------------------------------------------
-
-# Default action: show available commands (marked with double '#').
-all : commands
-
-## quick    : build just the bootcamp home page.
-quick : $(OUT)/index.html
-	jekyll -t build -d $(OUT)
-
-## install  : install on the server.
-install : $(OUT)/index.html
-	rm -rf $(INSTALL_DIR)
-	cp -r _site $(INSTALL_DIR)
-	mv $(INSTALL_DIR)/contents.html $(INSTALL_DIR)/index.html
+# Directives.
+.INTERMEDIATE : $(BOOK_MD)
 
-## site     : build site.
-site : $(BOOK_DST)
+#----------------------------------------------------------------------
+# Specify the default target before any other targets are defined so
+# that we're sure which one Make will choose.
+#----------------------------------------------------------------------
 
-$(BOOK_DST) : $(OUT)/index.html $(BOOK_TMP) _templates/book.tpl tmp/gloss.md bin/make-book.py
-	python bin/make-book.py $(BOOK_TMP) \
-	| pandoc --email-obfuscation=none --template=_templates/book.tpl -t html -o - \
-	| sed -e 's!../../gloss.html#!#g:!g' \
-	| sed -e 's!../gloss.html#!#g:!g' \
-	> $@
-
-# Build HTML versions of Markdown source files using Jekyll.
-$(OUT)/index.html : $(MARKDOWN_SRC) $(NOTEBOOK_MD)
-	jekyll -t build -d $(OUT)
-	sed -i -e 's!img src="novice/python/!img src="!g' $(OUT)/novice/python/??-*.html
-
-index.html setup.md : _includes/setup.html
-
-# Build Markdown versions of IPython Notebooks.
-%.md : %.ipynb _templates/ipynb.tpl
-	ipython nbconvert --template=_templates/ipynb.tpl --to=markdown --output="$(subst .md,,$@)" "$<"
-
-# Patch targets and links in the glossary for inclusion in the book.
-tmp/gloss.md : gloss.md
-	@mkdir -p $$(dirname $@)
-	sed -e 's!](#!](#g:!g' -e 's!<a name="!<a name="g:!g' $< > $@
+all : commands
 
-# Patch image paths in the sections.
-tmp/novice/shell/%.md : novice/shell/%.md
-	@mkdir -p $$(dirname $@)
-	sed -e 's!<img src="img!<img src="novice/shell/img!g' $< > $@
+#----------------------------------------------------------------------
+# Create Markdown versions of IPython Notebooks in CACHED directory.
+#----------------------------------------------------------------------
 
-tmp/novice/git/%.md : novice/git/%.md
-	@mkdir -p $$(dirname $@)
-	sed -e 's!<img src="img!<img src="novice/git/img!g' $< > $@
+# IPython Notebooks (split by directory so that they can be
+# interpolated into other variables later on).
+IPYNB_SRC_PYTHON = $(sort $(wildcard novice/python/??-*.ipynb))
+IPYNB_SRC_SQL = $(sort $(wildcard novice/sql/??-*.ipynb))
 
-tmp/novice/python/%.md : novice/python/%.md
-	@mkdir -p $$(dirname $@)
-	sed -e 's!<img src="img!<img src="novice/python/img!g' $< > $@
+# Notebooks converted to Markdown.
+IPYNB_TX_PYTHON = $(patsubst %.ipynb,$(CACHED)/%.md,$(IPYNB_SRC_PYTHON))
+IPYNB_TX_SQL = $(patsubst %.ipynb,$(CACHED)/%.md,$(IPYNB_SRC_SQL))
 
-tmp/novice/sql/%.md : novice/sql/%.md
-	@mkdir -p $$(dirname $@)
-	sed -e 's!<img src="img!<img src="novice/sql/img!g' $< > $@
+# Convert a .ipynb to .md.
+$(CACHED)/%.md : %.ipynb $(IPYNB_TPL)
+	ipython nbconvert --template=$(IPYNB_TPL) --to=markdown --output="$(subst .md,,$@)" "$<"
 
-tmp/novice/extras/%.md : novice/extras/%.md
-	@mkdir -p $$(dirname $@)
-	sed -e 's!<img src="img!<img src="novice/extras/img!g' $< > $@
+#----------------------------------------------------------------------
+# Build everything with Jekyll.
+#----------------------------------------------------------------------
 
-# All other Markdown files used in the book.
-tmp/%.md : %.md
-	@mkdir -p $$(dirname $@)
-	cp $< $@
+# Book source (in Markdown).  These are listed in the order in which
+# they appear in the final book-format version of the notes, and
+# include Markdown files generated by other tools from other formats.
+BOOK_SRC = \
+	intro.md \
+	team.md \
+	novice/shell/index.md $(sort $(wildcard novice/shell/??-*.md)) \
+	novice/git/index.md $(sort $(wildcard novice/git/??-*.md)) \
+	novice/python/index.md $(IPYNB_TX_PYTHON) \
+	novice/sql/index.md $(IPYNB_TX_SQL) \
+	novice/extras/index.md $(sort $(wildcard novice/extras/??-*.md)) \
+	novice/teaching/index.md  $(sort $(wildcard novice/teaching/??-*.md)) \
+	novice/ref/index.md  $(sort $(wildcard novice/ref/??-*.md)) \
+	bib.md \
+	gloss.md \
+	rules.md \
+	LICENSE.md
 
-#-----------------------------------------------------------
+# All source pages (including things not in the book).
+PAGES_SRC = \
+	contents.md \
+	$(BOOK_SRC)
+
+# Build the temporary input for the book by concatenating relevant
+# sections of Markdown files, patching glossary references and image
+# paths, and then running the whole shebang through Jekyll at the same
+# time as everything else.
+$(BOOK_MD) : $(PAGES_SRC) bin/make-book.py
+	python bin/make-book.py $(BOOK_SRC) > $@
+
+# Convert from Markdown to HTML.  This builds *all* the pages (Jekyll
+# only does batch mode), and erases the SITE directory first, so
+# having the output index.html file depend on all the page source
+# Markdown files triggers the desired build once and only once.
+$(INDEX) : $(BOOK_MD)
+	jekyll -t build -d $(SITE)
+
+#----------------------------------------------------------------------
+# Targets.
+#----------------------------------------------------------------------
 
 ## commands : show all commands.
 commands :
 	@grep -E '^##' Makefile | sed -e 's/## //g'
 
+## site    : build the site as GitHub will see it.
+site : $(INDEX) $(BOOK)
+
+## install  : install on the server.
+install : $(INDEX)
+	rm -rf $(INSTALL)
+	mkdir -p $(INSTALL)
+	cp -r $(SITE)/* $(INSTALL)
+	mv $(INSTALL)/contents.html $(INSTALL)/index.html
+
 ## contribs : list contributors (uses .mailmap file).
 contribs :
 	git log --pretty=format:%aN | sort | uniq
 
 ## fixme    : find places where fixes are needed.
 fixme :
-	@grep -i -n FIXME $$(find -f shell git python sql -type f -print | grep -v .ipynb_checkpoints)
-
-## gloss    : check glossary.
-gloss :
-	@bin/gloss.py ./gloss.md $(MARKDOWN_DST) $(NOTEBOOK_DST)
-
-## images   : create a temporary page to display images.
-images :
-	@bin/make-image-page.py $(MARKDOWN_SRC) $(NOTEBOOK_SRC) > image-page.html
-	@echo "Open ./image-page.html to view images"
-
-## valid    : check validity of HTML book.
-# Depends on xmllint to check validity of generated pages.
-# Also depends on linklint, an HTML link-checking module from
-# http://www.linklint.org/, which has been put in bin/linklint.
-# Look in output directory's 'error.txt' file for results.
-valid : tmp-book.html
-	xmllint --noout tmp-book.html 2>&1 | python bin/unwarn.py
-	@bin/linklint -doc $(LINK_OUT) -textonly -root $(OUT) /@
+	@grep -i -n FIXME $$(find novice -type f -print | grep -v .ipynb_checkpoints)
 
 ## clean    : clean up all generated files.
 clean : tidy
-	@rm -rf $(OUT) $(NOTEBOOK_MD)
+	rm -rf $(SITE)
 
-## tidy     : clean up intermediate files only.
+## tidy     : clean up odds and ends.
 tidy :
-	@rm -rf \
-	image-page.html \
-	tmp \
+	rm -rf \
 	$$(find . -name '*~' -print) \
-	$$(find . -name '*.pyc' -print) \
-	$$(find . -name '??-*_files' -type d -print)
-
-# show variables (for debugging)
-show :
-	@echo "OUT" $(OUT)
-	@echo "TMP" $(TMP)
-	@echo "LINK_OUT" $(LINK_OUT)
-	@echo "MARKDOWN_SRC" $(MARKDOWN_SRC)
-	@echo "NOTEBOOK_SRC" $(NOTEBOOK_SRC)
-	@echo "NOTEBOOK_MD" $(NOTEBOOK_MD)
-	@echo "HTML_DST" $(HTML_DST)
+	$$(find . -name '*.pyc' -print)