Parstat package

Version 1.1

Parstat is a package for the OpTeX format that counts glyphs and spaces on paragraph lines. From these numbers, statistics are generated and get printed to our console and logfile.

One important measure of paragraph readability is the number of characters per line. It should be somewhere between 45–75 (spaces included) for optimal reading experience. This macro gives us the numbers to tell how good our layout is in that. The space counter also tells us the word count on the line (words = spaces + 1).

All those calculations are done directly after breaking the paragraph into lines by Lua code inside the LuaTeX engine, so no external tools are used. We can much more easily customize it to our specific work demands and get more precise results.

The downside of this is that we analyze glyph nodes that are already shaped. So the term "glyphs", used throughout the package, is correct. While this works well with Latin (see Limitations section), it will probably fail on Arabic or Indic text, which builds on many ligatures and where glyph shaping was more complex.

Usage

The first step is to load the package \load[parstat].

Then we must enable it by \parstatenable. From this moment on, the statistic for every finished paragraph is counted. If we want to disable it, then use its counterpart \parstatdisable. These macros work in TeX groups as we would expect.

Output detail level can be set with the \parstatverbose counter. Default value 1 means per-paragraph statistics output. Values of 2 or more give specific line-by-line statistics. With a value of 0 or less, there is no output except from explicit package commands.

At any time we can print the current statistic \parstat, which shows the state of the statistic at that point of execution. For printing a summary at the end, we can, for example, redefine the \bye macro.

\def\bye{\par\parstat \_bye}

To reset the total statistic, use \parstatreset.

We can ignore lines at the beginning of the paragraph by the counter \parstatfskip. This is handy for ignoring indented lines or when using initials, which would otherwise distort the statistic. It has the default value 1, as paragraphs start with indented lines.

We can also skip lines from the end of the paragraph by setting the counter \parstatbskip. In most cases it should be 1, which is the default, as the last one is usually shorter than the rest.

Negative line-skip counts will be clamped to zero.

Example and output interpretation

Minimal full detail example looks like this:

\load[parstat]
\parstatverbose=2
\parstatenable
\lipsum[1]
\parstat
\bye

After processing with OpTeX, we get this output:

Parstat 1 from ./cosi.tex:4
  1X:(100g,14s) 2:(101g,12s) 3:(101g,13s) 4:(99g,16s) 5:(107g,14s)
  6:(107g,16s) 7:(104g,14s) 8:(104g,16s) 9X:(36g,5s)
  Glyphs: ave 103.29, stddev 3.09, min 99, max 107
  Spaces: ave 14.43, stddev 1.62, min 12, max 16
Parstat summary from ./cosi.tex:5
  Analyzed 1 paragraphs, 7 lines in total
  Glyphs: ave 103.29, stddev 3.09, min 99, max 107
  Spaces: ave 14.43, stddev 1.62, min 12, max 16

The first line tells us that we see the first statistic and where it came from. Followed by counts of glyphs (g) and spaces (s) for every line. Line numbers ending with "X" are the ignored lines. Statistics of glyphs and spaces finish the paragraph stat.

Summary triggered with \parstat continues in the same style.

If we are in interactive mode, the file and line are not set, so it prints the specific sequence :0.

Limitations

• Counting ligature components works only if the shaper is TeX and not OpenType or Harf. Harf is default in OpTeX now, and we use OpenType fonts, so ligatures are counted as single characters. The reason for this is that when counting, the glyphs are already shaped (glyph subtype is 256) and there is no way to track their components.

One possible workaround is to temporarily disable ligatures by using \setff{-liga}. This works, but it will change line breaks.

• Math formulas are not counted.

License

Parstat uses the LaTeX Project Public License (LPPL-1.3c).

Repository

Parstat code lives in this GitHub repository. Issues can be reported there.