================================
=== Mako's Beamer Templates ====
================================

Copyright (c) 2013-2026 Benjamin Mako Hill <mako@atdot.cc> / <makohill@uw.edu>

This repository contains a Beamer presentation template I use for my
own presentations. Others in the CDSC lab also use it for lab
presentations. It is released under the GNU GPL version 3 or later.

The latest version can be found on GitLab at:
https://gitlab.com/makoshark/beamer-mako

You can clone the repository with:

  git clone https://gitlab.com/makoshark/beamer-mako.git

Bug reports, comments, questions, and patches can be directed to:

  Benjamin Mako Hill <makohill@uw.edu> [work]
  Benjamin Mako Hill <mako@atdot.cc> [personal]

Patches can be submitted as merge requests via GitLab, or by cloning
the repository and sending patches by email:

  git format-patch origin/master
  git send-email *.patch

================================
=== Dependencies ===============
================================

On Debian or Ubuntu, install the following packages:

  * latexmk
  * texlive-luatex
  * texlive-latex-recommended
  * texlive-latex-extra

  apt install latexmk texlive-luatex texlive-latex-recommended \
  texlive-latex-extra

On other systems, installing a full TeX Live distribution should provide
everything needed.

The template uses the Metropolis Beamer theme, bundled in the template/
directory along with the OpenSans and RobotoMono fonts it requires.

================================
=== Accessibility ==============
================================

Slides are built as tagged PDFs that validate against PDF/UA-2
(ISO 14289-2), which is what upload targets like Canvas check for. Check
a file with veraPDF (https://verapdf.org/):

  verapdf -f ua2 my-talk.pdf

The pieces that do this work are:

  * \DocumentMetadata declares PDF/UA-2, PDF 2.0, and the document
    language. The language tag tells a screen reader how to pronounce
    the text.
  * tagpdf with activate-all turns tagging on.
  * The frametitle template is patched to emit H1 tags, since Beamer
    does not treat frame titles as headings on its own.
  * unicode-math replaces the Computer Modern math fonts, which carry no
    Unicode mappings and leave formulas unreadable to assistive software.
  * \hypersetup{pdfdisplaydoctitle=true} makes viewers announce the
    document title instead of the filename.
  * The tikz overlays behind \credit, \marktopleft, and \markbottomright
    are marked as artifacts so they stay out of the reading order.

Use a slides-only build (make slides) for anything shared. Builds that
include speaker notes do not validate, because Beamer repeats the frame
title and section headings on the notes half of each page.

Validating is not the same as being accessible, and this template does
the first better than the second. Frame titles and links are tagged;
body text, lists, and figures are not, so a screen reader gets the
outline of a talk rather than its contents. Closing that gap needs
automatic tagging from the LaTeX kernel (\DocumentMetadata{tagging=on}),
which requires TeX Live 2025 or later and is waiting on Overleaf to
support it, and Beamer support in the LaTeX Tagging Project, which does
not exist yet. The alt={...} arguments in the template are written for
that day; they are dropped by the current toolchain.

================================
=== Scripts ====================
================================

new_beamer_presentation
-----------------------
Creates a new presentation directory from the template. Takes a
destination directory as its argument:

  new_beamer_presentation <directory>

Example:

  new_beamer_presentation my-talk

This creates my-talk/ populated with the template files, with the main
source file renamed to my-talk.tex. Fonts are symlinked from the source
repository rather than copied, so the repository must remain in place.

Symlink the script into your PATH with:

  ln -s ~/tex/beamer-mako/new_beamer_presentation ~/bin/
