summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/zref-clever/zref-clever.tex
blob: c2fa9f19b2c8c3dc8d9084f61ef1bab2c02977d9 (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
1861
1862
1863
1864
1865
1866
1867
1868
1869
1870
1871
1872
1873
1874
1875
1876
1877
1878
1879
1880
1881
1882
1883
1884
1885
1886
1887
1888
1889
1890
1891
1892
1893
1894
1895
1896
1897
1898
1899
1900
1901
1902
1903
1904
1905
1906
1907
1908
1909
1910
1911
1912
1913
1914
1915
1916
1917
1918
1919
1920
1921
1922
1923
1924
1925
1926
1927
1928
1929
1930
1931
1932
1933
1934
1935
1936
1937
1938
1939
1940
1941
1942
1943
1944
1945
1946
1947
1948
1949
1950
1951
1952
1953
1954
1955
1956
1957
1958
1959
1960
1961
1962
1963
1964
1965
1966
1967
1968
1969
1970
1971
1972
1973
1974
1975
1976
1977
1978
1979
1980
1981
1982
1983
1984
1985
1986
1987
1988
1989
1990
1991
1992
1993
1994
1995
1996
1997
1998
1999
2000
2001
2002
2003
2004
2005
2006
2007
2008
2009
2010
2011
2012
2013
2014
2015
2016
2017
2018
2019
2020
2021
2022
2023
2024
2025
2026
2027
2028
2029
2030
2031
2032
2033
2034
2035
2036
2037
2038
2039
2040
2041
2042
2043
2044
2045
2046
2047
2048
2049
2050
2051
2052
2053
2054
2055
2056
2057
2058
2059
2060
2061
2062
2063
2064
2065
2066
2067
2068
2069
2070
2071
2072
2073
2074
2075
2076
2077
2078
2079
2080
2081
2082
2083
2084
2085
2086
2087
2088
2089
2090
2091
2092
2093
2094
2095
2096
2097
2098
2099
2100
2101
2102
2103
2104
2105
2106
2107
2108
2109
2110
2111
2112
2113
2114
2115
2116
2117
2118
2119
2120
2121
2122
2123
2124
2125
2126
2127
2128
2129
2130
2131
2132
2133
2134
2135
2136
2137
2138
2139
2140
2141
2142
2143
2144
2145
2146
2147
2148
2149
2150
2151
2152
2153
2154
2155
2156
2157
2158
2159
2160
2161
2162
2163
% \iffalse meta-comment
%
% File: zref-clever.tex
%
% This file is part of the LaTeX package "zref-clever".
%
% Copyright (C) 2021  Gustavo Barros
%
% It may be distributed and/or modified under the conditions of the
% LaTeX Project Public License (LPPL), either version 1.3c of this
% license or (at your option) any later version.  The latest version
% of this license is in the file:
%
%    https://www.latex-project.org/lppl.txt
%
% and version 1.3 or later is part of all distributions of LaTeX
% version 2005/12/01 or later.
%
%
% This work is "maintained" (as per LPPL maintenance status) by
% Gustavo Barros.
%
% This work consists of the files zref-clever.dtx,
%                                 zref-clever.ins,
%                                 zref-clever.tex,
%                                 zref-clever-code.tex,
% and the derived files listed in MANIFEST.md.
%
% The released version of this package is available from CTAN.
%
% -----------------------------------------------------------------------
%
% The development version of the package can be found at
%
%    https://github.com/gusbrs/zref-clever
%
% for those people who are interested.
%
% -----------------------------------------------------------------------
%
% \fi

\documentclass{l3doc}

% The package itself *must* be loaded so that \GetFileInfo can pick up date
% and version data.  Naturally, we also use it.
\usepackage[cap,check,titleref]{zref-clever}

\usepackage[T1]{fontenc}

\usepackage[sc]{mathpazo}
\linespread{1.05}
\usepackage[scale=.88]{tgheros} % sans
\usepackage[varqu,scaled=1.03]{inconsolata} % tt

\usepackage{listings}

\usepackage{microtype}

\hypersetup{hidelinks}

\NewDocumentCommand\opt{m}{\texttt{#1}}

\definecolor{reffmtbox}{gray}{0.15}
\definecolor{reffmtback}{gray}{0.85}
\NewDocumentCommand\reffmt{m}{%
  \fcolorbox{reffmtbox}{reffmtback}{%
    \rule[-0.2\baselineskip]{0pt}{0.8\baselineskip}\texttt{#1}}}

\newlist{refformat}{itemize}{1}
\setlist[refformat]{label={}, beginpenalty=500, midpenalty=500}

\NewDocumentCommand\zctask{m}{%
  \begin{description}
  \item[Task] #1
  \end{description}}

\lstdefinestyle{code}{
  language=[LaTeX]TeX,
  moretexcs={
    AddToHook,
    define@key,
    patchcmd,
    eq@setnumber,
    DeclareFloatingEnvironment,
    newlist,
    setlist,
    zexternaldocument,
    next@label,
    next@label@pre,
    @empty,
    tag,
    text,
    lstset,
    condition,
  }
}
\lstdefinestyle{zrefclever}{
  style=code,
  moretexcs={
    zcref,
    zcpageref,
    zlabel,
    zcsetup,
    zcLanguageSetup,
    zcRefTypeSetup,
    zcheck,
  }
}
\lstset{
  style=zrefclever,
  basicstyle=\ttfamily\small,
  columns=fullflexible,
  keepspaces,
  xleftmargin=\leftmargin,
  xrightmargin=.5\leftmargin,
}
% Setup inspired by https://tex.stackexchange.com/a/4068. For how to use these
% environments in a .dtx context see https://tex.stackexchange.com/a/31026.
\newcounter{zchowto}
\lstnewenvironment{zchowto}[1][]{%
  \renewcommand{\lstlistingname}{How-to}%
  \lstset{#1}%
  \setcounter{lstlisting}{\value{zchowto}}%
}{}
\newcounter{zcworkaround}
\lstnewenvironment{zcworkaround}[1][]{%
  \renewcommand{\lstlistingname}{Work-around}%
  \lstset{#1}%
  \setcounter{lstlisting}{\value{zcworkaround}}%
}{}
\lstnewenvironment{zcexample}[1][]{%
  \renewcommand{\lstlistingname}{Example}%
  \lstset{#1}%
}{}
\ExplSyntaxOn
\makeatletter
\lst@AddToHook { PreInit }
  {
    \cs_if_exist:cT { c@ \lstenv@name }
      { \exp_args:Nx \refstepcounter { \lstenv@name } }
  }
\makeatother
\ExplSyntaxOff

\zcRefTypeSetup{zchowto}{
  Name-sg = {How-to},
  name-sg = {how-to},
  Name-pl = {How-tos},
  name-pl = {how-tos},
}
\zcRefTypeSetup{zcworkaround}{
  Name-sg = {Work-around},
  name-sg = {work-around},
  Name-pl = {Work-arounds},
  name-pl = {work-arounds},
}

\begin{document}

\GetFileInfo{zref-clever.sty}

\title{%
  The \pkg{zref-clever} package%
  \thanks{This file describes \fileversion, released \filedate.}%
}

\author{%
  Gustavo Barros%
  \thanks{\url{https://github.com/gusbrs/zref-clever}}%
}

\date{\filedate}

\maketitle

\begin{abstract}
  \pkg{zref-clever} provides an user interface for making \LaTeX{}
  cross-references which automates some of their typical features, thus easing
  their input in the document and improving the consistency of typeset
  results.  A reference made with \cs{zcref} includes a ``name'' according to
  its ``type'' and lists of multiple labels can be automatically sorted and
  compressed into ranges when due.  The reference format is highly and easily
  customizable, both globally and locally.  \pkg{zref-clever} is based on
  \pkg{zref}'s extensible referencing system.
\end{abstract}

\begin{center}
  \small
  \textbf{EXPERIMENTAL}

  Please read \zcref{sec:warning} carefully.
\end{center}

\tableofcontents

\section{Introduction}

Cross-referencing is an area which lends itself quite naturally to automation.
Not only for input convenience but also, and most importantly, for end results
consistency.  Indeed, the standard \LaTeX{} cross-referencing system -- with
\cs{label}, \cs{ref}, and \cs{pageref} -- is already a form of automation, by
relieving us from checking the number of the referenced object, and the page
where it lies.

But the plethora of existing features, packages and document classes which, in
one way or another, extends this basic functionality is a clear indication of
a demand for more automation.  Just to name the most popular: \pkg{cleveref},
\pkg{hyperref}, \pkg{titleref}, \pkg{nameref}, \pkg{varioref}, \pkg{fancyref},
and the kernel's \cs{labelformat}.

However, the standard cross-referencing system stores two, and only two,
properties with the label: the printed representation of the counter last
incremented with \cs{refstepcounter} and the page.  Of course, out of the
mentioned desire to automate more, the need arose to store more information
about the label to support this: the title or caption of the referenced
object; its counter or, even better, its ``type'', that is, whether it is a
section, chapter, figure, etc.; its hyperlink anchor, and so on.  Thus those
two property ``fields'' of the standard label became quite a disputed real
state.  And the packages in this area of functionality were bound to step on
each other's toes as a result.

Out of this conundrum, Heiko Oberdiek eventually developed \pkg{zref}, which
implements an extensible referencing system, making the labels store a
property list of flexible length, so that new properties can be easily added
and queried.  However, even when \pkg{zref} can rightfully boast this powerful
basic concept and is really quite featureful, with several different modules
available, it is fair to say that, for the average user, the package may
appear to be somewhat raw.  Indeed, for someone who ``just wants to make a
cross-reference'', the user interface of the \pkg{zref-user} module is akin to
the standard \LaTeX{} cross-referencing system, and even requires some extra
work if you want to have a hyperlinked reference.  In other words, \pkg{zref}
seems to have focused on infrastructure and on performing a number of
specialized tasks with different modules, and a large part of the landscape of
automation features available for the standard referencing system was not
carried over to \pkg{zref}, neither by the \pkg{zref} itself nor by other
packages.

\pkg{zref-clever} tries to cover this gap, by bringing a number of existing
features available for the standard referencing system to \pkg{zref}, and
hopefully making \pkg{zref} more accessible, and interesting, to the average
user.  And the package's name makes it clear that the core of the envisaged
feature set is that of \pkg{cleveref}, even though the attempt was less one of
replicating functionality per se than that of having it as a successful point
of reference, from where we could then try to tap into \pkg{zref}'s potential.
Indeed, although there is a significant intersection, the features of
\pkg{zref-clever} are neither a superset nor a subset of those of
\pkg{cleveref}.  There are things either of them can do that the other can't.
There are also important differences in user interface design.  In particular,
\pkg{zref-clever} relies heavily on \texttt{key=value} interfaces both for
general configuration and for centering in a single user command, \cs{zcref},
as the main entrance for reference making, whose behavior can be modulated by
local options.

Considering that \pkg{zref} itself offers the \pkg{zref-titleref} module, and
that the integration with \pkg{zref-check} allows \pkg{zref-clever} to make
context sensitive references, akin to those of \pkg{varioref}, a significant
part of the most prominent automation features available to the standard
referencing system is thus brought to \pkg{zref}, working under a single
consistent underlying infrastructure and user interface.  Alas, there are
limitations, of course (see \zcref{sec:limitations}).  Still, all in all,
hopefully \pkg{zref-clever} can be the missing piece for \pkg{zref} to fulfill
the promise insinuated by the ``z'' in its name, and be your ``last ref''.


\subsection{Warning}
\zlabel{sec:warning}

This package is in its early days, and should be considered experimental.  By
this I don't mean I expect it to be ``edgy'', indeed quite a lot of effort has
been put into it so that this is not the case.  However, during the initial
development, I had to make a number of calls for which I felt I had
insufficient information: in relation to features, packages, or classes I
don't use much, or to languages I don't know well, user needs I found hard to
anticipate etc.  Hence, the package needs some time, and some use by more
adventurous people, until it can settle down with more conviction.  In the
meantime, polishing the user interface and the infrastructure have a clear
priority over backward compatibility.  So, if you choose to use this package,
you should be ready to accommodate to eventual upstream changes.


\section{Loading the package}
\zlabel{sec:loading-package}

As usual:

\begin{zcexample}[escapeinside=`']
\usepackage`\oarg{options}'{zref-clever}
\end{zcexample}


\subsection{Dependencies}

\pkg{zref-clever} requires \pkg{zref}, and \LaTeX{} kernel 2021-11-15, or
newer.  It also needs \pkg{l3keys2e} and \pkg{ifdraft}.  Some packages are
leveraged by \pkg{zref-clever} if they are present, but are not loaded by
default or required by it, namely: \pkg{hyperref}, \pkg{zref-check}, and
\pkg{zref}'s \pkg{zref-titleref}, \pkg{zref-hyperref}, and \pkg{zref-xr}
modules.


\section{User interface}
\zlabel{sec:user-interface}

\begin{function}{\zcref}
  \begin{syntax}
    \cs{zcref}\meta{*}\oarg{options}\marg{labels}
  \end{syntax}
\end{function}
Typesets references to \meta{labels}, given as a comma separated list.  When
\pkg{hyperref} support is enabled, references will be hyperlinked to their
respective anchors, according to options.  The starred version of the command
does the same as the plain one, just does not form links.  The \meta{options}
are (mostly) the same as those of the package, and can be given to local
effect.  The \meta{labels} argument is protected by \pkg{zref}'s
\cs{zref@wrapper@babel}, so that it enjoys the same support for \pkg{babel}'s
active characters as \pkg{zref} itself does.

\begin{function}{\zcpageref}
  \begin{syntax}
    \cs{zcpageref}\meta{*}\oarg{options}\marg{labels}
  \end{syntax}
\end{function}
Typesets page references to \meta{labels}, given as a comma separated list.
It is equivalent to calling \cs{zcref} with the \opt{ref=page} option:
\cs{zcref}\texttt{\meta{*}[}\meta{options}\texttt{,ref=page]}\marg{labels}.


\begin{function}{\zcsetup}
  \begin{syntax}
    \cs{zcsetup}\marg{options}
  \end{syntax}
\end{function}
Sets \pkg{zref-clever}'s general options (see \zcref{sec:options,
  sec:reference-format}).  The settings performed by \cs{zcsetup} are local,
within the current group.  But, of course, it can also be used to global
effects if ungrouped, e.g.\ in the preamble.

\begin{function}{\zcRefTypeSetup}
  \begin{syntax}
    \cs{zcRefTypeSetup}\marg{type}\marg{options}
  \end{syntax}
\end{function}
Sets type-specific reference format options (see \zcref{sec:ref-format-opts}).
Just as for \cs{zcsetup}, the settings performed by \cs{zcRefTypeSetup} are
local, within the current group.

\bigskip{}

Besides these, user facing commands related to \zcref*[ref=title,
  noname]{sec:internationalization} are presented in
\zcref{sec:internationalization}.  Note still that all user commands are
defined with \cs{NewDocumentCommand}, which translates into the usual handling
of arguments by it and/or processing by \pkg{l3keys}, particularly with regard
to brace-stripping and space-trimming.

Furthermore, \pkg{zref-clever} loads \pkg{zref}'s \pkg{zref-user} module by
default.  So you also have its user commands available out of the box, notably
\cs{zlabel}, but also \cs{zref} and \cs{zpageref} themselves.



\subsection{Options}
\zlabel{sec:options}

\pkg{zref-clever} is highly configurable, offering a lot of flexibility in
typeset results of the references, but it also tries to keep these ``handles''
as convenient and user friendly as possible.  To this end, most of what one
can do with \pkg{zref-clever} (pretty much all of it), can be achieved
directly through the standard and familiar ``comma separated list of
\texttt{key=value} options''.

There are two main groups of options in \pkg{zref-clever}: ``general
options'', which affect the overall behavior of the package, or the reference
as a whole; and ``reference format options'', which control the detail of
reference formatting, including type-specific and language-specific settings.

This section covers the first group (for the second one, see
\zcref{sec:ref-format-opts}).  General options can be set globally either as
package options at load-time (see \zcref{sec:loading-package}) or by means of
\cs{zcsetup} in the preamble (see \zcref{sec:user-interface}).  They can also
be set locally with \cs{zcsetup} along the document or through the optional
argument of \cs{zcref} (see \zcref{sec:user-interface}).  Most general options
can be used in any of these contexts, but that is not necessarily true for all
cases, some restrictions may apply, as described in each option's
documentation.

\bigskip{}

\DescribeOption{ref} %
\DescribeOption{page} %
The \opt{ref} option controls the label property to which \cs{zcref} refers
to.  It can receive \pkg{zref} properties, as long as they are declared, but
notably \texttt{default}, \texttt{page}, \texttt{thecounter} and, if
\pkg{zref-titleref} is loaded, \texttt{title}.  The package's default is,
well, \texttt{default}, which is our standard reference.  \texttt{thecounter}
is a property set by \pkg{zref-clever} and is similar to \pkg{zref}'s
\texttt{default} property, except that it is not affected by the kernel's
\cs{labelformat}.\footnote{Technical note: the \texttt{default} property
  stores \cs{@currentlabel}, while the \texttt{thecounter} property stores
  \cs{the}\cs{@currentcounter}.  The later is exactly what \cs{refstepcounter}
  uses to build \cs{@currentlabel}, except for the \cs{labelformat} prefix
  and, hence, has the advantage of being unaffected by it.  But the former is
  \emph{more reliable} since \cs{@currentlabel} is expected to be correct
  pretty much anywhere whereas, although \cs{refstepcounter} does set
  \cs{@currentcounter}, it is not everywhere that uses \cs{refstepcounter} for
  the purpose.  In the cases where the references from these two do diverge,
  \pkg{zref-clever} will likely misbehave (reference type, sorting and
  compression inevitably depend on a correct \opt{currentcounter}), but using
  \texttt{default} at least ensures that the reference itself is correct.
  That said, if you do set \cs{labelformat} for some reason,
  \texttt{thecounter} may be useful.}  By default, reference formatting,
sorting, and compression are done according to information inferred from the
\emph{current counter} (see \opt{currentcounter} option below).  Special
treatment in these areas is provided for \texttt{page}, but not for any other
properties.  The \opt{page} option is a convenience alias for
\texttt{ref=page}.

\DescribeOption{typeset} %
\DescribeOption{noname} %
\DescribeOption{noref} %
When \cs{zcref} typesets a set of references, each group of references of the
same type can be, and by default are, preceded by the type's ``name'', and
this is indeed an important feature of \pkg{zref-clever}.  This is optional
however, and the \opt{typeset} option controls this behavior.  It can receive
values \texttt{ref}, in which case it typesets only the reference(s),
\texttt{name}, in which case it typesets only the name(s), or \texttt{both},
in which case it typesets, well, both of them.  Note that, when value
\texttt{name} is used, the name is still typeset according to the set of
references given to \cs{zcref}.  For example, for multiple references, the
plural form is used, capitalization options are honored, etc.  Also
hyperlinking behaves just \emph{as if} the references were present and,
depending on the corresponding options, the name may be linked to the first
reference of the type group.  The \opt{noname} and \opt{noref} options are
convenience aliases for \texttt{typeset=ref} and \texttt{typeset=name},
respectively.

\DescribeOption{sort} %
\DescribeOption{nosort} %
The \opt{sort} option controls whether the list of \meta{labels} received as
argument by \cs{zcref} should be sorted or not.  It is a boolean option, and
defaults to \texttt{true}.  The \opt{nosort} option is a convenience alias for
\texttt{sort=false}.

\DescribeOption{typesort} %
\DescribeOption{notypesort} %
Sorting references of the same type can be done with well defined logical
criteria.  They either have the same counter or their counters share a clear
hierarchical relation (in the resetting behavior), such that a definite
sorting rule can be inferred from the label's data.  The same is not true for
sorting of references of different types.  Should ``tables'' come before or
after ``figures''?  The \pkg{typesort} option allows to specify the sorting
priority of different reference types.  It receives as value a comma separated
list of reference types, specifying that their sorting is to be done in the
order of that list.  But \opt{typesort} does not need to receive \emph{all}
possible reference types.  The special value \texttt{\{\{othertypes\}\}} (yes,
double braced, one for \pkg{l3keys}, so that the second can make the list) can
be placed anywhere along the list, to specify the sort priority of any type
not included explicitly.  If \texttt{\{othertypes\}} is not present in the
list, it is presumed to be at the end of it.  Any unspecified types (that is,
those falling implicitly or explicitly into the \texttt{\{othertypes\}}
category) get sorted between themselves in the order of their first appearance
in the label list given as argument to \cs{zcref}.  I presume the common use
cases will not need to specify \texttt{\{othertypes\}} at all but, for the
sake of example, if you just really dislike equations, you could use
\texttt{typesort=\{\{\{othertypes\}\}, equation\}}.  \opt{typesort}'s default
value is \texttt{\{part, chapter, section, paragraph\}}, which places the
sectioning reference types first in the list, in their hierarchical order, and
leaves everything else to the order of appearance of the labels.  The
\opt{notypesort} option behaves like \texttt{typesort=\{\{\{othertypes\}\}\}}
would do, that is, it sorts all types in the order of the first appearance in
the labels' list.

\DescribeOption{comp} %
\DescribeOption{nocomp} %
\cs{zcref} can automatically compress a set of references of the same type
into a range, when they occur in immediate sequence.  The \opt{comp} controls
whether this compression should take place or not.  It is a boolean option,
and defaults to \texttt{true}.  The \opt{nocomp} option is a convenience alias
for \texttt{comp=false}.  Of course, for better compression results the
\opt{sort} is recommended, but the two options are technically independent.

\DescribeOption{range} %
By default (that is, when the \opt{range} option is not given), \cs{zcref}
typesets a complete list of references according to the \meta{labels} it
received as argument, and only compresses some of them into ranges if the
\opt{comp} option is enabled and if references of the same type occur in
immediate sequence.  The \opt{range} option makes \cs{zcref} behave
differently.  Sorting is implied by this option (the \opt{sort} option is
disregarded) and, for each reference type group in \meta{labels}, \cs{zcref}
builds a range from the first to the last reference in it, even if references
in between do not occur in immediate sequence.  \cs{zcref} is smart enough,
though, to recognize when the first and last references of a type do happen to
be contiguous, in which case it typesets a ``pair'', instead of a ``range''.
It is a boolean option, and the package's default is \texttt{range=false}.
The option given without a value is equivalent to \texttt{range=true} (in the
\pkg{l3keys}' jargon, the \emph{option}'s default is \texttt{true}).

\DescribeOption{cap} %
\DescribeOption{nocap} %
\DescribeOption{capfirst} %
The \opt{cap} option controls whether the reference type names should be
capitalized or not.  It is a boolean option, and the package's default is
\texttt{cap=false}.  The option given without a value is equivalent to
\texttt{cap=true}.  The \opt{nocap} option is a convenience alias for
\texttt{cap=false}.  The \opt{capfirst} option ensures that the reference type
name of the \emph{first} type block is capitalized, even when \opt{cap} is set
to \texttt{false}.

\DescribeOption{abbrev} %
\DescribeOption{noabbrev} %
\DescribeOption{noabbrevfirst} %
The \opt{abbrev} option controls whether to use abbreviated reference type
names when they are available.  It is a boolean option, and the package's
default is \texttt{abbrev=false}.  The option given without a value is
equivalent to \texttt{abbrev=true}.  The \opt{noabbrev} option is a
convenience alias for \texttt{abbrev=false}.  The \opt{noabbrevfirst} ensures
that the reference type name of the \emph{first} type block is never
abbreviated, even when \opt{abbrev} is set to \texttt{true}.

\DescribeOption{S} %
\opt{S} for ``Sentence''.  The \opt{S} option is a convenience alias for
\texttt{capfirst=true, noabbrevfirst=true}, and is intended to be used in
references made at the beginning of a sentence.  It is highly recommended that
you make a habit of using the \opt{S} option for beginning of sentence
references.  Even if you do happen to be currently using \texttt{cap=true,
  abbrev=false}, proper semantic markup will ensure you get expected results
even if you change your mind in that regard later on.  For that reason, it was
made short and mnemonic, it can't get any easier.

\DescribeOption{hyperref} %
The \opt{hyperref} option controls the use of \pkg{hyperref} by
\pkg{zref-clever} and takes values \opt{auto}, \opt{true}, \opt{false}.  The
default value, \opt{auto}, makes \pkg{zref-clever} use \pkg{hyperref} if it is
loaded, meaning that references made with \cs{zcref} get hyperlinked to the
anchors of their respective \meta{labels}.  \opt{true} does the same thing,
but warns if \pkg{hyperref} is not loaded (\pkg{hyperref} is never loaded for
you).  In either of these cases, if \pkg{hyperref} is loaded, module
\pkg{zref-hyperref} is also loaded by \pkg{zref-clever}.  \opt{false} means
not to use \pkg{hyperref} regardless of its availability.  This is a preamble
only option, but \cs{zcref} provides granular control of hyperlinking by means
of its starred version.

\DescribeOption{nameinlink} %
The \opt{nameinlink} option controls whether the type name should be included
in the reference hyperlink or not (provided there is a link, of course).
Naturally, the name can only be included in the link of the \emph{first}
reference of each type block.  \opt{nameinlink} can receive values
\texttt{true}, \texttt{false}, \texttt{single}, and \texttt{tsingle}.  When
the value is \texttt{true} the type name is always included in the hyperlink.
When it is \texttt{false} the type name is never included in the link.  When
the value is \texttt{single}, the type name is included in the link only if
\cs{zcref} is typesetting a single reference (not necessarily having received
a single label as argument, as they may have been compressed), otherwise, the
name is left out of the link.  When the value is \texttt{tsingle}, the type
name is included in the link for each type block with a single reference,
otherwise, it isn't.  An example: suppose you make a couple of references to
something like \cs{zcref}\texttt{\{chap:chapter1\}} and
\cs{zcref}\texttt{\{chap:chapter1, sec:section1, fig:figure1, fig:figure2\}}.
The ``figure'' type name will only be included in the hyperlink if
\opt{nameinlink} option is set to \texttt{true}.  If it is set to
\texttt{tsingle}, the first reference will include the name in the link for
``chapter'', as expected, but also in the second reference the ``chapter'' and
``section'' names will be included in their respective links, while that of
``figure'' will not.  If the option is set to \texttt{single}, only the name
for ``chapter'' in the first reference will be included in the link, while in
the second reference none of them will.  The package's default is
\texttt{nameinlink=tsingle}, and the option given without a value is
equivalent to \texttt{nameinlink=true}.

\DescribeOption{preposinlink} %
The \opt{preposinlink} option controls whether the \opt{refpre} and
\opt{refpos} reference format options (see \zcref{sec:ref-format-opts}) are
included in the reference hyperlink or not.  It is a boolean option.  The
package's default is \texttt{preposinlink=false}, and the option given without
a value is equivalent to \texttt{preposinlink=true}.

\DescribeOption{lang} %
The \opt{lang} option controls the language used by \cs{zcref} when looking
for language-specific reference format options (see
\zcref{sec:ref-format-opts}).  The default value, \texttt{current}, uses the
current language, as defined by \pkg{babel} or \pkg{polyglossia} (or
\texttt{english} if none of them is loaded).  Value \texttt{main} uses the
main document language, as defined by \pkg{babel} or \pkg{polyglossia} (or
\texttt{english} if none of them is loaded).  The \opt{lang} option also
accepts that the language be specified directly by its name, as long as it's a
language known by \pkg{zref-clever}.  For more details on
\zcref*[ref=title,noname]{sec:internationalization}, see
\zcref{sec:internationalization}.

\DescribeOption{d} %
The \opt{d} option sets the declension case, and affects the type name used
for typesetting the reference.  Whether this option is operative, and which
values it accepts, depends on the declared setup for each language.  For
details, see \zcref{sec:internationalization}.

\DescribeOption{nudge} %
\DescribeOption{nudgeif} %
\DescribeOption{nonudge} %
\DescribeOption{sg} %
\DescribeOption{g} %
This set of options revolving around \opt{nudge} aims to offer some guard
against mischievous automation on the part of \pkg{zref-clever} by providing a
number of ``nudges'' (compilation time messages) for cases in which you may
wish to revise material \emph{surrounding} the reference -- an article, a
preposition -- according to the reference typeset results.  Useful mainly for
languages which inflect the preceding article to gender and/or number, but may
be used generally to fine-tune the language and style around the
cross-references made with \cs{zcref}.  The \opt{nudge} option is the main
entrance to this feature and takes values \texttt{true}, \texttt{false},
\texttt{ifdraft}, or \texttt{iffinal}.  The first two, respectively, enable or
disable the ``nudging'' unconditionally.  With \texttt{ifdraft}, \opt{nudge}
keeps quiet when option \texttt{draft} is given to \cs{documentclass}, while
with \texttt{iffinal}, nudging is only enabled when option \texttt{final} is
(explicitly) passed to \cs{documentclass}.  The option given without a value
is equivalent to \texttt{nudge=true} and the package's default is
\texttt{nudge=false}.  \opt{nonudge} is a convenience alias for
\texttt{nudge=false}, and can be used to silence individual references.  The
\opt{nudgeif} option controls the events which may trigger a nudge.  It takes
a comma separated list of elements, and recognizes values \texttt{multitype},
\texttt{comptosing}, \texttt{gender}, and \texttt{all}.  The
\texttt{multitype} nudge warns when the reference is composed by multiple type
blocks (see \zcref{sec:ref-format-opts}).  The \texttt{comptosing} nudge let's
you know when multiple labels of the same type have been compressed to a
singular type name form.  It can be combined with the \opt{sg} option, which
is the way to tell \cs{zcref} you know it's a singular and so not to nudge if
a compression to singular occurs, but to nudge if the contrary occurs, that
is, when a plural type name form is employed.  The \texttt{gender} nudge must
be combined with option \opt{g}, and depends on the language having support
for it.  In essence language dictionaries can store the gender of each type
name (this is done for built-in dictionaries, but can also be done with
\cs{zcLanguageSetup} for languages declared to support it).  The \opt{g}
option let's you specify the gender you expect for that particular reference
and the nudge is triggered if there is a mismatch between \opt{g} and the
gender for the type name in the dictionary.  Both the \texttt{comptosing} and
the \texttt{gender} nudges have a type block as its scope.  See
\zcref{sec:internationalization} for more details and intended use cases of
the ``nudging'' feature.

\DescribeOption{font} %
The \opt{font} option can receive font styling commands to change the
appearance of the whole reference list (see also the \opt{namefont} and
\opt{reffont} reference format options in \zcref{sec:ref-format-opts}).  It
does not affect the content of the \opt{note}, however.  The option is
intended exclusively for commands that only change font attributes: style,
family, shape, weight, size, color, etc.  Anything else, particularly commands
that may generate typeset output, is not supported.  Given how package options
are handled by \LaTeX{}, the fact that this option receives commands as value
means this option \emph{can't} be set at load time, as a package option.  If
you want to set it globally, use \cs{zcsetup} instead.

\DescribeOption{titleref} %
The \opt{titleref} option receives no value and, when given, loads
\pkg{zref}'s \pkg{zref-titleref} module.  This is a preamble only option.

\DescribeOption{note} %
The \opt{note} option receives as value some text to be typeset at the end of
the whole reference list.  It is separated from it by \opt{notesep} (see
\zcref{sec:ref-format-opts}).

\DescribeOption{check} %
Provides integration of \pkg{zref-clever} with the \pkg{zref-check} package.
In the preamble, the \opt{check} option receives no value and, when given,
loads \pkg{zref-check}.  In the document body, \opt{check} requires a value,
which works exactly like the optional argument of \cs{zcheck}, and can receive
both checks and \cs{zcheck}'s options.  And the checks are performed for each
label in \marg{labels} received as argument by \cs{zcref}.  See the User
manual of \pkg{zref-check} for details.  The checks done by the \opt{check}
option in \cs{zcref} comprise the complete reference, including the \opt{note}
(see \zcref{sec:ref-format-opts}).  If \pkg{zref-check} was not loaded in the
preamble, at begin document the option is made no-op and issues a warning.

\DescribeOption{countertype} %
The \opt{countertype} option allows to specify the ``reference type'' of each
counter, which is stored as a label property when the label is set.  This
``reference type'' is what determines how a reference to this label will
eventually be typeset when it is referred to (see
\zcref{sec:reference-types}).  A value like \texttt{countertype = \{foo =
  bar\}} sets the \texttt{foo} counter to use the reference type \texttt{bar}.
There's only need to specify the \opt{countertype} for counters whose name
differs from that of their type, since \pkg{zref-clever} presumes the type has
the same name as the counter, unless otherwise specified.  Also, the default
value of the option already sets appropriate types for basic \LaTeX{}
counters, including those from the standard classes.  Setting a counter type
to an empty value removes any (explicit) type association for that counter, in
practice, this means it then uses a type equal to its name.  Since this option
only affects how labels are set, it is not available in \cs{zcref}.

\DescribeOption{\raisebox{-.2em}{\dbend}\ counterresetters} %
\DescribeOption{counterresetby} %
The sorting and compression of references done by \cs{zcref} requires that we
know the counter associated with a particular label but also information on
any counter whose stepping may trigger its resetting, or its ``enclosing
counters''.  This information is not easily retrievable from the counter
itself but is (normally) stored with the counter that does the resetting.  The
\opt{counterresetters} option adds counter names, received as a comma
separated list, to the list of counters \pkg{zref-clever} uses to search for
``enclosing counters'' of the counter for which a label is being set.
Unfortunately, not every counter gets reset through the standard machinery for
this, including some \LaTeX{} kernel ones (e.g. the \texttt{enumerate}
environment counters).  For those, there is really no way to retrieve this
information directly, so we have to just tell \pkg{zref-clever} about them.
And that's what the \opt{counterresetby} option is made for.  It receives a
comma separated list of \texttt{key=value} pairs, in which \texttt{key} is the
counter, and \texttt{value} is its ``enclosing counter'', that is, the counter
whose stepping results in its resetting.  This is not really an ``option'' in
the sense of ``user choice'', it is more of a way to inform \pkg{zref-clever}
of something it cannot know or automatically find in general.  One cannot
place arbitrary information there, or \pkg{zref-clever} can be thoroughly
confused.  The setting must correspond to the actual resetting behavior of the
involved counters.  \opt{counterresetby} has precedence over the search done
in the \opt{counterresetters} list.  The default value of
\opt{counterresetters} includes the counters for sectioning commands of the
standard classes which, in most cases, should be the relevant ones for
cross-referencing purposes.  The default value of \opt{counterresetby}
includes the \texttt{enumerate} environment counters.  So, hopefully, you
don't need to ever bother with either of these options.  But, if you do, they
are here.  Use them with caution though.  Since these options only affect how
labels are set, they are not available in \cs{zcref}.

\DescribeOption{\raisebox{.4em}{\dbend}\ currentcounter} %
\LaTeX{}'s \cs{refstepcounter} sets two variables which potentially affect the
\cs{zlabel} set after it: \cs{@currentlabel} and \cs{@currentcounter}.
Actually, traditionally, only the current label was thus stored, the current
counter was added to \cs{refstepcounter} somewhat recently (with the
2020-10-01 kernel release).  But, since \pkg{zref-clever} relies heavily on
the information of what the current counter is, it must set \pkg{zref} to
store that information with the label, as it does.  As long as the document
element we are trying to refer to uses the standard machinery of
\cs{refstepcounter} we are on solid ground and can retrieve the correct
information.  However, it is not always ensured that \cs{@currentcounter} is
kept up to date.  For example, packages which handle labels specially, for one
reason or another, may or may not set \cs{@currentcounter} as required.
Considering the addition of \cs{@currentcounter} to \cs{refstepcounter} itself
is not that old, it is likely that in a good number of places a reliable
\cs{@currentcounter} is not really in place.  Therefore, it may happen we need
to tell \pkg{zref-clever} what the current counter is in certain
circumstances, and that's what \opt{currentcounter} does.  The same as with
the previous two options, this is not really an ``user choice'' kind of
option, but a way to tell \pkg{zref-clever} a piece of information it has no
means to retrieve automatically.  The setting must correspond to the actual
``current counter'', meaning here ``the counter underlying
\cs{@currentlabel}'' in a given situation.  Also, when using the
\opt{currentcounter} option, make sure the setting is duly grouped because, if
set, it has precedence over \cs{@currentcounter} and, contrary to the later,
the former is not reset the next time \cs{refstepcounter} runs.  Its default
value is, quite naturally, \cs{@currentcounter}.  Since this option only
affects how labels are set, it is not available in \cs{zcref}.

\DescribeOption{nocompat} %
Some packages, document classes, or LaTeX features may require specific
support to work with \pkg{zref-clever} (see \zcref{sec:limitations}).
\pkg{zref-clever} tries to make things smoother by covering some of them.
Depending on the case, this can take the form of some simple setup for
\pkg{zref-clever}, or may involve the use of hooks to external environments or
commands and, eventually, a patch or redefinition.  By default, all the
available compatibility modules are enabled.  Should this be undesired or
cause any problems in your environment, the option \opt{nocompat} can
selectively or completely inhibit their loading.  \opt{nocompat} receives a
comma separated list of compatibility modules to disable (for the list of
available modules and details about each of them, see
\zcref{sec:comp-modules}).  You can disable all modules by setting
\opt{nocompat} without a value (or an empty one).  This is a preamble only
option.

\section{Reference format}
\zlabel{sec:reference-format}

\subsection{Reference types}
\zlabel{sec:reference-types}

A ``reference type'' is the basic \pkg{zref-clever} setup unit for specifying
how a cross-reference group of a certain kind is to be typeset.  Though,
usually, it will have the same name as the underlying \LaTeX{} \emph{counter},
they are conceptually different.  \pkg{zref-clever} sets up \emph{reference
  types} and an association between each \emph{counter} and its \emph{type},
it does not define the counters themselves, which are defined by your
document.  One \emph{reference type} can be associated with one or more
\emph{counters}, and a \emph{counter} can be associated with different
\emph{types} at different points in your document.  But each label is stored
with only one \emph{type}, as specified by the counter-type association at the
moment it is set, and that determines how the reference to that label is
typeset.  References to different \emph{counters} of the same \emph{type} are
grouped together, and treated alike by \cs{zcref}.  A \emph{reference type}
may be known to \pkg{zref-clever} when the \emph{counter} it is associated
with is not actually defined, and this inconsequential.  In practice, the
contrary may also happen, a \emph{counter} may be defined but we have no
\emph{type} for it, but this must be handled by \pkg{zref-clever} as an error
(at least, if we try to refer to it), usually a ``missing name'' error.

\pkg{zref-clever} provides default settings for the following reference types:
\texttt{part}, \texttt{chapter}, \texttt{section}, \texttt{paragraph},
\texttt{appendix}, \texttt{subappendix}, \texttt{page}, \texttt{line},
\texttt{figure}, \texttt{table}, \texttt{item}, \texttt{footnote},
\texttt{endnote}, \texttt{note}, \texttt{equation}, \texttt{theorem},
\texttt{lemma}, \texttt{corollary}, \texttt{proposition}, \texttt{definition},
\texttt{proof}, \texttt{result}, \texttt{remark}, \texttt{example},
\texttt{algorithm}, \texttt{listing}, \texttt{exercise}, and
\texttt{solution}.  Therefore, if you are using a language for which
\pkg{zref-clever} has built-in support (see \zcref{sec:internationalization}),
these reference types are available for use out of the box.\footnote{There may
  be slight availability differences depending on the language, but
  \pkg{zref-clever} strives to keep this complete list available for the
  languages it has built-in dictionaries.}  And, in any case, it is always
easy to setup custom reference types with \cs{zcRefTypeSetup} or
\cs{zcLanguageSetup} (see \zcref{sec:user-interface, sec:reference-format,
  sec:internationalization}).

The association of a \emph{counter} to its \emph{type} is controlled by the
\opt{countertype} option.  As seen in its documentation, \pkg{zref-clever}
presumes the \emph{type} to be the same as the \emph{counter} unless
instructed otherwise by that option.  This association, as determined by the
local value of the option, affects how the \emph{label} is set, which stores
the type among its properties.  However, when it comes to typesetting, that is
from the perspective of \cs{zcref}, only the \emph{type} matters.  In other
words, how the reference is supposed to be typeset is determined at the point
the \emph{label} gets set.  In sum, they may be namesakes (or not), but type
is type and counter is counter.

Indeed, a reference type can be associated with multiple counters because we
may want to refer to different document elements, with different
\emph{counters}, as a single \emph{type}, with a single name.  One prominent
case of this are sectioning commands.  \cs{section}, \cs{subsection}, and
\cs{subsubsection} have each their counter, but we'd like to refer to all of
them by ``sections'' and group them together.  The same for \cs{paragraph} and
\cs{subparagraph}.

There are also cases in which we may want to use different \emph{reference
  types} to refer to document objects sharing the same \emph{counter}.
Notably, the environments created with \LaTeX{}'s \cs{newtheorem} command and
the \cs{appendix}.


One more observation about ``reference types'' is due here.  A \emph{type} is
not really ``defined'' in the sense a variable or a function is.  It is more
of a ``string'' which \pkg{zref-clever} uses to look for a whole set of
type-specific reference format options (see \zcref{sec:ref-format-opts}).
Each of these options individually may be ``set'' or not, ``defined'' or not.
And, depending on the setup and the relevant precedence rules for this, some
of them may be required and some not.  In practice, \pkg{zref-clever} uses the
\emph{type} to look for these options when it needs one, and issues a
compilation warning when it cannot find a suitable value.


\subsection{Reference format options}
\zlabel{sec:ref-format-opts}

Formatting how the reference is to be typeset is, quite naturally, a big part
of the user interface of \pkg{zref-clever}.  In this area, we tried to balance
``flexibility'' and ``user friendliness''.  But the former does place a big
toll overall, since there are indeed many places where tweaking may be
desired, and the settings may depend on at least two important dimensions of
variation: the reference type and the language.  Combination of those
necessarily makes for a large set of possibilities.  Hence, the attempt here
is to provide a rich set of ``handles'' for fine tuning the reference format
but, at the same time, do not \emph{require} detailed setup by the users,
unless they really want it.

With that in mind, we have settled with an user interface for reference
formatting which allows settings to be done in different scopes, with more or
less overarching effects, and some precedence rules to regulate the relation
of settings given in each of these scopes.  There are four scopes in which
reference formatting can be specified by the user, in the following precedence
order: i) as \emph{general options}; ii) as \emph{type-specific options}; iii)
as \emph{language-specific and type-specific translations}; and iv) as
\emph{default translations} (that is, language-specific but not
type-specific).  Besides those, there's a fifth \emph{internal} scope, with
the least priority of all, a ``fallback'', for the cases where it is
meaningful to provide some value, even for an unknown language.  The package
itself places the default setup for reference formatting at low precedence
levels, and the users can easily and conveniently override them as desired.

``General options'' (i) can be given by the user in the optional argument of
\cs{zcref}, but also set through \cs{zcsetup} or even, depending on the case,
as package options at load-time (see \zcref{sec:options}).\footnote{The use of
  \cs{zcsetup} for global reference format settings is recommended though.
  Whether you can use load-time options or not depends on the values of the
  options: due to how \LaTeX{} handles package options, if the values of the
  options you are setting include \emph{commands} you can't set them at
  load-time, and rather \emph{must} use \cs{zcsetup}.}  ``Type-specific
options'' (ii) are handled by \cs{zcRefTypeSetup} (see
\zcref{sec:user-interface}).  ``Language-specific translations'', be they
``type-specific'' (iii) or ``default'' (iv) have their user interface in
\cs{zcLanguageSetup}, and have their values populated by the package's
built-in dictionaries (see \zcref{sec:internationalization}).  Not all
reference format specifications can be given in all of these scopes, though.
Some of them can't be type-specific, others must be type-specific, so the set
available in each scope depends on the pertinence of the case.
\zcref{tab:reference-format} introduces the available reference format
options, which will be discussed in more detail soon, and lists the scopes in
which each is available.


\begin{table}[htb]
  \centering
  \begin{tabular}{l>{\ttfamily}lcccc}
    \toprule
                    &            & General   & Type      & Type-specific & Default      \\
                    &            & options   & options   & translations  & translations \\
                    &            & (i)       & (ii)      & (iii)         & (iv)         \\

    \midrule
    Necessarily not & tpairsep   & $\bullet$ &           &               &  $\bullet$   \\
    type-specific   & tlistsep   & $\bullet$ &           &               &  $\bullet$   \\
                    & tlastsep   & $\bullet$ &           &               &  $\bullet$   \\
                    & notesep    & $\bullet$ &           &               &  $\bullet$   \\

    \addlinespace
    Possibly        & namesep    & $\bullet$ & $\bullet$ &   $\bullet$   &  $\bullet$   \\
    type-specific   & pairsep    & $\bullet$ & $\bullet$ &   $\bullet$   &  $\bullet$   \\
                    & listsep    & $\bullet$ & $\bullet$ &   $\bullet$   &  $\bullet$   \\
                    & lastsep    & $\bullet$ & $\bullet$ &   $\bullet$   &  $\bullet$   \\
                    & rangesep   & $\bullet$ & $\bullet$ &   $\bullet$   &  $\bullet$   \\
                    & refpre     & $\bullet$ & $\bullet$ &   $\bullet$   &  $\bullet$   \\
                    & refpos     & $\bullet$ & $\bullet$ &   $\bullet$   &  $\bullet$   \\

    \addlinespace
    Necessarily     & Name-sg    &           & $\bullet$ &   $\bullet$   &              \\
    type-specific   & name-sg    &           & $\bullet$ &   $\bullet$   &              \\
                    & Name-pl    &           & $\bullet$ &   $\bullet$   &              \\
                    & name-pl    &           & $\bullet$ &   $\bullet$   &              \\
                    & Name-sg-ab &           & $\bullet$ &   $\bullet$   &              \\
                    & name-sg-ab &           & $\bullet$ &   $\bullet$   &              \\
                    & Name-pl-ab &           & $\bullet$ &   $\bullet$   &              \\
                    & name-pl-ab &           & $\bullet$ &   $\bullet$   &              \\

    \addlinespace
    Font            & namefont   & $\bullet$ & $\bullet$ &               &              \\
    options         & reffont    & $\bullet$ & $\bullet$ &               &              \\
    \bottomrule
  \end{tabular}
  \caption{Reference format options and their scopes}
  \zlabel{tab:reference-format}
\end{table}


Understanding the role of each of these reference format options is likely
eased by some visual schemes of how \pkg{zref-clever} builds a reference based
on the labels' data and the value of these options. Take a \texttt{ref} to be
that which a standard \LaTeX{} \cs{ref} would typeset.  A \pkg{zref-clever}
``reference block'', or \texttt{ref-block}, is constructed as:

\begin{refformat}
\item \reffmt{ref-block} \(\equiv\)
\item \reffmt{refpre} \reffmt{ref} \reffmt{refpos}
\end{refformat}

A \texttt{ref-block} is built for \emph{each} label given as argument to
\cs{zcref}.  When the \meta{labels} argument is comprised of multiple labels,
each ``reference type group'', or \texttt{type-group} is potentially made from
the combination of single reference blocks, ``reference block pairs'',
``reference block lists'', or ``reference block ranges'', where each is
respectively built as:

\begin{refformat}
\item \reffmt{type-group} is a combination of:
\item \reffmt{ref-block}
\item \reffmt{ref-block1} \reffmt{pairsep} \reffmt{ref-block2}
\item \reffmt{ref-block1} \reffmt{listsep} \reffmt{ref-block2}
  \reffmt{listsep} \reffmt{ref-block3} \dots{} \par \qquad
  \dots{}\reffmt{ref-blockN-1} \reffmt{lastsep} \reffmt{ref-blockN}
\item \reffmt{ref-block1} \reffmt{rangesep} \reffmt{ref-blockN}
\end{refformat}

To complete a ``type-block'', a \texttt{type-group} only needs to be
accompanied by the ``type name'':

\begin{refformat}
\item \reffmt{type-block} \(\equiv\)
\item \reffmt{type-name} \reffmt{namesep} \reffmt{type-group}
\end{refformat}

The \texttt{type-name} is determined not by one single reference format option
but by the appropriate one among the \opt{[Nn]ame-} options according to the
composition of \texttt{type-group} and the general options.  The reference
format name options are eight in total: \opt{Name-sg}, \opt{name-sg},
\opt{Name-pl}, \opt{name-pl}, \opt{Name-sg-ab}, \opt{name-sg-ab},
\opt{Name-pl-ab}, and \opt{name-pl-ab}.  The initial uppercase ``\texttt{N}''
signals the capitalized form of the type name.  The \texttt{-sg} suffix stands
for singular, while \texttt{-pl} for plural.  The \texttt{-ab} is appended to
the abbreviated type name form options.  When setting up a type, not
necessarily all forms need to be provided.  \pkg{zref-clever} will always use
the non-abbreviated form as a fallback to the abbreviated one, if the later is
not available.  Hence, if a reference type is not intended to be used with
abbreviated names (the most common case), only the basic four forms are
needed.  Besides that, if you are using the \opt{cap} option, only the
capitalized forms will ever be required by \cs{zcref}, so you can get away
setting only \opt{Name-sg} and \opt{Name-pl}.  You should not do the contrary
though, and provide only the non-capitalized forms because, even if you are
using the \opt{nocap} option, the capitalized forms will be still required for
\opt{capfirst} and \opt{S} options to work.  Whatever the case may be, you
need not worry too much about being remiss in this area: if \cs{zcref} does
lack a name form in any given reference, it will let you know with a
compilation warning (and will typeset the usual missing reference sign:
``\textbf{??}'').

A complete reference typeset by \cs{zcref} may be comprised of multiple
\texttt{type-block}s, in which case the ``type-block-group'' can also be made
of single type blocks, ``type block pairs'' or ``type block lists'', where
each is respectively built as:

\begin{refformat}
\item \reffmt{type-block-group} is one of:
\item \reffmt{type-block}
\item \reffmt{type-block1} \reffmt{tpairsep} \reffmt{type-block2}
\item \reffmt{type-block1} \reffmt{tlistsep} \reffmt{type-block2}
  \reffmt{tlistsep} \reffmt{type-block3} \dots{} \par \qquad \dots{}
  \reffmt{type-blockN-1} \reffmt{tlastsep} \reffmt{type-blockN}
\end{refformat}

Finally, since \cs{zcref} can also receive an optional \opt{note}, its full
typeset output is built as:

\begin{refformat}
\item A complete \reffmt{\cs{zcref}} reference:
\item \reffmt{type-block-group} \reffmt{notesep} \reffmt{note}
\end{refformat}

Reference format options can yet be divided in two general categories: i)
``string'' options, the ones which we have seen thus far, as ``building
blocks'' of the reference; and ii) ``font'' options, which control font
attributes of parts of the reference, namely \opt{namefont} and \opt{reffont}.
These options set the font, respectively, for the \texttt{type-name} and for
\texttt{ref} (to set the font for the whole reference, see the \opt{font}
option in \zcref{sec:options}).  ``String'' options is not really a strict
denomination for the first category, but this set of options is intended
exclusively for typesetting material: things you expect to see in the output
of your references.  The ``font'' options, on the other hand, are intended
exclusively for commands that only change font attributes: style, family,
shape, weight, size, color, etc.  In either case, anything other than their
intended uses is not supported.

Finally, a comment about the internal ``fallback'' reference format values
mentioned above.  These ``last resort'' option values are required by
\pkg{zref-clever} for a clear particular case: if the user loads either
\pkg{babel} or \pkg{polyglossia}, or explicitly sets a language, with a
language that \pkg{zref-clever} does not know and has no dictionary for, it
cannot guess what language that is, and thus has to provide some reasonable
``language agnostic'' default, at least for the options for which this makes
sense (all the ``string'' options, except for the \texttt{[Nn]ame-} ones).
Users do not need to have access to this scope, since they know the language
of their document, or know the values they want for those options, and can set
them as general options, type-specific options, or language options through
the user interface provided for the purpose.  But the ``fallback'' options are
documented here so that you can recognize when you are getting these values
and change them appropriately as desired.  Though hopefully reasonable, they
may not be what you want.  The ``fallback'' option values are the following:

\begin{zcexample}[escapeinside=`']
tpairsep  = {,`\textvisiblespace{}'} ,
tlistsep  = {,`\textvisiblespace{}'} ,
tlastsep  = {,`\textvisiblespace{}'} ,
notesep   = {`\textvisiblespace{}'} ,
namesep   = {\nobreakspace} ,
pairsep   = {,`\textvisiblespace{}'} ,
listsep   = {,`\textvisiblespace{}'} ,
lastsep   = {,`\textvisiblespace{}'} ,
rangesep  = {\textendash} ,
refpre    = {} ,
refpos    = {} ,
\end{zcexample}


\section{Internationalization}
\zlabel{sec:internationalization}

\pkg{zref-clever} provides internationalization facilities and integrates with
\pkg{babel} and \pkg{polyglossia} to adapt to the languages in use by either
of these language packages, or to a language specified directly by the user.
This is primarily relevant for reference format options, particularly
reference type \emph{names} (though not only, since most reference format
options can have language-specific values, or ``translations'', see
\zcref{sec:ref-format-opts}).  But other features of the package also cater
for language specific needs.

As far as language selection is concerned, if the language is declared and
\pkg{zref-clever} has a built-in ``dictionary'' for it, most use cases will
likely be covered by the \opt{lang} option (see \zcref{sec:options}), and its
values \texttt{current} and \texttt{main}.  When the \opt{lang} option is set
to \texttt{current} or \texttt{main}, \pkg{zref-check} will use, respectively,
the \emph{current} or \emph{main} language of the document, as defined by
\pkg{babel} or \pkg{polyglossia}.\footnote{Technically, \pkg{zref-clever} uses
  \cs{languagename} and \cs{bbl@main@language} for \pkg{babel}, and
  \cs{babelname} and \cs{mainbabelname} for \pkg{polyglossia}, which boils
  down to \pkg{zref-clever} always using \emph{\pkg{babel} names} internally,
  regardless of which language package is in use.  Indeed, an acquainted user
  will note that \zcref{tab:languages-and-aliases} contains only \pkg{babel}
  language names.}  Users can also set \opt{lang} to a specific language
directly, in which case \pkg{babel} and \pkg{polyglossia} are disregarded.
\pkg{zref-clever} provides a number of built-in ``dictionaries'', for the
languages listed in \zcref{tab:languages-and-aliases}, which also includes the
declared aliases to those languages.

\pkg{zref-clever}'s ``dictionaries'' are loaded sparingly and lazily.  A
dictionary for a single language -- that specified by user options in the
preamble, which by default is the current document language -- is loaded at
\texttt{begindocument}.  If any other dictionary is needed, it is loaded on
the fly, if and when required.  Of course, in either case, conditioned on
availability.  In sum, \pkg{zref-clever} loads as little as possible, but
allows for convenient on the fly loading of dictionaries if the values are
indeed required, without users having to worry about it at all.

\begin{table}
  \centering
  \begin{tabular}{ll}
    \toprule
    Language   & Aliases      \\
    \midrule
    english    & american     \\
               & australian   \\
               & british      \\
               & canadian     \\
               & newzealand   \\
               & UKenglish    \\
               & USenglish    \\
    french     & acadian      \\
               & canadien     \\
               & francais     \\
               & frenchb      \\
    \bottomrule
  \end{tabular}
  \quad
  \begin{tabular}{ll}
    \toprule
    Language   & Aliases      \\
    \midrule
    german     & austrian     \\
               & germanb      \\
               & ngerman      \\
               & naustrian    \\
               & nswissgerman \\
               & swissgerman  \\
    portuguese & brazilian    \\
               & brazil       \\
               & portuges     \\
    spanish    &              \\
               &              \\
    \bottomrule
  \end{tabular}
  \caption{Declared languages and aliases}
  \zlabel{tab:languages-and-aliases}
\end{table}


But if the built-in dictionaries do not cover your language, or if you'd like
to adjust some of the default language-specific options, this can be done with
\cs{zcDeclareLanguage}, \cs{zcDeclareLanguageAlias}, and
\cs{zcLanguageSetup}.\footnote{Needless to say, if you'd like to contribute a
  dictionary or improve an existing one, that is much welcome at
  \url{https://github.com/gusbrs/zref-clever/issues}.}

\begin{function}{\zcDeclareLanguage}
  \begin{syntax}
    \cs{zcDeclareLanguage}\oarg{options}\marg{language}
  \end{syntax}
\end{function}
Declare a new language for use with \pkg{zref-clever}.  If \meta{language} has
already been declared, just warn.  The \meta{options} argument receives the
usual \texttt{key=value} list and recognizes three keys: \opt{declension},
\opt{gender}, and \opt{allcaps}.  \opt{declension} receives a coma separated
list of valid declension cases for \meta{language}.  The first element of the
list is considered to be the default case, both for the \opt{d} option in
\cs{zcref} and for the \opt{case} option in \cs{zcLanguageSetup}.  Similarly,
\opt{gender} receives a comma separated list of genders for \meta{language}.
The elements in this list are those which are recognized as valid for the
language for both the \opt{g} option in \cs{zcref} and the \opt{gender} option
in \cs{zcLanguageSetup}.  There is no default presumed in this case.  Finally,
\opt{allcaps} can be used with languages for which nouns must be always
capitalized for grammatical reasons.  For a language declared with the
\opt{allcaps} option, the \opt{cap} reference option (see \zcref{sec:options})
is disregarded, and \cs{zcref} always uses the capitalized type name forms.
This means that dictionaries for languages with such a trait can be halved in
size, and that user customization for them is simplified, only requiring the
capitalized name forms.  On the other hand, the non-capitalized \texttt{name-}
reference format options are rendered no-op for the language in question.
\zcref[S]{tab:language-options} presents an overview of the options in effect
for the languages declared by \pkg{zref-clever}.  \cs{zcDeclareLanguage} is
preamble only.

\begin{table}
  \centering
  \begin{tabular}{l>{\ttfamily}c>{\ttfamily}c>{\ttfamily}c}
    \toprule
    Language   & declension & gender & allcaps \\
    \midrule
    english    & --         & --     & --      \\
    french     & --         & f,m    & --      \\
    german     & N,A,D,G    & f,m,n  & yes     \\
    portuguese & --         & f,m    & --      \\
    spanish    & --         & f,m    & --      \\
    \bottomrule
  \end{tabular}
  \caption{Options for declared languages}
  \zlabel{tab:language-options}
\end{table}

\begin{function}{\zcDeclareLanguageAlias}
  \begin{syntax}
    \cs{zcDeclareLanguageAlias}\marg{language alias}\marg{aliased language}
  \end{syntax}
\end{function}
Declare \meta{language alias} to be an alias of \meta{aliased language}.
\meta{aliased language} must be already known to \pkg{zref-clever}.  Once set,
the \meta{language alias} is treated by \pkg{zref-clever} as completely
equivalent to the \meta{aliased language} for any language specification by
the user. \cs{zcDeclareLanguageAlias} is preamble only.

\begin{function}{\zcLanguageSetup}
  \begin{syntax}
    \cs{zcLanguageSetup}\marg{language}\marg{options}
  \end{syntax}
\end{function}
Sets language-specific reference format options for \meta{language} (see
\zcref{sec:ref-format-opts}), be they type-specific or not. \meta{language}
must be already known to \pkg{zref-clever}.  Besides reference format options,
\cs{zcLanguageSetup} knows three other keys: \opt{type}, \opt{case}, and
\opt{gender}.  The first two work like a ``switch'' affecting the options
\emph{following} it.  For example, if \texttt{type=foo} is given in
\meta{options} the options following it will be set as type-specific options
for reference type \texttt{foo}.  Similarly, after \texttt{case=X} (provided
\texttt{X} is a valid declension case for \meta{language}), the following
\texttt{[Nn]ame-} options will set values for the \texttt{X} declension case
(other reference format options are not affected by \opt{case}).  Before the
first occurrence of either \opt{type} or \opt{case} default values are set.
For \opt{case} this means the default declension case, which is the first
element of the list provided to the \opt{declension} option in
\cs{zcDeclareLanguage}.  For \opt{type} this means ``default translations'',
which are language-specific but not type-specific option values (see
\zcref{sec:ref-format-opts}).  An empty valued \texttt{type=} key can also
``unset'' the type.  The \opt{gender} key sets the gender of the current
\texttt{type} (provided the value it receives is one of the declared genders
for \meta{language}).  \cs{zcLanguageSetup} is preamble only.

A couple of examples to illustrate the syntax of \cs{zcLanguageSetup}:

\begin{zcexample}
\zcLanguageSetup{french}{
  type = section ,
    gender = f ,
    Name-sg = Section ,
    name-sg = section ,
    Name-pl = Sections ,
    name-pl = sections ,
}
\zcLanguageSetup{german}{
  type = section ,
    gender = m ,
    case = N ,
      Name-sg = Abschnitt ,
      Name-pl = Abschnitte ,
    case = A ,
      Name-sg = Abschnitt ,
      Name-pl = Abschnitte ,
    case = D ,
      Name-sg = Abschnitt ,
      Name-pl = Abschnitten ,
    case = G ,
      Name-sg = Abschnitts ,
      Name-pl = Abschnitte ,
}
\end{zcexample}

\bigskip{}

As already noted, \pkg{zref-clever} has some support for languages with
declension.  This means mainly the declension of \emph{nouns}, which is used
for the reference type names.  But some tools are also provided to support the
user in getting better results for the text surrounding a reference,
particularly for numbered and gendered articles, even if those don't have
their typeset output automated.

For reference type names, the declension cases for each language must be
declared with \cs{zcDeclareLanguage}, and the name reference format options
must be provided for each case, which is done for built-in dictionaries of
languages which have noun declension, and can be done by the user with
\cs{zcLanguageSetup}, as we've seen.  \pkg{zref-clever} does not try to guess
or infer the case though, you must tell it to \cs{zcref}.  And this is done by
means of the \opt{d} option (see \zcref{sec:options}).  So you may write
something like ``\texttt{nach den
  \cs{zcref}[d=D]\{sec:section-1,sec:section-2\}}'' to get ``nach den
Abschnitten 1 und 2''.  Or ``\texttt{trotz des
  \cs{zcref}[d=G]\{eq:theorem-1\}}'' to get ``trotz des Theorems 1''.

Regarding the text surrounding the reference -- the inflected article, the
passing preposition, etc.\ --, the issue is more delicate.  \pkg{zref-clever}
cannot and intends not to typeset those for you.  But, depending on the
language, it is true that the kind of automation provided by \pkg{zref-clever}
may betray your best efforts to get a proper surrounding text.  Multiple
labels passed to \cs{zcref} may result in singular type names, either because
the labels are of different types, or because they got compressed into a
single reference.  References comprised of multiple type blocks may have each
a name with a different gender.  Or, worse, \opt{tpairsep}, \opt{tpairsep},
and \opt{tlastsep} may not provide a general enough way to separate different
type blocks in your language altogether.  You may change something in your
document that causes a label to change its type, and hence the gender of the
type name.  A page reference to a couple of floats which were by chance on the
same page and all of a sudden no longer are.  And so on.

In this area, the approach taken by \pkg{zref-clever} is to identify some
typical situations in which your attention may be required in reviewing the
surrounding text, and signal it at compilation time.  Just like bad boxes, for
example.  This feature can be enabled by the \opt{nudge} option (which is
opt-in, see \zcref{sec:options}).  There are three ``nudges'' available for
this purpose which trigger messages at different events: \opt{multitype},
\opt{comptosing}, and \opt{gender}.  \opt{multitype} nudges when a reference
is comprised of multiple type blocks.  \opt{comptosing} when multiple labels
of the same type block have been compressed into a single one and, hence, the
type name used is singular.  Finally, \opt{gender} nudges when there is a
mismatch between the gender specified in \cs{zcref} with the \opt{g} option
and the gender of the type name, as stored in the dictionary or language
settings, for each type block.  Which nudges to use is configurable with the
option \opt{nudgeif}.  And, if you're sure of the results for a particular
\cs{zcref} call, you can always silence the nudges locally with the
\opt{nonudge} option.

The main reason to watch for multiple type references with the \opt{multitype}
nudge is that bundling together automatically a list of type blocks is less
smooth an operation than it is for a single reference type.  While it arguably
works reasonably well for English, even there it is not always flawless, and
depending on the language, results may range from ``poor style'' to outright
wrong.  A typical case would be of that of a language with inflected articles
and a reference with multiple types of different genders or numbers.  For
example, in French, with a standard ``\texttt{au \cs{zcref}\{cha:chapter-3,
  sec:section-3.1\}}'' we get ``au chapitre 3 et section 3.1'' which sounds
ugly, at best.  So we may be better off writing instead ``\texttt{au
  \cs{zcref}\{cha:chapter-3\} et à la \cs{zcref}\{sec:section-3.1\}}''.  Or
something else, of course.  But the general point is that, depending on
circumstances and on the language, the results of automating the grouping of
multiple reference types, as \pkg{zref-clever} is able to do, may leave things
to be desired for.  Hence it lets you know when one such case occurs, so that
you can review it for best results.

The case of the \opt{comptosing} and \opt{gender} nudges is more objective in
nature, they respectively signal mismatches of number and gender.  When a
reference is made with \cs{zcref} to a single label we are sure the type name
will be a singular form.  However, when \cs{zcref} receives multiple labels of
the same type, the type name will normally be a plural, but not necessarily
so, since the labels may be compressed into a single one (see the \opt{comp}
option in \zcref{sec:options}), in which case the singular is used.  The
compression of multiple labels into a single reference should be an exception
for default references, but not so for \opt{page} references, where it is easy
to conceive practical situations where it may occur.  Suppose, for example,
you have two contiguous floats in your document and make a page reference to
both of them.  Will they end up in the same page or not?  Maybe we know what
the current state is, but we cannot know what may happen as the document keeps
being edited.  As a consequence, we don't know whether that reference will end
up having a plural or a singular type name.  That given, the logic of the
\opt{comptosing} nudge is the following.  If we are giving multiple labels to
\cs{zcref}, we can \emph{presume} a plural type name, but we get a nudge in
case the compression of the labels results in a singular type name form.  If
one such compression did happen to one of your references, you can use a
singular article and then tell \cs{zcref} you did so with option \opt{sg}.
The effect of the \opt{sg} option is to inhibit the nudge when a compression
to singular occurs, but to do it instead when the compression \emph{ceases} to
occur, that is, if we get a plural type name again at some point.

The \opt{gender} nudge aims to guard against one particular situation:
possible changes of a reference's type.  This does not occur by reason of any
internal behavior of \pkg{zref-clever}, but it may be caused by changes in the
document.  You may wish to change one \texttt{theorem} into a
\texttt{proposition} and, if you're writing in French or Portuguese, for
example, that implies that the reference to it changes gender and the likely
preceding article will no longer pass to the reference.  The \opt{gender}
nudge requires that the gender of each type name and of each reference be
explicitly specified.  For the type names, this is done for the built-in
dictionaries of languages were this matters, and can be done with
\cs{zcLanguageSetup} as well.  For the references, that is the purpose of the
\opt{g} option.  When there is a mismatch between the two for any type block,
the nudge is triggered.  Of couse, this means that the gender markup has to be
supplied in the document at each reference.  And considering such type changes
may not be frequent for you, or considered not particularly problematic,
you'll have to balance if doing so is worth it.  Still, the feature is
available, and it's up to you.


\section{How-tos}

This section gathers some usage examples, or ``how-tos'', of cases which may
require some \pkg{zref-clever} setup, or usage adjustments, and each item is
set around a cross-reference ``task'' we'd like to perform with
\pkg{zref-clever}.


\subsection{Context sensitive references}

\zctask{Make cross-references which are sensitive to the relative position
  between the reference and the label being referred to, à la \pkg{varioref}.}

\pkg{varioref}'s \cs{vref} provides for varied references for three different
basic cases: when the reference and the label are on the same page, it
typesets a plain reference; when the reference and the label are in contiguous
pages (next, previous, or facing), it typesets the reference and a fixed
string corresponding to the relative position; when the reference and the
label are in different non-contiguous pages, it typesets a regular reference
and a page reference.  The same end result, but with a different user
interface concept can be achieved through \pkg{zref-clever}'s integration with
\pkg{zref-check}.  For this, the later must be loaded, which can be most
conveniently done with the \opt{check} option in the preamble.  With that in
place, the different cases could be covered by the following examples:

\begin{zcexample}
\zcref[check=thispage]{fig:1}
\zcref[check=nextpage,note={on the following page}]{fig:1}
\zcref[check=prevpage,note={on the preceding page}]{fig:1}
\zcref[check=facing,note={on the facing page}]{fig:1}
\zcref[check=pagegap]{fig:1} on \zcpageref{fig:1}
\end{zcexample}

And, similarly for the cases of \cs{vpageref}:

\begin{zcexample}
\zcref[noref,check=thispage,note={on this page}]{fig:1}
\zcref[noref,check=nextpage,note={on the following page}]{fig:1}
\zcref[noref,check=prevpage,note={on the preceding page}]{fig:1}
\zcref[noref,check=facing,note={on the facing page}]{fig:1}
\zcref[noref,check=pagegap]{fig:1} on \zcpageref{fig:1}
\end{zcexample}

Since \cs{zcref} can receive multiple labels, and make ranges out of them, it
is not difficult to extend these examples to the functionality of
\cs{vrefrange} and \cs{vpagerefrange}.

Evidently, this does not fully automate the typeset results, but it does
automate the checking that the reference context is the intended one.  If the
relation between the reference and the label does not correspond to the
specified one, a compilation warning is issued (according to the options given
to \pkg{zref-check}), so that the problem can be easily identified and
corrected.  See \pkg{zref-check}'s documentation for details, and further
available checks.


\subsection{\cs{newtheorem}}

Since \LaTeX{}'s \cs{newtheorem} allows users to create arbitrary numbered
environments, with respective arbitrary counters, the most \pkg{zref-clever}
can do in this regard is to provide some ``typical'' built-in reference types
to smooth user setup but, in the general case, some user setup may be indeed
required.  The examples below are equaly valid for \pkg{amsthm}'s
\cs{newtheorem} since, even it provides features beyond those available in the
kernel, its syntax and underlying relation with counters is pretty much the
same.  The same for \pkg{ntheorem}.  For \pkg{thmtools}' \cs{declaretheorem},
though some adjustments to the examples below may be required, the basic logic
is the same (there is no integration with the \opt{Refname}, \opt{refname},
and \opt{label} options, which are targeted to the standard reference system,
but you don't actually need them to get things working conveniently).


\subsubsection*{Simple case}

\zctask{Setup up a new theorem environment created with \cs{newtheorem} to be
  referred to with \cs{zcref}.  The theorem environment does not share its
  counter with other theorem environments, and one of \pkg{zref-clever}
  built-in reference types is adequate for my needs.}

Suppose you set a ``Lemma'' environment with:

\begin{zcexample}
\newtheorem{lemma}{Lemma}[section]
\end{zcexample}

In this case, since \pkg{zref-clever} provides a built-in \texttt{lemma} type
(for supported languages) and presumes the reference type to be the same name
as the counter, there is no need for setup, and things just work out of the
box.  So, you can go ahead with:

\begin{zchowto}[caption={\cs{newtheorem}, simple case}]
\documentclass{article}
\usepackage{zref-clever}
\newtheorem{lemma}{Lemma}[section]
\begin{document}
\section{Section 1}
\begin{lemma}\zlabel{lemma-1}
  A lemma.
\end{lemma}
\zcref{lemma-1}
\end{document}
\end{zchowto}

If, however, you had chosen an environment name which did not happen to
coincide with the built-in reference type, all you'd need to do is instruct
\pkg{zref-clever} to associate the counter for your environment to the desired
type with the \opt{countertype} option:

\begin{zchowto}[caption={\cs{newtheorem}, simple case}]
\documentclass{article}
\usepackage{zref-clever}
\zcsetup{countertype={lem=lemma}}
\newtheorem{lem}{Lemma}[section]
\begin{document}
\section{Section 1}
\begin{lem}\zlabel{lemma-1}
  A lemma.
\end{lem}
\zcref{lemma-1}
\end{document}
\end{zchowto}


\subsubsection*{Shared counter}

\zctask{Setup up two new theorem environments created with \cs{newtheorem} to
  be referred to with \cs{zcref}.  The theorem environments share the same
  counter, and the available \pkg{zref-clever} built-in reference types are
  adequate for my needs.}

In this case, we need to set the \opt{countertype} option in the appropriate
contexts, so that the labels of each environment get set with the expected
reference type.  As we've seen (at \zcref{sec:user-interface}), \cs{zcsetup}
has local effects, so it can be issued inside the respective environments for
the purpose.  Even better, we can leverage the kernel's new hook management
system and just set it for all occurrences with
\cs{AddToHook}\texttt{\{env/\meta{myenv}/begin\}}.

\begin{zchowto}[caption={\cs{newtheorem}, shared counter}]
\documentclass{article}
\usepackage{zref-clever}
\AddToHook{env/mytheorem/begin}{%
  \zcsetup{countertype={mytheorem=theorem}}}
\AddToHook{env/myproposition/begin}{%
  \zcsetup{countertype={mytheorem=proposition}}}
\newtheorem{mytheorem}{Theorem}[section]
\newtheorem{myproposition}[mytheorem]{Proposition}
\begin{document}
\section{Section 1}
\begin{mytheorem}\zlabel{theorem-1}
  A theorem.
\end{mytheorem}
\begin{myproposition}\zlabel{proposition-1}
  A proposition.
\end{myproposition}
\zcref{theorem-1, proposition-1}
\end{document}
\end{zchowto}


\subsubsection*{Custom type}

\zctask{Setup up a new theorem environment created with \cs{newtheorem} to be
  referred to with \cs{zcref}.  The theorem environment does not share its
  counter with other theorem environments, but none of \pkg{zref-clever}
  built-in reference types is adequate for my needs.}

In this case, we need to provide \pkg{zref-clever} with settings pertaining to
the custom reference type we'd like to use.  Unless you need to typeset your
cross-references in multiple languages, in which case you'd require
\cs{zcLanguageSetup}, the most convenient way to setup a reference type is
\cs{zcRefTypeSetup}.  In most cases, what we really need to provide for a
custom type are the ``type names'' and other reference format options can rely
on default translations already provided by the package (assuming the language
is supported).

\begin{zchowto}[caption={\cs{newtheorem}, custom type}]
\documentclass{article}
\usepackage{zref-clever}
\newtheorem{myconjecture}{Conjecture}[section]
\zcRefTypeSetup{myconjecture}{
  Name-sg = Conjecture ,
  name-sg = conjecture ,
  Name-pl = Conjectures ,
  name-pl = conjectures ,
}
\begin{document}
\section{Section 1}
\begin{myconjecture}\zlabel{conjecture-1}
  A conjecture.
\end{myconjecture}
\zcref{conjecture-1}
\end{document}
\end{zchowto}


\subsection{\pkg{newfloat}}

\zctask{Setup a new float environment created with \pkg{newfloat} to be
  referred to with \cs{zcref}.  None of \pkg{zref-clever} built-in reference
  types is adequate for my needs.}

The case here is pretty much the same as that for \cs{newtheorem} with a
custom type.  Hence, we need to setup a corresponding type, for which
providing the ``type names'' should normally suffice.  Note that, as far as
\pkg{zref-clever} is concerned, there's nothing specific to the \pkg{newfloat}
package in the setup, the same procedure can be used with \cls{memoir}'s
\cs{newfloat} command or with the \pkg{float}, \pkg{floatrow}, and
\pkg{trivfloat} packages.

\begin{zchowto}[caption={\pkg{newfloat}}]
\documentclass{article}
\usepackage{newfloat}
\DeclareFloatingEnvironment{diagram}
\usepackage{zref-clever}
\zcRefTypeSetup{diagram}{
  Name-sg = Diagram ,
  name-sg = diagram ,
  Name-pl = Diagrams ,
  name-pl = diagrams ,
}
\begin{document}
\section{Section 1}
\begin{diagram}
  A diagram.
  \caption{A diagram}
  \zlabel{diagram-1}
\end{diagram}
\zcref{diagram-1}
\end{document}
\end{zchowto}


\subsection{\pkg{amsmath}}

\zctask{Make references to \pkg{amsmath} display math environments with
  \cs{zcref}.}

Given how \pkg{amsmath}'s display math environments work, they need to handle
\cs{label} specially, and this support is quite hard-wired into the
environments, but it is not extended to \cs{zlabel}.  \pkg{zref-clever}'s
\opt{amsmath} compatibility module provides that a \cs{label} used inside
these environments set both a regular \cs{label} and a \cs{zlabel}, so that we
can refer to the equations with both referencing systems.  Note the use of
\cs{zlabel} for \env{subequations} though.  For more details, see the
description of the \opt{amsmath} compatibility module at
\zcref{sec:comp-modules}.

\begin{zchowto}[caption={\pkg{amsmath}},label={how:amsmath}]
\documentclass{article}
\usepackage{amsmath}
\usepackage{zref-clever}
\usepackage{hyperref}
\begin{document}
\section{Section 1}
\begin{equation}\label{eq:1}
  A^{(1)}_l =\begin{cases} n!,&\text{if }l =1\\
    0,&\text{otherwise}.\end{cases}
\end{equation}
\begin{equation*} \tag{foo}\label{eq:2}
  A^{(1)}_l =\begin{cases} n!,&\text{if }l =1\\
    0,&\text{otherwise}.\end{cases}
\end{equation*}
\begin{subequations}\zlabel{eq:3}
  \begin{align}
    A+B&=B+A\\
    C&=D+E\label{eq:3b}\\
    E&=F
  \end{align}
\end{subequations}
\zcref{eq:1, eq:2, eq:3, eq:3b}
\end{document}
\end{zchowto}


\subsection{\pkg{listings}}

\zctask{Make references to a \env{lstlisting} environment from the
  \pkg{listings} package with \cs{zcref}.}

Being \env{lstlisting} a verbatim environment, setting labels inside it
requires special treatment.  \pkg{zref-clever}'s \opt{listings} compatibility
module provides that a label given to the \opt{label} option gets set with
both a regular \cs{label} and a \cs{zlabel}, so that we can refer to it with
both referencing systems.  Setting labels for specific lines of the
environment can be done with \cs{zlabel} directly, subject to the same
escaping as for the standard \cs{label}.  For more details, see the
description of the \opt{listings} compatibility module at
\zcref{sec:comp-modules}.

\begin{zchowto}[caption={\pkg{listings}},label={how:listings},escapeinside=`']
\documentclass{article}
\usepackage{listings}
\usepackage{zref-clever}
\usepackage{hyperref}
\begin{document}
\section{Section 1}
\lstset{escapeinside={(*@}{@*)}, numbers=left, numberstyle=\tiny}
\begin{lstlisting}[caption={Useless code}, label=lst:1]
  for i:=maxint to 0 do
  begin
      { do nothing }(*@\zlabel{ln:1.1}@*)
  end;
\end{lstlisting}
\zcref{lst:1, ln:1.1}
\end{document}
\end{zchowto}


\subsection{\pkg{enumitem}}

\zctask{Setup a custom enumerate environment created with \pkg{enumitem} to be
  referred to with \cs{zcref}.}

Since the \texttt{enumerate} environment's counters are reset at each nesting
level, but not with the standard machinery, we have to inform
\pkg{zref-clever} of this resetting behavior with the \opt{counterresetby}
option.  Also, given the naming of the underlying counters is tied with the
environment's name and the level's number, we cannot really rely on an
implicit counter-type association, and have to set it explicitly with the
\opt{countertype} option.

\begin{zchowto}[caption={\pkg{enumitem}}]
\documentclass{article}
\usepackage{zref-clever}
\zcsetup{
  countertype = {
    myenumeratei   = item ,
    myenumerateii  = item ,
    myenumerateiii = item ,
    myenumerateiv  = item ,
  } ,
  counterresetby = {
    myenumerateii  = myenumeratei ,
    myenumerateiii = myenumerateii ,
    myenumerateiv  = myenumerateiii ,
  }
}
\usepackage{enumitem}
\newlist{myenumerate}{enumerate}{4}
\setlist[myenumerate,1]{label=(\arabic*)}
\setlist[myenumerate,2]{label=(\Roman*)}
\setlist[myenumerate,3]{label=(\Alph*)}
\setlist[myenumerate,4]{label=(\roman*)}
\begin{document}
\begin{myenumerate}
\item An item.\zlabel{item-1}
  \begin{myenumerate}
  \item An item.\zlabel{item-2}
    \begin{myenumerate}
    \item An item.\zlabel{item-3}
      \begin{myenumerate}
      \item An item.\zlabel{item-4}
      \end{myenumerate}
    \end{myenumerate}
  \end{myenumerate}
\end{myenumerate}
\zcref{item-1, item-2, item-3, item-4}
\end{document}
\end{zchowto}


\subsection{\pkg{zref-xr}}

\zctask{Make references to labels set in an external document with
  \cs{zcref}.}

\pkg{zref} itself offers this functionality with module \pkg{zref-xr}, and
\pkg{zref-clever} is prepared to make use of it.  Just a couple of details
have to be taken care of, for it to work as intended: i) \pkg{zref-clever}
must be loaded in both the main document and the external document, so that
the imported labels also contain the properties required by \pkg{zref-clever};
ii) since \cs{zexternaldocument} defines any properties it finds in the labels
from the external document when it imports them, it must be called after
\pkg{zref-clever} is loaded, otherwise the later will find its own internal
properties already defined when it does get loaded, and will justifiably
complain.  Note as well that the starred version of \cs{zexternaldocument*},
which imports the standard labels from the external document, is not
sufficient for \pkg{zref-clever}, since the imported labels will not contain
all the required properties.

Assuming here \file{documentA.tex} as the main file and \file{documentB.tex}
as the external one, and also assuming we just want to refer in ``\texttt{A}''
to the labels from ``\texttt{B}'', and not the contrary, a minimum setup would
be the following.


\begin{zchowto}[caption={\pkg{zref-xr}},escapeinside=`']
`\hspace*{-1em}\file{documentA.tex}:\vspace{1ex}'
\documentclass{article}
\usepackage{zref-clever}
\usepackage{zref-xr}
\zexternaldocument[B-]{documentB}
\usepackage{hyperref}
\begin{document}
\section{Section A1}
\zlabel{sec:section-a1}
\zcref{sec:section-a1, B-sec:section-b1}
\end{document}
`\vspace{-1ex}'
`\hspace*{-1em}\file{documentB.tex}:\vspace{1ex}'
\documentclass{article}
\usepackage{zref-clever}
\usepackage{hyperref}
\begin{document}
\section{Section B1}
\zlabel{sec:section-b1}
\end{document}
\end{zchowto}

\section{Compatibility}
\zlabel{sec:compatibility}

\subsection{Limitations}
\zlabel{sec:limitations}

Being based on \pkg{zref} entails one quite sizable advantage for
\pkg{zref-clever}: the extensible referencing system of the former allows
\pkg{zref-clever} to store and retrieve the information it needs to work
without having to redefine some core \LaTeX{} commands.  This alone makes for
reduced compatibility problems and less load order issues than the average
package in this functionality area.  On the other hand, being based on
\pkg{zref} also does impair the supported scope of \pkg{zref-clever}.  Not
because of any particular limitation of either, but because any class or
package which implements some special handling for reference labels
universally does so aiming at the standard referencing system, and whether
specific support for \pkg{zref} is included, or whether things work by
spillover of the particular technique employed, is not guaranteed.

The limitation here is less one of \pkg{zref-clever} than that of a potencial
lack of support for \pkg{zref} itself.  Broadly speaking, what
\pkg{zref-clever} does is setup \pkg{zref} so that its \cs{zref@newlabel}s
contains the information we need using \pkg{zref}'s API.  Once the \cs{zlabel}
is set correctly, there is little in the way of \pkg{zref-clever}, it can just
extract the label's information, again using \pkg{zref}'s API, and do its job.
Therefore, the problems that may arise are really in \emph{label setting}.

For \cs{zlabel} to be able to set a label with everything \pkg{zref-clever}
needs, some conditions must be fulfilled, most of which are pretty much the
same as that of a regular label, but not only.  As far as my experience goes,
the following label setting requirements can be potentially problematic and
are not necessarily granted for \cs{zlabel}:

\begin{enumerate}
\item One must be able to call \cs{zlabel}, directly or indirectly, at the
  appropriate scope/location so as to set the label.
\item When \cs{zlabel} is set, it must see a correct value of
  \cs{@currentcounter}.
\end{enumerate}

As to the first, it is not everywhere we technically can set a (z)label.  On
verbatim-like environments it depends on how they are defined and whether they
provide a proper place or option to do so.  But other places may be
problematic too, for example, \pkg{amsmath} display math environments also
handle \cs{label} specially and the same work is not done for \cs{zlabel}.

Regarding the second, a correctly set \cs{@currentcounter} is critical for the
task of \pkg{zref-clever}: the reference type will depend on that and,
consequently, sorting and compression as well, counter resetting behavior
information is also retrieved based on it, and so on.  Since the 2020-10-01
\LaTeX{} release, \cs{@currentcounter} is set by \cs{refstepcounter} alongside
\cs{@currentlabel} and, since the 2021-11-15 release, the support for
\cs{@currentcounter} has been further extended in the kernel.  Hence, as long
as kernel features are involved, or as long as \cs{refstepcounter} is the tool
used for the purpose of reference setting, \cs{zlabel} will tend to have all
information within its grasp at label setting time.  But that's not always the
case.  For this reason, \pkg{zref-clever} has the option \opt{currentcounter}
which at least allows for some viable work-arounds when the value of
\cs{@currentcounter} cannot be relied upon.  Whether we have a proper opening
to set it, depends on the case.  Still, \cs{refstepcounter} is ubiquitous
enough a tool that we can count on \cs{@currentcounter} most of the time.

All in all, most things work, but some things don't.  And if the later will
eventually work depends essentially on whether support for \pkg{zref} is
provided by the relevant packages and classes or not.  Or, failing that,
whether \pkg{zref-clever} is able to provide some specific support when a
reasonable way to do so is within reach.


\subsection{Compatibility modules}
\zlabel{sec:comp-modules}

This section gives a description of each compatibility module provided by
\pkg{zref-clever}.  These modules intend to smooth the interaction of \LaTeX{}
features, document classes, and packages with \pkg{zref-clever} and
\pkg{zref}, and they can be selectively or completely disabled with the option
\opt{nocompat} (see \zcref{sec:options}).  This set is not to be confused with
``the list of packages or classes supported by \pkg{zref-clever}''.  In most
circumstances, things should just work out of the box, and need no specific
handling.  These are just the ones for which some special treatment was
required.  Of course, this effort is bound to be incomplete (see
\zcref{sec:limitations}).

The purpose of outlining to some extend what the compatibility modules do is
twofold.  First, some of them require usage adjustments for label setting,
which must be somehow conveyed in this documentation.  Second, the kind and
degree of intervention in external code varies significantly for each module,
and since this is an area of potential friction, a minimum of information for
the users to judge whether they want to leave these modules enabled or not is
due.  For this reason, this is also a little technical, but for full details,
see the code documentation.

\bigskip{}

\DescribeOption{appendix} %
The \cs{appendix} command provided by many document classes is normally used
to change the behavior of the sectioning commands after that point.  Usually,
depending on the class, the changes that interest us involve using \cs{@Alph}
for numbering and \cs{appendixname} for chapter's names.  In sum, we'd like to
refer to the appendix sectioning commands as ``appendices'' rather than
``chapters'' or ``sections''.  Since the sectioning commands are the same as
before \cs{appendix}, and so are their underlying counters, we must configure
the counter type of the sectioning counters to \texttt{appendix}.  And this is
what this compatibility module does, and it uses a \pkg{ltcmdhooks} hook on
\cs{appendix} for the purpose.  Hence, this module applies to any document
class or package which provides that command.

\DescribeOption{appendices} %
This module implements support for the \env{appendices} and
\env{subappendices} environments provided by the \pkg{appendix} package, and
also by \cls{memoir}.  The task is the same as for the \texttt{appendix}
module: set proper counter types for the sectioning counters.  This module
employs environment hooks to \env{appendices} and \env{subappendices} and a
command hook to \cs{appendix} for the purpose.

\DescribeOption{memoir} %
The \cls{memoir} class implements several features with one or another
implication for cross-referencing, usually bearing just the standard
referencing system in mind, and related mainly to captions, subfloats, and
notes.  This compatibility module tries to adjust \pkg{zref-clever} to these
features with support for the following: i) set counter types for counters
\texttt{subfigure}, \texttt{subtable}, and \texttt{poemline} (used in the
\env{verse} environment); ii) configure resetting behavior
(\opt{counterresetby} option) for \texttt{subfigure} and \texttt{subtable}
counters; iii) provide that the \meta{label} arguments to environments
\env{sidecaption} and \env{sidecontcaption} and commands \cs{bitwonumcaption},
\cs{bionenumcaption}, and \cs{bicaption} \emph{also} set a \cs{zlabel} of the
same name; iv) provide the \pkg{zref} property ``\texttt{subcaption}'' so that
we can refer to, for example, \texttt{\cs{zcref}[ref=subcaption]\{subcap-1\}}
to emulate the functionality of \cls{memoir}'s \cs{subcaptionref}; v) provide
that \cs{footnote}, \cs{verbfootnote}, \cs{sidefootnote}, and \cs{pagenote}
get a proper \opt{currentcounter} set; and v) set counter types for counters
\texttt{sidefootnote} and \texttt{pagenote}.  Naturally, the sheer number of
features that required some specific support implies that some gymnastics were
needed here.  But the most sensitive changes are: i) a local redefinition of
\cs{label} inside the environments \env{sidecaption} and \env{sidecontcaption}
and the commands \cs{bitwonumcaption}, \cs{bionenumcaption}, and
\cs{bicaption}; and ii) the use of \pkg{ltcmdhooks} command hooks on
\cs{bitwonumcaption}, \cs{bionenumcaption}, \cs{bicaption},
\cs{@memsubcaption}, \cs{@makefntext}, and \cs{@makesidefntext}.

\DescribeOption{KOMA} %
The \cls{KOMA-Script} document classes are much more strict than \cls{memoir}
in using standard mechanisms for cross-reference related features, so that
very little adjustment is needed here.  Only the environments
\env{captionbeside} and \env{captionofbeside} require special treatment.  And,
though they do use \cs{refstepcounter} under the hood, since they are
environments, we don't get to see reference variables outside them.
\cs{@currentlabel} is smuggled out of the group, but not \cs{@currentcounter},
so we must arrange for the later to have a correct value outside the caption
environments too.  Environment hooks are used for the purpose, essentially
setting \cs{@currentcounter} to \cs{@captype}, which would be the value the
captioning infrastructure would set for it.

\DescribeOption{amsmath} %
\pkg{amsmath}'s display math environments have their contents processed twice,
once for measuring and the second does the final typesetting.  Hence,
\pkg{amsmath} needs to handle \cs{label} specially inside these environments,
otherwise we'd have duplicate labels all around, and indeed it does redefine
\cs{label} locally inside them.  Alas, the same treatment is not granted to
\cs{zlabel}.  However, \cs{label} is set basically to \emph{store} the value
of the argument inside the environments, and its global meaning is kept in
\cs{ltx@label} which is called at the appropriate time to actually set the
label.  So, what \pkg{zref-clever} does is redefine \cs{ltx@label} to set
\texttt{both} a regular \cs{label} and a \cs{zlabel} for the same \meta{label}
(which does not generate a duplicate label problem since the referencing
systems are independent).  Therefore, you must use \cs{label} (not
\cs{zlabel}) inside \pkg{amsmath}'s display math environments, and this
compatibility module arranges that you can also refer to that label with
\pkg{zref} and, thus, with \cs{zcref} as well.  The following environments are
subject to this usage restriction: \env{equation}, \env{align}, \env{alignat},
\env{flalign}, \env{xalignat}, \env{gather}, \env{multline}, and their
respective starred versions.  In particular, the same is not the case for the
\env{subequations} environment, inside which \cs{zlabel} works as usual (to
refer to the main equation number, that is, right after
\texttt{\cs{begin}\{subequations\}}).  See the \zcref{how:amsmath} for an
usage example.  The module also ensures proper \opt{currentcounter} values are
in place for the display math environments, for which it uses environment
hooks, and sets the font of equation references to \cs{upshape}, following
\pkg{amsmath}'s \cs{eqref}.  Note, however, that \pkg{zref-clever} is not the
only package to redefine \cs{ltx@label}, and compatibility problems may arise
if this module is used with such packages or with document classes that do the
same.  In case of trouble, you can load \pkg{zref-clever} with option
\texttt{nocompat=amsmath} and either use the standard referencing system's
facilities to refer to \pkg{amsmath}'s equations or check the code
documentation for the technique used for this (which is pretty standard) and
adapt it to your case.  Given that any trouble that may arise here is one of
the proper ``timing'' of the redefinition, it should not be particularly
complicated to make such adjustments.

\DescribeOption{mathtools} %
\pkg{mathtools} has a feature to show the numbers only for those equations
actually referenced (with \cs{eqref} or \cs{refeq}), which is enabled by the
\opt{showonlyrefs} option.  This compatibility module adds support for this
feature, such that equation references made with \cs{zcref} also get marked as
``referenced'' for \pkg{mathtools}, when the option is active, of course.  The
module uses a couple of \pkg{mathtools} functions, but does not need to
redefine or hook into anything, everything is handled on \pkg{zref-clever}'s
side.

\DescribeOption{breqn} %
This compatibility module only sets proper \opt{currentcounter} values for the
environments \env{dgroup}, \env{dmath}, \env{dseries}, and \env{darray}, and
uses environment hooks for the purpose.  Note that these environments offer a
\opt{label} option for label setting, but implements it in a way that is
somewhat tricky to grab for our purposes, so we don't do it.  However,
\pkg{breqn}'s documentation says the following about the use of \cs{label}
inside its environments: \textquote{Use of the normal \cs{label} command
  instead of the \opt{label} option works, I think, most of the time
  (untested)}.  My light testing suggests the same is true for \cs{zlabel},
which can then be used directly in these environments.  But the ``second
class'' status for this use is the one granted by \pkg{breqn}, there's not
much we can do here.  If you have any trouble with this, you may wish to check
\zcref{wkrnd:breqn}.

\DescribeOption{listings} %
Being \env{lstlisting}s environments what they are, one cannot simply place a
label inside them without special treatment.  \pkg{listings} arranges to this
by providing a \opt{label} option for setting a label for the whole
environment, and a properly escaped label command inside the environment can
be used to refer to the line number.  While the later can also be used to set
a \cs{zlabel} to make line number references, the \opt{label} option is
catered to the standard labels exclusively.  Hence, this compatibility module
uses the same label name -- which luckily and atypically is stored in a
variable -- and sets a \cs{zlabel} as well.  This is done by using
\pkg{listings}' \texttt{PreInit} hook, se we don't have to redefine or tamper
with anything for the purpose.  Besides this, the module also sets appropriate
\opt{countertype}, \opt{counterresetby} and \opt{currentcounter} values for
the \pkg{listings}' counters: \texttt{lstlisting} and \texttt{lstnumber}. See
the \zcref{how:listings} for an usage example.

\DescribeOption{enumitem} %
\LaTeX{}'s \env{enumerate} environment requires some special treatment from
\pkg{zref-clever}, since its resetting behavior is not stored in the standard
way, and the counters' names, given they are numbered by level, do not map to
the reference type naturally.  This is done by default for the up to four
levels of nested \env{enumerate} environments the kernel offers.
\pkg{enumitem}, though, allows one to increase this maximum list depth for
\env{enumerate} and, if this is done, setup for these deeper nesting levels
have also to be taken care of, and that's what this compatibility module does.
All settings here are internal to \pkg{zref-clever}, no hooks or redefinitions
are needed, we just check the existing pertinent counters at
\texttt{begindocument}, and supply settings for them.  Of course, this means
that only \pkg{enumitem}'s settings done in the preamble will be visible to
the module and provided for.

\DescribeOption{subcaption} %
This compatibility module sets appropriate \opt{countertype} and
\opt{counterresetby} for the \texttt{subfigure} and \texttt{subtable}
counters, and provides the \pkg{zref} property ``\texttt{subref}'' so that we
can refer to, for example, \texttt{\cs{zcref}[ref=subref]\{\meta{label}\}} to
emulate the functionality of \cls{subcaption}'s \cs{subref}.  The later
feature uses the \cs{caption@subtypehook} provided by \pkg{caption} to locally
add the \texttt{subref} property to \pkg{zref}'s main property list.

\DescribeOption{subfig} %
This module just sets appropriate \opt{countertype} and \opt{counterresetby}
for the \texttt{subfigure} and \texttt{subtable} counters.


\subsection{Work-arounds}

\marginpar{\raggedleft\raisebox{-1.5ex}{\dbend}}As should be clear by now, the
use of \pkg{zref}'s \cs{zlabel} and thus of \pkg{zref-clever} may occasionally
require some adjustments, since it does not enjoy the universal support the
standard referencing system does.  The compatibility modules presented in
\zcref{sec:comp-modules} go a long way in ensuring the user has to worry very
little about it, but they cannot hopefully go all the way.  Not only because
this kind of support will never be exhaustive, but also since, sometimes,
given the way certain features are implemented by packages or document
classes, there may not be a reasonable way to provide this support, from our
side.  But, still, most of the time, it is still ``viable'' to get there, if
one really wishes to do so.  So, this section keeps track of some known
recipes, which I don't think belong in \pkg{zref-clever} itself, but which you
may choose to use.  Note that this list is intended to spare users from having
to reinvent the wheel every time someone needs something of the sort, but from
\pkg{zref-clever}'s perspective, their status is ``not supported''.


\subsection*{\pkg{breqn}}

As mentioned in \opt{breqn}'s compatibility module (\zcref{sec:comp-modules}),
\pkg{breqn}'s math environments \env{dgroup}, \env{dmath}, \env{dseries}, and
\env{darray} offer a \opt{label} option (plus \opt{labelprefix}) for the
purpose of label setting.  Setting a \cs{zlabel} alongside with a regular
\cs{label} based on that option requires redefining some of \pkg{breqn}
internals.  Also, \pkg{breqn} does not use \cs{refstepcounter} to increment
the equation counters and, as a result, fails to set \pkg{hyperref} anchors
for the equations (thus affecting standard labels too).  The example below
also provides to that.\footnote{The later work-around thanks to Heiko
  Oberdiek, at \url{https://tex.stackexchange.com/a/241150}.}


\begin{zcworkaround}[caption={\pkg{breqn}},label={wkrnd:breqn}]
\documentclass{article}
\usepackage{zref-clever}
\usepackage{breqn}
\makeatletter
\define@key{breqn}{label}{%
  \edef\next@label{%
    \noexpand\label{\next@label@pre#1}%
    \noexpand\zlabel{\next@label@pre#1}}%
  \let\next@label@pre\@empty}
\makeatother
\usepackage{hyperref}
\usepackage{etoolbox}
\makeatletter
\patchcmd\eq@setnumber{\stepcounter}{\refstepcounter}{}{%
  \errmessage{Patching \noexpand\eq@setnumber failed}}
\makeatother
\begin{document}
\section{Section 1}
\begin{dmath}[label={eq:1}]
  f(x)=\frac{1}{x} \condition{for $x\neq 0$}
\end{dmath}
\begin{dmath}[labelprefix={eq:},label={2}]
  H_2^2 = x_1^2 + x_1 x_2 + x_2^2 - q_1 - q_2
\end{dmath}
\zcref{eq:1, eq:2}
\end{document}
\end{zcworkaround}

Of course, you can always adapt things to your needs and, e.g., make the
\opt{label} option set just \cs{zlabel} instead of both labels, or create a
separate \opt{zlabel} option.


\section{Acknowledgments}

\pkg{zref-clever} would not be possible without other people's previous work
and help.

Heiko Oberdiek's \pkg{zref}, now maintained by the Oberdiek Package Support
Group, is the underlying infrastructure of this package.  The potential of its
basic concept and the solid implementation were certainly among the reasons
I've chosen to venture into these waters, to start with.  And I believe they
will remain one of the main assets of \pkg{zref-clever} as it matures.

The name of the package makes no secret that a major inspiration for the kind
of ``feel'' I strove to achieve has been Toby Cubitt's \pkg{cleveref}.
Indeed, I have been an user of \pkg{cleveref} for several years, and a happy
one at that.  But the role \pkg{cleveref} played in the development of
\pkg{zref-clever} extends beyond the visible influence in the design of user
facing functionality.  Some technical solutions and, specially, the handling
of support for other packages were a valuable reference.  Hence, the
accumulated experience of \pkg{cleveref} allowed for \pkg{zref-clever} to
start on a more solid foundation than would otherwise be the case.

The long term efforts of the \LaTeX3 \cs{Team} around \pkg{expl3} and
\pkg{xparse} have also left their marks in this package.  By implementing
powerful tools and smoothing several regular programming tasks, they have
certainly reduced my entry barrier to \LaTeX{} programming and enabled me to
develop this package with a significantly reduced effort.  And, given the
constraints of my abilities, the result is no doubt much better than it would
be in their absence.

Besides these more general acknowledgments, a number of people have
contributed to \pkg{zref-clever}, whether they are aware of it or not.
Suggestions, ideas, solutions to problems, bug reports or even encouragement
were generously provided by: Ulrike Fischer, Frank Mittelbach, Phelype
Oleinik, Jonathan P.\ Spratte, Enrico Gregorio, Steven B.\ Segletes,
\texttt{@samcarter}, Alan Munn, Florent Rougon, and David Carlisle.

If I have inadvertently left anyone off the list I apologize, and please let
me know, so that I can correct the oversight.

Thank you all very much!


\section{Change history}

A change log with relevant changes for each version, eventual upgrade
instructions, and upcoming changes, is maintained in the package's repository,
at \url{https://github.com/gusbrs/zref-clever/blob/main/CHANGELOG.md}.  An
archive of historical versions of the package is also kept at
\url{https://github.com/gusbrs/zref-clever/releases}.

\end{document}