summaryrefslogtreecommitdiff
path: root/systems/doc/pdftex/manual/pdftex-syntax.txt
blob: 59cb911e35ae6fa4a7025cb3aee506c81c98b2d2 (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
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
%% $Id: syntaxform.pl 742 2016-04-25 17:30:55Z karl $
%% This is the list of new or extended primitives provided by pdftex.
%% Don't edit this file, as it is now auto-generated from the
%% pdfTeX manual source pdftex-t.tex (and the generated
%% pdftex-syntax.tex) by the script syntaxform.awk.
%% Syntax rule conventions borrowed from `TeXbook naruby' by Petr Olsak.

%% Integer registers:
\efcode <font> <8-bit number>                           (integer)
\knaccode <font> <8-bit number>                         (integer)
\knbccode <font> <8-bit number>                         (integer)
\knbscode <font> <8-bit number>                         (integer)
\lpcode <font> <8-bit number>                           (integer)
\pdfadjustinterwordglue                                 (integer)
\pdfadjustspacing                                       (integer)
\pdfappendkern                                          (integer)
\pdfcompresslevel                                       (integer)
\pdfdecimaldigits                                       (integer)
\pdfdraftmode                                           (integer)
\pdfforcepagebox                                        (integer)
\pdfgamma                                               (integer)
\pdfgentounicode                                        (integer)
\pdfimageapplygamma                                     (integer)
\pdfimagegamma                                          (integer)
\pdfimagehicolor                                        (integer)
\pdfimageresolution                                     (integer)
\pdfinclusioncopyfonts                                  (integer)
\pdfinclusionerrorlevel                                 (integer)
\pdfinfoomitdate                                        (integer)
\pdfmajorversion                                        (integer)
\pdfminorversion                                        (integer)
\pdfobjcompresslevel                                    (integer)
\pdfomitcharset                                         (integer)
\pdfomitinfodict                                        (integer)
\pdfomitprocset                                         (integer)
\pdfoutput                                              (integer)
\pdfpagebox                                             (integer)
\pdfpkresolution                                        (integer)
\pdfprependkern                                         (integer)
\pdfprotrudechars                                       (integer)
\pdfsuppressptexinfo                                    (integer)
\pdfsuppresswarningdupdest                              (integer)
\pdfsuppresswarningdupmap                               (integer)
\pdfsuppresswarningpagegroup                            (integer)
\pdftracingfonts                                        (integer)
\pdfuniqueresname                                       (integer)
\rpcode <font> <8-bit number>                           (integer)
\shbscode <font> <8-bit number>                         (integer)
\showstream                                             (integer)
\stbscode <font> <8-bit number>                         (integer)
\tagcode <font> <8-bit number>                          (integer)
\tracinglostchars                                       (integer)
\tracingstacklevels                                     (integer)

%% Read-only integers:
\pdfelapsedtime                                         (read-only integer)
\pdflastannot                                           (read-only integer)
\pdflastlink                                            (read-only integer)
\pdflastobj                                             (read-only integer)
\pdflastxform                                           (read-only integer)
\pdflastximage                                          (read-only integer)
\pdflastximagecolordepth                                (read-only integer)
\pdflastximagepages                                     (read-only integer)
\pdflastxpos                                            (read-only integer)
\pdflastypos                                            (read-only integer)
\pdfrandomseed                                          (read-only integer)
\pdfretval                                              (read-only integer)
\pdfshellescape                                         (read-only integer)
\pdftexversion                                          (read-only integer)

%% Dimen registers:
\pdfdestmargin                                          (dimen)
\pdfeachlinedepth                                       (dimen)
\pdfeachlineheight                                      (dimen)
\pdffirstlineheight                                     (dimen)
\pdfhorigin                                             (dimen)
\pdfignoreddimen                                        (dimen)
\pdflastlinedepth                                       (dimen)
\pdflinkmargin                                          (dimen)
\pdfpageheight                                          (dimen)
\pdfpagewidth                                           (dimen)
\pdfpxdimen                                             (dimen)
\pdfthreadmargin                                        (dimen)
\pdfvorigin                                             (dimen)

%% Token registers:
\pdfpageattr                                            (tokens)
\pdfpageresources                                       (tokens)
\pdfpagesattr                                           (tokens)
\pdfpkmode                                              (tokens)

%% Expandable commands:
\expanded <tokens>                                      (expandable)
\ifincsname                                             (expandable)
\ifpdfabsdim                                            (expandable)
\ifpdfabsnum                                            (expandable)
\ifpdfprimitive <control sequence>                      (expandable)
\input <general text>                                   (expandable)
\leftmarginkern <box number>                            (expandable)
\pdfcolorstackinit [page] [direct] <general text>       (expandable)
\pdfcreationdate                                        (expandable)
\pdfescapehex <general text>                            (expandable)
\pdfescapename <general text>                           (expandable)
\pdfescapestring <general text>                         (expandable)
\pdffiledump [offset <integer>] [length <integer>] <general text> (expandable)
\pdffilemoddate <general text>                          (expandable)
\pdffilesize <general text>                             (expandable)
\pdffontname <font>                                     (expandable)
\pdffontobjnum <font>                                   (expandable)
\pdffontsize <font>                                     (expandable)
\pdfincludechars <font> <general text>                  (expandable)
\pdfinsertht <integer>                                  (expandable)
\pdflastmatch <integer>                                 (expandable)
\pdfmatch [icase] [subcount <integer>] <general text> <general text> (expandable)
\pdfmdfivesum [file] <general text>                     (expandable)
\pdfnormaldeviate                                       (expandable)
\pdfpageref <page number>                               (expandable)
\pdfstrcmp <general text> <general text>                (expandable)
\pdftexbanner                                           (expandable)
\pdftexrevision                                         (expandable)
\pdfunescapehex <general text>                          (expandable)
\pdfuniformdeviate <number>                             (expandable)
\pdfxformname <object number>                           (expandable)
\pdfximagebbox <integer> <integer>                      (expandable)
\rightmarginkern <box number>                           (expandable)

%% General commands:
\letterspacefont <control sequence> <font> <integer>
\partokenname <control sequence>
\pdfannot <annot type spec>                             (h, v, m)
\pdfcatalog <general text> [openaction <action spec>]
\pdfcolorstack <stack number> <stack action> <general text>
\pdfcopyfont <control sequence> <font>
\pdfdest <dest spec>                                    (h, v, m)
\pdfendlink                                             (h, m)
\pdfendthread                                           (v, m)
\pdffakespace
\pdffontattr <font> <general text>
\pdffontexpand <font> <stretch> <shrink> <step> [autoexpand]
\pdfglyphtounicode <general text> <general text>
\pdfinfo <general text>
\pdfinterwordspaceoff
\pdfinterwordspaceon
\pdfliteral [shipout] [direct | page] <general text>    (h, v, m)
\pdfmapfile <map spec>
\pdfmapline <map spec>
\pdfnames <general text>
\pdfnobuiltintounicode <font>
\pdfnoligatures <font>
\pdfobj <object type spec>                              (h, v, m)
\pdfoutline [<attr spec>] <action spec> [count <integer>] <general text> (h, v, m)
\pdfprimitive <control sequence>
\pdfrefobj <object number>                              (h, v, m)
\pdfrefxform <object number>                            (h, v, m)
\pdfrefximage <object number>
\pdfresettimer
\pdfrestore
\pdfrunninglinkoff
\pdfrunninglinkon
\pdfsave
\pdfsavepos                                             (h, v, m)
\pdfsetmatrix
\pdfsetrandomseed <number>
\pdfspacefont <general text>
\pdfstartlink [<rule spec>] [<attr spec>] <action spec> (h, m)
\pdfthread [<rule spec>] [<attr spec>] <id spec>        (h, v, m)
\pdftrailer <general text>
\pdftrailerid <general text>
\pdftstartthread [<rule spec>] [<attr spec>] <id spec>  (v, m)
\pdfxform [<attr spec>] [<resources spec>] <box number> (h, v, m)
\pdfximage [<rule spec>] [<attr spec>] [<page spec>] [<colorspace spec>] [<pdf box spec>] <general text> (h, v, m)
\quitvmode
\special {pdf: <text> }
\special {pdf:direct: <text> }
\special {pdf:page: <text> }
\special [shipout] {<general text> }
\vadjust [<pre spec>] <filler> { <vertical mode material> } (h, m)

%% Syntax rules:
<general text> --> { <balanced text> }
<attr spec> --> attr <general text>
<resources spec> --> resources <general text>
<rule spec> --> (width | height | depth) <dimen> [<rule spec>]
<object type spec> --> reserveobjnum
                     | [useobjnum <number>] [stream [<attr spec>]] <object contents>
<annot type spec> --> reserveobjnum
                    | [useobjnum <number>] [<rule spec>] <general text>
<object contents> --> <file spec>
                    | <general text>
<xform attr spec> --> [<attr spec>] [<resources spec>]
<image attr spec> --> [<rule spec>] [<attr spec>] [<page spec>] [<colorspace spec>] [<pdf box spec>]
<outline spec> --> [<attr spec>] <action spec> [count <number>] <general text>
<action spec> --> user <user-action spec>
                | goto <goto-action spec>
                | thread <thread-action spec>
<user-action spec> --> <general text>
<goto-action struct spec> --> struct (<numid> | nameid | <general text>)
<goto-action spec> --> [<goto-action struct spec>] <numid>
                     | [<file spec>] [<goto-action struct spec>] <nameid>
                     | [<file spec>] [<goto-action struct spec>] [<page spec>] <general text>
                     | <file spec> [<goto-action struct spec>] <nameid> <newwindow spec>
                     | <file spec> [<goto-action struct spec>] [<page spec>] <general text> <newwindow spec>
<thread-action spec> --> [<file spec>] <numid>
                       | [<file spec>] <nameid>
<colorspace spec> --> colorspace <number>
<pdf box spec> --> mediabox | cropbox | bleedbox | trimbox | artbox
<map spec> --> { [<map modifier>] <balanced text> }
<map modifier> --> + | = | -
<numid> --> num <number>
<nameid> --> name <general text>
<newwindow spec> --> newwindow | nonewwindow
<dest spec> --> [struct <number>] \\
              (<numid> | <nameid>)
              <dest type>
<dest type> --> xyz [zoom <number>]
              | fitr <rule spec>
              | fitbh
              | fitbv
              | fitb
              | fith
              | fitv
              | fit
<thread spec> --> [<rule spec>] [<attr spec>] <id spec>
<id spec> --> <numid> | <nameid>
<file spec> --> file <general text>
<page spec> --> page <number>
<expand spec> --> <stretch> <shrink> <step> [autoexpand]
<stretch> --> <number>
<shrink> --> <number>
<step> --> <number>
<pre spec> --> pre
<pdfspecial spec> --> { [<pdfspecial id> [<pdfspecial modifier>]] <balanced text> }
<pdfspecial id> --> pdf: | PDF:
<pdfspecial modifier> --> direct:
<stack action> --> set | push | pop | current
<goto-action spec> --> [<goto-action struct spec>] <numid>
                     | [<file spec>] [<goto-action struct spec>] <nameid>
                     | [<file spec>] [<goto-action struct spec>] [<page spec>] <general text>
                     | <file spec> [<goto-action struct spec>] <nameid> <newwindow spec>
                     | <file spec> [<goto-action struct spec>] [<page spec>] <general text> <newwindow spec>
<text> }} is equivalent to \Syntax{\pdfliteral
shipout { <text> }}.
================= ERROR
%***********************************************************************
================= ERROR
\subsection{Strings}
================= ERROR
\pdftexprimitive{\Syntax{\pdfescapestring <general text>
                                                        (expandable)}}
\bookmark{\pdfescapestring}
================= ERROR
Starting with version 1.30.0, \PDFTEX\ provides a mechanism for converting
a general text into \PDF\ string. Many characters that may be needed inside
such a text (especially parenthesis), have a special meaning inside a \PDF\
string object and thus, can't be used literally. The primitive replaces each
special \PDF\ character by its literal representation by inserting a backslash
before that character. Some characters (\eg\ space) are also converted into
3-digit octal number. In example, \type{\pdfescapestring{Text (1)}} will be
expanded to \type{Text\040\(1\)}. This ensures a literal interpretation of the
text by the \PDF\ viewer.
\introduced{1.30.0}
================= ERROR
\pdftexprimitive{\Syntax{\pdfescapename <general text>
                                                        (expandable)}}
\bookmark{\pdfescapename}
================= ERROR
In analogy to \type{\pdfescapestring}, \type{\pdfescapename} replaces each
special \PDF\ character inside the general text by its hexadecimal
representation preceded by \type{#} character. This ensures the proper
interpretation of the text if used as a \PDF\ name object. In example,
\type{Text (1)} will be replaced by \type{Text#20#281#29}.
\introduced{1.30.0}
================= ERROR
\pdftexprimitive{\Syntax{\pdfescapehex <general text>
                                                        (expandable)}}
\bookmark{\pdfescapehex}
================= ERROR
This command converts each character of <general text> into its
hexadecimal representation. Each character of the argument becomes a pair of
hexadecimal digits. \introduced{1.30.0}
================= ERROR
\pdftexprimitive{\Syntax{\pdfunescapehex <general text>
                                                        (expandable)}}
\bookmark{\pdfunescapehex}
================= ERROR
This command treats each character pair of <general text> as
a hexadecimal number and returns an \ASCII\ character of this code.
\introduced{1.30.0}
================= ERROR
\pdftexprimitive{\Syntax{\pdfstrcmp <general text>
                     <general text>                     (expandable)}}
\bookmark{\pdfstrcmp}
================= ERROR
This command compares two strings and expands to \type{0} if the strings
are equal, to \type{-1} if the first string ranks before the second, and
to \type{1} otherwise.  \introduced{1.30.0}
================= ERROR
\pdftexprimitive{\Syntax{\pdfmatch [icase]
                     [subcount <integer>] <general text>
                     <general text>                     (expandable)}}
\bookmark{\pdfmatch}
================= ERROR
This command implements pattern matching (using the syntax of \POSIX\
extended regular expressions). The first <general text> is a
pattern and the second is a string.  The command expands to \type{-1} if
the pattern is invalid, to \type{0} if no match is found, and to
\type{1} if a match is found. With the \type{icase} option, the matching
is case-insensitive.  The \type{subcount} option sets the size of the
table storing the found (sub)patterns; its default is 10.
\introduced{1.30.0}
================= ERROR
\pdftexprimitive{\Syntax{\pdflastmatch <integer>
                                                        (expandable)}}
\bookmark{\pdflastmatch}
================= ERROR
The matches found with \type{\pdfmatch} are stored in a table. This
command returns the entry for <integer>, in the format
<position>\type{->}<string>; <position> is
the position of the match (starting at zero) or \type{-1} if no match
was found, and <string> is the matched substring.
================= ERROR
Entry~0 contains the match as a whole; the subsequent entries contain
submatches corresponding to the subpatterns, up to \type{subcount-1}.
================= ERROR
If <integer> is less than zero, an error is given.
================= ERROR
For instance:
================= ERROR
\starttyping
\pdfmatch subcount 3 {ab(cd)*ef(gh)(ij)}{abefghij}
\pdflastmatch0 % "0->abefghij"
\pdflastmatch1 % "-1->"
\pdflastmatch2 % "4->gh"
\pdflastmatch3 % "-1->"
\stoptyping
================= ERROR
Entry~1 is empty because no match was found for \type{cd}, and entry~3
is empty because it exceeds the table's size as set by \type{subcount}.
\introduced{1.30.0}
================= ERROR
%***********************************************************************
================= ERROR
\subsection{Numbers}
================= ERROR
\pdftexprimitive{\Syntax{\ifpdfabsnum                   (expandable)}}
\bookmark{\ifpdfabsnum}
================= ERROR
This conditional works like the standard \type{\ifnum}, except that it
compares absolute values of numbers. Although it seems to be a trivial
shortcut for a couple of \type{\ifnum x<0} tests, as a primitive it is
considerably more friendly in usage and works a bit faster.
\introduced{1.40.0}
================= ERROR
\pdftexprimitive{\Syntax{\ifpdfabsdim                   (expandable)}}
\bookmark{\ifpdfabsdim}
================= ERROR
Analogous to \type{\ifpdfabsnum}, this conditional works like
\type{\ifdim}, except that it compares absolute values of
dimensions. \introduced{1.40.0}
================= ERROR
\pdftexprimitive{\Syntax{\pdfuniformdeviate <number>
                                                        (expandable)}}
\bookmark{\pdfuniformdeviate}
================= ERROR
Generate a uniformly-distributed random integer value between 0
(inclusive) and <number> (exclusive). This primitive expands
to a list of tokens. \introduced{1.30.0}
================= ERROR
\pdftexprimitive{\Syntax{\pdfnormaldeviate              (expandable)}}
\bookmark{\pdfnormaldeviate}
================= ERROR
Generate a normally-distributed random integer with a mean of~0 and
standard deviation 65\,536.  That is, about 68\% of the time, the result
will be between $-65536$ and $65536$ (one standard deviation away from
the mean).  About 95\% of results will be within two standard
deviations, and 99.7\% within three.  This primitive expands to a list
of tokens. \introduced{1.30.0}
================= ERROR
\pdftexprimitive{\Syntax{\pdfrandomseed                 (read-only integer)}}
\bookmark{\pdfrandomseed}
================= ERROR
You can use \type{\the\pdfrandomseed} to query the current seed value,
so you can \eg\ write the value to the log file.  The initial value of
the seed is derived from the system time, and is not more than
1\,000\,999\,999 (this ensures that the value can be used with commands
like \type{\count}). \introduced{1.30.0}
================= ERROR
\pdftexprimitive{\Syntax{\pdfsetrandomseed <number>}}
\bookmark{\pdfsetrandomseed}
================= ERROR
Set the random seed (\type{\pdfrandomseed}) to a specific value,
allowing you to replay sequences of semi-randoms at a later moment.
\introduced{1.30.0}
================= ERROR
%***********************************************************************
================= ERROR
\subsection{Timekeeping}
================= ERROR
\pdftexprimitive{\Syntax{\pdfelapsedtime                (read-only integer)}}
\bookmark{\pdfelapsedtime}
================= ERROR
Return a number that represents the time elapsed from the moment of the
start of the run. The elapsed time is returned in `scaled seconds',
meaning seconds divided by 65536, \eg\ \PDFTEX\ has run for
\the\pdfelapsedtime\ `scaled seconds' when this paragraph was
typeset. Of course, the command will never return a value greater than
the highest number available in \TeX: if the time exceeds 32767 seconds,
the constant value $2^{31}-1$ will be returned.  \introduced{1.30.0}
================= ERROR
\pdftexprimitive{\Syntax{\pdfresettimer}}
\bookmark{\pdfresettimer}
================= ERROR
Reset the internal timer so that \type{\pdfelapsedtime}
starts returning micro-time from~0 again. \introduced{1.30.0}
================= ERROR
%***********************************************************************
================= ERROR
\subsection{Files}
================= ERROR
\pdftexprimitive{\Syntax{\pdffilemoddate <general text>
                                                        (expandable)}}
\bookmark{\pdffilemoddate}
================= ERROR
Expands to the modification date of file <general text> in the
same format as for \type{\pdfcreationdate}, \eg\ it's {\tt
\pdffilemoddate {./pdftex-t.tex}} for the source of this manual. As of
version 1.40.20, if the \type{SOURCE_DATE_EPOCH} and
\type{FORCE_SOURCE_DATE} environment variables are both set,
\type{\pdffilemoddate} returns a value in UTC, ending in \type{Z}.
\introduced{1.30.0}
================= ERROR
\pdftexprimitive{\Syntax{\pdffilesize <general text>
                                                        (expandable)}}
\bookmark{\pdffilesize}
================= ERROR
Expands to the size of file <general text>, \eg\ it's {\tt
\pdffilesize {./pdftex-t.tex}} for the source of this manual.
\introduced{1.30.0}
================= ERROR
\pdftexprimitive{\Syntax{\pdfmdfivesum
                     [file]
                     <general text>                     (expandable)}}
\bookmark{\pdfmdfivesum\ file}
================= ERROR
If the keyword \type{file} is given, expands to the \MDFIVE\ of file
\Somethingtext{general text} in uppercase hexadecimal format (same as
\type{\pdfescapehex}). Without \type{file}, expands to the \MDFIVE\ of
the \Somethingtext{generaltext} taken as a string. For example, it's
{\tt \pdfmdfivesum file {./pdftex-t.tex}} for the source of this manual.
\introduced{1.30.0}
================= ERROR
\pdftexprimitive{\Syntax{\pdffiledump
                     [offset <integer>]
                     [length <integer>]
                     <general text>                     (expandable)}}
\bookmark{\pdffiledump}
================= ERROR
Expands to the dump of the first \type{length} \Somethingtext{integer}
bytes of the file \Somethingtext{general text}, in uppercase hexadecimal
format (same as \type{\pdfescapehex}), starting at offset
\type{offset}~\Somethingtext{number}, or the beginning of the file if
\type{offset}. If \type{length} is not given, the default is zero, so
expands to nothing. Both \Somethingtext{integer}s must be $\ge0$. For
example, the first ten bytes of the source of this manual are {\tt
\pdffiledump length 10 {./pdftex-t.tex}}. \introduced{1.30.0}
================= ERROR
\pdftexprimitive{\Syntax{\input <general text>
                                                        (expandable)}}
\bookmark{\input}
================= ERROR
As of \TEXLIVE\ 2020, the \type{\input} primitive in all \TEX\ engines,
including \PDFTEX, now also accepts a group-delimited filename argument,
as a system-dependent extension, as in \type{\input} {
\type{foo.tex} }. The usage of \type{\input} with a standard
space/token-delimited filename is completely unchanged.
================= ERROR
This group-delimited argument was previously implemented in Lua\TEX; now
it is available in all engines. \ASCII\ double quote characters
(\type{"}) are removed from the filename, but it is otherwise left
unchanged after tokenization.
================= ERROR
This extension is unlike most others in that it affects a primitive in
standard \TEX\ (\type{\input}), rather than being related to a new
primitive, command line option, etc. This is allowed because additional
methods of recognizing filenames are explicitly mentioned in
\type{tex.web} as acceptable system-dependent extensions.
================= ERROR
Incidentally, this does not directly affect \LATEX's \type{\input}
command, as that is a macro redefinition of the standard \type{\input}
primitive.
================= ERROR
\introduced{1.40.21}
================= ERROR
%***********************************************************************
================= ERROR
\subsection{Color stack}
================= ERROR
\PDFTEX\ 1.40.0 comes with color stack support (actually any graphic state
stack).
================= ERROR
\pdftexprimitive{\Syntax{\pdfcolorstackinit [page]
                     [direct] <general text>            (expandable)}}
\bookmark{\pdfcolorstackinit}
================= ERROR
The primitive initializes a new graphic stack and returns its number. Optional
page keyword instructs \PDFTEX\ to restore the graphic at the
beginning of every new page. Also optional direct has the same effect
as for \pdfliteral primitive. \introduced{1.40.0}
================= ERROR
\pdftexprimitive{\Syntax{\pdfcolorstack <stack number>
                     <stack action> <general text>}}
\bookmark{\pdfcolorstack}
================= ERROR
The command operates on the stack of a given number. If \Something{stack
action} is push keyword, the new value provided as
<general text> is inserted into the top of the graphic stack
and becomes the current stack value. If followed by pop, the
top value is removed from the stack and the new top value becomes the
current. set keyword replaces the current value with
<general text> without changing the stack size.
current keyword instructs just to use the current stack value
without modifying the stack at all. \introduced{1.40.0}
================= ERROR
%***********************************************************************
================= ERROR
\subsection{Transformations}
================= ERROR
Since the content of \pdfliteral is not interpreted anyhow, any
transformation inserted directly into the content stream, as well as saving
and restoring the current transformation matrix, remains unnoticed by
\PDFTEX\ positioning mechanism. As a consequence, links and other annotations
(that are formed in \PDF\ as different layer then the page content) are not
affected by such user-defined transformations. \PDFTEX\ 1.40.0 solves this
problem with three new primitives.
================= ERROR
\pdftexprimitive{\Syntax{\pdfsetmatrix}}
\bookmark{\pdfsetmatrix}
================= ERROR
Afine transformations are normally expressed with six numbers. First
four (no unit) values defining scaling, rotating and skewing, plus two
extra dimensions for shifting. Since the translation is handled by \TeX\
itself, \pdfsetmatrix primitive expects as an argument a string
containing just the first four numbers of the transformation separated
by a space and assumes two position coordinates to be~0. In example,
\type{\pdfsetmatrix{0.87 -0.5 0.5 0.87}} rotates the current space by 30
degrees, inserting \type{0.87 -0.5 0.5 0.87 0 0 cm} into the content
stream. \introduced{1.40.0}
================= ERROR
\pdftexprimitive{\Syntax{\pdfsave}}
\bookmark{\pdfsave}
================= ERROR
The command saves the current transformation by inserting \type{q}
operator into the content stream. \introduced{1.40.0}
================= ERROR
\pdftexprimitive{\Syntax{\pdfrestore}}
\bookmark{\pdfrestore}
================= ERROR
The command restores previously saved transformation by inserting \type{Q}
operator into the content stream. One should keep in mind that \pdfsave
and \pdfrestore pairs should always be properly nested and should start
and end at the same group level. \introduced{1.40.0}
================= ERROR
%***********************************************************************
================= ERROR
\subsection{Macro programming}
================= ERROR
Expansion-related.
================= ERROR
\pdftexprimitive{\Syntax{\expanded <tokens>
                                                        (expandable)}}
\bookmark{\expanded}
================= ERROR
Expands <tokens> in exactly the same way as \type{\message}.
In contrast to \type{\edef}, macro parameter characters do not need to
be doubled. \type{\protected} macros are not expanded.
\introduced{1.40.20}
================= ERROR
================= ERROR
\pdftexprimitive{\Syntax{\ifincsname                    (expandable)}}
\bookmark{\ifincsname}
================= ERROR
This conditional is true if evaluated inside \type{\csname ... \endcsname},
and false otherwise.
================= ERROR
================= ERROR
\pdftexprimitive{\Syntax{\ifpdfprimitive <control sequence>
                                                        (expandable)}}
\bookmark{\ifpdfprimitive}
================= ERROR
This condition checks if the following control sequence has its
primitive meaning. If it has, \type{\ifpdfprimitive} returns true. In
any other case (redefined, made \type{\undefined}, has never been
primitive) false is returned.  \introduced{1.40.0}
================= ERROR
================= ERROR
flapping\pdftexprimitive{\Syntax{\partokencontext <number>}}
\bookmark{\partokencontext}
================= ERROR
The {\em par-token} (i.e., the token with the name given by
\type{\partokenname}, or \type{\par} by default; see
\type{\partokenname}, next) is inserted into the input stream in
different places, according to the \type{\partokencontext} value. This
value can be:
================= ERROR
0: {\em par-token} is inserted at empty lines (more exactly, when a
                     token category~5 is seen in state~$N$, reading a line); before
                     \type{\end}, \type{\vskip}, \type{\hrule}, \type{\unvbox}, and
                     \type{\halign}, if \TeX{} is in horizontal mode when those commands
                     are seen; and in various error recovery situations. These are the
                     standard cases, and this is the default value.
================= ERROR
1: {\em par-token} is inserted as above, and also at the end of
                     \type{\vbox}, \type{\vtop}, and \type{\vcenter}, if \TeX{} is in
                     horizontal mode at the time.
================= ERROR
2: {\em par-token} is inserted as above, and also at the end of
                     \type{\insert}, \type{\vadjust}, \type{\output}, \type{\noalign}, and
                     items of \type{\valign}, again if \TeX{} is in horizontal mode at the
                     time.
================= ERROR
With the default \type{\partokencontext=0}, \TEX\ behaves in its normal
way: the situations in cases 1 and 2 are processed by a direct call of
{\em end-paragraph} routine, with no emitted {\em par-token}.
================= ERROR
If \type{\partokencontext=1} then \TeX\ inserts the {\em par-token} in
additional cases: when vertical boxes are completed but horizontal mode
is not finished. Since vboxes are not uncommonly inserted directly by
users, with horizontal mode material, this allows macro programmers to
control all such boxes being finished by a {\em par-token}. An example:
================= ERROR
\starttyping
\partokenname\_mypar
\partokencontext=1
\def\_mypar{Hi there!\endgraf}
\vbox{Vbox text.}
\stoptyping
================= ERROR
This will output ``\type{Hi there!''}\ after ``\type{Vbox text.}''.
================= ERROR
Finally, with \type{\partokencontext=2}, all cases where classical \TeX\
uses the direct {\em end-paragraph} routine are changed to emit the {\em
par-token} instead. In contrast to case~1, these commands are rarely
invoked directly by users with horizontal mode material.
================= ERROR
The setting of the register \type{\partokencontext} is local.
\introduced{1.40.24}
================= ERROR
\pdftexprimitive{\Syntax{\partokenname <control sequence>}}
\bookmark{\partokenname}
================= ERROR
\TeX{} internally inserts a control sequence, named \type{\par} by
default, into the input stream at empty lines, the end of vboxes, and
various other places (see \type{\partokencontext}, above). Let's call this
control sequence the {\em par-token}.
================= ERROR
Executing \type{\partokenname}<control-sequence> changes the
name of the {\em par-token} from \type{\par} to the given
<control-sequence>. The setting performed by
\type{\partokenname} is global.
================= ERROR
This makes it possible to release the name \type{\par} to the ``user's
name space'', i.e., after \type{\partokenname}, users can define and use
\type{\par} as they wish without changing the behavior of anything
internal to \TeX{}. For example:
================= ERROR
\starttyping
\catcode`\_=11
\partokenname\_mypar % use \_mypar at user level
\let\_mypar=\par     % make \_mypar equivalent to built-in \par
\def\par{some random text} % redefine \par
Hello world.
================= ERROR
Goodbye.
\end
\stoptyping
================= ERROR
This will not output ``\type{some random text}'' (the definition of
\type{\par}), due to the \type{\partokenname} setting.
================= ERROR
By default, the meaning of the {\em par-token} is to end a paragraph
(also named as \type{\endgraf} in the plain \TEX\ format). It can be
changed as usual with, for example, \type{\def}. Naturally, it is the
control sequence name given to \type{\partokenname} that must be
redefined. Continuing the previous example (prior to the \type{\end}):
================= ERROR
\starttyping
\def\_mypar{Hi there!\endgraf}
Paragraph one.
================= ERROR
Paragraph two.\let\_mypar=\endgraf
\stoptyping
================= ERROR
This will output ``\type{Hi there!''}\ after ``\type{Paragraph one.}'',
before ending the paragraph.
================= ERROR
Another behavior of the {\em par-token} built into \TEX\ is that macros
not defined as \type{\long} cause the error ``runaway argument'' if the
{\em par-token} is scanned as a parameter. After
\type{\setpartokenname}, it will be the new control sequence name that
triggers this error, not \type{\par}. For example (still continuing the
same example):
================= ERROR
\starttyping
\def\amac#1{}
\amac{long test, no error: \par}
\amac{long test, gives error: \_mypar}
\stoptyping
================= ERROR
\introduced{1.40.24}
================= ERROR
\pdftexprimitive{\Syntax{\pdfprimitive <control sequence>}}
\bookmark{\pdfprimitive}
================= ERROR
This command executes the primitive meaning of the following control
sequence, regardless of whether the control sequence has been redefined
or made undefined. If the primitive was expandable, \type{\pdfprimitive}
expands also. On the other hand, if the following control sequence never
was a primitive, nothing happens and no error is raised. (In some
versions of \PDFTEX\ prior to 1.40.19, an error was wrongly given.)
\introduced{1.40.0}
================= ERROR
%***********************************************************************
================= ERROR
\subsection{Typesetting}
================= ERROR
\pdftexprimitive{\Syntax{\pdfinsertht <integer>
                                                        (expandable)}}
\bookmark{\pdfinsertht}
================= ERROR
If <integer> is the number of an insertion class, this command
returns the height of the corresponding box at the current time.
For instance, the following returns \type{12pt} in plain \TEX:
================= ERROR
\starttyping
Abc\footnote*{Whatever.}\par
\pdfinsertht\footins
\stoptyping
================= ERROR
================= ERROR
\pdftexprimitive{\Syntax{\pdflastxpos                   (read-only integer)}}
\bookmark{\pdflastxpos}
================= ERROR
This primitive returns an integer number representing the absolute $x$
coordinate of the last point marked by \type{\pdfsavepos}. The unit is
`scaled points' (sp).
================= ERROR
================= ERROR
\pdftexprimitive{\Syntax{\pdflastypos                   (read-only integer)}}
\bookmark{\pdflastypos}
================= ERROR
Completely analogous to \type{\pdflastxpos}, returning the $y$ coordinate.
================= ERROR
================= ERROR
\pdftexprimitive{\Syntax{\pdfsavepos                    (h, v, m)}}
\bookmark{\pdfsavepos}
================= ERROR
This primitive marks the current absolute ($x,y$) position on the
media, with the reference point in the lower left corner. It is active
only during page shipout, when the page is finally assembled. The
position coordinates can then be retrieved by the \type{\pdflastxpos}
and \type{\pdflastypos} primitives, and \eg\ written out to some
auxiliary file. The coordinates can be used only after the current
\type{\shipout} has been finalized, therefore normally two \PDFTEX\
runs are required to utilize these primitives. Starting with
\PDFTEX\ 1.40.0, this mechanism can be used also while running
in \DVI\ mode.
================= ERROR
================= ERROR
\pdftexprimitive{\Syntax{\quitvmode}}
\bookmark{\quitvmode}
================= ERROR
The primitive instructs \PDFTEX\ to quit vertical mode and start
typesetting a paragraph. Thus, \type{\quitvmode} has the same basic
effect as the \type{\leavevmode} macro from \type{plain.tex}. However,
\type{\leavevmode} expands the \type{\everypar} tokens list, which may
or may not be desired. \type{\quitvmode} does not expand
\type{\everypar}. \introduced{1.21a}
================= ERROR
================= ERROR
\pdftexprimitive{\Syntax{\vadjust
                     [<pre spec>]
                     <filler>
                     { <vertical mode material> }
                                                        (h, m)