convert README to markdown

README.md

@@ -1,6 +1,4 @@
-================================
+# UW LaTeX Letterhead
-=== UW LaTeX Letterhead ========
-================================
 
 Copyright (c) 2018-2026 Benjamin Mako Hill <mako@atdot.cc> / <makohill@uw.edu>
 Copyright (c) 2017 Sayamindu Dasgupta <sdg1@uw.edu>
@@ -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
+tagged, accessible PDF/UA-2 output, it requires
-(https://www.luatex.org/) (not XeLaTeX or PDFLaTeX). LuaLaTeX is
+[LuaLaTeX](https://www.luatex.org/) (not XeLaTeX or PDFLaTeX). LuaLaTeX
-supported by Overleaf (https://overleaf.com/) although it is not the
+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 \
   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,18 +42,19 @@ 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,
+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
+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
+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
+```
 
 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
@@ -62,10 +62,12 @@ 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
+```
 
-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 <directory>
+```
 
 Example:
 
+```
 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/
+```
 
 
-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
+<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
+```
 
 Patches can be submitted by email to Benjamin Mako Hill:
 
-  Benjamin Mako Hill <makohill@uw.edu> [work]
+* Benjamin Mako Hill <makohill@uw.edu> \[work]
-  Benjamin Mako Hill <mako@atdot.cc> [personal]
+* Benjamin Mako Hill <mako@atdot.cc> \[personal]
-
 
+```
 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/
+<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
+Sayamindu Dasgupta. We dedicated the work to the public domain by
-rights to the work worldwide under copyright law, including all
+waiving all of our rights to the work worldwide under copyright law,
-related and neighboring rights, to the extent allowed by law. You can
+including all related and neighboring rights, to the extent allowed by
-copy, modify, distribute and perform the work, even for commercial
+law. You can copy, modify, distribute and perform the work, even for
-purposes, all without asking permission.
+commercial purposes, all without asking permission.
 
-See details here: https://creativecommons.org/publicdomain/zero/1.0/
+See details here:
+<https://creativecommons.org/publicdomain/zero/1.0/>
 
 As a result, if you completely remove the UW branding, there are no
 restrictions on how you can use the work in this repository.

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/*