Dave Jarvis' Repositories

# Themes

Themes in {{app.title}} define the visual appearance and layout of typeset PDF
documents. They control elements fonts, spacing, colours, page dimensions, and
structural formatting. Users can achieve high-quality outputs without modifying
document content. Themes are based on ConTeXt setups and can be selected during
PDF export to match different document purposes, such as manuscripts, user
manuals, or wills.

## Customization

Users may define unique document appearances by creating new theme setups. This
involves structuring a theme directory with required files to integrate with
the application's typesetting process.

All themes must have:

* a separate directory;
* a main entry point;
* a reference to XHTML setups; and
* a properties file.

For example, a new theme named "dīvus" would have the following file structure,
relative to the themes directory:

```
dīvus/
├── main.tex
├── xhtml.tex
└── theme.properties
```

### Theme directory

The theme directory organizes all files for a single theme. For consistency,
the theme directory name:

* must not include spaces;
* must be a sibling directory of all other themes;
* should be lowercase; and
* should be a single word (Latin works well).

### Entry point

The theme's main entry point defines how the document is presented during
typesetting. The main entry point, `main.tex`, is passed to the typesetting
software by the editor immediately prior to typesetting. The purpose of the
entry point is to import all the other files that define how the document is to
be presented.

Minimally, the file must include the XHTML setups file, which may be
accomplished with the following line:

``` tex
\input xhtml
```

### XHTML setups

XHTML setups map document elements to typesetting commands. To typeset the
document, the editor first converts the content into a data format known as
XHTML. Using XHTML allows mapping common document elements to commands that the
typesetting software can execute to format the output document.

A file named `xhtml.tex` must exist alongside the main file (that is, in the
same directory). The file must contain the following:

``` tex
\usesubpath[../xhtml]
\input ../xhtml/setups
```

These commands instruct the typesetter to import instructions from the `xhtml`
directory, which must exist in the parent directory. The XHTML setups are
responsible for translating XML elements from the XHTML document into ConTeXt
macros.

### Properties file

The `theme.properties` files identify a theme's name to the application. This
file allows the editor to display a drop-down having user-friendly names.  The
format of the file follows:

``` properties
name=Theme Name
```

The `name` is the key that the editor uses and the `Theme Name` is the value
that the theme's author may assign. For the dīvus example, the file would
resemble:

    name=Dīvus

For consistency, the theme name:

* should use title case (start words with an uppercase letter);
* should be short (will be truncated to 20 characters);
* must be uniquely named; and
* must not contain punctuation (letters and numbers only).

If a theme does not contain this file, the theme will be unavailable for users
to select when exporting.

## Text replacement

Sometimes we want to bend typography to our will. {{app.title}} themes
provide a mechanism to leverage the power of TeX to change the typesetting
for particular words without adding hints to the source document. This
truly exhibits the power of moving presentation logic elsewhere.

Lua is a programming language that is tightly integrated with ConTeXt. Here's
an example of using Lua to create a list of text replacements:

``` lua
\startluacode
userdata = userdata or {}

userdata.TextReplacements = {
  [1] = { "a.m.", "\\cap{am}" },
  [2] = { "TeX", "\\TeX{}" },
}
\stopluacode
```

This will replace `a.m.` with its small caps version and all occurrences of
`TeX` with its iconic lowered-E formatting. Replacements are case-sensitive.
Most themes, including *Boschet*, list replacement rules in a file called
`replace.tex` located in the theme's subdirectory.

## Resources

Styling themes with ConTeXt macros is beyond this manual's scope. Refer to the
theme source code for examples. Additionally, the following links are
excellent resources for support:

* [ConTeXt Mailing List](https://mailman.ntg.nl/mailman/listinfo/ntg-context)
* [TeX Stack Exchange](https://tex.stackexchange.com/questions/tagged/context)

See [@cha:typesetting-resources] for a library of books on ConTeXt.