Source Browser ?

2% language=us runpath=texruns:manuals/musings
3
4\startcomponent musings-viewers
5
6\environment musings-style
7
8\defineexternalfigure[default][width=.75tw]
9
10\startchapter[title={Viewers}]
11
12\startsection[title={Introduction}]
13
14In this musing I show some images that give an impression of how a few viewers
15that I have on my machine deal with indicating that some area in the text has a
16special meaning. The screen dumps were made in September 2024 when I added
17support for highlights (per user request).
18
19\stopsection
20
21\startsection[title={Highlights}]
22
23A highlight is an annotation. Normally annotations are bounded by a rectangle
24made by $llx$, $lly$, $urx$, and $ury$, so basically a bounding box. Highlights
25on the other hand need both a bounding box and list of quad points: $(x_1, y_1)$,
26$(x_2, y_2)$, $(x_3, y_3)$ and $(x_4, y_4)$ that represent the corners of a
27(possibly rotated) area. If you implement this according the the official
28standard you get in Acrobat Reader \in {figure} [fig:hl-acrobat], in Okular \in
29{figure} [fig:hl-okular] and in Sumatra (which uses muPDF) \in {figure}
30[fig:hl-sumatra]. \footnote {Quad points were already in \CONTEXT\ but mainly for
31supporting interactive features in \METAFUN\ with more fancy shapes. For multi
32line hyperlinks one could also turn in on in regular text but this was never
33advocated, if only because I couldn't test all these viewers.}
34
35\startplacefigure[reference=fig:hl-acrobat,title=Highlight in Acrobat.]
36    \externalfigure[musings-highlight-acrobat.png][default]
37\stopplacefigure
38
39\startplacefigure[reference=fig:hl-okular,title=Highlight in Okular.]
40    \externalfigure[musings-highlight-okular.png][default]
41\stopplacefigure
42
43\startplacefigure[reference=fig:hl-sumatra,title=Highlight in Sumatra.]
44    \externalfigure[musings-highlight-sumatra.png][default]
45\stopplacefigure
46
47However, this doesn't look that good. It happens that we need to swap the third and
48fourth coordinates, which we can do with:
49
50\starttyping
51\enabledirectives[backend.pdf.fixhighlight]
52\stoptyping
53
54The result is shown in \in {figure} [fig:hl-okular-fixed]. We don't make this
55feature default because the specification doesn't explain what viewers are
56supposed to do. The fact that Acrobat also suffers from this indicates that a bug
57has become a feature (creating and viewing has to match here). In regular links
58the active area conforms to the specification.
59
60\startplacefigure[reference=fig:hl-okular-fixed,title=Highlight in Okular with swapped coordinates.]
61    \externalfigure[musings-highlight-fixed-okular.png][default]
62\stopplacefigure
63
64All viewers apply some form of transparency so when this is used in a workflow
65you need to keep in mind that rendering of the highlighted area can differ per
66viewer, so choose colors wisely, especially when the text itself also has a
67color. Also test the viewers that your authors use and make sure that they don't
68see garbage. Here are some tested that we (Mikael & Hans) did September 14, 2024:
69
70\starttabulate
71\NC Firefox    \NC follows standard but also works with swapping \NC \NR
72\NC EBookDroid \NC follows standard but does something when swapping \NC \NR
73\NC Google     \NC show nothing \NC \NR
74\NC okular     \NC swap 3 and 4 \NC \NR
75\NC evince     \NC swap 3 and 4 \NC \NR
76\NC zathura    \NC swap 3 and 4 \NC \NR
77\NC qpdf       \NC swap 3 and 4 \NC \NR
78\NC acrobat    \NC swap 3 and 4 \NC \NR
79\NC sumatra    \NC swap 3 and 4, more curved \NC \NR
80\stoptabulate
81
82Hraban did some tests on his Apple machine and most viewers expected the fix
83while some didn't show anything at all. Because normally highlights are a temporary
84(editorial) trick it's not that important in the end.
85
86\stopsection
87
88\startsection[title={Rotation}]
89
90Out of curiosity I decided to look at how viewers handled a rotated highlight.
91Getting the quad points right is possible but in the end it is more reliable to
92use a generous bounding area instead. It's not like users will turn their head
93when commenting on your proposal. \in {Figures} [fig:hr-acrobat], \in
94[fig:hr-okular] \in {and} [fig:hr-sumatra] show the outcome.
95
96\startplacefigure[reference=fig:hr-acrobat,title=Highlight in Acrobat with rotated text.]
97    \externalfigure[musings-highlight-rotated-acrobat.png][default]
98\stopplacefigure
99
100\startplacefigure[reference=fig:hr-okular,title=Highlight in Okular with rotated text.]
101    \externalfigure[musings-highlight-rotated-okular.png][default]
102\stopplacefigure
103
104\startplacefigure[reference=fig:hr-sumatra,title=Highlight in Sumatra with rotated text.]
105    \externalfigure[musings-highlight-rotated-sumatra.png][default]
106\stopplacefigure
107
108It looks like Okular and Sumatra use the same algorithm for rendering the shape:
109both have rather ugly corners, maybe emulating some kind of pen. Acrobat might have
110an issue with the bounding box here but I'm not going to waste time on investigating
111this.
112
113\stopsection
114
115\startsection[title={Selection}]
116
117Talking of rotation, I was also curious how normal selection works out. Here
118Acrobat is a clear winner: compare \in {figures} [fig:rs-acrobat], \in
119[fig:rs-okular] \in {and} [fig:rs-sumatra]. It must be said: Okular makes for a
120nice image and uses transparency wisely. \footnote {Selecting an unrotated text
121also can give interesting effects especially when a viewer decided not to use the
122characters bounding box but font specific ascender and descender properties.}
123
124\startplacefigure[reference=fig:rs-acrobat,title=Selection in Acrobat with rotated text.]
125    \externalfigure[musings-selection-rotated-acrobat.png][default]
126\stopplacefigure
127
128\startplacefigure[reference=fig:rs-okular,title=Selection in Okular with rotated text.]
129    \externalfigure[musings-selection-rotated-okular.png][default]
130\stopplacefigure
131
132\startplacefigure[reference=fig:rs-sumatra,title=Selection in Sumatra with rotated text.]
133    \externalfigure[musings-selection-rotated-sumatra.png][default]
134\stopplacefigure
135
136\stopsection
137
138\startsection[title={Post scriptum}]
139
140Just to be complete I show how one can use highlights in \CONTEXT. This feature was
141made for Hraban who has a need for it.
142
143\starttyping
144\enabledirectives[backend.pdf.fixhighlight]
145
146\definecolor[pdfhighlight:Rhaban][r=.8,g=1,b=1]
147\definecolor[pdfhighlight:Hans]  [r=1,g=.5,b=.5]
148\definecolor[pdfhighlight:Ton]   [r=1,g=1,b=.8]
149
150test \PDFhighlight[Rhaban]        {\samplefile{tufte}} test \blank
151test \PDFhighlight[Hans]          {what a mess}        test \blank
152test \PDFhighlight[Ton]           {\samplefile{ward}}  test \blank
153test \PDFhighlight[Hans][whatever]{\samplefile{knuth}} test \blank
154\stoptyping
155
156The first argument indicates the author and you can define a color specific to
157one. The second optional argument specifies some content and it depends on the
158viewer how all gets represented: in a side menu, as roll over, or by point and
159click. There is also a \typ {\startPDFhighlight} with matching \typ
160{\stopPDFhighlight} command. We deliberately use a \type {PDF} name space and
161simple color setup (no instances) because this is a fragile feature from the
162perspective of viewers. One can also wonder how it impacts validation because
163conforming to the standard doesn't give the best results.
164
165You can use this command to see what highlights are in a file:
166
167\starttyping
168mtxrun --script pdf --highlights demo.pdf
169\stoptyping
170
171\stoptext
172