FontProof - a font design testing class for SILE

FontProof enables you to produce PDF font test documents without fiddling with InDesign or other manual page layout or word processing programs. You can apply one of the predesigned test documents (to be added later) or use FontProof to build your own custom font test document.

Note that FontProof is very much a work-in-progress, so there's a lot that doesn't work yet, or doesn't work very elegantly. Use at your own risk, and help us make it better.

Installation

FontProof requires The SILE Typesetter. You'll need to install SILE according to that package's instructions.

Note that SILE is changing rapidly. The current class was developed for and tested with release 0.13.0 or newer.

To install FontProof on SILE 0.13.0 or later, run:

$ sile -e 'installPackage("fontproof");os.exit()'

On older versions, download this project (or better yet, git clone it) into any folder on your drive. From within that directory you should then be able to compile the basic FontProof test doc:

$ sile fpTest.sil

As long as you run all your SILE files from within the original installation folder, this is all you need to do. If you wish to be able to run FontProof from any location, then:

• Find your SILE installation directory,
• Copy the file classes/fontproof.lua into the sile/classes folder, and
• Copy the following files into your installation sile/packages folder:
  • packages/fontprooftexts.lua
  • packages/fontproofgroups.lua
  • packages/gutenberg-client.lua

Using the templates

To use one of the provided templates, open it in a text editor (maybe make a copy of it first) and change the \setTestFont line to point to your font. The font doesn't even have to be installed. If it is installed you can also specify font by family name. Either way you can set the default size:

\setTestFont[family="Georgia", size=13pt]

Then run SILE on the file with sile filename.

You can also specify the test font on the sile command line and leave the font unspecified in the document, as in:

\setTestFont[size=13pt]

Then use the -e parameter on the sile command to set the fontfile parameter, as in:

$ sile -e 'fontfile = "font.ttf"' test.sil

For this to work you must have a \setTestFont command in your SILE file, even if only to set an initial size. Without that command any font specified on the command line will be ignored. Also - if you set the font name or filename in the SILE file it will always override anything you try to set on the command line.

(Note: In earlier versions of fontproof this was -f or -p, however this a slightly more awkward but more robust way to do it.)

At this point there is one main template - fpFull.sil - but more will follow. That template will show you almost all that FontProof can do. SILE itself is capable of far, far, more, and you're very welcome to play around with it.

Docker usage

As an alternative method to use FontProof, Docker images are available from Docker Hub or the GitHub Container Registry with SILE and the fontproof class baked in and ready for use. Released versions are tagged to match (e.g. v1.6.2), the latest release will be tagged latest, and a master tag is also available with the freshest development build. In order to be useful you need to tell the Docker run command a way to reach your source documents (and hence also to give it a place to write the output) as well as tell it who you are on the host machine so the output generated inside the container can be created with the expected ownership properties. You may find it easiest to run with an alias like this:

$ alias fontproof='docker run -it --volume "$(pwd):/data" --user "$(id -u):$(id -g)" siletypesetter/fontproof:latest'
$ fontproof proofs.sil

Remote usage

Any remote CI system that can use Docker images as job runners could be configured to run FontProof jobs. Additionally a ready-made GitHub Action is available on the marketplace:

name: FontProof
on: [push, pull_request]
jobs:
  fontproof:
    runs-on: ubuntu-latest
    name: FontProof
    steps:
      - name: Checkout
        uses: actions/checkout@v3
      - name: FontProof
        uses: sile-typesetter/fontproof@latest
        with:
          args: proofs.sil

Add to your repository as .github/workflows/fontproof.yml. This work flow assumes your project has a source file proofs.sil and will leave behind a proofs.pdf. Note that the comments in the section about Docker regarding tagged versions besides latest apply equally here, but GitHub Actions uses an @ separator instead of Docker's :.

Adding or modifying tests

Each template can contain a full selection of tests. Each test is specified using a command in this general format:

\commandname[set of parameters]{text to be typeset}

Some tests may have only parameters, or only text, or neither, as in this example that is natively supported within SILE itself:

\pangrams

More details on running commands in SILE can be found in the SILE manual.

Headings and sections

By default, the running head lists the filename, font (family or filename), date, and time. The content is not (currently) configurable, but you can set the font and size with the \setRunHeadStyle command. Note that this has no relation to the test font.

%\setRunHeadStyle[filename="packages/fontproofsupport/Lato2OFL/Lato-Bold.ttf", size="12pt"]

To add a section and subsection headings:

\section{Heading text}
\subsection{Heading text}

The style of these is not currently configurable, but you can manually tweak them for all FontProof docs by changing the settings in classes/fontproof.lua.

Test types

The following kinds of tests are supported, and are illustrated in fpFull.sil :

• Simple test text
• Waterfall (a text repeated in multiple sizes)
• Patterns (where a text is repeated with one or more substituted characters)
• Lorem ipsum
• Pangrams
• Full glyph repertoire

Details on the commands used to specify these are below.

Contributing to the project

FontProof is Copyright © 2016-2020 SIL International and licensed under the MIT license. BTW - Despite the name similarity, SILE itself is not developed by SIL International, though we like the project very much. You're very welcome to contribute to both FontProof and SILE.

Proof Tests and Options

Commands provided by FontProof

These commands are currently supported.

\proof[]{}

This is the main FontProof command, and can be used to set both simple test texts and waterfalls. Optional parameters include font (by family or filename) and size(s). You can also set a test heading here rather than using a separate \section command.

\proof{This is basic proof text using the test font}

\proof[family="Gentium Plus",heading=A basic family test]{This is basic text with a font defined by family}

\proof[size="10pt",filename="packages/fontproofsupport/Lato2OFL/Lato-Light.ttf",heading=A basic filename test]{This is another basic text with common parameters}

\proof[size="10pt,11pt,12pt,16pt"]{This is basic proof text in a range of sizes}

\proof[size="10,11,12,13,20"]{This is basic proof text in a range of sizes with numbers only}

\proof[features="Ligatures=Rare, Ligatures=Discretionary"]{This is a proof with rare ligatures turned on}

\proof[features="+dlig,+hlig"]{This is a proof with features manipulated manually}

\proof[language="grk",direction = "rtl"]{Here are some options which are passed on to the font command}

\proof[color="green"]{Here are some options which are passed on to the color command}

\proof[shapers="ot,fallback"]{Here we pass a list of subshapers to Harfbuzz}

\pattern[]{}

This produces multiple copies of a text with a range of characters substituted in key places. These are sometimes referred to as 'frame tests'. Traditionally a common test of this type was the 'hobonop' test. A 'hobonop' for the letters a b c d would look like:

haoabaoanaoap hbobbbobnbobp hcocbcocncocp hdodbdodndodp

The command to produce this would be:

\pattern[chars="@",reps="abcd"]{h@o@b@o@n@o@p}

This defines a placeholder character, then the set of letters used to replace it, then the text pattern containing the placeholder(s).

You can also use multiple placeholders to create all combinations, as in:

ooaxoo oobxoo oocxoo
ooayoo oobyoo oocyoo

The command for this would be: (Be sure to follow the syntax of this exactly, or you may get very confusing errors!)

\pattern[chars="@,#",reps="abc,xy"]{oo@#oo}

There are some characters that are special to SILE and Lua and shouldn't be used as chars. (A list of suggested safe ones would be a good addition here!) It's also a bad idea to use a character that is in reps.

There is one more optional parameter to the \pattern command:

• format = "table" (the default) will typeset patterns with multiple placeholders grouped into one paragraph per second placeholder replacement.
• format = "list" will typeset each pattern in a separate line (paragraph).
• format = "para" will group all results into a single paragraph.

It's easier to demonstrate this than to explain. First the formatted example, then the command to produce it:

ooaxoo oobxoo oocxoo
ooayoo oobyoo oocyoo

\pattern[chars="@,#",reps="abc,xy",format="table"]{oo@#oo}

ooaxoo
oobxoo
oocxoo
ooayoo
oobyoo
oocyoo

\pattern[chars="@,#",reps="abc,xy",format="list"]{oo@#oo}

ooaxoo oobxoo oocxoo ooayoo oobyoo oocyoo

\pattern[chars="@,#",reps="abc,xy",format="para"]{oo@#oo}

\patterngroup[]{}

This is cool! Say that you have a group of letters that you want to use in multiple pattern tests, but don't want to have to define them over and over again. You can define these as a pattern group, with a specific name. Note that you have to define these groups in your document before you refer to them. Also note that this command doesn't really produce anything on the page by itself. It's only useful for later \pattern commands.

\patterngroup[name="vowels"]{aeiou}

To refer to this in a \pattern command prefix the group name with "group_" and use in the reps parameter. For example:

\pattern[chars="@,#",reps="group_vowels,xy",format="table"]{oo@#oo}

There are also a few predefined groups, as listed below. You can also define your own permanent groups in packages/fontproofgroups.lua.

Additional FontProof Features

textxxxxx_

FontProof includes a range of built-in test texts. Set the content of a \proof or \pattern command to any of the following preset text_xxxx names. You can also add your own texts in packages/fontprooftexts.lua.

\adhesion

This uses dictionaries to produce garbage text made up of real words, similar to \lorem. However the words would only contain letters from a set you supply:

\adhesion[characters=hamburgefonsiv]

Optional arguments are words, the number of words (defaulting to 120), and dict, the path of a dictionary file. The class looks in /usr/share/dict/words and /usr/dict/words if the dict option is not provided. Words are selected from the dictionary file if they contain only the characters specified.

\gutenberg

This downloads and typesets a text from Project Gutenberg.

\gutenberg[id=100] % The complete works of Shakespeare

\pi

Typesets some digits of pi:

\pi[digits=500]

\unicharchart

This produces a simple unbordered table that would show a range of unicode and any glyphs that represent the USVs in that range.

Some examples:

\unicharchart[type="all",columns="12",rows="16"]

This produces a table that shows every encoded character in the font, formatted as a table with increasing USVs descending down a column, 16 chars per column, with a maximum of 12 columns before breaking into a new table. This is very similar to the tables in The Unicode Standard code charts, and could be the default settings for a simple \unicharchart.

\unicharchart[type="range",start="AA80",end="AADF"]

This produces the same, except only showing the given range of USVs.

Commands provided natively by SILE

These work in SILE even without FontProof, although you would then need to load them with \script[src=packages/specimen].

\pangrams

This produces a set of predefined pangrams.

\lorem[words=#]

This produces garbage lorem ipsum text, with the number of words indicated.

\repertoire

This produces a nicely arranged table of all the glyphs in the font.

Future features

Here are some commands we hope to someday support, with suggested command formats. Some may never be implemented. Suggestions welcome!

Enhancements to \proof

We'd love to see even more potential parameters to \proof:

\proof[
  size = "10, 11/13, 12/16",
  columns = 3,
  lines = 12
]{Text}

Support for multiple fonts with a single test type

Oooooh!

What else would you like?