summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/l3backend/l3backend-header.dtx
blob: 84f8ab53b7aee6f3dd633032ba1774b845365816 (plain)
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
% \iffalse meta-comment
%
%% File: l3backend-header.dtx
%
% Copyright (C) 2019-2024 The LaTeX Project
%
% It may be distributed and/or modified under the conditions of the
% LaTeX Project Public License (LPPL), either version 1.3c of this
% license or (at your option) any later version.  The latest version
% of this license is in the file
%
%    https://www.latex-project.org/lppl.txt
%
% This file is part of the "l3backend bundle" (The Work in LPPL)
% and all files in that bundle must be distributed together.
%
% -----------------------------------------------------------------------
%
% The development version of the bundle can be found at
%
%    https://github.com/latex3/latex3
%
% for those people who are interested.
%
%<*driver>
\documentclass[full,kernel]{l3doc}
\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%
% \title{^^A
%   The \pkg{l3backend-header} module\\ Backend graphics support^^A
% }
%
% \author{^^A
%  The \LaTeX{} Project\thanks
%    {^^A
%      E-mail:
%        \href{mailto:latex-team@latex-project.org}
%          {latex-team@latex-project.org}^^A
%    }^^A
% }
%
% \date{Released 2024-03-14}
%
% \maketitle
%
% \begin{documentation}
%
% \end{documentation}
%
% \begin{implementation}
%
% \section{\pkg{l3backend-header} implementation}
%
%    \begin{macrocode}
%<*dvips&header>
%    \end{macrocode}
%
% \begin{macro}[no-user-doc]{color.sc}
%   Empty definition for color at the top level.
%    \begin{macrocode}
/color.sc { } def
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[int]{TeXcolorseparation, separation}
%   Support for separation/spot colors: this strange naming is so
%   things work with the color stack.
%    \begin{macrocode}
TeXDict begin
/TeXcolorseparation { setcolor } def
end
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[int]{pdf.globaldict}
%   A small global dictionary for backend use.
%    \begin{macrocode}
true setglobal
/pdf.globaldict 4 dict def
false setglobal
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[int]
%   {
%     pdf.cvs     ,
%     pdf.dvi.pt  ,
%     pdf.pt.dvi  ,
%     pdf.rect.ht
%   }
%   Small utilities for PostScript manipulations. Conversion to DVI dimensions
%   is done here to allow for |Resolution|. The total height of a rectangle
%   (an array) needs a little maths, in contrast to simply extracting a value.
%    \begin{macrocode}
/pdf.cvs { 65534 string cvs } def
/pdf.dvi.pt { 72.27 mul Resolution div } def
/pdf.pt.dvi { 72.27 div Resolution mul } def
/pdf.rect.ht { dup 1 get neg exch 3 get add } def
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[int]{pdf.linkmargin, pdf.linkdp.pad, pdf.linkht.pad}
%   Settings which are defined up-front in |SDict|.
%    \begin{macrocode}
/pdf.linkmargin { 1 pdf.pt.dvi } def
/pdf.linkdp.pad { 0 } def
/pdf.linkht.pad { 0 } def
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[int]
%   {
%     pdf.rect        ,
%     pdf.save.ll     ,
%     pdf.save.ur     ,
%     pdf.save.linkll ,
%     pdf.save.linkur ,
%     pdf.llx         ,
%     pdf.lly         ,
%     pdf.urx         ,
%     pdf.ury
%   }
%   Functions for marking the limits of an annotation/link, plus drawing the
%   border. We separate links for generic annotations to support adding a
%   margin and setting a minimal size.
%    \begin{macrocode}
/pdf.rect
  { /Rect [ pdf.llx pdf.lly pdf.urx pdf.ury ] } def
/pdf.save.ll
  {
    currentpoint
    /pdf.lly exch def
    /pdf.llx exch def
  }
    def
/pdf.save.ur
  {
    currentpoint
    /pdf.ury exch def
    /pdf.urx exch def
  }
    def
/pdf.save.linkll
  {
    currentpoint
    pdf.linkmargin add
    pdf.linkdp.pad add
    /pdf.lly exch def
    pdf.linkmargin sub
    /pdf.llx exch def
  }
    def
/pdf.save.linkur
  {
    currentpoint
    pdf.linkmargin sub
    pdf.linkht.pad sub
    /pdf.ury exch def
    pdf.linkmargin add
    /pdf.urx exch def
  }
    def
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[int]
%   {
%     pdf.dest.anchor ,
%     pdf.dest.x      ,
%     pdf.dest.y      ,
%     pdf.dest.point  ,
%     pdf.dest2device ,
%     pdf.dev.x       ,
%     pdf.dev.y       ,
%     pdf.tmpa        ,
%     pdf.tmpb        ,
%     pdf.tmpc        ,
%     pdf.tmpd
%   }
%   For finding the anchor point of a destination link. We make the use case
%   a separate function as it comes up a lot, and as this makes it easier to
%   adjust if we need additional effects. We also need a more complex approach
%   to convert a co-ordinate pair correctly when defining a rectangle: this
%   can otherwise be out when using a landscape page. (Thanks to Alexander
%   Grahn for the approach here.)
%    \begin{macrocode}
/pdf.dest.anchor
  {
    currentpoint exch
    pdf.dvi.pt 72 add
    /pdf.dest.x exch def
    pdf.dvi.pt
    vsize 72 sub exch sub
    /pdf.dest.y exch def
  }
    def
/pdf.dest.point
  { pdf.dest.x pdf.dest.y } def
/pdf.dest2device
  {
    /pdf.dest.y exch def
    /pdf.dest.x exch def
    matrix currentmatrix
    matrix defaultmatrix
    matrix invertmatrix
    matrix concatmatrix
    cvx exec
    /pdf.dev.y exch def
    /pdf.dev.x exch def
    /pdf.tmpd exch def
    /pdf.tmpc exch def
    /pdf.tmpb exch def
    /pdf.tmpa exch def
    pdf.dest.x pdf.tmpa mul
      pdf.dest.y pdf.tmpc mul add
      pdf.dev.x add
    pdf.dest.x pdf.tmpb mul
      pdf.dest.y pdf.tmpd mul add
      pdf.dev.y add
  }
    def
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[int]
%   {
%     pdf.bordertracking          ,
%     pdf.bordertracking.begin    ,
%     pdf.bordertracking.end      ,
%     pdf.leftboundary            ,
%     pdf.rightboundary           ,
%     pdf.brokenlink.rect         ,
%     pdf.brokenlink.skip         ,
%     pdf.brokenlink.dict         ,
%     pdf.bordertracking.endpage  ,
%     pdf.bordertracking.continue ,
%     pdf.originx                 ,
%     pdf.originy
%   }
%    To know where a breakable link can go, we need to track the boundary
%    rectangle. That can be done by hooking into |a| and |x| operations:
%    those names have to be retained. The boundary is stored at the end of
%    the operation. Special effort is needed at the start and end of pages
%    (or rather galleys), such that everything works properly.
%    \begin{macrocode}
/pdf.bordertracking false def
/pdf.bordertracking.begin
  {
    SDict /pdf.bordertracking true put
    SDict /pdf.leftboundary undef
    SDict /pdf.rightboundary undef
    /a where
      {
        /a
          {
            currentpoint pop
            SDict /pdf.rightboundary known dup
              {
                SDict /pdf.rightboundary get 2 index lt
                  { not }
                if
              }
            if
              { pop }
              { SDict exch /pdf.rightboundary exch put }
            ifelse
            moveto
            currentpoint pop
            SDict /pdf.leftboundary known dup
              {
                SDict /pdf.leftboundary get 2 index gt
                  { not }
                if
              }
            if
              { pop }
              { SDict exch /pdf.leftboundary exch put }
            ifelse
          }
        put
      }
    if
  }
    def
/pdf.bordertracking.end
  {
    /a where { /a { moveto } put } if
    /x where { /x { 0 exch rmoveto } put } if
    SDict /pdf.leftboundary known
      { pdf.outerbox 0 pdf.leftboundary put }
    if
    SDict /pdf.rightboundary known
      { pdf.outerbox 2 pdf.rightboundary put }
    if
    SDict /pdf.bordertracking false put
  }
    def
  /pdf.bordertracking.endpage
{
  pdf.bordertracking
    {
      pdf.bordertracking.end
      true setglobal
      pdf.globaldict
        /pdf.brokenlink.rect [ pdf.outerbox aload pop ] put
      pdf.globaldict
        /pdf.brokenlink.skip pdf.baselineskip put
      pdf.globaldict
        /pdf.brokenlink.dict
          pdf.link.dict pdf.cvs put
      false setglobal
      mark pdf.link.dict cvx exec /Rect
        [
          pdf.llx
          pdf.lly
          pdf.outerbox 2 get pdf.linkmargin add
          currentpoint exch pop
          pdf.outerbox pdf.rect.ht sub pdf.linkmargin sub
        ]
      /ANN pdf.pdfmark
    }
  if
}
  def
/pdf.bordertracking.continue
  {
    /pdf.link.dict pdf.globaldict
      /pdf.brokenlink.dict get def
    /pdf.outerbox pdf.globaldict
      /pdf.brokenlink.rect get def
    /pdf.baselineskip pdf.globaldict
      /pdf.brokenlink.skip get def
    pdf.globaldict dup dup
    /pdf.brokenlink.dict undef
    /pdf.brokenlink.skip undef
    /pdf.brokenlink.rect undef
    currentpoint
    /pdf.originy exch def
    /pdf.originx exch def
    /a where
      {
        /a
          {
            moveto
            SDict
            begin
            currentpoint pdf.originy ne exch
              pdf.originx ne or
              {
                pdf.save.linkll
                /pdf.lly
                  pdf.lly pdf.outerbox 1 get sub def
                pdf.bordertracking.begin
              }
            if
            end
          }
        put
      }
    if
    /x where
      {
        /x
          {
            0 exch rmoveto
            SDict
            begin
            currentpoint
            pdf.originy ne exch pdf.originx ne or
              {
                pdf.save.linkll
                /pdf.lly
                  pdf.lly pdf.outerbox 1 get sub def
                pdf.bordertracking.begin
              }
            if
            end
          }
        put
      }
    if
  }
    def
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[int]
%   {
%     pdf.breaklink       ,
%     pdf.breaklink.write ,
%     pdf.count           ,
%     pdf.currentrect
%   }
%   Dealing with link breaking itself has multiple stage. The first step is to
%   find the |Rect| entry in the dictionary, looping over key--value pairs.
%   The first line is handled first, adjusting the rectangle to stay inside the
%   text area. The second phase is a loop over the height of the bulk of the
%   link area, done on the basis of a number of baselines. Finally, the end of
%   the link area is tidied up, again from the boundary of the text area.
%    \begin{macrocode}
/pdf.breaklink
  {
    pop
    counttomark 2 mod 0 eq
      {
        counttomark /pdf.count exch def
          {
            pdf.count 0 eq { exit } if
            counttomark 2 roll
            1 index /Rect eq
              {
                dup 4 array copy
                dup dup
                  1 get
                  pdf.outerbox pdf.rect.ht
                  pdf.linkmargin 2 mul add sub
                  3 exch put
                dup
                  pdf.outerbox 2 get
                  pdf.linkmargin add
                  2 exch put
                dup dup
                  3 get
                  pdf.outerbox pdf.rect.ht
                  pdf.linkmargin 2 mul add add
                  1 exch put
                /pdf.currentrect exch def
                pdf.breaklink.write
                  {
                    pdf.currentrect
                    dup
                      pdf.outerbox 0 get
                      pdf.linkmargin sub
                      0 exch put
                    dup
                      pdf.outerbox 2 get
                      pdf.linkmargin add
                      2 exch put
                    dup dup
                      1 get
                      pdf.baselineskip add
                      1 exch put
                    dup dup
                      3 get
                      pdf.baselineskip add
                      3 exch put
                    /pdf.currentrect exch def
                    pdf.breaklink.write
                  }
                1 index 3 get
                pdf.linkmargin 2 mul add
                pdf.outerbox pdf.rect.ht add
                2 index 1 get sub
                pdf.baselineskip div round cvi 1 sub
                  exch
                repeat
                pdf.currentrect
                dup
                  pdf.outerbox 0 get
                  pdf.linkmargin sub
                  0 exch put
                dup dup
                  1 get
                  pdf.baselineskip add
                  1 exch put
                dup dup
                  3 get
                  pdf.baselineskip add
                  3 exch put
                dup 2 index 2 get  2 exch put
                /pdf.currentrect exch def
                pdf.breaklink.write
                SDict /pdf.pdfmark.good false put
                exit
              }
              { pdf.count 2 sub /pdf.count exch def }
            ifelse
          }
        loop
      }
    if
    /ANN
  }
    def
/pdf.breaklink.write
  {
    counttomark 1 sub
    index /_objdef eq
      {
        counttomark -2 roll
        dup wcheck
          {
            readonly
            counttomark 2 roll
          }
          { pop pop }
        ifelse
      }
    if
    counttomark 1 add copy
    pop pdf.currentrect
    /ANN pdfmark
  }
    def
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[int]
%   {
%     pdf.pdfmark      ,
%     pdf.pdfmark.good ,
%     pdf.outerbox     ,
%     pdf.baselineskip ,
%     pdf.pdfmark.dict
%   }
%   The business end of breaking links starts by hooking into |pdfmarks|.
%   Unlike \pkg{hypdvips}, we avoid altering any links we have not created
%   by using a copy of the core |pdfmarks| function. Only mark types which
%   are known are altered. At present, this is purely |ANN| marks, which are
%   measured relative to the size of the baseline skip. If they are
%   more than one apparent line high, breaking is applied.
%    \begin{macrocode}
/pdf.pdfmark
  {
    SDict /pdf.pdfmark.good true put
    dup /ANN eq
      {
        pdf.pdfmark.store
        pdf.pdfmark.dict
          begin
            Subtype /Link eq
            currentdict /Rect known and
            SDict /pdf.outerbox known and
            SDict /pdf.baselineskip known and
              {
                Rect 3 get
                pdf.linkmargin 2 mul add
                pdf.outerbox pdf.rect.ht add
                Rect 1 get sub
                pdf.baselineskip div round cvi 0 gt
                  { pdf.breaklink }
                if
              }
            if
          end
        SDict /pdf.outerbox undef
        SDict /pdf.baselineskip undef
        currentdict /pdf.pdfmark.dict undef
      }
    if
    pdf.pdfmark.good
      { pdfmark }
      { cleartomark }
    ifelse
  }
    def
/pdf.pdfmark.store
  {
    /pdf.pdfmark.dict 65534 dict def
    counttomark 1 add copy
    pop
      {
        dup mark eq
          {
            pop
            exit
          }
          {
            pdf.pdfmark.dict
            begin def end
          }
        ifelse
      }
    loop
}
  def
%    \end{macrocode}
% \end{macro}
%
%    \begin{macrocode}
%</dvips&header>
%    \end{macrocode}
%
% \end{implementation}
%
% \PrintIndex