Installation

Requirements

Required

• A built Unicon tree ( ./configure && make from the unicon sources)

Optional (PDF only)

• A TeX engine on your PATH : pdflatex , xelatex , or lualatex . uscribe picks the first one it finds. HTML and --format=latex ( .tex only) do not need TeX.

There is no Homebrew or apt package literally named pdflatex ; that name is a program shipped inside a TeX distribution. Install one of the packages below, then confirm:

which pdflatex || which xelatex || which lualatex

TeX / PDF dependencies by platform

macOS (Homebrew)

Compact (recommended for uscribe):

brew install --cask basictex

Full MacTeX (much larger):

brew install --cask mactex
# or: brew install --cask mactex-no-gui

After BasicTeX or MacTeX, restart the terminal (or run eval "$(/usr/libexec/path_helper)" ) so the new binaries are on PATH .

Debian / Ubuntu

Minimal (often enough):

sudo apt update
sudo apt install texlive-latex-base

Recommended if pdflatex complains about missing packages (hyperref, fancyvrb, graphicx fonts, and similar):

sudo apt install texlive-latex-recommended texlive-fonts-recommended

Larger kitchen-sink options:

sudo apt install texlive-latex-extra
# or everything: sudo apt install texlive-full

Fedora / RHEL-family

sudo dnf install texlive-latex
# fuller: sudo dnf install texlive-scheme-medium
# everything: sudo dnf install texlive-scheme-full

Arch Linux

sudo pacman -S texlive-basic texlive-latex
# or a broader set: sudo pacman -S texlive-meta

Windows

Install either MiKTeX (https://miktex.org/download) — packages on demand — or TeX Live for Windows (https://tug.org/texlive/).

Ensure the installer puts pdflatex on your PATH , then open a new Command Prompt or PowerShell window.

What uscribe LaTeX output needs

Generated STEM.tex uses a small set of packages ( graphicx , hyperref , xcolor , fancyvrb , booktabs , longtable , array ). multirow is loaded when the .sty is installed (needed for grid-table row spans). caption is loaded when present so Word-style Figure N / Table N captions can use \\caption* ; without it uscribe falls back to a centered paragraph. framed is loaded when present so code samples get a shaded box; without it the listing is still full-width Verbatim . A latex recommended install is usually enough; GitHub Pages installs texlive-latex-extra so the user-guide PDF build has the full set. If pdflatex stops with File …sty not found , install the matching TeX Live or MiKTeX package (or a larger scheme) and retry.

SVG figures are not embedded in PDF; convert them to PDF or PNG, or accept the boxed placeholder uscribe emits for .svg paths.

Build uscribe

From the unicon tree:

cd uni/uscribe
make

That compiles the uscribe package, links ./uscribe , and installs a copy to ../../bin/uscribe . make install in this directory does the same. A top-level make install also installs uscribe into $(bindir) alongside unicon , udb , and the other addon tools, and copies themes to $(libdir)/unicon/uni/uscribe/themes .

Regenerate Make dependencies after adding .icn files:

make deps

Verify

uscribe
# no book.manifest in this directory: prints usage and exits

Build this manual

HTML:

cd doc/uscribe
make
# open out/index.html

PDF (after installing a TeX engine as above):

cd doc/uscribe
make pdf
# open out/uscribe-userguide.pdf

make latex writes out/uscribe-userguide.tex without running a TeX engine. make pdf writes the .tex and runs the engine twice (TOC and cross-references).