Debian Codegraph @

texmf-dist/doc/latex/forest-ext/README.md

raw
1 $Id: README.md 11668 2026-02-21 02:34:38Z cfrees $
2
3 # forest-ext
4
5 Small extensions for Sašo Živanović's fantastic Forest package.
6
7 Currently the package provides the following Forest libraries:
8 - ext.ling (simple wrapper styles)
9 - ext.multi (children with multiple parents)
10 - ext.tagging (produce tagged PDF)
11 - ext.utils (minor tweaks)
12
13 Debugging versions of all libraries are provided.
14
15 ## v0.2
16
17 Now uses memoize-ext's support for tagging content memoized with Memoize.
18
19 ## Licence
20
21 Copyright 2025-2026 Clea F. Rees
22
23 This work may be distributed and/or modified under the
24 conditions of the LaTeX Project Public License, either version 1.3c
25 of this license or (at your option) any later version.
26 The latest version of this license is in
27 https://www.latex-project.org/lppl.txt
28 and version 1.3c or later is part of all distributions of LaTeX
29 version 2008-05-04 or later.
30
31 This work has the LPPL maintenance status `maintained'.
32
33 The Current Maintainer of this work is Clea F. Rees.
34
35 This file may only be distributed together with a copy of the package
36 chronos. You may however distribute the package chronos without
37 such generated files.
38
39 This work consists of all files listed in manifest.txt.
40
41 ## Features
42
43 Forest is incompatible with the LaTeX Project's code for producing tagged PDF.
44 `ext.tagging` enables Forest trees to be included in tagged documents by
45 auto-generating alternative text based on the content of trees' nodes and edge
46 labels. The result can be configured using Forest options and registers and/or
47 providing custom plugs for the provided sockets.
48
49 I find myself using certain style tweaks repeatedly in both my own documents
50 and answers on TeX SE. A few of these are provided here for convenience:
51 - align parent with the middle child, if the parent has an odd number of
52 children;
53 - add labels for levels or tiers at the edge of the tree;
54 - include children with multiple parents;
55 - 'pretty nice empty nodes' (for linguists).
56
57 ## Limitations
58
59 The tagging code, in particular, is far from being a panacea. Known limitations
60 include the following.
61
62 The bounding box calculation is based on the size of the tree. In the best
63 case, this will be _almost_ but not quite correct. In such cases, I assume the
64 dimensions should be perfectly satisfactory. However, in the worst case, the
65 dimensions will be _very_ wrong. If the code is otherwise useful, I will look
66 into the possibility of calculating the dimensions at a later point. (Right now,
67 the problem is that they are calculated too early and so do not account for
68 additions in `tikz` keys, for instance.)
69
70 Trees are tagged with `alt` text or nothing. No other options are available. In
71 particular, none of `text`, `actualtext` and `artifact` (all supported by
72 `latex-lab` for TikZ) are provided. It would be easy to support `artifact` and
73 `actualtext`, but I doubt these are useful for trees.
74
75 **Content is provided as simple text. Mathematics, logic and other symbolic
76 markup is NOT rendered into luamml, xml or html. No associated files are
77 written or embedded.** It is, to say the least, unclear how content of this
78 kind should be tagged. `alt` text is almost certainly a poor substitute, but
79 there is not currently any obvious way to improve this.
80
81 It would be relatively straightforward to write a structured xml or similar to
82 represent the tree. Unfortunately, I don't believe anything is available to
83 make use of such a file. Individual formulae could be marked up as luamml, but
84 in the absence of some standard way to represent the _structure_ of the tree,
85 this does not seem especially useful.
86
87 A hybrid consisting of `alt` text with luamml components might work for maths
88 and, possibly, logic and linguistics, but that seems alien to the framework in
89 the PDF specification. `alt` text is designed, as far as I can tell, for
90 pictures. Trying to fit linguistic analyses or formal proofs into that space is
91 unlikely to yield satisfactory results.
92
93 But these limitations are imposed by the various technical specifications and
94 far beyond the control of any package.
95
96 (Possibly trees could be mapped to a specialised structure in the tagged
97 content, which is, after all, itself arranged as a tree. But I am not certain
98 whether a structure of that kind is possible within the tagging framework
99 generated by the LaTeX format or if it is even permissible according to the
100 somewhat complex specifications for accessible PDF. If that was possible,
101 symbolic content might then be marked up as such, without disconnecting it from
102 the structure.)
103
104 ## Code Repositories
105
106 Code for the package is hosted at
107 https://codeberg.org/cfr/prooftrees
108 For convenience, the repository will be mirrored at
109 https://github.com/cfr42/prooftrees
110
111 ## Contact Details
112
113 Bug reports, feature requests etc. should be filed at
114 https://codeberg.org/cfr/prooftrees/issues
115
116
117 Clea F. Rees
118 Version 0.3
119 2026-02-21
120
121 vim: et:tw=80:ts=2: