Makefile for building classwork from markdown files and LaTeX

Question

The following makefile builds my classwork for my various college classes and builds pdfs to hold the notes I took during class. I would like feedback on my directory structure and any optimizations that can be thought of to help improve it. I've been using and updating it for the past 18 months. I know that I should probably document it a bit better

The directory structure of the classes is as follows

ROOT
|- (class short code)
|  |- various subdirs for classwork
|- .. repeated for each of the classes I'm taking this semester
|- old
|  |- s1 (classes from semester 1)
|  |- s2 (classes from semester 2)
|- mybib.bib (biblatex file for sources)

The makefile is then as follows

# Makefile for college essays
#

PANDOC  := pandoc 
#LATEX_FLAGS := -interaction=batchmode

SEARCHDIR  := $(shell find ./* -prune -type d \( ! -name "old*" \) -print)
LATEXFILES := $(shell find ${SEARCHDIR} -name '*.tex')
MARKDOWN   := \
    $(shell find ${SEARCHDIR} \( -name '*.md' -and ! -path '*node_modules*' \))
DOT_GRAPHS := $(shell find ${SEARCHDIR} -name '*.dot')
SLIDESHOWS := $(shell find ${SEARCHDIR} -name '*.slideshow')

# Pandoc Stuff
TEMPLATE   := college.latex
BIBFILE    := mybib.bib

PDFS       := $(MARKDOWN:.md=.pdf) $(LATEXFILES:.tex=.pdf)
#DOCX       := $(MARKDOWN:.md=.docx)
GRAPHOUT   := $(DOT_GRAPHS:.dot=.eps)
SLDESHWOUT := $(SLIDESHOWS:.slideshow=.ss.pdf)
NULLREDIR:= #> /dev/null

# Begin Primary Target
all: $(PDFS) $(GRAPHOUT) $(SLDESHWOUT)

# target to just build the latex documents
latex-out: $(LATEXFILES:.tex=.pdf)

# Clean up targets
clean: mdclean texclean dotclean
mdclean:
    rm -f $(PDFS)
texclean:
    rm -f *.aux
    rm -f *.bbl
    rm -f *.bbl
    rm -f *.log
    rm -f *.blg
    rm -f *.xml
    rm -f *.out
    rm -f *.bcf
dotclean:
    rm -f $(GRAPHOUT)
    rm -f $(DOT_GRAPHS:.dot=-eps-converted-to.pdf)

#######################################
# Build Rules for Various File Types
#######################################
%.pdf: %.md college.latex apa.csl
    $(info $@ from $<)
    @${PANDOC} --bibliography ${BIBFILE} --filter pandoc-citeproc \
        $< -o $@ --template ${TEMPLATE}

%.pdf: %.tex mybib.bib
    -$(info $@ from $<)
    -pdflatex ${LATEX_FLAGS} $< $(NULLREDIR)
    -if [ -e $(notdir $(basename $<)).bcf ] ; then \
            biber $(notdir $(basename $<)).bcf $(NULLREDIR) ; \
        else \
            bibtex $(notdir $(basename $<)).aux $(NULLREDIR) ; \
        fi
    -pdflatex ${LATEX_FLAGS} $< $(NULLREDIR)
    -pdflatex ${LATEX_FLAGS} $< $(NULLREDIR)
    -mv $(notdir $@) $@ $(NULLREDIR)
    -rm -f $(basename $<).aux

%.ss.pdf: %.slideshow
    pandoc --bibliography ${BIBFILE} -f markdown \
        -t beamer $< -o $@


%.eps: %.dot
    dot -Teps $< -o $@

%.png: %.dot
    dot -Tpng $< -o $@

include depend.makefile

Answer 1

I have a similar script. So from my experiences I would:

build the pdfs through latexmk

sometimes it needs more runs of pdflatex. I found it too hard to get right in plain make.

have directories for work and artefacts.

I don't like to have temporary files among my carefully written texts. The risk of an accidental rm or overwrite is just always present.
Generally the idea is to split files into: pure input, files that are created. And also these split into files that can be discarded and which should be archived (say they were handed in).

I found it useful to have a "work" directory for the dirty stuff. It helps to give each document its own subfolder. In latexmk I can use the -o parameter as -o work/($basename $<)/. That keeps files reasonably separated. Then I can also do parallel builds.

Stuff that needs to be kept can just be moved over with a rule to copying them. Cleaning also gets much easier as you can just wipe the work folder empty.

make smaller projects

I would at least at the class level give them their separate makefile and directory structure. Personally I do it per each document. Just imagine that after say a year you need to adjust something in the build - and then you end up debugging all your previous essays makefiles and/or text to not lose them.

Not makefile related - but useful is to have the texts in git repositories. If you put all in one monolithic project the history is going to be very messy. Much easier to follow on a per project basis.