From c7aa5d9e9265a2ca17df42efadfdde088fca4c92 Mon Sep 17 00:00:00 2001 From: Benjamin Mako Hill Date: Sat, 15 Aug 2026 10:04:10 +0900 Subject: [PATCH] convert README to markdown --- README => README.md | 104 ++++++++++++++++++++++++-------------------- new_tex_uwletter | 2 +- 2 files changed, 57 insertions(+), 49 deletions(-) rename README => README.md (62%) diff --git a/README b/README.md similarity index 62% rename from README rename to README.md index 97d8280..87711db 100644 --- a/README +++ b/README.md @@ -1,6 +1,4 @@ -================================ -=== UW LaTeX Letterhead ======== -================================ +# UW LaTeX Letterhead Copyright (c) 2018-2026 Benjamin Mako Hill / Copyright (c) 2017 Sayamindu Dasgupta @@ -14,13 +12,12 @@ distributed as a Microsoft Word "DOCX" file by UW Brand and Creative Services. -Requirements -============= +## Requirements Because this document uses OpenType and TrueType fonts and produces -tagged, accessible PDF/UA-2 output, it requires LuaLaTeX -(https://www.luatex.org/) (not XeLaTeX or PDFLaTeX). LuaLaTeX is -supported by Overleaf (https://overleaf.com/) although it is not the +tagged, accessible PDF/UA-2 output, it requires +[LuaLaTeX](https://www.luatex.org/) (not XeLaTeX or PDFLaTeX). LuaLaTeX +is supported by [Overleaf](https://overleaf.com/) although it is not the default. On Debian or Ubuntu, install the following packages: @@ -30,8 +27,10 @@ On Debian or Ubuntu, install the following packages: * texlive-latex-recommended * texlive-latex-extra - apt install latexmk texlive-luatex texlive-latex-recommended \ +``` +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 tagging code requires TeX Live 2025 or later. On @@ -43,29 +42,32 @@ The two required fonts, Matrix-II and OpenSans, are both included in this repository, so no additional font packages are needed. -Accessibility -============= +## Accessibility The letter is a tagged PDF declaring PDF/UA-2 (ISO 14289-2). Two keys -in the \DocumentMetadata block at the top of the .tex file do this, -and both are needed: tagging=on loads the kernel code that puts the -text into the PDF's structure tree, and pdfstandard=ua-2 writes the +in the `\DocumentMetadata` block at the top of the .tex file do this, +and both are needed: `tagging=on` loads the kernel code that puts the +text into the PDF's structure tree, and `pdfstandard=ua-2` writes the conformance claim. -You can check a built letter with veraPDF (https://verapdf.org/): +You can check a built letter with [veraPDF](https://verapdf.org/): - verapdf -f ua2 washington_letterhead_letter-matrix-deptartment.pdf +``` +verapdf -f ua2 washington_letterhead_letter-matrix-deptartment.pdf +``` Note that a PASS is necessary but not sufficient. A letter whose body text is all marked as artifact passes too, because the standard only -requires that content which is not real be an artifact. +requires that content which is not real be an artifact. You can confirm there is something in the structure tree as well: - python3 -c "import pikepdf,sys; d=pikepdf.open(sys.argv[1]); \ - print(d.Root.get('/StructTreeRoot') and 'tagged' or 'UNTAGGED')" file.pdf +``` +python3 -c "import pikepdf,sys; d=pikepdf.open(sys.argv[1]); \ + print(d.Root.get('/StructTreeRoot') and 'tagged' or 'UNTAGGED')" file.pdf +``` -The signature image carries an alt= description, which is what a +The signature image carries an `alt=` description, which is what a screen reader announces in place of it. Keep that in place if you swap in your own signature. @@ -74,8 +76,7 @@ like other running header content, so it is skipped rather than described. -Encrypted signature files -=========================== +## Encrypted signature files If you'd like, you can encrypt the signature file. There are several lines in the Makefile you can uncomment to do this. We've included an @@ -85,19 +86,22 @@ customize this. To use this, you will also need GNU Privacy Guard (GPG) installed on your system. -Scripts -======== +## Scripts + +### new_tex_uwletter -new_tex_uwletter ------------------ Creates a new letter directory from the template. Takes a destination directory as its argument: - new_tex_uwletter +``` +new_tex_uwletter +``` Example: - new_tex_uwletter my-letter +``` +new_tex_uwletter my-letter +``` This creates my-letter/ populated with the template files, with the main source file renamed to my-letter.tex. Fonts are symlinked from @@ -106,39 +110,42 @@ remain in place. Symlink the script into your PATH with: - ln -s ~/tex/uw_tex_letterhead/new_tex_uwletter ~/bin/ +``` +ln -s ~/tex/uw_tex_letterhead/new_tex_uwletter ~/bin/ +``` -Contributing changes -======================= +## Contributing changes If you notice issues with this template, please fix them and contribute back a patch so others can benefit! The latest version can be found at: -https://gitea.communitydata.science/mako/uw_tex_letterhead + You can clone the repository with: - git clone https://gitea.communitydata.science/mako/uw_tex_letterhead.git +``` +git clone https://gitea.communitydata.science/mako/uw_tex_letterhead.git +``` Patches can be submitted by email to Benjamin Mako Hill: - Benjamin Mako Hill [work] - Benjamin Mako Hill [personal] +* Benjamin Mako Hill \[work] +* Benjamin Mako Hill \[personal] + +``` +git format-patch origin/master +git send-email *.patch +``` - git format-patch origin/master - git send-email *.patch - - -Copyright and Usage -===================== +## Copyright and Usage This template was modeled after the Microsoft Word "Matrix" stationery template published by UW Brand and Creative Services here: -https://www.washington.edu/brand/templates/stationery/ + It is hopefully obvious that there are many ethical and legal restrictions on when one can and cannot (and should or shouldn't) use @@ -147,13 +154,14 @@ official communication). If you have any questions, contact UW Brand and Creative Services at the link above. This TeX template itself was created by Benjamin Mako Hill and -Sayamindu Dasgupta. We dedicated the work to the public domain by waiving all of our -rights to the work worldwide under copyright law, including all -related and neighboring rights, to the extent allowed by law. You can -copy, modify, distribute and perform the work, even for commercial -purposes, all without asking permission. +Sayamindu Dasgupta. We dedicated the work to the public domain by +waiving all of our rights to the work worldwide under copyright law, +including all related and neighboring rights, to the extent allowed by +law. You can copy, modify, distribute and perform the work, even for +commercial purposes, all without asking permission. -See details here: https://creativecommons.org/publicdomain/zero/1.0/ +See details here: + As a result, if you completely remove the UW branding, there are no restrictions on how you can use the work in this repository. diff --git a/new_tex_uwletter b/new_tex_uwletter index a548bca..7d407c6 100755 --- a/new_tex_uwletter +++ b/new_tex_uwletter @@ -23,7 +23,7 @@ then mv "$WORK_DIR" "$1" cd "$1" mv "washington_letterhead_letter-matrix-deptartment.tex" "$(basename "$1").tex" - rm -f "new_tex_uwletter" "README" "COPYING" + rm -f "new_tex_uwletter" "README.md" "COPYING" # create a symlink farm for the fonts rm -rf ./fonts/*