Debian Codegraph @

texmf-dist/doc/optex/parstat/README.md

raw
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.