summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/eplain/base/hlink.texi
blob: 083bfa99fac71c79f1fc739b4aef2ca0d2390807 (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
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
1159
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
1174
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
1189
1190
1191
1192
1193
1194
1195
1196
1197
1198
1199
1200
1201
1202
1203
1204
1205
1206
1207
1208
1209
1210
1211
1212
1213
1214
1215
1216
1217
1218
1219
1220
1221
1222
1223
1224
1225
1226
1227
1228
1229
1230
1231
1232
1233
1234
1235
1236
1237
1238
1239
1240
1241
1242
1243
1244
1245
1246
1247
1248
1249
1250
1251
1252
1253
1254
1255
1256
1257
1258
1259
1260
1261
1262
1263
1264
1265
1266
1267
1268
1269
1270
1271
1272
1273
1274
1275
1276
1277
1278
1279
1280
1281
1282
1283
1284
1285
1286
1287
1288
1289
1290
1291
1292
1293
1294
1295
1296
1297
1298
1299
1300
1301
1302
1303
1304
1305
1306
1307
1308
1309
1310
1311
1312
1313
1314
1315
1316
1317
1318
1319
1320
1321
1322
1323
1324
1325
1326
1327
1328
1329
1330
1331
1332
1333
1334
1335
1336
1337
1338
1339
1340
1341
1342
1343
1344
1345
1346
1347
1348
1349
1350
1351
1352
1353
1354
1355
1356
1357
1358
1359
1360
1361
1362
1363
1364
1365
1366
1367
1368
1369
1370
1371
1372
1373
1374
1375
1376
1377
1378
1379
1380
1381
1382
1383
1384
1385
1386
1387
1388
1389
1390
1391
1392
1393
1394
1395
1396
1397
1398
1399
1400
1401
1402
1403
1404
1405
1406
1407
1408
1409
1410
1411
1412
1413
1414
1415
1416
1417
1418
1419
1420
1421
1422
1423
1424
1425
1426
1427
1428
1429
1430
1431
1432
1433
1434
1435
1436
1437
1438
1439
1440
1441
1442
1443
1444
1445
1446
1447
1448
1449
1450
1451
1452
1453
1454
1455
1456
1457
1458
1459
1460
1461
1462
1463
1464
1465
1466
1467
1468
1469
1470
1471
1472
1473
1474
1475
1476
1477
1478
1479
1480
1481
1482
1483
1484
1485
1486
1487
1488
1489
1490
1491
1492
1493
1494
1495
1496
1497
1498
1499
1500
1501
1502
1503
1504
1505
1506
1507
1508
1509
1510
1511
1512
1513
1514
1515
1516
1517
1518
1519
1520
1521
1522
1523
1524
1525
1526
1527
1528
1529
1530
1531
1532
1533
1534
1535
1536
1537
1538
1539
1540
1541
1542
1543
1544
1545
1546
1547
1548
1549
1550
1551
1552
1553
1554
1555
1556
1557
1558
1559
1560
1561
1562
1563
1564
1565
1566
1567
1568
1569
1570
1571
1572
1573
1574
1575
1576
1577
1578
1579
1580
1581
1582
1583
1584
1585
1586
1587
1588
1589
1590
1591
1592
1593
1594
1595
1596
1597
1598
1599
1600
1601
1602
1603
1604
1605
1606
1607
1608
1609
1610
1611
1612
1613
1614
1615
1616
1617
1618
1619
1620
1621
1622
1623
1624
1625
1626
1627
1628
1629
1630
1631
1632
1633
1634
1635
1636
1637
1638
1639
1640
1641
1642
1643
1644
1645
1646
1647
1648
1649
1650
1651
1652
1653
1654
1655
1656
1657
1658
1659
1660
1661
1662
1663
1664
1665
1666
1667
1668
1669
1670
1671
1672
1673
1674
1675
1676
1677
1678
1679
1680
1681
1682
1683
1684
1685
1686
1687
1688
1689
1690
1691
1692
1693
1694
1695
1696
1697
1698
1699
1700
1701
1702
1703
1704
1705
1706
1707
1708
1709
1710
1711
1712
1713
1714
1715
1716
1717
1718
1719
1720
1721
1722
1723
1724
1725
1726
1727
1728
1729
1730
1731
1732
1733
1734
1735
1736
1737
1738
1739
1740
1741
1742
1743
1744
1745
1746
1747
1748
1749
1750
1751
1752
1753
1754
1755
1756
1757
1758
1759
1760
1761
1762
1763
1764
1765
1766
1767
1768
1769
1770
1771
1772
1773
1774
1775
1776
1777
1778
1779
1780
1781
1782
1783
1784
1785
1786
1787
1788
1789
1790
1791
1792
1793
1794
1795
1796
1797
1798
1799
1800
1801
1802
1803
1804
1805
1806
1807
1808
1809
1810
1811
1812
1813
1814
1815
1816
1817
1818
1819
1820
1821
1822
1823
1824
1825
1826
1827
1828
1829
1830
1831
1832
1833
1834
1835
1836
1837
1838
1839
1840
1841
1842
1843
1844
1845
1846
1847
1848
1849
1850
1851
1852
1853
1854
1855
1856
1857
1858
1859
1860
@c This is part of the Eplain manual.  Public domain.

@node Hyperlinks
@chapter Hyperlinks

@cindex links, hypertext
@cindex hypertext links
This chapter describes the support which Eplain provides for hypertext
links (@dfn{hyperlinks} for short).  Hyperlinks can be created
implicitly by the cross-reference, indexing and other macros in
Eplain.  Macros for constructing explicit hyperlinks are also
provided.

@menu
* Introduction to hyperlinks::
* Explicit hyperlinks::
* Implicit hyperlinks::
* Hyperlink drivers::
* Setting hyperlink types and options::
* Turning hyperlinks on/off::
@end menu


@node Introduction to hyperlinks
@section Introduction to hyperlinks

@cindex hyperlink drivers
@cindex drivers, hyperlink
The original @TeX{} engine has no built-in support for hyperlinks.
Many of the present-day file formats with hyperlinking capabilities
did not even exist at the time @TeX{} was written.  However, @TeX{}'s
@findex special
@code{\special} primitive can be used to instruct @TeX{} to write
special directives into its @file{.dvi} output file.  These directives
are not interpreted by @TeX{} in any way; they are intended for programs
which process the @file{.dvi} files produced by @TeX{}, be it printing
or converting to other formats, such as
@pindex .ps @r{files}
@pindex .pdf @r{files}
@file{.ps} or @file{.pdf}.

Another approach is to extend the original @TeX{} engine with the
ability to generate one of the hyperlinking formats; @TeX{}'s set of
primitives can be extended to include hyperlink commands.  This is the
approach used by the pdf@TeX{} engine, which is capable of producing
@file{.pdf} files directly from the @TeX{} source, skipping the
@file{.dvi} generation and processing step.

It turns out that the sets of commands for different formats are mostly
not interchangeable, as each of the file formats has its own quirks and
capabilities.  And this is where Eplain @dfn{hyperlink drivers} come
into play.

In order for Eplain to generate proper commands, Eplain has to know
two things: which engine or @file{.dvi} processor you are using, and
the set of commands it understands.

The knowledge about the commands that the various processors
understand is programmed into Eplain's hyperlink drivers.  Eplain
provides two drivers, @code{pdftex} and @code{dvipdfm}, named after
the programs which process the hyperlink commands,
@pindex pdftex
pdf@TeX{} and
@pindex dvipdfm
dvipdfm.  Therefore, Eplain can only produce hyperlink commands for one
of these two programs---except that the extended @code{dvipdfmx} program
can be used as well as the original @code{dvipdfm}, since they are
compatible.

To tell Eplain which @file{.dvi} processor or extended @TeX{} engine you
are using, use the command
@findex enablehyperlinks
@code{\enablehyperlinks}.

For example:

@example
\enablehyperlinks
@end example

@noindent instructs Eplain to attempt to automatically detect which
driver to use, as follows: if it detects pdf@TeX{} in PDF mode, it
loads the @code{pdftex} driver.  If it does not detect pdf@TeX{} in
PDF mode, the @code{dvipdfm} driver is loaded.  The detection is based
on the
@findex ifpdf
@code{\ifpdf} switch (@pxref{Checking for PDF output}).

If necessary, you can explicitly specify the driver name:

@example
\enablehyperlinks[pdftex]
@end example

@noindent will start producing hyperlinks under the assumption that
you are using pdf@TeX{}.

Eplain does not produce any hyperlinks until you explicitly enable
them with @code{\enablehyperlinks}.  For one thing, this keeps Eplain
backward-compatible with previous releases without hyperlink support.
For another, you may be using a program other than pdf@TeX{} or
@code{dvipdfm}, which does not understand their hyperlink commands.

@subheading Concepts and Terminology

In general, hyperlinks work as follows.  You mark some place in your
document as a hyperlink destination, associating a @dfn{hyperlink
label} with that destination.  Next, somewhere within your document,
you create a hyperlink, using a label to identify the destination you
want this link to point to.  A hyperlink is a region in the document
(which can take many forms, for example, text or a picture); when a
user clicks on that region, they will be taken to a place in the
document marked by the corresponding destination.  The following two
sections (@ref{Explicit hyperlinks}, and @ref{Implicit hyperlinks})
describe the macros you can use to define destinations and create
links pointing to those destinations.

In the rest of this chapter, we will often need to refer to links and
destinations jointly, in which case we will use the term
@dfn{hyperlinks}.  We will use the terms @dfn{links} and
@dfn{destinations} in cases when we need to refer specifically to
links or destinations.

@cindex link type
@cindex destination type
@cindex type, link and destination
Hyperlink drivers provide several kinds of links and destinations.  We
will refer to them as @dfn{link types} and @dfn{destination types}.

For example, one of the destination types that the @code{pdftex}
driver provides is the @samp{xyz} type; when the user follows a link
pointing to an @samp{xyz} destination, the exact location marked by
that destination is displayed.  Another destination type provided by
the @code{pdftex} driver is the @samp{fit} type; when the user follows
a link pointing to a @samp{fit} destination, the page containing that
destination is zoomed to fit into the window in which the document is
displayed.

Similarly, drivers support various link types.  For example, with the
@code{pdftex} driver, the usual link type used to refer to
destinations in the current document is called @samp{name}.  You can
also create a link pointing to another local document (by using the
@samp{filename} link type) or to a URL (by using the @samp{url} link
type).

@cindex link options
@cindex destination options
@cindex options, link and destination
In addition, each hyperlink driver supports a number of destination and
link @dfn{options}.  By setting these options you can customize
hyperlink parameters (e.g., the thickness of the border drawn around a
hyperlink) or pass information to hyperlinks (for example, file name of
a document, for a link pointing to a destination in another document).

@xref{Hyperlink drivers}, for the description of hyperlink types and
options supported by the drivers.  @xref{Setting hyperlink types and
options}, for the information on how to set hyperlink options.


@node Explicit hyperlinks
@section Explicit hyperlinks

@cindex explicit hyperlinks
@cindex hyperlinks, explicit
@findex hldest
Explicit hyperlinks are created by you, in the source of your
document.  The simplest command is @code{\hldest}, which marks the
current position in your document as a destination:

@example
\hldest@{@var{type}@}@{@var{options}@}@{@var{label}@}
@end example

@noindent Here @var{type} is one of the destination types supported by
the hyperlink driver (@pxref{Hyperlink drivers}), @var{options} is a
comma-separated list of option assignments, and @var{label} is the
hyperlink label to associate with this destination.  This label will
identify the destination when creating links pointing to this
destination.  For example, with the @code{pdftex} driver, the command

@example
\hldest@{xyz@}@{zoom=2000@}@{index@}
@end example

@noindent creates a destination of type @samp{xyz} (``the current
position''), sets the magnification ratio for this destination to be
200%, and associates the label @code{index} with the destination.

@findex hlstart
@findex hlend
Another command, @code{\hlstart}, paired with @code{\hlend}, turns all
intervening material into a link:

@example
\hlstart@{@var{type}@}@{@var{options}@}@{@var{label}@} @dots{} \hlend
@end example

@noindent Here @var{type}, @var{options} and @var{label} have the same
meaning as for @code{\hldest}.  Continuing the previous example,

@example
\hlstart@{name@}@{bstyle=U,bwidth=2@}@{index@} Index\hlend
@end example

@noindent typesets the word `Index' as a link with underline border of
width@tie{}2@tie{}PostScript points, pointing to the named destination
@code{index} defined in the previous example.  (The other options, like
highlight mode and border color, are determined by the defaults,
@pxref{Setting default types and options}).

Both @code{\hldest} and @code{\hlstart} ignore following spaces.

Both @code{\hldest} and @code{\hlstart} expand the first token of
@var{options} once, so you can save a list of options in a macro and
pass it for the @var{options}.  For example:

@example
\def\linkopts@{bstyle=U,bwidth=2@}
\hlstart@{name@}@{\linkopts@}@{index@}Index\hlend
@end example

@noindent is functionally equivalent to the previous example.


@node Implicit hyperlinks
@section Implicit hyperlinks

@cindex implicit hyperlinks
@cindex hyperlinks, implicit
@dfn{Implicit hyperlinks} are hyperlinks created implicitly by various
Eplain macros, such as the macros for citations, cross-references,
indexing, etc.

@cindex link group
@cindex linkgroup
@cindex group, link
@cindex destination group
@cindex destgroup
@cindex group, destination
All such macros are divided into @dfn{link groups} and
@dfn{destination groups} (or @dfn{linkgroups} and @dfn{destgroups} for
short) so that parameters can be set individually for each group.  For
example, all equation macros which define a destination are assigned
to the `eq' destgroup; equation macros which create a link are
assigned to the `eq' linkgroup.  By setting parameters for the `eq'
linkgroup (destgroup), you can uniformly customize all links
(destinations) related to equation references, without interfering
with settings for the other groups.

@xref{Setting hyperlink types and options}, for information on how to
set parameters for a group.

Here is the list of the linkgroups:

@display
cite, ref, xref, eq, idx, foot, footback, url.
@end display

And here are the destgroups:

@display
bib, li, definexref, xrdef, eq, idx, foot, footback.
@end display

The following subsections describe each of the linkgroups and destgroups
and the hyperlink support provided.

@menu
* URL hyperlinks::                  url
* Citation hyperlinks::             cite, bib
* List hyperlinks::                 li
* Cross-reference hyperlinks::      definexref, ref
* Page reference hyperlinks::       xrdef, xref
* Equation reference hyperlinks::   eq
* Index hyperlinks::                idx
* Footnote hyperlinks::             foot, footback
* Contents hyperlinks::
@end menu


@node URL hyperlinks
@subsection URL hyperlinks:  url

@cindex URL hyperlink
@cindex hyperlinks, URL
@cindex group `url'
@cindex linkgroup `url'
The `url' linkgroup covers the
@findex url @r{(hyperlinks)}
@code{\url} command from the @LaTeX{} package
@pindex url.sty
@file{url} (@pxref{Packages known to work}), as well as any new
@code{\url}-like commands you define.  The type for this linkgroup is
set to @samp{url} by the drivers which support this link type.
@samp{url} links use the parameter to the @code{\url} command as the URL
to point to.

You may be using the @code{\url} command to typeset something other than
a URL, e.g., a path, for which you do not want a link to be created; in
that case, you can disable the `url' linkgroup with the command
@code{\hloff[url]} (@pxref{Turning hyperlinks on/off for a group}).


@node Citation hyperlinks
@subsection Citation hyperlinks:  cite, bib

@cindex citations, hyperlinks
@cindex hyperlinks, citations
@cindex group `cite'
@cindex linkgroup `cite'
@findex cite @r{(hyperlinks)}
The `cite' linkgroup includes only the @code{\cite} command
(@pxref{Citations}).  @code{\cite} turns each of the references in the
list into a link pointing to the respective bibliography entry
produced by the @code{\bibliography} command.

@cindex bibliography, hyperlinks
@cindex hyperlinks, bibliography
@cindex group `bib'
@cindex destgroup `bib'
@findex bibliography @r{(hyperlinks)}
The `bib' destgroup includes the macros related to the
@code{\bibliography} command (@pxref{Citations}).  @code{\bibliography}
inputs a @file{.bbl} file, which contains a list of bibliography
entries.  For each of the entries, a destination is defined.

Both commands use the citation label as the hyperlink label.


@node List hyperlinks
@subsection List hyperlinks:  li

@cindex lists, hyperlinks
@cindex hyperlinks, lists
@findex li @r{(hyperlinks)}
@cindex group `li'
@cindex destgroup `li'
The `li' destgroup consists of the @code{\li} command (@pxref{Lists}),
which defines a destination if you supply the optional argument
(cross-reference label).  This label is also used as the hyperlink
label.


@node Cross-reference hyperlinks
@subsection Cross-reference hyperlinks:  definexref, ref

@findex definexref @r{(hyperlinks)}
@cindex cross-references, hyperlinks
@cindex hyperlinks, cross-references
@cindex group `definexref'
@cindex destgroup `definexref'
The `definexref' destgroup is for the @code{\definexref} command
(@pxref{Defining generic references}).  @code{\definexref} defines a
destination using the cross-reference label (the first argument) as the
hyperlink label.

@cindex group `ref'
@cindex linkgroup `ref'
The `ref' linkgroup includes @code{\refn} and @code{\xrefn} (they are
synonyms), @code{\ref}, and @code{\refs} (@pxref{Using generic
references}).

@findex refn @r{(hyperlinks)}
@findex xrefn @r{(hyperlinks)}
@code{\refn} turns the cross-reference it produces into a link, using
the cross-reference label as the hyperlink label.  If an optional
argument is present, it is tied by
@findex reftie
@code{\reftie} to the reference and become part of the link.

@findex ref @r{(hyperlinks)}
@code{\ref} works similarly to @code{\refn}.  It takes an optional
argument, which is treated the same way as the optional argument to
@code{\refn}.  In addition, @code{\ref} can produce a ``class word''.
Both the optional argument and the class word become part of the link,
when present.  The cross-reference is tied by
@findex reftie
@code{\reftie} to the preceding word.  The optional argument is
separated from the class word by
@findex refspace
@code{\refspace}.

@findex refs @r{(hyperlinks)}
Unlike @code{\ref}, @code{\refs} does not take an optional argument and
does not make the class word part of the link, which is appropriate for
its intended use.


@node Page reference hyperlinks
@subsection Page reference hyperlinks:  xrdef, xref

@findex xrdef @r{(hyperlinks)}
@cindex page reference hyperlink
@cindex hyperlinks, page references
@cindex group `xrdef'
@cindex destgroup `xrdef'
The `xrdef' destgroup is for @code{\xrdef} (@pxref{Page references}).
@code{\xrdef} defines a destination using cross-reference label as the
hyperlink label.

@findex xref @r{(hyperlinks)}
@findex refspace
@findex xrefpageword
@cindex group `xref'
@cindex linkgroup `xref'
The `xref' linkgroup includes the @code{\xref} command (@pxref{Page
references}).  @code{\xref} turns its optional argument (followed by
@code{\refspace}), @code{\xrefpageword} and the cross-reference (page
number) into a link, using the cross-reference label as the hyperlink
label.


@node Equation reference hyperlinks
@subsection Equation reference hyperlinks:  eq

@findex eqdef @r{(hyperlinks)}
@findex eqdefn @r{(hyperlinks)}
@findex eqsubdef @r{(hyperlinks)}
@findex eqsubdefn @r{(hyperlinks)}
@cindex equations, hyperlinks
@cindex hyperlinks, equations
@cindex group `eq'
@cindex destgroup `eq'
All commands that define equation labels are part of the `eq' destgroup.
These are @code{\eqdef}, @code{\eqdefn}, @code{\eqsubdef} and
@code{\eqsubdefn} (@pxref{Equation references}).  All these commands use
the equation label as the hyperlink label.  However, if the equation
label is empty, they make up a (hopefully) unique hyperlink label for
the destination.  This label will be used for the link when you refer to
this empty-labeled equation with one of the equation reference macros.

@findex phantomeqlabel
@findex phantomeqnumber
The command @code{\phantomeqlabel} is called to generate hyperlink
labels for the empty-labeled equations.  By default, it produces the
labels in the format @samp{PHEQ@var{number}}, where @var{number} comes
from the count register @code{\phantomeqnumber}; this count register is
incremented at every empty-labeled equation definition.

@findex eqref
@findex eqrefn
@findex reftie
@cindex group `eq'
@cindex linkgroup `eq'
The commands @code{\eqref} and @code{\eqrefn} (@pxref{Equation
references}) form the `eq' linkgroup.  These commands take an optional
argument, which, when present, is tied with @code{\reftie} to the
equation reference and becomes part of the link.  The equation label is
used for the hyperlink label; if the label is empty, the link is for the
label generated for the last empty-labeled equation.


@node Index hyperlinks
@subsection Index hyperlinks:  idx

@findex idx @r{(hyperlinks)}
@findex idxname @r{(hyperlinks)}
@findex idxmarked @r{(hyperlinks)}
@findex idxsubmarked @r{(hyperlinks)}
@cindex index hyperlink
@cindex hyperlinks, index
@cindex group `idx'
@cindex linkgroup `idx'
@cindex destgroup `idx'
All indexing commands (@code{\idx}, @code{\idxname}, @code{\idxmarked},
@code{\idxsubmarked} and their silent equivalents, @pxref{Indexing
commands}) form the `idx' destgroup.  The `idx' linkgroup consists of
the macros which are used to typeset the index when you say
@findex readindexfile @r{(hyperlinks)}
@code{\readindexfile@{@var{index-letter}@}} (@pxref{Typesetting an
index}).

@pindex makeindex
To create the links in index entries, Eplain uses MakeIndex's
``encapsulation'' feature.  When you use an indexing macro to mark an
index term, Eplain writes out a line to the
@pindex .idx @r{files}
@file{.idx} file of the following general form:

@example
\indexentry@{@var{entry}|@var{pagemarkup}@}@{@var{pageno}@}
@end example

@noindent where @var{entry} is the index entry (converted into the
internal format that MakeIndex understands), @var{cs} is the markup
command you specified with the @code{pagemarkup=@var{cs}} optional
argument to the indexing commands (@pxref{Modifying index entries}),
and @var{pageno} is the page number on which the term appeared.  When
processing the @file{.idx} file, MakeIndex makes the page number an
argument to the page markup command (``encapsulates'' the page
number), so the page number in the
@pindex .ind @r{files}
@file{.ind} file appears as @code{\@var{cs}@{@var{pageno}@}}.  Eplain
internally replaces the @var{cs} command name with its own command,
which, in addition to calling the original @code{\@var{cs}}
encapsulator, turns the page number into a link.

Eplain provides two approaches to linking page numbers in the index to
locations of index terms in the text.

@menu
* Exact destinations for index terms::
* Page destinations for index terms::
* Choosing destination placement::
* Index page list and page range parsers::
* Hyperlinks in see and see also entries::
@end menu


@node Exact destinations for index terms
@subsubsection Exact destinations for index terms

In this approach, each command that marks an index term defines a unique
destination and passes its label on to the @file{.idx} file as part of
the @code{\indexentry} command.  The @code{\indexentry} line that Eplain
writes to the @file{.idx} file becomes

@example
\indexentry@{@var{entry}|hlidx@{@var{label}@}@{@var{cs}@}@}@{@var{pageno@}}
@end example

@findex hlidx
@noindent where @code{\hlidx} is the command that is defined by Eplain
to take three arguments:  a hyperlink label (@var{label}), a name of
page number encapsulator (@var{cs}) and a page number (@var{pageno}).
In the @file{.ind} file that MakeIndex will generate, the page number
will now appear as

@example
\hlidx@{@var{label}@}@{@var{cs}@}@{@var{pageno}@}
@end example

@noindent The result of this command is
@code{\@var{cs}@{@var{pageno}@}}, wrapped up into a link pointing to
@var{label} destination.

The hyperlink labels for the index terms are generated by the
@findex hlidxlabel
@code{\hlidxlabel} command, by default in the format
@samp{IDX@var{number}}, where @var{number} is the value of the count
register
@findex hlidxlabelnumber
@code{\hlidxlabelnumber}.  This count register is incremented at each
index term.

@cindex exact index hyperlinks
@cindex index, exact hyperlinks
@cindex hyperlinks, index, exact
The advantage of this approach, as compared to the second approach
described below, is that links in the index point to exact locations of
the indexed terms on the page.  The disadvantage of this approach is
that MakeIndex will regard @emph{all} index entries as distinct, because
each one contains a (unique) hyperlink label.  This disadvantage can be
partially overcome by the script
@pindex idxuniq
@cindex filtering index entries with hyperlinks
@cindex hyperlinks, filtering index entries
@file{idxuniq} distributed with Eplain in the @file{util} directory.
This script filters out @code{\indexentry} lines differing only in the
hyperlink label but identical otherwise.  You should process the
@file{.idx} with this script before passing it on to MakeIndex.  For
example:

@example
prompt$ ./idxuniq file.idx | makeindex > file.ind
@end example

@noindent Still, this solution is not ideal, as the page-range formation
ability of MakeIndex will not work, and there will be problems of
apparently identical index entries clashing (e.g., when a range-end
entry appears on the same page as another entry with the same
definition; @file{idxuniq} will not filter out the second entry).


@node Page destinations for index terms
@subsubsection Page destinations for index terms

In the second approach, Eplain does not write out any destination labels
for the index terms.  Instead, Eplain writes out a wrapper for page
number encapsulator which can parse the page number and generate a link
pointing to the @emph{page} on which the term appeared.  On top of each
page containing an index term, Eplain defines a destination with label
produced by
@findex hlidxpagelabel
@code{\hlidxpagelabel}.  The @code{\hlidxpagelabel} command takes a
single argument (page number @var{number}) and by default produces the
label in the format @samp{IDXPG@var{number}}.

With this approach, the @code{\indexentry} line which Eplain writes to
the @code{.idx} file looks like this:

@example
\indexentry@{@var{entry}|hlidxpage@{@var{cs}@}@}@{@var{pageno@}}
@end example

@findex hlidxpage
@noindent where @code{\hlidxpage} is the command that is defined by Eplain
to take two arguments:  a name of page number encapsulator (@var{cs})
and a page number (@var{pageno}).  In the @file{.ind} file that
MakeIndex will generate, the page number will appear as

@example
\hlidxpage@{@var{cs}@}@{@var{pageno}@}
@end example

The advantage of this approach is that all features of MakeIndex are
intact.  The drawback is that links in the index do not point to exact
locations of indexed terms on a page, but to the top of a page on
which the term appears.

@cindex index, parsing page numbers
@cindex page range, parsing
@cindex page list, parsing
@cindex parsing page numbers
Another disadvantage is that this approach depends on the page range and
page list separators which MakeIndex was configured to output.
@code{\hlidxpage} must be able to parse the first page number in a page
range like @samp{1--4}.  In addition, page list parsing is needed
because MakeIndex combines two consecutive page numbers in one call to
the page number encapsulator, so @code{\hlidxpage} can be passed, e.g.,
@samp{1, 2} for the @var{pageno}.  In this last case, @code{\hlidxpage}
splits the two page numbers, applies @code{\@var{cs}} to each of them,
and makes each of the page numbers a link to the appropriate page.  Note
that this will alter typesetting slightly, because now the page list
separator (a comma followed by a space, by default) is not typeset using
the page number encapsulator (@code{\@var{cs}}).

Eplain's defaults for the page list and page number delimiters are the
same as those in MakeIndex, a comma followed by a space (@samp{, }) and
two dashes (@samp{--}), respectively.  If you customize MakeIndex to use
different delimiters, you must not forget to let Eplain know about them
with the commands

@example
\setidxpagelistdelimiter@{@var{list-delim}@}
\setidxpagerangedelimiter@{@var{page-delim}@}
@end example

@noindent (@pxref{Page list and page range parsers}).


@node Choosing destination placement
@subsubsection Choosing destination placement

@cindex index, placement of destinations
@cindex index, destination placement
@cindex index, selecting destination placement
@cindex index, choosing destination placement
@cindex hyperlinks, index destination placement
The approach that Eplain should use for the index terms can be
selected in the
@findex enablehyperlinks
@code{\enablehyperlinks} command.  The optional argument it accepts is
a comma-separated list of options.  The
@findex idxexact
@code{idxexact} option selects the first approach,
@findex idxpage
@code{idxpage} the second, and
@findex idxnone
@code{idxnone} disables hyperlink support for the index terms
altogether, in case you want to stop Eplain from writing its link
wrappers into the @file{.idx} file.  The default is @code{idxpage}.

For example:

@example
\enablehyperlinks[idxexact]
@end example

@noindent selects the first approach (``exact index links'').


@node Index page list and page range parsers
@subsubsection Index page list and page range parsers

The macros that Eplain uses to parse page lists and page ranges,
@code{\idxparselist} and @code{\idxparserange}, can sometimes be useful
when defining page number encapsulators.  @xref{Page list and page range
parsers}, for the description of these commands and an example of their
usage.


@node Hyperlinks in see and see also entries
@subsubsection Hyperlinks in see and see also entries

@cindex hyperlinks, see and see also index entries
@cindex index, hyperlinks in see and see also entries
@cindex see also index entries and hyperlinks
@cindex see, and index entries, hyperlinks
There is no automatic support for hyperlinks with ``see'' and ``see
also'' index entries, as there is not enough information to trace the
parameters of
@findex indexsee
@code{\indexsee} and
@findex indexseealso
@code{\indexseealso} to corresponding index entries.  But if desired,
this can be implemented with @code{\hldest} and @code{\hlstart}
(@pxref{Explicit hyperlinks}); for example:

@example
\sidx@{semantic theory of truth@@%
      \leavevmode\hldest@{@}@{@}@{idx:theo truth@}semantic theory of truth@}
@dots{}
\sidx[seealso]@{truth@}[definition of]%
      @{\hlstart@{@}@{@}@{idx:theo truth@}semantic theory of truth\hlend@}
@end example


@node Footnote hyperlinks
@subsection Footnote hyperlinks:  foot, footback

@cindex footnotes, hyperlinks
@cindex hyperlinks, footnotes
@cindex group `foot'
@cindex group `footback'
@cindex linkgroup `foot'
@cindex linkgroup `footback'
@cindex destgroup `foot'
@cindex destgroup `footback'
The `foot' link and destination groups include the
@findex numberedfootnote @r{(hyperlinks)}
@code{\numberedfootnote} and
@findex footnote @r{(hyperlinks)}
@code{\footnote} macros (@pxref{Footnotes}).  The `footback' groups
include the same macros, but control parameters for links and
destinations created inside the footnote to point back to the footnote
mark within the text body.

The macros use hyperlink labels generated by
@findex hlfootlabel
@code{\hlfootlabel} and
@findex hlfootbacklabel
@code{\hlfootbacklabel}.  The default formats for the labels are
@samp{FOOT@var{number}} and @samp{FOOTB@var{number}}, respectively,
where @var{number} is the value of the count register
@findex hlfootlabelnumber
@code{\hlfootlabelnumber}.  This register is incremented at every
footnote.


@node Contents hyperlinks
@subsection Contents hyperlinks

@cindex table of contents, hyperlinks
@cindex contents, hyperlinks
@cindex hyperlinks, table of contents
There is currently no special support for hyperlinks in the table of
contents (@pxref{Contents}), but implementing them with the
@code{\hldest} and @code{\hlstart @dots{} \hlend} commands
(@pxref{Explicit hyperlinks}) should be possible.


@node Hyperlink drivers
@section Hyperlink drivers

This section describes the hyperlink drivers: the types of hyperlinks
they support, and the options they accept.  During the first reading,
you may only want to skim through this section.

Some of the descriptions below come from @cite{Portable Document Format
Reference Manual Version@tie{}1.3}, March@tie{}11, 1999.

@menu
* Options supported by all drivers::
* Hyperlink drivers pdftex and dvipdfm::
* Hyperlink driver nolinks::
@end menu


@node Options supported by all drivers
@subsection Options supported by all drivers

@cindex hyperlink options, common
This subsection describes the destination and link options which are
supported by all hyperlink drivers.


@subsubheading Destination options supported by all drivers

@cindex destination options, common
@cindex options, destination, common
@table @code
@item raise
@findex raise @r{(hyperlink option)}
@cindex raising hyperlink destinations
@cindex hyperlink destination, raising
@cindex destinations, raising
Specifies how much to raise destinations above the baseline.  When set
to zero or empty, destinations are placed at the baseline.

It is usually convenient to set this option to some variable parameter,
so that the height to which destinations are raised is automatically
adjusted according to the current context.  For example, setting it to
@findex normalbaselineskip
@code{\normalbaselineskip} (or some fraction of it, like
@code{1.7\normalbaselineskip}) makes the setting appropriate for
different point sizes, in case your document uses more than one.

The default setting is @code{\normalbaselineskip}.  Initially, the
destgroups do not define this option, so they fall back on the default,
except for the `eq' destgroup, for which this option is set to
@code{1.7\normalbaselineskip},
@cindex mathematics displays, hyperlinks
@cindex displayed math and hyperlinks
@cindex large operators and hyperlinks
@cindex hyperlinks, large operators
@cindex destinations, large operators
to accommodate the usual cases of large operators in displayed math.

Example:  @code{\hldestopts[eq]@{raise=2.5\normalbaselineskip@}}
@end table


@subsubheading Link options supported by all drivers
@cindex link options, common
@cindex options, link, common

@table @code
@item colormodel
@itemx color
@findex colormodel @r{(hyperlink option)}
@findex color @r{(hyperlink option)}
@cindex color, hyperlinks
These two options define the color to be used for rendering the link
text.  The colors are used only when a @code{\color} command is defined,
e.g., by loading the @LaTeX{} `color' package (@pxref{Packages known to
work}).  The @code{\color} command is called as
@code{\color[@var{colormodel}]@{@var{color}@}}, where @var{colormodel}
and @var{color} are the definitions of the @code{colormodel} and
@code{color} options, respectively.  However, if @var{colormodel} is
empty, the optional argument to @code{\color} is omitted; and if
@var{color} is empty, the @code{\color} command is omitted altogether.
The default setting is @code{@var{colormodel}=cmyk} and
@code{@var{color}=0.28,1,1,0.35}.

When specifying colors with several components delimited by commas
(e.g., RGB and CMYK colors in the @LaTeX{} `color' package), it is not
possible to specify the components directly in the option list of
@code{\hlopts}, because comma is the option list delimiter.  With the
`color' package, it is possible to specify such colors by defining a
custom color with @code{\definecolor} and using the new color name with
an empty @var{colormodel} (see examples below).

Examples:
@example
\hlopts@{colormodel=,color=blue@}% predefined color
\definecolor@{mycolor@}@{rgb@}@{.3,.8,.95@}
\hlopts@{colormodel=,color=mycolor@}% custom color
\hlopts@{colormodel=gray,color=.4@}
@end example
@end table


@node Hyperlink drivers pdftex and dvipdfm
@subsection Hyperlink drivers @code{pdftex} and @code{dvipdfm}

@cindex @code{pdftex}, hyperlink driver
@cindex @code{dvipdfm}, hyperlink driver
@cindex driver @code{pdftex}
@cindex driver @code{dvipdfm}
@cindex hyperlink driver @code{pdftex}
@cindex hyperlink driver @code{dvipdfm}
This subsection describes link and destination types and options
supported by the @code{pdftex} and @code{dvipdfm} drivers.  Many of the
hyperlink types and options are common to both drivers, so we describe
them together.

@menu
* Destination types for pdftex and dvipdfm::
* Destination options for pdftex and dvipdfm::
* Link types for pdftex and dvipdfm::
* Link options for pdftex and dvipdfm::
@end menu


@node Destination types for pdftex and dvipdfm
@subsubsection Destination types for @code{pdftex} and @code{dvipdfm}

@cindex destination types, @code{pdftex}
@cindex destination types, @code{dvipdfm}
@cindex types, destination, @code{pdftex}
@cindex types, destination, @code{dvipdfm}
@cindex @code{pdftex}, destination types
@cindex @code{dvipdfm}, destination types
@table @code
@item xyz
@findex xyz @r{(destination type)}
``Current position''.  The option
@findex zoom @r{(destination option)}
@code{zoom} specifies magnification to use (zero or empty means leave
magnification unchanged, which is the default).  This is the default
type.

For @code{dvipdfm}:  the options
@findex left @r{(destination option)}
@code{left} and
@findex top @r{(destination option)}
@code{top} specify position coordinates to use (empty options mean
current position coordinate, which is the default).

Example:  @code{\hldest@{xyz@}@{zoom=2000@}@{dest123@}}

@item fit
@findex fit @r{(destination type)}
Fit the page to the window.

Example:  @code{\hldest@{fit@}@{@}@{dest123@}}

@item fith
@findex fith @r{(destination type)}
Fit the width of the page to the window.

For @code{dvipdfm}:  the
@findex top @r{(destination option)}
@code{top} option specifies vertical position (default is empty, meaning
current position).

Example:  @code{\hldest@{fith@}@{@}@{dest123@}}

@item fitv
@findex fitv @r{(destination type)}
Fit the height of the page to the window.

For @code{dvipdfm}:  The option
@findex left @r{(destination option)}
@code{left} specifies horizontal position (default is empty, meaning
current position).

Example:  @code{\hldest@{fitv@}@{@}@{dest123@}}

@item fitb
@findex fitb @r{(destination type)}
Fit the page's bounding box to the window.

Example:  @code{\hldest@{fitb@}@{@}@{dest123@}}

@item fitbh
@findex fitbh @r{(destination type)}
Fit the width of the page's bounding box to the window.

For @code{dvipdfm}:  the option
@findex top @r{(destination option)}
@code{top} specifies vertical position (default is empty, meaning
current position).

Example:  @code{\hldest@{fitbh@}@{@}@{dest123@}}

@item fitbv
@findex fitbv @r{(destination type)}
Fit the height of the page's bounding box to the window.

For @code{dvipdfm}:  the option
@findex left @r{(destination option)}
@code{left} specifies horizontal position (default is empty, meaning
current position).

Example:  @code{\hldest@{fitbv@}@{@}@{dest123@}}

@item fitr
@findex fitr @r{(destination type)}
For @code{pdftex}:  fit the rectangle specified by the options
@findex width @r{(destination option)}
@code{width},
@findex height @r{(destination option)}
@code{height} and
@findex depth @r{(destination option)}
@code{depth} (as a @TeX{} rule specification) in the window.  For
dimensions set to empty, the corresponding value of the parent box is
used (these are the defaults).

For @code{dvipdfm}:  fit the rectangle specified by the options
@findex left @r{(destination option)}
@code{left},
@findex bottom @r{(destination option)}
@code{bottom},
@findex right @r{(destination option)}
@code{right} and
@findex top @r{(destination option)}
@code{top} (in
@cindex PostScript point
PostScript points, 72@tie{}points per inch) in the window.  For
dimensions set to empty, current position coordinate is substituted
(these are the defaults).

Example for @code{pdftex}:

@example
\hldest@{fitr@}@{width=\hsize,height=.5\vsize,depth=0pt@}@{dest123@}
@end example

Example for @code{dvipdfm}:

@example
\hldest@{fitr@}@{left=72,bottom=72,right=720,top=360@}@{dest123@}
@end example

@item raw
@findex raw @r{(destination type)}
The destination specification (in the form of a pdf@TeX{} command or a
dvipdfm @code{\special}) is taken from the command sequence
@code{\@var{cs}}, where @var{cs} is the value of the
@findex cmd @r{(destination option)}
@code{cmd} option.  In the definition of @code{\@var{cs}}, use
@findex @@hllabel
@code{\@@hllabel} to refer to the hyperlink label.  This option is
intended to be used with destgroups (@pxref{Setting hyperlink types and
options}), as it does not make sense to use it in a direct call to
@findex hldest
@code{\hldest}---you can just call the raw command.

Example for @code{pdftex}:

@example
\makeatletter
\def\mydest@{\pdfdest name@{\@@hllabel@} xyz@}
\hldesttype@{raw@}
\hldestopts@{cmd=mydest@}
\resetatcatcode
@end example

Example for @code{dvipdfm}:

@example
\makeatletter
\def\mydest@{\special@{pdf: dest (\@@hllabel)
                          [@@thispage /XYZ @@xpos @@ypos 0]@}@}
\hldesttype@{raw@}
\hldestopts@{cmd=mydest@}
\resetatcatcode
@end example
@end table


@node Destination options for pdftex and dvipdfm
@subsubsection Destination options for @code{pdftex} and @code{dvipdfm}

@cindex destination options, @code{pdftex}
@cindex destination options, @code{dvipdfm}
@cindex options, destination, @code{pdftex}
@cindex options, destination, @code{dvipdfm}
@cindex @code{pdftex}, destination options
@cindex @code{dvipdfm}, destination options
With respect to the destination options, the @code{pdftex} and
@code{dvipdfm} differ in the way the fit rectangle is specified
(relative coordinates for @code{pdftex}, absolute coordinates for
@code{dvipdfm}).


@subsubheading Common destination options

@table @code
@item cmd
@findex cmd @r{(destination option)}
Name of the macro (without the leading @samp{\}) containing a
pdf@TeX{} command or a dvipdfm @code{\special} for the @code{raw}
destination.

For an example of usage, @pxref{Destination types for pdftex and
dvipdfm}, description of the @code{raw} destination.

@item zoom
@findex zoom @r{(destination option)}
@cindex destinations, magnification
@cindex hyperlink destination, magnification
@cindex magnification, hyperlink destination
@cindex zooming, hyperlink destination
Magnification ratio times 1000 (like @TeX{}'s scale factor).
Zero or empty means leave magnification unchanged, which is the
default.

Example:  @code{\hldest@{xyz@}@{zoom=2000@}@{dest123@}}
@end table


@subsubheading @code{pdftex}-specific destination options

The dimension options below must be specified as a @TeX{} rule
specification.  When set to empty, the corresponding value
of the parent box is used (this is the default for all dimension
options).

@table @code
@item depth
@findex depth @r{(destination option)}
@cindex destinations, dimensions
@cindex hyperlink destination, dimensions
@cindex dimensions, hyperlink destination
Depth of the fit rectangle for the @code{fitr} destination.

@item height
@findex height @r{(destination option)}
@cindex destinations, dimensions
@cindex hyperlink destination, dimensions
@cindex dimensions, hyperlink destination
Height of the fit rectangle for the @code{fitr} destination.

@item width
@findex width @r{(destination option)}
@cindex destinations, dimensions
@cindex hyperlink destination, dimensions
@cindex dimensions, hyperlink destination
Width of the fit rectangle for the @code{fitr} destination.

Example:

@example
\hldest@{fitr@}@{width=\hsize,height=.5\vsize,depth=0pt@}@{dest123@}
@end example
@end table


@subsubheading @code{dvipdfm}-specific destination options

The dimension options below must be specified in
@cindex PostScript point
PostScript points (72@tie{}points per inch), as a number without the
@samp{bp} unit name.  When set to empty, the current position
coordinate is used (this is the default for all dimension options).

@table @code
@item bottom
@findex bottom @r{(destination option)}
@cindex destinations, dimensions
@cindex hyperlink destination, dimensions
@cindex dimensions, hyperlink destination
Bottom position coordinate of a box specification for the various
destination types.

@item left
@findex left @r{(destination option)}
@cindex destinations, dimensions
@cindex hyperlink destination, dimensions
@cindex dimensions, hyperlink destination
Left position coordinate of a box specification for the various
destination types.

@item right
@findex right @r{(destination option)}
@cindex destinations, dimensions
@cindex hyperlink destination, dimensions
@cindex dimensions, hyperlink destination
Right position coordinate of a box specification for the various
destination types.

@item top
@findex top @r{(destination option)}
@cindex destinations, dimensions
@cindex hyperlink destination, dimensions
@cindex dimensions, hyperlink destination
Top position coordinate of a box specification for the various
destination types.

Example:

@example
\hldest@{fitr@}@{left=72,bottom=72,right=720,top=360@}@{dest123@}
@end example
@end table


@node Link types for pdftex and dvipdfm
@subsubsection Link types for @code{pdftex} and @code{dvipdfm}

@cindex link types, @code{pdftex}
@cindex link types, @code{dvipdfm}
@cindex types, link, @code{pdftex}
@cindex types, link, @code{dvipdfm}
@cindex @code{pdftex}, link types
@cindex @code{dvipdfm}, link types
Link types are the same for the @code{pdftex} and @code{dvipdfm}
drivers, except that the @code{pdftex} driver provides one additional
link type @code{num} (link to a numbered destination).  dvipdfm does not
support numbered destinations, therefore it does not have this link
type.  Note that all destinations created by Eplain hyperlink macros are
named destinations; to define a numbered destination, you have to use
low-level pdf@TeX{} commands.


@subsubheading Common link types

@table @code
@item name
@findex name @r{(hyperlink type)}
@cindex named destination
@cindex destinations, named
@cindex hyperlink destination, named
Go to a ``named destination''.  The label is the destination name.
All destinations created with @code{\hldest} are named destinations.
This is the default type.

Example:  @code{\hlstart@{name@}@{@}@{dest123@}Link to dest123\hlend}

@item page
@findex page @r{(hyperlink type)}
@cindex page destination
@cindex destinations, page
@cindex hyperlink destination, page
Go to a page.  The label is the page number (counting from@tie{}1).
Page fitting is specified by the
@findex pagefit @r{(hyperlink option)}
@code{pagefit} option.

Example:

@example
\hlstart@{page@}@{pagefit=/FitH 600@}@{123@}Link to page~123\hlend
@end example

@item filename
@findex filename @r{(hyperlink type)}
@cindex file, hyperlink to
@cindex destinations, in another file
@cindex hyperlinks, to another file
Go to a named destination in another file.  The label is the
destination name.  The file name is specified by the
@findex file @r{(hyperlink option)}
@code{file} option.  Page fitting is specified by the
@findex pagefit @r{(hyperlink option)}
@code{pagefit} option.  The
@findex newwin @r{(hyperlink option)}
@code{newwin} option specifies whether the destination document is
opened in the same window or in a new window.

Example:
@example
\hlstart@{filename@}@{file=book.pdf,newwin=1@}@{dest123@}
  Link to dest123 in file `book.pdf'\hlend
@end example

@item filepage
@findex filepage @r{(hyperlink type)}
@cindex file, hyperlink to
@cindex destinations, in another file
@cindex hyperlinks, to another file
Go to a page in another file.  The label is the page number (counting
from@tie{}1).  The file name is specified by the
@findex file @r{(hyperlink option)}
@code{file} option.  Page fitting is specified by the
@findex pagefit @r{(hyperlink option)}
@code{pagefit} option.  The
@findex newwin @r{(hyperlink option)}
@code{newwin} option specifies whether the destination document is
opened in the same window or in a new window.

Example:
@example
\hlstart@{filepage@}@{file=book.pdf,newwin=,%
                   pagefit=/FitR 50 100 300 500@}@{1@}
  Link to page~1 in file `book.pdf'\hlend
@end example

@item url
@findex url @r{(hyperlink type)}
@cindex URL hyperlink
@cindex destinations, URL
@cindex hyperlinks, URL
Go to a URL.  The label is the URL.

Example:  @code{\hlstart@{url@}@{@}@{http://tug.org/eplain/@}Eplain home\hlend}

@item raw
@findex raw @r{(hyperlink type)}
The link specification (in the form of a pdf@TeX{} command or a dvipdfm
@code{\special} primitive) is taken from the command sequence
@code{\@var{cs}}, where @var{cs} is the value of the
@findex cmd @r{(hyperlink option)}
@code{cmd} option.  This option is intended to be used with linkgroups
(@pxref{Setting hyperlink types and options}), as it does not make sense
to use it in a direct call to
@findex hlstart
@code{\hlstart}---you can just call the raw command.

Example for @code{pdftex}:

@example
% Redirect all \url links to the first page
\def\mycmd@{\pdfstartlink goto page 1 @{/Fit@}@}
\hltype[url]@{raw@}
\hlopts[url]@{cmd=mycmd@}
@end example

Example for @code{dvipdfm}:

@example
% Redirect all \url links to the first page
\def\mycmd@{\special@{pdf: beginann <</Type/Annot /Subtype/Link
                                    /Dest[0 /Fit]>>@}@}
\hltype[url]@{raw@}
\hlopts[url]@{cmd=mycmd@}
@end example
@end table

@subsubheading @code{pdftex}-specific link types

@table @code
@item num
@findex num @r{(hyperlink type)}
@cindex numbered destination
@cindex destinations, numbered
@cindex hyperlink destination, numbered
Go to a ``numbered destination''.  The label is the destination
number.

Example:  @code{\hlstart@{num@}@{@}@{123@}Link to 123\hlend}
@end table


@node Link options for pdftex and dvipdfm
@subsubsection Link options for @code{pdftex} and @code{dvipdfm}

@cindex link options, @code{pdftex}
@cindex link options, @code{dvipdfm}
@cindex options, link, @code{pdftex}
@cindex options, link, @code{dvipdfm}
@cindex @code{pdftex}, link options
@cindex @code{dvipdfm}, link options
Link options are mostly the same for the @code{pdftex} and
@code{dvipdfm} drivers.  The @code{pdftex} driver has additional
options to specify link dimensions.


@subsubheading Common link options

@table @code
@item bcolor
@findex bcolor @r{(hyperlink option)}
@cindex hyperlink border color
@cindex border color, hyperlink
@cindex color, hyperlink border
Border color.  An array of three numbers in the range 0 to 1,
representing a color in DeviceRGB@.

Example:  @code{\hlstart@{name@}@{bcolor=.1 .5 1@}@{dest123@}Link\hlend}

@item bdash
@findex bdash @r{(hyperlink option)}
@cindex dashed hyperlink border
@cindex hyperlinks, border style
@cindex border style, hyperlink
Array of numbers representing on and off stroke lengths for drawing
dashes.

Example:  @code{\hlstart@{name@}@{bstyle=D,bdash=2 4@}@{dest123@}Link\hlend}

@item bstyle
@findex bstyle @r{(hyperlink option)}
@cindex solid hyperlink border
@cindex dashed hyperlink border
@cindex beveled hyperlink border
@cindex inset hyperlink border
@cindex underline hyperlink border
@cindex hyperlinks, border style
@cindex style, hyperlink border
@cindex border style, hyperlink
Link border style:

@table @code
@item S
The border is drawn as a solid line.

@item D
The border is drawn with a dashed line (the dash pattern is specified
by the
@findex bdash @r{(hyperlink option)}
@code{bdash} option).

@item B
The border is drawn in a beveled style.

@item I
The border is drawn in an inset style.

@item U
The border is drawn as a line on the bottom of the link rectangle.
@end table

The default is @samp{S}.

Example:  @code{\hlstart@{name@}@{bstyle=D,bdash=2 4@}@{dest123@}Link\hlend}

@item bwidth
@findex bwidth @r{(hyperlink option)}
@cindex width, hyperlink border
@cindex hyperlinks, border width
@cindex border width, hyperlink
Border width in
@cindex PostScript point
PostScript points (72@tie{}points per inch).  The default is@tie{}1.

Example:  @code{\hlstart@{name@}@{bwidth=2@}@{dest123@}Link\hlend}

@item cmd
@findex cmd @r{(hyperlink option)}
Name of the macro (without the leading @samp{\}) containing a
pdf@TeX{} command or a dvipdfm @code{\special} for the @code{raw} link.

For an example of usage, @pxref{Link types for pdftex and dvipdfm},
description of the @code{raw} link.

@item file
@findex file @r{(hyperlink option)}
File name for the @code{filename} and @code{filepage} link types.

For an example of usage, @pxref{Link types for pdftex and dvipdfm},
description of the @code{filename} and @code{filepage} links.

@item hlight
@findex hlight @r{(hyperlink option)}
@cindex hyperlinks, highlight mode
@cindex highlight modes, hyperlink
Link border highlight modes:

@table @code
@item I
The rectangle specified by the bounding box of the link is inverted.

@item N
No highlighting is done.

@item O
The border of the link is inverted.

@item P
The region underneath the bounding box of the link is drawn inset into
the page.
@end table

The default is @samp{I}.

Example:  @code{\hlstart@{name@}@{bstyle=S,hlight=O@}@{dest123@}Link\hlend}

@item newwin
@findex newwin @r{(hyperlink option)}
@cindex hyperlinks, opening in a new window
@cindex new window, opening hyperlink in
For the @code{filename} and @code{filepage} links, specifies whether the destination document is
opened in the same window or in a new window.  The settings are:

@table @code
@item 0
Open in the same window.
@item @r{non-}0
Open in a new window.
@item @r{empty}
Behavior according to the viewer settings.
@end table

The default is empty.

For an example of usage, @pxref{Link types for pdftex and dvipdfm},
description of the @code{filename} and @code{filepage} links.

@item pagefit
@findex pagefit @r{(hyperlink option)}
For the @code{page} and @code{filepage links}, specifies how the page
must be fitted to the window.  @code{pagefit} specification is written
to the PDF file as is, so it must conform to the PDF standard.

For an example of usage, @pxref{Link types for pdftex and dvipdfm},
description of the @code{page} and @code{filepage} links.
@end table


@subsubheading @code{pdftex}-specific link options

The dimension options below must be specified as a @TeX{} rule
specification.  When set to empty, the corresponding value
of the parent box is used (this is the default for all dimension
options).

@table @code
@item depth
@findex depth @r{(hyperlink option)}
@cindex hyperlink dimensions
@cindex dimensions, hyperlink
Depth of the link.

@item height
@findex height @r{(hyperlink option)}
@cindex hyperlink dimensions
@cindex dimensions, hyperlink
Height of the link.

@item width
@findex width @r{(hyperlink option)}
@cindex hyperlink dimensions
@cindex dimensions, hyperlink
Width of the link.

Example:

@example
\hlstart@{name@}@{width=5in,height=20pc,depth=0pt@}@{dest123@}
  Link\hlend
@end example
@end table


@node Hyperlink driver nolinks
@subsection Hyperlink driver @code{nolinks}

@cindex @code{nolinks}, hyperlink driver
@cindex driver @code{nolinks}
@cindex hyperlink driver @code{nolinks}
@cindex omitting hyperlinks
@cindex disabling hyperlinks
@cindex hyperlinks, disabling
@cindex destinations, disabling
@cindex spacing, preserving with hyperlinks
@cindex hyperlinks, preserving spacing
@cindex page-breaking, preserving with hyperlinks
@cindex hyperlinks, preserving page-breaking
Select this driver to suppress all hyperlinks in your document.

Selecting this driver is quite different from not selecting any driver
at all, or from selecting some driver and then turning hyperlinks off
for the entire document with
@findex hloff
@code{\hloff} and
@findex hldestoff
@code{\hldestoff} (@pxref{Turning hyperlinks on/off}).

The purpose of @code{\hldestoff} and @code{\hloff} is to mark (parts) of
your document where hyperlinks should never appear.  (Imagine you want
to prevent a cross-referencing macro from generating a link at a certain
spot in your document.)

If instead you have prepared a document with hyperlinks and just want to
compile a version without them, it is better to select the driver
@code{nolinks}.  This ensures that spacing and page-breaking are the
same as what you were getting with hyperlinks enabled.

The reason for this is that hyperlinks are produced by the
@code{\special} primitives or low-level hyperlink commands.  Each such
command is placed inside a
@cindex whatsits, made by hyperlinks
@dfn{whatsit} (an internal @TeX{} object), which may introduce
legitimate breakpoints at places where none would exist without the
whatsits.  The macros @code{\hldestoff} and @code{\hloff} disable the
hyperlink macros completely, so that no whatsits are produced.

In contrast, the @code{nolinks} driver does not completely disable
hyperlink macros.  Instead, it defines them to merely write to the log
file (what gets written is unimportant).  This also produces
whatsits, thus imitating the whatsits from the hyperlink commands.
(This trick was borrowed from the
@pindex color.sty
@cindex graphics collection, @LaTeX{}
@cindex @LaTeX{} graphics collection
@LaTeX{} `color' package.)

Another reason for using @code{nolinks} is that in horizontal mode
@code{\hldest} places destinations inside boxes of zero width, height,
and depth.  When you say @code{\hldestoff}, @code{\hldest} will omit
both destination definitions and these boxes.  The missing boxes can
again cause the typesetting to be inconsistent with that with
destinations enabled.  Here again, the @code{nolinks} driver helps by
defining @code{\hldest} to produce the empty boxes.


@node Setting hyperlink types and options
@section Setting hyperlink types and options

@cindex default hyperlink type
@cindex default hyperlink options
@cindex hyperlinks, default type
@cindex hyperlinks, default options
@cindex destinations, default type
@cindex destinations, default options
You can define default types for links and destinations, which will be
used when you do not specify a type in
@findex hlstart
@code{\hlstart} or
@findex hldest
@code{\hldest}.  Similarly, you can define default values for the
options; the default value for an option is used when you do not set the
option in the argument to @code{\hlstart} or @code{\hldest}.

@cindex group, type hyperlink
@cindex group, options hyperlink
@cindex hyperlinks, group type
@cindex hyperlinks, group options
@cindex link, group type
@cindex link, group options
@cindex linkgroup, type
@cindex linkgroup, options
@cindex destinations, group type
@cindex destinations, group options
@cindex destgroup, type
@cindex destgroup, options
The parameters for implicit links and destinations can be customized by
setting the ``group'' types and options.  When not set, the defaults are
used.

All these settings are local to the current (@TeX{}) group, so if
you want to set an option temporarily, you can do so inside a
@code{\begingroup@dots{}\endgroup} block; when the group ends, the
previous settings are restored.

@menu
* Setting default types and options::
* Setting group types::
* Setting group options::
@end menu


@node Setting default types and options
@subsection Setting default types and options

@findex hltype
@findex hldesttype
The default types for links and destinations can be set with the
following commands:

@example
\hltype@{@var{type}@}
\hldesttype@{@var{type}@}
@end example

@noindent where @var{type} is one of the
link/destination types supported by the selected hyperlink driver
(@pxref{Hyperlink drivers}).

@findex hlopts
@findex hldestopts
Default values for the options can be set with the following commands:

@example
\hlopts@{@var{options}@}
\hldestopts@{@var{options}@}
@end example

@noindent where @var{options} is a comma-separated list of option
assignments in the format @samp{@var{option}=@var{value}}.  Again, what options
are allowed depends on the selected hyperlink driver.


@node Setting group types
@subsection Setting group types

@findex hltype
@findex hldesttype
@cindex group, type hyperlink
@cindex hyperlinks, group type
@cindex link, group type
@cindex linkgroup, type
@cindex destinations, group type
@cindex destgroup, type
When called with an optional argument, as in

@example
\hltype[@var{groups}]@{@var{type}@}
\hldesttype[@var{groups}]@{@var{type}@}
@end example

@noindent where @var{groups} is a comma-separated list of groups,
@code{\hltype} and @code{\hldesttype} set the type for each group from
@var{groups} to @var{type}.  The default type is used for all groups
with an empty type (this is the initial setting for all groups, except
that the type for the `url' linkgroup is set to @samp{url} by the
drivers which support this link type).

@cindex group `' (empty)
@cindex default hyperlink type
@cindex default hyperlink options
@cindex hyperlinks, default type
@cindex hyperlinks, default options
@cindex destinations, default type
@cindex destinations, default options
There are two special ``groups'' which can be used inside the
@var{groups} list.  An empty group sets the default type.  This allows
to set the default type and group types in one command, for example:

@example
\hltype[eq,]@{@var{type}@}
@end example

@noindent sets the link type for the `eq' linkgroup and the
default link type to @var{type}.

@cindex group `*'
@cindex groups, specifying all
@cindex all groups, specifying
Another special group is a star (@samp{*}) group, which signifies all
defined groups.  For example, the command

@example
\hldesttype[*,]@{@var{type}@}
@end example

@noindent sets the destination type to @var{type} for each group,
as well as the default destination type.


@node Setting group options
@subsection Setting group options

@cindex group, options hyperlink
@cindex hyperlinks, group options
@cindex link, group options
@cindex linkgroup, options
@cindex destinations, group options
@cindex destgroup, options
Option values for each group are stored as a list of option
assignments.  This list does not have to contain every supported
option.  Values for options missing from this list are taken from the
default option values.

@findex hlopts
@findex hldestopts
To manipulate the list of option values for the groups, you use the
@code{\hlopts} and @code{\hldestopts} commands with an optional
argument:

@example
\hlopts[@var{groups}]@{@var{options}@}
\hldestopts[@var{groups}]@{@var{options}@}
\hlopts![@var{groups}]@{@var{options}@}
\hldestopts![@var{groups}]@{@var{options}@}
@end example

@noindent where @var{groups} is a comma-separated list of groups and
@var{options} is a comma-separated list of option assignments.  The
two special ``groups'', the empty group and the star (@samp{*})
group, have the same meaning as for @code{\hltype} and
@code{\hldesttype}.
@cindex group, preserving option list
@cindex hyperlink group, preserving option list
@cindex option list, preserving for group
When used without the exclamation mark, @code{\hlopts} and
@code{\hldestopts} preserve the current list of options for the groups,
and only update the options listed in @var{options}.  If you add the
exclamation mark, the current list of options for each group in
@var{groups} is discarded and the new list is set to @var{options}.

The ``overriding'' nature of the @samp{!} is appropriate when you give
a complete specification of the options for a group, e.g., at the
beginning of your document.  On the other hand, when you want to
adjust some option(s) and leave others intact, you should use the
macros without the @samp{!}.

@findex raise @r{(hyperlink option)}
@cindex mathematics displays, hyperlinks
@cindex displayed math and hyperlinks
@cindex large operators and hyperlinks
@cindex hyperlinks, large operators
@cindex destinations, large operators
@cindex raising hyperlink destinations
For example, with displayed mathematical formulas, you often need to
adjust the @samp{raise} option for the
@cindex group `eq'
@cindex linkgroup `eq'
`eq' destgroup, because the formulas often contain large parentheses and
brackets.  But when doing so, you want to leave the other settings
unchanged.  To achieve this, call @code{\hldestopts} without the
@samp{!}, for example:

@example
$$\hldestopts[eq]@{raise=2.5\normalbaselineskip@}
@dots{}
$$
@end example

@noindent The display commands (@samp{$$}) implicitly put the entire
formula inside a (@TeX{}) group (@code{\begingroup@dots{}\endgroup}), so
you do not need to isolate the setting of the @samp{raise} option---it
will be restored after the closing @samp{$$}.

@cindex option list, group
@cindex group option list
@cindex hyperlinks, group option list
Initially, Eplain sets the option lists for almost all groups to empty,
so that the groups fall back on the default values for all options.  The
one exception to this rule is the `eq' destgroup, whose initial option
list contains one setting:

@example
raise=1.7\normalbaselineskip
@end example

@noindent This setting usually accommodates the large operators, which often
appear in displayed math.


@node Turning hyperlinks on/off
@section Turning hyperlinks on/off

@cindex omitting hyperlinks
@cindex disabling hyperlinks
@cindex hyperlinks, disabling
@cindex destinations, disabling
Links and/or destinations can be turned on or off globally by disabling
the low-level commands, or for each group individually.

All these settings are local to the current (@TeX{}) group, so if you
want to enable or disable links/destinations temporarily, you can do so
inside a @code{\begingroup@dots{}\endgroup} block; when the group ends, the
previous settings are restored.

@menu
* Turning low-level commands on/off::
* Turning hyperlinks on/off for a group::
@end menu


@node Turning low-level commands on/off
@subsection Turning low-level commands on/off

@findex hldeston
@findex hldestoff
@findex hlon
@findex hloff
The low-level commands @code{\hlstart}, @code{\hlend} and
@code{\hldest} can be turned on/off with the following commands:

@example
\hldeston
\hldestoff
\hlon
\hloff
@end example

@noindent @xref{Hyperlink driver nolinks}, for the implications of using
these commands to disable hyperlinks for the entire document.


@node Turning hyperlinks on/off for a group
@subsection Turning hyperlinks on/off for a group

@cindex group, disabling hyperlinks
@cindex hyperlink group, disabling hyperlinks
If you want to disable links/destinations produced by certain groups,
you can give a list of the groups as an optional argument to these
commands:

@example
\hldeston[@var{groups}]
\hldestoff[@var{groups}]
\hlon[@var{groups}]
\hloff[@var{groups}]
@end example

@noindent where @var{groups} is the list of linkgroups/destgroups.  This
list can contain two special groups.  The empty group switches the
low-level commands (@pxref{Turning low-level commands on/off}), and the
star (@samp{*}) group operates on all defined groups.

Note that turning off the low-level commands disables all hyperlinks
globally, including groups which have them enabled.  Turning off certain
linkgroups/destgroups records the fact that the macros in the group
should not produce links/destinations.  To illustrate the distinction,
assume that all links are on; after the following sequence of commands:

@example
\hloff
\hloff[eq]
\hlon
@end example

@noindent all links are on except for the `eq' linkgroup.