| 1 |
Parstat package |
| 2 |
=============== |
| 3 |
_Version 1.0 (first public version)_ |
| 4 |
|
| 5 |
Parstat is a package for the OpTeX format that counts glyphs and |
| 6 |
spaces on paragraph lines. From these numbers a statistic is made, |
| 7 |
which is printed into the logfile. |
| 8 |
|
| 9 |
One important measure of paragraph readability is the number of |
| 10 |
characters per line. It should be somewhere between 45–75 (spaces |
| 11 |
included) for optimal reading experience. This macro gives us the |
| 12 |
numbers to tell how good our layout is in that. The space counter |
| 13 |
also tells us the word count on the line (`words = spaces + 1`). |
| 14 |
|
| 15 |
That all is done directly after breaking the paragraph into lines by |
| 16 |
Lua code inside the LuaTeX engine, so no external tools are used. We |
| 17 |
can much more easily customize it to our specific work demands and get |
| 18 |
more precise results. |
| 19 |
|
| 20 |
The downside of this is that we analyze glyph nodes that are already |
| 21 |
shaped. So the term "glyphs", used throughout the package, is correct. |
| 22 |
While this works well with Latin (see Limitations section), it will |
| 23 |
probably fail on Arabic or Indic text, which builds on many ligatures |
| 24 |
and where glyph shaping was more complex. |
| 25 |
|
| 26 |
Usage |
| 27 |
----- |
| 28 |
The first step is to load the package `\load[parstat]`. |
| 29 |
|
| 30 |
Then we must enable it by `\parstatenable`. From this moment on, we |
| 31 |
get the statistic for every finished paragraph. If we want to disable |
| 32 |
it, then use its counterpart `\parstatdisable`. These macros work in |
| 33 |
TeX groups as we would expect. |
| 34 |
|
| 35 |
We can ignore lines at the beginning of the paragraph by the counter |
| 36 |
`\_parstat_fskip`. This is handy for ignoring indented lines or when |
| 37 |
using initials, which would otherwise distort the statistic. |
| 38 |
|
| 39 |
We can also skip lines from the end of the paragraph by setting the |
| 40 |
counter `\_parstat_bskip`. In most cases it should be 1, which is the |
| 41 |
default, as the last one is mostly shorter than regular lines. |
| 42 |
|
| 43 |
At any time we can print the current statistic `\parstat`, which shows |
| 44 |
the state of the statistic at that point of execution. For printing |
| 45 |
a summary at the end, we can, for example, redefine the `\bye` macro. |
| 46 |
|
| 47 |
``` |
| 48 |
\def\bye{\par\parstat \_bye} |
| 49 |
``` |
| 50 |
|
| 51 |
We can reset the total statistic at any time by using `\parstatreset`. |
| 52 |
|
| 53 |
Example and output interpretation |
| 54 |
--------------------------------- |
| 55 |
Minimal example looks like this: |
| 56 |
``` |
| 57 |
\load[parstat] |
| 58 |
\parstatenable |
| 59 |
\lipsum[1] |
| 60 |
\parstat |
| 61 |
\bye |
| 62 |
``` |
| 63 |
|
| 64 |
After running, we get this output in the log: |
| 65 |
``` |
| 66 |
Parstat 1 in './test.tex' at line 3 |
| 67 |
1X:(100g,14s) 2:(101g,12s) 3:(101g,13s) 4:(99g,16s) 5:(107g,14s) |
| 68 |
6:(107g,16s) 7:(104g,14s) 8:(104g,16s) 9X:(36g,5s) |
| 69 |
Glyphs: ave 103.29, stddev 3.09, min 99, max 107 |
| 70 |
Spaces: ave 14.43, stddev 1.62, min 12, max 16 |
| 71 |
Parstat summary from './test.tex' at line 4 |
| 72 |
Analyzed 1 paragraphs, 7 lines in total |
| 73 |
Glyphs: ave 103.29, stddev 3.09, min 99, max 107 |
| 74 |
Spaces: ave 14.43, stddev 1.62, min 12, max 16 |
| 75 |
``` |
| 76 |
|
| 77 |
The first line tell us that we see the first statistic and where it |
| 78 |
came from. Followed by counts of glyphs (g) and spaces (s) for every |
| 79 |
line. Line numbers ending with "X" are the ignored lines. Statistics |
| 80 |
of glyphs and spaces finishes the paragraph stat. |
| 81 |
|
| 82 |
Summary triggered with `\parstat` continues in the same style. |
| 83 |
|
| 84 |
Limitations |
| 85 |
----------- |
| 86 |
* Counting ligature components works only if the shaper is TeX and not |
| 87 |
OpenType or Harf. Harf is default in OpTeX now, and we use OpenType |
| 88 |
fonts, so ligatures are counted as single characters. The reason for |
| 89 |
this is that when counting, the glyphs are already shaped (glyph |
| 90 |
subtype is 256) and there is no way to track their components. |
| 91 |
|
| 92 |
One possible workaround is to temporarily disable ligatures by using |
| 93 |
`\setff{-liga}`. This works, but it will change line breaks. |
| 94 |
|
| 95 |
* Math formulas are not counted. |
| 96 |
|
| 97 |
License |
| 98 |
------- |
| 99 |
Parstat use the LaTeX Project Public License |
| 100 |
([LPPL-1.3c](https://www.latex-project.org/lppl.txt)). |
| 101 |
|
| 102 |
Repository |
| 103 |
---------- |
| 104 |
Parstat code lives |
| 105 |
in [this GitHub repository](https://github.com/petrk23/parstat). |
| 106 |
Issues can be reported there. |