summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/source/latex/showlabels/showlabels.dtx
blob: ef6f107f608d4cd35bc04c27b6a86c82e0358f3d (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
% \iffalse % meta-comment
%
%% This is the showlabels package
%%
%%%% Copyright 1999, 2001-09, 2013-21, Norman Gray
%%
%% This work may be distributed and/or modified under the
%% conditions of the LaTeX Project Public Licence, either version 1.3c
%% of this licence or (at your option) any later version.
%% The latest version of this licence is in
%%   http://www.latex-project.org/lppl.txt
%% and version 1.3c or later is part of all distributions of LaTeX
%% version 2005/12/01 or later.
%%
%% This work has the LPPL maintenance status `maintained'.
%%
%% The Current Maintainer of this work is Norman Gray <https://nxg.me.uk>
%%
%% This work consists of the files showlabels.dtx and showlabels.ins,
%% and the derived file showlabels.sty.

%%%% File: showlabels.dtx
%%%% Source: 1f8b1fcbe557, 2021-10-27T16:06:03+01:00

% This is revision 1f8b1fcbe557, 2021-10-27T16:06:03+01:00.
%<+package>\NeedsTeXFormat{LaTeX2e}
%<+package>\ProvidesPackage{showlabels}[2021/10/27\space v1.9.1]
%<+package>\typeout{Package: `showlabels' v1.9.1\space<2021/10/27>}
%
%<*driver>
\documentclass{ltxdoc}
\EnableCrossrefs
%    \end{macrocode}
%    Some commonly used abbreviations for option names, filenames,
% counters and packages.
%    \begin{macrocode}
\newcommand\Lopt[1]{\textsf{#1}}		% package options
\newcommand\file[1]{\texttt{#1}}		% filename
%\newcommand\Lcount[1]{\textsl{\small#1}}
\newcommand\Lenv[1]{\textsl{\{#1\}}}
\newcommand\Lpackage[1]{\textsf{\{#1\}}}		% packages
%% \url macro (url.sty does this better, but we don't want extra dependencies)
\def\setpathdots{\discretionary{.}{}{.}}
\def\setpathslash{\discretionary{/}{}{/}}
{\catcode`\.=\active
 \catcode`\/=\active
  \gdef\pathcats{%
    \catcode`\%=12      \catcode`\~=12
    \catcode`\.=\active  \let.\setpathdots
    \catcode`\/=\active \let/\setpathslash
    \catcode`\#=12      \catcode`\_=12}%
    }
\def\setpath#1{\ttfamily <\nobreak #1\nobreak>\endgroup}
\def\url{\begingroup\pathcats\setpath}
\begin{document}
% \OnlyDescription
\DocInput{showlabels.dtx}
\PrintIndex
\end{document}
%</driver>
%
% \fi
%
%
% \title{The \texttt{showlabels} package}
% \author{Norman Gray\\|gray@nxg.name|}
% \date{Version 1.9.1, 2021 October 27}
%
% \maketitle
%
% This package helps you keep track of all the labels you define, by
% putting the name of new labels into the margin whenever the
% |\label| command is used.
%
% You can do the same thing for other commands (see below).
% The only one for which this is \emph{obviously} useful is the
% |\cite| command, but it is also reasonable to do it with, for example,
% the |\ref| or |\begin| commands.
%
% Invoke this package with the command |\usepackage{showlabels}| in
% the preamble, and you may give the following options:
% \begin{quotation}
% \begin{tabular}{lp{25em}}
%    \Lopt{outer}    & [default] all notes are placed in the text's outer
%                      margin\\
%    \Lopt{inner}    & \dots inner margin\\
%    \Lopt{left}     & \dots left margin\\
%    \Lopt{right}    & \dots right margin\\
%    \Lopt{marginal} & [default] put notes in the margin\\
%    \Lopt{inline}   & put notes inline, as much as possible, and ignore
%                      any of the margin-placement options above \\
%    \Lopt{nolabel}  & do not insert a marginal note for |\label| commands
%                      (see command |\showlabels| below)\\
%    \Lopt{draft}    & [default] does nothing, partner of\dots\\
%    \Lopt{final}    & turns off all the package's functionality
% \end{tabular}
% \end{quotation}
% If you don't use the \Lopt{twoside} option,
% then all pages are `right-hand' pages, and the `outer margin' is the
% right hand one.
%
% The package will also work in the presence of the \Lopt{twocolumn}
% option.  In this case, the options \Lopt{inner}, \Lopt{outer},
% \Lopt{left} and \Lopt{right} will be ignored, and the label will be
% placed in the nearer margin.
%
% Finally, we have the options \Lopt{final} and \Lopt{draft}.  The option
% \Lopt{final} turns off all the functionality of this package.  This
% is included so that if that
% option is given globally in the |\documentclass| declaration then this
% package does respect it.  The \Lopt{draft} option does nothing, and therefore
% simply continues the default behaviour of this package; it is here
% to partner the \Lopt{final} option.
%
% \DescribeMacro{\showlabels}
% If you wish the package to do its magic with another command |\foo|
% which takes at least one argument (for example |\cite|),
% then give the command |\showlabels{foo}|.
% The default behaviour of the package is to give the command
% |\showlabels{label}| internally; if you don't want this to happen --
% perhaps because you \emph{only} want |\cite| commands highlighted --
% then give the option \Lopt{nolabel} to the |\usepackage| command:
% |\usepackage[nolabel]{showlabels}|.
%
% You can call |\showlabels{foo}| with commands which have starred
% forms, |\foo*{arg}|, or optional arguments, |\foo[opt]{arg}|.  A
% technical wrinkle is that, in each case, the |{arg}| is read with
% all of its characters being catcode `other'; I~can't think of a
% realistic case where this is a problem, since the commands typically
% given to |\showlabels| will almost certainly do something equivalent
% to this anyway, but it is a mild change from the default behaviour
% of the command |\foo|.
%
% You can do this |\showlabels| step even with commands that you
% invoke only implicitly.  If, for example, you want to label each of the
% entries in your bibliography, then |\showlabels{bibitem}|
% will do this for each of the items that appear in the
% \Lenv{thebibliography} environment, whether it is writen by you or
% by \BibTeX\ (if you use the `biblatex' package, then the
% corresponding command would be
% |\makeatletter\showlabels{blx@bibitem}\makeatother|, but notice that
% this is in principle an undocumented internal of the `biblatex'
% package, so may change).
%
% By default, the package displays labels in the margin of the
% document, but as an alternative, labels can be kept inline as much
% as possible; this is much more legible when there are multiple
% labels on a single line.  To select this, give the option
% \Lopt{inline}, and to select the default behaviour, use
% \Lopt{marginal}.
%
% \DescribeMacro{\showlabelsinline}
% It is sometimes convenient (for example when a document encounters a
% situation which this package mishandles) to force inline labels
% temporarily, within a block or environment.  Use the
% |\showlabelsinline| macro to do that.
%
% \section{Formatting}
%
% If you want to change the font the labels appear in, redefine the
% |\showlabelfont| command, which by default expands to
% |\small\ttfamily|.  For example, to have labels in a slanted font,
% and green, you could include the definition
% \begin{quote}
% |\renewcommand{\showlabelfont}{\small\slshape\color{green}}|
% \end{quote}
% in the preamble of your document (as long as you have loaded the
% \Lpackage{color} package, of course).
%
% Alternatively, the |\showlabels| command has an optional argument containing
% formatting commands, which allows you to format |\cite| labels, for
% example, differently from |\label|.  Thus:
% \begin{quote}
% |\showlabels[\color{green}]{cite}|
% \end{quote}
% The optional formatting command can be either a font-changing
% command, as illustrated here, \emph{or} a command which takes a
% single argument, such as
% \begin{quote}
% |\showlabels[\fbox]{cite}|
% \end{quote}
%
% If, finally, you want complete control over the labels, you can
% instead override |\showlabelsetlabel|, which initially expands to
% just |\showlabelfont #1|.  You can use this mechanism to get a
% variety of effects.  For example, if you say
% \begin{quote}
% |\usepackage{showlabels,rotating}|\\
% |\renewcommand{\showlabelsetlabel}[1]|\\
% \null\qquad |{\begin{turn}{60}\showlabelfont #1\end{turn}}|\\
% \end{quote}
% then you end up with your labels at a jaunty angle in the margin.
%
% The command |\showlabeltype| will expand to the current label type
% (ie, `label' or `cite', etc), so it would be possible for
% |\showlabelsetlabel| to conditionalise on that, if you felt that
% were necessary.\footnote{The support for an one-argument command in
% $\backslash$\texttt{showlabels}, and the presence of the
% $\backslash$\texttt{showlabeltype} macro, were added in version 1.9.}
%
% If instead you want to adjust how inline markings are displayed, you
% can change the definition of the
% |\showlabelrefline| rule from its default.
% For example, defining this to be
% \begin{quote}
% |\color{red}\hrule width 0.1em height 1.5ex depth 0pt |
% \end{quote}
% produces a fattish red line, and defining it to be
% \begin{quote}
% |\hrule width 0pt height 1.5ex depth 0pt|
% \end{quote}
% suppresses the line but still positions the text between the lines.
%
% \section{Compatibility with other packages, and other problems}
%
% The \Lpackage{showlabels} package works by redefining the |\label|
% command, along with a few internal \LaTeX\ commands.  All the other commands it
% defines are `hidden' by prefixing them with `\texttt{SL@}', with
% the exception of the user commands |\showlabelfont| and
% |\showlabelsetlabel|.  Each of
% the three redefined commands carefully includes its previous
% definition.  The \Lpackage{showlabels} package should therefore come
% \emph{last} of the packages you include using |\usepackage|.
%
% In version 1.1, the package was modified to conform to the slightly
% different mechanism that \texttt{amsmath} uses to produce equation
% numbers.  Do note that the
% |\usepackage{showlabels}| command \emph{must} appear after the
% |\usepackage{amsmath}| if it is to detect that you are using the
% \Lpackage{amsmath} package\footnote{Note that AMS-\LaTeX\ and the
% \texttt{amstex} package have been declared `obsolete' in favour of
% the \texttt{amsmath} package.  This package now claims conformance
% with the \texttt{amsmath} package alone, though it will probably
% work with older versions in fact.}.
%
% In version 1.3e, the package became compatible with the
% \Lpackage{hyperref} package in particular, and in general with other
% packages which themselves modify the |\label| command.  This will
% work, however, only if the \Lpackage{showlabels} package is loaded
% after other packages which do this.  Notwithstanding Sebastian
% Rahtz's excellent general advice on this, \Lpackage{showlabels} should
% be loaded after \Lpackage{hyperref}.
%
% In version 1.7, the package became compatible with the
% equation-numbering mechanism of the \Lpackage{IEEEtrantools}
% package.  As with \Lpackage{amsmath}, this involves a certain amount
% of special-casing.
%
% For reasonably obvious reasons, this package will not work at all
% well with the \Lpackage{multicol} package, and for possibly less obvious
% reasons, it won't work with the \Lopt{leqno} option either (at some point
% it should be modified to at least recognise and warn of the conflict in
% either case, though it's not obvious to me how to do that).  The
% package \emph{should} now work with \Lpackage{wrapfig}, though I'm not
% sure that I've exhausted that package's various clevernesses, and
% there might be some spacing and layout bugs which manifest
% themselves in that context.  Please report them; in the mean time,
% using option \Lopt{inline} should act as a workaround for any that
% appear.
%
% When labels appear in the margins, they sometimes appear on the
% `wrong' side in \Lopt{twoside} mode.  This is a fairly inevitable
% side-effect of the way that \TeX\ builds pages, and a specific
% symptom of the general problem described in
% \url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=oddpage}.
% As that answer suggests, there are bear-traps involved in the
% standard solutions.  Now, showlabels is (a)~permanently teetering
% on the edge of clashing with everything else that messes around with
% labels, and (b)~a draft-only package rather than anything that
% would appear in a final document.  (a)~means that I'm rather nervous
% about putting too much cleverness in there, and incidentally shy of
% putting any dependencies on other packages; (b)~means that I feel it
% doesn't really matter enough to be worth removing robustness.  So
% I'm afraid I don't plan to change this, and I simply put up with the
% occasional slip.  Again the \Lopt{inline} option is a possible
% workaround.
%
% The package might still work with \LaTeX2.09, but that's neither
% supported, nor even still tested.
%
% This software is copyright, 1999, 2001-09, 2013-21 Norman Gray.
% It is released under the terms of the \LaTeX\ Project Public Licence.
% See the copyright declaration at the top of file \texttt{showlabels.dtx},
% and the file \texttt{lppl.txt}, for the licence conditions.
%
% The canonical home page of the package is
% \url{https://purl.org/nxg/dist/showlabels}, and it is on CTAN at
% \url{https://www.ctan.org/pkg/showlabels}.  The source is in
% a repository online: \url{https://hg.sr.ht/~nxg/showlabels}.
%
% \section{Other packages}
%
% The \Lpackage{showlabels} package has a large overlap in
% functionality with David Carlisle's \Lpackage{showkeys}, although
% the latter will only handle |\label| and |\cite| keys.  If
% \Lpackage{showlabels} fails in some particular situation, you might
% want to try using \Lpackage{showkeys}, but please do mention the
% problem, typically by email to me.
%
% \section{History and Credits}
%
% I've received bug reports, fixes, or implementable suggestions from many
% people, including
%   Andreas Balser,
%   bartgol (on Stackexchange),
%   Francesco Biccari,
%   Francis M. C. Ching,
%   Sven de Vries,
%   A L Dukeman,
%   Michael Friendly,
%   Guillermo Garza,
%   Tino G\"ortem\"oller,
%   Lester L. Helms,
%   Boris Kheyfets,
%   Hagen Kleinert,
%   David R. Leal Valmana,
%   Olivier Michel,
%   Enno Nagel,
%   Sungmo Park,
%   Ignacy Sawicki,
%   Andrei Shelankov,
%   Patrick Sibille,
%   `Stirling' (on Stackexchange),
%   Mariano Su\'arez-Alvarez,
%   Ji\v ri Vesely,
%   Elmar Walhorn,
%   Alex Watson,
%   Ben William Carabelli,
%   Roland Winkler.
% Many thanks to all.  If I've missed your name out of this list
% (or indeed if I've alphabetised you incorrectly),
% please accept my apologies, and do let me know.
%
% The package was originally released by me on 1991 September 21, under the name
% \texttt{labels.sty}.
% On 1992 January 29, Darrel Hankerson
% \url{hank@ducvax.auburn.edu}, made the update to NFSS, and
% changed the name to `showlabel.sty'.
%
% \subsection{Release notes}
% \begingroup
% \iffalse the following are variously unsatisfactory
%   \def~{\texttt{\textasciitilde}}
%   \def~{$\sim$}
% \fi
% \catcode`\~=12
% \iffalse @RELEASENOTES@ \fi
% \begin{description}\item[1.9.1, 2021 October 27]\relax Commands with optional arguments, such as
%       |\bibitem[P\'olya]{polya_54}| are now handled with the
%       correct catcodes.
%       Fixes issue 1\footnote{\url{https://todo.sr.ht/~nxg/showlabels/1}}
%       (new sequencing for issues).
%       Thanks to Michael Levitin for the report here.\par \item[1.9, 2021 October 9]\relax   \P\thinspace Robustness fix: macros in arguments are now handled, so that
%   (after |\showlabel{index}|),
%   |\index{Poincar\'e}| doesn't cause an error.  \P\thinspace The |\showlabel[optarg]{command}| optional argument
%   can now take a one-argument command.  \P\thinspace The macro |\showlabeltype| expands to the current
%   label type, for possible use in |\showlabelsetlabel|.  \P\thinspace The code has moved from Bitbucket to
%   Sourcehut\footnote{\url{https://sourcehut.org}}: the new repository is
%   https://hg.sr.ht/~nxg/showlabels\footnote{\url{https://hg.sr.ht/~nxg/showlabels}}.
%   The issues links in the list below are therefore broken.\par\item[1.8, 2016 June 9]\relax The |ntheorem| package exposed an apparently
% long-standing incompleteness in the handling of |amsmath|
% documents.
% Fixes issue 9\footnote{\url{https://bitbucket.org/nxg/showlabels/issues/9/}}.\par \item[1.7, 2015 December 8]\relax Release v1.7.\par \item[1.7b2, 2015 December 7]\relax Make the combination of amsmath and [inline] mode work
% (fixes issue 8\footnote{\url{https://bitbucket.org/nxg/showlabels/issue/8/}}
% – thanks to A L Dukeman for the report;
% what is it about showlabels and 6 December?!).\par \item[1.7b1, 2014 December 6]\relax This is a much-delayed bugfix release (by coincidence
% \emph{exactly} a year after the previous release!).\par   \P\thinspace Give |\showlabels| an optional formatting argument
% (implements issue 1\footnote{\url{https://bitbucket.org/nxg/showlabels/issue/1/}}
% – thanks to Francesco Biccari for the suggestion).  \P\thinspace Special-case the IEEEtrantools package
% (fixes issue 2\footnote{\url{https://bitbucket.org/nxg/showlabels/issue/2/}}
% – thanks to Boris Kheyfets for the report and test case, and to
% Ben William Carabelli for additional analysis and a draft fix).  \P\thinspace The |[final]| option now works with the
% |{amsmath}| package
% (fixes issue 3\footnote{\url{https://bitbucket.org/nxg/showlabels/issue/3/}}
% – thanks to Guillermo Garza and Enno Nagel for the report, and to
% Guillermo for the test case).  \P\thinspace Handle the hyperref package's |\ref*{label}| variant
% (fixes issue 4\footnote{\url{https://bitbucket.org/nxg/showlabels/issue/4/}}
% – thanks to Alex Watson for the report and test case).  \P\thinspace Handle the case where a label is in a display, but not in maths mode
% (fixes issue 5\footnote{\url{https://bitbucket.org/nxg/showlabels/issue/5/}}
% – thanks to ‘bartgol’ on Stackexchange for the report and test case).\par\item[1.6.6, 2013 December 6]\relax   \P\thinspace Add configuration interface |\showlabelrefline| and
% ensure that |\color| works in
% |\showlabelfont|.  \P\thinspace Various documentation tweaks.  \P\thinspace Change licence from GPL to LPPL.  \P\thinspace Fix link to repository.\par\item[1.6.5, 2009 May 27]\relax Fixed a bug in the way that labels including underscores (and
% other ‘exotic’ characters) were displayed.\par \item[1.6.4, 2008 October 10]\relax Fixed another poor interaction between eqnarray and amsart.  Now
% we get equation labels in eqnarray, and we don't get marginal notes
% about |\eqref| (which is good; might this finally be fixed?).\par \item[1.6.3, 2008 July 24]\relax Release 1.6.2 broke compatibility with the \emph{rest} of
% amsmath (|eqnarray| became the only thing that worked
% within amsmath)!  Fixed.  Doh!\par \item[1.6.2, 2008 June 27]\relax The reimplementation of eqnarray within amsart was such that
% equation labels disappeared in that case.  Fixed.\par \item[1.6.1, 2007 June 17]\relax Fix an errant test, which mangled equation labels starting
% with two identical letters.\par \item[1.6, 2006 May 26]\relax The |\showlabels| command will now work with commands
%   (such as |\cite| or |\includegraphics|) which
%   take an optional argument.\par \item[1.5a, 2005 March 17]\relax Defined |\showlabelfont| using
% |\ttfamily| rather than |\tt| (I'd
% avoided doing this before to avoid a seemingly pointless
% incompatibility with LaTeX 2.09, but (a) I imagine the
% package is incompatible with that for other reasons, and (b)
% it's really not worth the hassle...).\par \item[1.5, 2004 October 8]\relax Added |\showlabelfont| and
% |\showlabelsetlabel| commands, allowing
% customisation of the printed labels.  Added and documented
% options [final], [draft] (the former makes this package do
% nothing; the latter is the default behaviour).\par \item[1.4a, 2003 January 28]\relax Acquired the |[left]| and
% |[right]| options, and fixed a bug which affected
% |\label| commands in captions.\par \item[1.4, 2001 July 24]\relax Became (more) compatible with the
% wrapfig package.  Also, I added the
% |\showlabels| command, to have the package display
% references to commands other than |\label|
% (|\cite| and |\ref| are obvious ones),
% and an |[inline]| option to have labels (etc.)
% displayed inline where possible, rather than always in the
% margin.\par \item[1.3e, 2001 May 30]\relax Became compatible with the hyperref package in
% particular, and in general with other packages which
% themselves modify the |\label| command.  This will
% work, however, only if the showlabels package is loaded after
% other packages which do this.  Notwithstanding Sebastian
% Rahtz's excellent general advice on this, showlabels should
% indeed be loaded after hyperref.\par \item[1.3e, 2001 May 31]\relax After a long delay, here is an updated version of my showlabels
% package.  It corrects all the reported bugs which I could reproduce,
% namely:\par   \P\thinspace The package now formats labels correctly when the
% |\label| command appears outside either an equation or a
% |\caption| (silly of me).  \P\thinspace A couple of people reported problems in the interaction with the
% amsmath package.  Either these were confined to that package's earlier
% incarnations as AMS-LaTeX or the amstex package, or else there's some
% arcane circumstance I can't reproduce, so I haven't found anything to
% fix on this matter.  Note that the
% |\usepackage{showlabels}| command must come \emph{after}
% the |\usepackage{amsmath}| command.  Bug-sightings here
% will be warmly appreciated.  \P\thinspace I haven't worried too much about the precise formatting of the
% labels – this is, after all, supposed to be a draft-only
% package.\par\item[1.1, 2001 January 1]\relax Modified to conform to the slightly
% different mechanism that |amsmath| uses to produce equation
% numbers.  I don't habitually use |amsmath|, so I won't
% discover any bugs or weaknesses with its support here, and I'd
% consequently be glad to be informed of any that appear.  Do note that
% the |\usepackage{showlabels}| command \emph{must} appear
% after the |\usepackage{amsmath}| if it is to detect that
% you are using the amsmath package.  Note also that, since these
% additions appeared, AMS-LaTeX and the |amstex| package seem
% to have been declared ‘obsolete’ in favour of the |amsmath|
% package.  This package now claims conformance with the
% |amsmath| package alone, though it will probably work with
% older versions in fact.\par This is the first version of the package to be distributed under
% the name |showlabels|.\par \item[Updated, 1992 January 29]\relax On 1992 January 29, Darrel Hankerson
% (|hank@ducvax.auburn.edu|), made the update to NFSS, and
% changed the name to |showlabel.sty|.\par \item[Original, 1991 September 21]\relax The package was originally released by me on 1991 September 21, under the name
% |labels.sty|.\par \end{description}% \endgroup
%
% \StopEventually{}
%
% \section{Implementation}
%    \begin{macrocode}
%<*package>
%    \end{macrocode}%
% \iffalse
% Update history:
% October 94: Norman Gray (gray@nxg.name). Modified to be a
% \LaTeX2e package.
% 29-Jan-92 Darrel Hankerson (hank@ducvax.auburn.edu)
%  Update to NFSS. Change name to `showlabel.sty'. Substitute
%  	\nintt -> \small\tt
%	\sevit -> \scriptsize\it
% 21-Sep-91 Norman Gray  no_gray@vax.acs.open.ac.uk
%  Original release of labels.sty
% \fi
%
% Before we do anything else, find out if we're using \Lpackage{amsmath}\dots.
% Note that, since these additions appeared, AMS-\LaTeX\ and the
% \texttt{amstex} package seem to have been declared `obsolete'.  This
% package now claims conformance with the \texttt{amsmath} package.
%    \begin{macrocode}
\newif\ifSL@AMS
\@ifundefined{maketag@@@}
  \SL@AMSfalse
  {\SL@AMStrue\typeout{with amsmath equation tags}}
%    \end{macrocode}
%
% The command which sets equation text is |\SL@eqntext|, which tests
% whether the content should be inline or not.
%    \begin{macrocode}
\def\SL@eqntext{%
  \ifSL@labelsinline
    \let\@tempa\SL@interlinetextleft
  \else
    \let\@tempa\SL@eqnlrtext
  \fi
  \@tempa
}
%    \end{macrocode}
%
% The |\SL@wrap@labeller| macro wraps the given macro in such a way
% that we display the label.
%    \begin{macrocode}
\def\SL@wrap@labeller#1{%
  \expandafter\let\csname SL@orig@#1\expandafter\endcsname\csname #1\endcsname
  \expandafter\def\csname #1\endcsname{%
    \csname SL@orig@#1\endcsname
    \ifx\SL@labelname\relax
      % do nothing
    \else
      \SL@eqntext{\SL@labelname}%
    \fi
    \global\let\SL@labelname\relax}}
%    \end{macrocode}
%
% \begin{macro}{\@eqnnum}
% This replacement for |\@eqnnum| will produce a note, sticking
% into the margin beside the equation number, showing the equation's label.
% |\SL@labelname| is initialised to |\relax|, redefined within the
% |\label| macro, and reset to |\relax| here.  If it's already equal
% to |\relax| here, the equation number hasn't been labelled, and so
% we avoid putting anything in the margin.  In the \Lpackage{amsmath} case
% we instead redefine |\maketag@@@|.
%
% First, deal with the case where the document uses the
% \Lpackage{amsmath} macros.
%    \begin{macrocode}
\ifSL@AMS
%    \end{macrocode}
%
% \Lpackage{amsmath} redefines |\label| to set the macro |\df@label|,
% and then uses |\maketag@@@{\df@label}| or |\tagform@| to form tags
% (ie, equation labels) in equations.  So we hook into \emph{both} of
% these macros.  If the |\df@label| is
% empty (almost certainly because the user has used the
% \Lenv{eqnarray} environment within \Lpackage{amsmath}), then fall back
% on the |\SL@labelname| contents instead.
% \iffalse See tests t2, t11 and t18. \fi
% We must make sure to leave |\SL@labelname| equal to |\relax| at the
% end of this macro, otherwise a |{eqnarray}| followed by an (AMSTeX)
% |\eqref| can end up with the wrong label being referred to by the
% |\maketag@@@| within |\eqref| (or something like that).
%
% The test here must be |\ifx\SL@labelname\relax| with
% |\global\let\SL@labelname\relax|, not |\expandafter\ifx\SL@...| and
% |\global\def\SL@labelname{\relax}| (as it once was), since the
% latter evaluates to true when |\SL@...| is |\relax| \emph{and} when
% |\SL@...| starts with two identical characters, which is wrong (it
% took embarrassingly many goes to get this right). The following is
% similar to the effect of |\SL@wrap@labeller|, but is not quite identical,
% because (a) |\maketag@@@| and |\tagform@| take an argument,
% and (b) we also have to check |\df@label|.
%    \begin{macrocode}
  \def\SL@setlabel@ams{%
    \ifx\df@label\@empty
      \ifx\SL@labelname\relax
        % do nothing
      \else
        \SL@eqntext{\SL@labelname}%
      \fi
    \else
      \SL@eqntext{\df@label}%
    \fi
    \global\let\SL@labelname\relax
  }
  \let\SL@orig@maketag@@@=\maketag@@@
  \def\SL@maketag@@@#1{%
    \SL@orig@maketag@@@{#1}%
    \SL@setlabel@ams
  }
  \let\SL@orig@tagform@\tagform@
  \def\SL@tagform@#1{%
    \SL@orig@tagform@{#1}%
    \SL@setlabel@ams
  }
\else
%    \end{macrocode}
%
% Next, deal with the `normal' case, without \Lpackage{amsmath}.
% Package \Lpackage{amsmath} redefines |\@eqnnum| in terms of
% |\maketag@@@|, so we should avoid doing this in the
% non-\Lpackage{amsmath} case.
%    \begin{macrocode}
  %% \let\SL@eqnnum=\@eqnnum
  %% \def\@eqnnum{%
  %%   \SL@eqnnum
  %%   \ifx\SL@labelname\relax
  %%     % do nothing
  %%   \else
  %%     \SL@eqntext{\SL@labelname}%
  %%   \fi
  %%   \global\let\SL@labelname\relax
  %% }
  \SL@wrap@labeller{@eqnnum}
\fi
%    \end{macrocode}
% \end{macro}
% And initialise the value of |\SL@labelname| to |\relax|, so that
% |\@eqnnum| starts off behaving the right way.
%    \begin{macrocode}
\global\let\SL@labelname\relax
%    \end{macrocode}
%
% Labels are printed with the font specified by |\showlabelfont|, which
% can be overridden within the document:
% Define this using |\ttfamily|, unless we're still using \LaTeX 2.09
% (surprising it still works!), in which case stick with |\tt|.
%    \begin{macrocode}
\@ifundefined{ttfamily}
  {\providecommand{\showlabelfont}{\small\tt}}
  {\providecommand{\showlabelfont}{\small\ttfamily}}
%    \end{macrocode}
%
% If you want slightly more general control over the labels, you can
% instead override |\showlabelsetlabel|.
%    \begin{macrocode}
\providecommand{\showlabelsetlabel}[1]{{\normalfont\showlabelfont\SL@fmt@{#1}}}
%    \end{macrocode}
%
% For the benefit of |\SL@prlabelname|, define |\SL@gobblethree| to do nothing
% other than eat three tokens.
%    \begin{macrocode}
\def\SL@gobblethree#1#2#3{}
%    \end{macrocode}
%
% \begin{macro}{\SL@prlabelname}
% Expansion is label name with all catcodes `other' (Appendix~D trickery
% abounds!).  Use |\r@#1| (defined by |\ref|), rather then just |\#1|
% to avoid defining any new control sequences.
%
% Note that this catcode magic, and the |\@sanitize| in
% |\SL@showlabels| below, are doing much the same job, and indeed are
% almost redundant with each other.  But this |\SL@prlabelname|
% doesn't cope with eg |\index{Poincar\'e}|, and the |\@sanitize|
% below doesn't cope with |\section{\label{a_b}Foo}| (see tests t4 and t19).
%    \begin{macrocode}
\def\SL@prlabelname#1{%
\expandafter\expandafter\expandafter\SL@gobblethree
    \expandafter\string\csname r@#1\endcsname}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\showlabels}
% Define the |\showlabels| command which allows us to redefine
% commands which are to have their arguments highlighted.
% That is, |\showlabels{foo}| means that the command |\foo{bar}| will
% write `bar' in the margin, as well as executing whatever |\foo| does
% normally.
%
% The net result of all this is that a |\showlabels{foo}| command
% arranges things so that, after |\begin{document}|, the original
% version of |\foo| is saved in |\SL@origfoo|, and |\foo{bar}| expands into
% |\SL@setlabel{bar}\SL@origfoo{bar}|.
%
% First, define a command |\SL@initfoo|, which, when executed, will
% save the current (at that time) behaviour of the command |\foo| as
% |\@SL@origfoo|, and then set |\foo| to be equivalent to |\SL@foo|,
% which does the magic; we will
% shortly give this command to |\AtBeginDocument|, so that it is
% switched on at the correct time, when other packages have done
% \emph{their} redefinitions of |\foo| (this makes it compatible with
% the \Lpackage{hyperref} package, which does its own wholesale redefinitions of
% things like |\label|).  Below, the locution
% |\the\@temptokena| causes the token contents of |\@temptokena| to be
% included unexpanded in the definition, despite the |\edef|.
%
% If the optional |\showlabels| argument is present, then use this as per-command
% formatting, so that, for example |\cite| instances may be formatted
% distinctively from |\label|.
%    \begin{macrocode}
\def\showlabels{\@ifnextchar[\showlabels@{\showlabels@[]}}
\def\showlabels@[#1]#2{%
  \@temptokena=\expandafter{\csname #2\endcsname}
  \def\@tempa{#1}%
  \ifx\@tempa\@empty
    \expandafter\let\csname SL@fmt@#2\endcsname\relax
  \else
    \expandafter\def\csname SL@fmt@#2\endcsname{#1}%
  \fi
  \expandafter\edef\csname SL@init@#2\endcsname{%
    \let\csname SL@orig#2\endcsname\the\@temptokena
    \let\the\@temptokena\csname SL@#2\endcsname}
  \AtBeginDocument{\csname SL@init@#2\endcsname}%
%    \end{macrocode}
% \emph{Now} define |\SL@foo| -- it must be undefined when we define
% |\SL@initfoo| above, so that it isn't expanded in the |\edef|.
%    \begin{macrocode}
  \expandafter\def\csname SL@#2\endcsname{%
    \expandafter\let\expandafter\SL@fmt@\csname SL@fmt@#2\endcsname
    \SL@showlabels{#2}}
}
%    \end{macrocode}
%
% We need a default definition of |\SL@fmt@| for the cases (some
% equation formatting) where we don't get to the formatting via this
% mechanism.
%    \begin{macrocode}
\let\SL@fmt@\relax
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\SL@showlabels}
% Now we get to the command which does the main processing.  The
% |\SL@showlabels| command calls |\SL@setlabel| to format the label
% (putting it in the margin, for example), then calls the original
% |\foo| command (namely |\SL@origfoo|) with the original argument.
%
% The command takes a single argument, namely the name of the command
% being wrapped (for example, `label').  We set |\@tempa| to be the
% original version of that command (stored in |\SL@orig#1|), and then
% take one of two similar paths, depending on whether the command has
% an optional argument or not.
%
% We have to be somewhat careful about the positioning of the
% |\@bsphack| and |\@esphack| commands.  The |\@esphack| command should
% \emph{not} come after the call to |\SL@origfoo|, since that would
% confuse things terribly if that command took any other arguments, or
% otherwise messed with the token stream (there's actually no problem
% in the most common case where we're replacing |\label|, and calling
% |\SL@origlabel|, but there are problems when we try to replace
% |\begin| or |\ref| in this way).  Instead, adapt the contents
% of |\@esphack|, but instead of calling |\ignorespaces| when
% |\@savsk| is positive, add an |\hskip| of 1~scaled point (equal to
% $1/65536\mathrm{pt}=5.363\times10^{-9}\mathrm{m}$).  This will be
% invisible, but it \emph{is} greater than zero, so that if
% |\SL@origfoo| itself uses a |\@bsphack|\dots|\@esphack| pair then
% the saved |\@savsk| will be positive, and that future |\@esphack|
% will correctly invoke |\ignorespaces|; that pair will also pick up
% the |\spacefactor| we restore here.  The net result is that the
% |\SL@setlabel| is invisible, and |\SL@origfoo| is able to make
% itself invisible, too.  Command sequence |\SL@setlabel| is what does
% the work -- this is |\let| equal to either |\SL@margtext| or
% |\SL@inlinetext| below.
%
% We must declare |\SL@showlabels| to be a robust command, or else we
% get confusing expansion problems when, for example, we do
% |\showlabels{ref}| and use |\ref| in a caption (see test case t3).
% We actually handle three distinct cases here, for |\foo{label}|,
% |\foo[opt]{label}| and |\foo*{label}| (the last is to handle the
% \Lpackage{hyperref} package's |\ref*{label}| variant; see test case
% t14).
%
% Note that in each case, the |label| is read with sanitised
% catcodes.  That is, I think, always an acceptable thing to do, in
% the sense that I can't think of cases where this breaks anything.
%
% We open a group in order to call |\@sanitize|; we're able to close
% it immediately, within the called macros.  We call |\@sanitize| in
% order to cope with eg |\index{Poincar\'e}| (see discussion of
% |\SL@prlabelname| above).  We carefully \emph{avoid} calling
% |\@sanitize| before reading an optional argument: this is so that
% we read that argument with the existing catcode
% assignments, so that eg |\bibitem[P{\'o}lya]{polya54}| works as
% expected (see test t20).
%
% We declare |\showlabeltype| to be the `current' label type.  It
% would be good to put this inside a group, so that it's only visible
% locally, but we would then have to be careful exactly when we closed
% the group: if we put it inside the group that's opened for
% |\@sanitize|, it would be closed too early to have an effect; if we
% open another group for |\showlabeltype|, then we'd have to close it
% \emph{after} |\SL@orig@@next|, where we risk colliding with whatever
% comes after it (and see above).  It might be possible to be cleverer
% about this, but it's at least harmeless to have the command defined
% globally.
%    \begin{macrocode}
\DeclareRobustCommand\SL@showlabels[1]{%
  \@bsphack
  \expandafter\let\expandafter\SL@orig@@next\csname SL@orig#1\endcsname
  \def\showlabeltype{#1}%
  \begingroup
  \@ifstar
    {\@sanitize\SL@showlabelsplainstar}
    {\@ifnextchar[
       {\SL@showlabelsopt}
       {\@sanitize\SL@showlabelsplain}}}
\def\SL@showlabelsopt[#1]{% #1 is read before \@sanitize
  \@sanitize
  \SL@showlabelsopt@ii{#1}}
\def\SL@showlabelsopt@ii#1#2{%
  \endgroup
  \SL@setlabel{#2}\relax
  \ifhmode \spacefactor\@savsf \ifdim\@savsk>\z@ \hskip1sp \fi\fi
  \SL@orig@@next[#1]{#2}}
\def\SL@showlabelsplain#1{%
  \endgroup
  \SL@setlabel{#1}\relax
  \ifhmode \spacefactor\@savsf \ifdim\@savsk>\z@ \hskip1sp \fi\fi
  \SL@orig@@next{#1}}
\def\SL@showlabelsplainstar#1{%
  \endgroup
  \SL@setlabel{#1}\relax
  \ifhmode \spacefactor\@savsf \ifdim\@savsk>\z@ \hskip1sp \fi\fi
  \SL@orig@@next*{#1}}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@makecaption}
% The |\@makecaption| command needs special treatment.  The
% |\SL@margtext| command doesn't work in figure captions, so we need
% to force the layout commands to use |\SL@inlinetext| instead, for
% all label types, and irrespective of whether we're using the
% \Lopt{inline} option.  The code here is independent of that in
% |\showlabels|, but imitates it, for consistency.
%    \begin{macrocode}
\def\SL@initmakecaption{%
  \let\SL@origmakecaption\@makecaption
  \def\@makecaption##1##2{{%
    \let\SL@setlabel\SL@inlinetext
    \SL@origmakecaption{##1}{##2}}}}
\AtBeginDocument{\SL@initmakecaption}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\SL@margtext}
% This is the central bit of this package, used by |\SL@showlabels|.
% The argument is the argument of the |\foo| command which we're
% processing (for example, the argument to a |\label| command).
%
% Depending on the mode, put the
% current label name in the margin in one of a variety of ways.
%    \begin{macrocode}
\def\SL@margtext#1{%
%    \end{macrocode}
%
% There are three cases here:
% \begin{enumerate}
% \item We are in maths mode, setting an equation.
% \item We are not in maths mode but we \emph{are} within a display
% (this can happen in, for example, the \Lenv{cases} environment from
% the \Lpackage{cases} package).
% \item We are in text.
% \end{enumerate}
%
% Case 1:
% In maths mode, produce a label name alongside the equation number.
% Save the label name in |\SL@labelname|, so we can use it later
% (this is redundant in most \Lpackage{amsmath} contexts, because that
% style generally saves this in |\df@label|, but sometimes -- for
% example when using the traditional \Lenv{eqnarray} environment
% within \Lpackage{amsart} -- |\df@label| can end up unset).
%    \begin{macrocode}
  \ifmmode
    \xdef\SL@labelname{\SL@prlabelname{#1}}%
%    \end{macrocode}
%
% Case 2:
% Check if we're within a display equation,
% and if so act as if we are in maths mode (ie, as above).
% Note: most contexts which match case~1 would also be caught by this
% test, since |\label| is used almost exclusively within displays,
% but it seems clearer to separate the two cases explicitly, as well
% as probably dealing better with cases where the package is used for
% non-|\label| commands.
%    \begin{macrocode}
  \else\ifdim\displaywidth>0pt
    \xdef\SL@labelname{\SL@prlabelname{#1}}%
%    \end{macrocode}
%
% Case 3:
% Otherwise, create a box with zero height and depth, and the same width
% as the page.  Put all this in braces, to contain the setting of
% |\box\@tempboxa| (which probably shouldn't be necessary).  The box
% here we set to be the width of |\hsize|.  This is \emph{probably}
% best, though there's always the worry that |\linewidth| would be the
% more \LaTeX-ish thing to do -- using |\columnwidth| is almost
% certainly wrong, since |\linewidth| can sometimes be changed without
% |\columnwidth| changing with it (for example, in package
% \Lpackage{wrapfig}), causing \Lpackage{showlabels} to fail badly.
%    \begin{macrocode}
  \else
    \setbox\@tempboxa=\vbox to 0pt{%
      \vss
      \hbox to \hsize{\SL@lrtext{#1}}}%
    \dp\@tempboxa\z@
%    \end{macrocode}
% Attach this box below the last one, using |\nointerlineskip| if we're in
% vertical mode, or |\vadjust| otherwise.  We need to save and restore
% the value of |\prevdepth| (which has the sentinel value -1000pt if we're
% adding this box at the beginning of a vertical list, and
% |\nointerlineskip| sets |\prevdepth| to this same value).  If we don't
% do this, we get extra (`interline') vertical space added in this
% case (it might be thought smart to use |\marginpar| here, and so
% avoid some of this nonsense, but that's not possible since this
% might be called within boxes, which |\marginpar| objects to).
%    \begin{macrocode}
    \ifvmode
      \@tempdima=\prevdepth
      \nointerlineskip\box\@tempboxa\nobreak
      \prevdepth=\@tempdima
    \else
      \vadjust{\box\@tempboxa\nobreak}%
    \fi
%    \end{macrocode}
% That's it.  Finish off the sequence of cases.
%    \begin{macrocode}
  \fi\fi
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\SL@inlinetext}
% This is an alternative way of formatting the label, which puts it
% inline as much as possible, and avoids straying into the margins.
% We just use the same mechanism as for |\SL@margtext|, but do the
% inline-or-not testing there.
%    \begin{macrocode}
\def\SL@inlinetext#1{%
  \SL@interlinetextright{\SL@prlabelname{#1}}%
}
%    \end{macrocode}
% In vmode, put the label between lines.  Set the box depth to zero to
% make sure that descenders don't mess up the spacing.
%    \begin{macrocode}
\def\SL@interlinetextleft{\SL@setlefttrue\SL@interlinetext}
\def\SL@interlinetextright{\SL@setleftfalse\SL@interlinetext}
\def\SL@interlinetext#1{%
  \setbox\@tempboxa=\hbox{\showlabelsetlabel{\SL@prlabelname{#1}}}\dp\@tempboxa\z@
  \ifvmode
    \nointerlineskip\vbox to 0pt{\vss
      \hbox to \columnwidth{\hss \box\@tempboxa}}%
%    \end{macrocode}
% And in horizontal mode, squeeze it between the lines, at the current point,
% carefully taking up no space.
%    \begin{macrocode}
  \else
    \ifSL@setleft
      \hbox to 0pt{%
 	\hss
 	\vbox to 0pt{\vss
 	  \hbox to 0pt{\hss\box\@tempboxa}%
 	  \showlabelrefline
        }}%
    \else
      \hbox to 0pt{%
 	\vbox to 0pt{\vss
 	  \box\@tempboxa
 	  \showlabelrefline
        }\hss}%
    \fi
    \penalty10000
  \fi
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\showlabelrefline}
% Set a short line which indicates the point where a label is
% attached, when producing inline labels.  This additionally positions
% the label up above the line.
%    \begin{macrocode}
\def\showlabelrefline{\hrule width 0.05em height 1.5ex depth 0pt }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\SL@margintext}
% Set the actual text of the label.  Use |\SL@prlabelname| here: without
% this, a label command given outside of an equation or a |\caption|
% will appear wrongly if the label has things like underscores within it.
%    \begin{macrocode}
\def\SL@margintext#1{{\showlabelsetlabel{\{\SL@prlabelname{#1}\}}}}
%    \end{macrocode}
% \end{macro}
%
% But where is the marginal text actually set?  It can be in the left
% margin, the right one, or can alternate.  |\SL@lrtext|, used in the
% |\vbox| above, is set, under the control of |\SL@labelposition| below, to
% one of |\SL@lefttext|, |\SL@righttext| or |\SL@alternatetext|.
% \begin{macro}{\SL@righttext}
% \begin{macro}{\SL@lefttext}
%    \begin{macrocode}
\def\SL@righttext#1{\hfill\rlap{\quad\SL@margintext{#1}}}
\def\SL@lefttext #1{\llap{\SL@margintext{#1}\quad}\hfill}
%    \end{macrocode}
% \end{macro}
% \end{macro}
%
% \begin{macro}{\SL@setLR}
% Define a switch which allows us to state whether we've decided to
% set a particular label to the left or the right, and a macro
% |\SL@setLR| to set it.  After |\SL@setLR|, |\ifSL@setleft| is true
% if a label should be set to the left, and is false if it should go
% to the right.
%    \begin{macrocode}
\newif\ifSL@setleft
\def\SL@setLR{%
  \ifcase\SL@labelposition
    % 0=outer margin
    \ifodd\c@page
      \SL@setleftfalse
    \else
      \SL@setlefttrue
    \fi
  \or
    % 1=inner margin
    \ifodd\c@page
      \SL@setlefttrue
    \else
      \SL@setleftfalse
    \fi
  \or
    % 2=left margin
    \SL@setlefttrue
  \or
    % 3=right margin
    \SL@setleftfalse
  \else
    \SL@canthappen{Impossible labelposition \the\SL@labelposition}
    \SL@labelposition=3 % put everything in the right-margin for now
    \SL@setleftfalse
  \fi
}
%    \end{macrocode}
% \end{macro}
%
% The code for |\SL@alternatetext| doesn't work perfectly, as it
% sometimes manages to get things on the wrong side of the text near the
% top of a new page.  This is a venial slip, however, as this package
% should never be used in a final version.
% \begin{macro}{\SL@alternatetext}
%    \begin{macrocode}
\def\SL@alternatetext{%
  \SL@setLR
  \ifSL@setleft
    \let\SL@next\SL@lefttext
  \else
    \let\SL@next\SL@righttext
  \fi
  \SL@next
}
%    \end{macrocode}
% \end{macro}
% The case where the \Lopt{twocolumn} option is set is slightly different.
% There we have to switch between placing the note in the left and right
% margins, depending on whether we're setting the first or second column.
% This macro, and |\SL@eqntwocoltext| below, uses the switch
% |\if@firstcolumn| to decide whether it's in the first or the second
% column of the text (I suppose it'll get terribly confused if we use
% \file{multicol.sty} along with this).  This is defined and maintained in
% the base file \file{ltoutput.dtx}.  It's not part of the defined
% interface, however (there doesn't seem to be one, grump), so I don't
% suppose we should really rely on it.  There isn't an option, however.
% \begin{macro}{\SL@twocoltext}
%    \begin{macrocode}
\def\SL@twocoltext{%
  \if@firstcolumn
    \let\SL@next\SL@lefttext
  \else
    \let\SL@next\SL@righttext
  \fi
  \SL@next}
%    \end{macrocode}
% \end{macro}
%
% We have very similar things for equations, except that they are set in
% place, rather than within a zero depth box.  This code \emph{assumes} that
% equation numbers are going to be on the right hand side of the page.  It
% should probably check for the existence of the \Lopt{leqno} option (how?).
% \begin{macro}{\SL@eqnrighttext}
% \begin{macro}{\SL@eqnlefttext}
%    \begin{macrocode}
\def\SL@eqnrighttext#1{\rlap{\quad\SL@margintext{#1}}}
\def\SL@eqnlefttext #1{\hbox to 0pt{\kern -\columnwidth
	\llap{\SL@margintext{#1}\quad}\hss}}
%    \end{macrocode}
% \end{macro}
% \end{macro}
% Now do the analogues for the equation numbers, in the case of the
% alternate page selection\dots
% \begin{macro}{\SL@eqnalternatetext}
%    \begin{macrocode}
\def\SL@eqnalternatetext{%
  \SL@setLR
  \ifSL@setleft
    \let\SL@next\SL@eqnlefttext
  \else
    \let\SL@next\SL@eqnrighttext
  \fi
  \SL@next
}
%    \end{macrocode}
% \end{macro}
% \dots and the twocolumn option
% \begin{macro}{\SL@eqntwocoltext}
%    \begin{macrocode}
\def\SL@eqntwocoltext{%
  \if@firstcolumn
    \let\SL@next\SL@eqnlefttext
  \else
    \let\SL@next\SL@eqnrighttext
  \fi
  \SL@next}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\SL@canthappen}
% Issues a |\PackageError| command, and solicits bug reports.
%    \begin{macrocode}
\def\SL@canthappen#1{%
    \PackageError{showlabels}{#1}
        {This shouldn't happen -- the package showlabels has a bug.
        \MessageBreak
        Please report this, if possible with a sample document which
        \MessageBreak
        demonstrates the problem, to \filemaintainer.  Thanks.}}
%    \end{macrocode}
% \end{macro}
%
% To control the positioning of labels, set the |\SL@labelposition|
% switch, which can take values 0, 1, 2, 3, meaning outer, inner,
% left, right margin respectively.
%    \begin{macrocode}
\newcount\SL@labelposition
\SL@labelposition=0
%    \end{macrocode}
%
% We select between the various possibilities using the \Lopt{outer} and
% \Lopt{inner} options and, implicitly, the \Lopt{twoside} option.
%    \begin{macrocode}
\DeclareOption{outer}{\SL@labelposition=0}
\DeclareOption{inner}{\SL@labelposition=1}
\DeclareOption{left}{\SL@labelposition=2}
\DeclareOption{right}{\SL@labelposition=3}
%    \end{macrocode}
%
% Labels can be set either in the margins or inline, by switching
% between definitions of |\SL@setlabel|.
%    \begin{macrocode}
\newif\ifSL@labelsinline
\SL@labelsinlinefalse
\DeclareOption{marginal}{\SL@labelsinlinefalse}
\DeclareOption{inline}{\SL@labelsinlinetrue}
%    \end{macrocode}
% \begin{macro}{\SL@setlabel}
%
% Macro |\SL@setlabel| is where we switch between inline and marginal labels.
%    \begin{macrocode}
\def\SL@setlabel{%
  \ifSL@labelsinline
    \let\@tempa\SL@inlinetext
  \else
    \let\@tempa\SL@margtext
  \fi
  \@tempa
}
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\showlabelsinline}
% It is sometimes convenient (for example when a document encounters a
% situation which this package mishandles) to force inline labels
% temporarily, within a block or environment.  Use this macro to do
% that.
%    \begin{macrocode}
\def\showlabelsinline{\SL@labelsinlinetrue}
%    \end{macrocode}
% \end{macro}
% By default, we run |\showlabels{label}|.  The option \Lopt{nolabel}
% turns this off.
%    \begin{macrocode}
\newif\ifSL@labellabel
\SL@labellabeltrue
\DeclareOption{nolabel}{\SL@labellabelfalse}
%    \end{macrocode}
%
% Define the options \Lopt{final} and \Lopt{draft}.  The option
% \Lopt{final} turns off all the functionality of this package by
% disabling the command |\showlabels|, including the implicit
% |\showlabels| command which the package issues as long as the
% \Lopt{nolabel} option has not been given.  This is included so that if that
% option is given in the |\documentclass| declaration then this
% package does respect it.  \Lopt{draft} does nothing, and therefore
% simply continues the default behaviour of this package; it is here
% purely to partner the \Lopt{final} option.
%    \begin{macrocode}
\DeclareOption{final}{\let\showlabels\@gobble}
\DeclareOption{draft}{}
%    \end{macrocode}
%
% Process any options that have been set.
%    \begin{macrocode}
\ProcessOptions
%    \end{macrocode}
% and use the values of |\SL@labelposition| and |if@twoside| which may have
% been set by those options, to set |\SL@lrtext| to be the
% appropriate control sequence.  The presence of the \Lopt{twocolumn} option
% means that we ignore the \Lopt{inner} and \Lopt{outer} options.
%    \begin{macrocode}
\if@twocolumn
  \let\SL@lrtext\SL@twocoltext
  \let\SL@eqnlrtext\SL@eqntwocoltext
\else
  \ifcase\SL@labelposition
    % 0=outer margin
    \if@twoside
      \let\SL@lrtext\SL@alternatetext
      \let\SL@eqnlrtext\SL@eqnalternatetext
    \else
      \let\SL@lrtext\SL@righttext
      \let\SL@eqnlrtext\SL@eqnrighttext
    \fi
  \or
    % 1=inner margin
    \if@twoside
      \let\SL@lrtext\SL@alternatetext
      \let\SL@eqnlrtext\SL@eqnalternatetext
    \else
      \let\SL@lrtext\SL@lefttext
      \let\SL@eqnlrtext\SL@eqnlefttext
    \fi
  \or
    % 2=left margin
    \let\SL@lrtext\SL@lefttext
    \let\SL@eqnlrtext\SL@eqnlefttext
  \or
    % 3=right margin
    \let\SL@lrtext\SL@righttext
    \let\SL@eqnlrtext\SL@eqnrighttext
  \else
    \SL@canthappen{Impossible labelposition \the\SL@labelposition}
    \SL@labelposition=3 % put everything in the right-margin for now
    \let\SL@lrtext\SL@righttext
    \let\SL@eqnlrtext\SL@eqnrighttext
  \fi
\fi
%    \end{macrocode}
%
% Finally, label all the |\label| commands
% (default behaviour),
% unless this has been suppressed through the \Lopt{nolabel} option.
%    \begin{macrocode}
\ifSL@labellabel
  \showlabels{label}
  \ifSL@AMS
    \ifx\showlabels\@gobble
      % do nothing -- we're in [final] mode (see test case t13)
    \else
      \AtBeginDocument{%
        \let\maketag@@@\SL@maketag@@@
        \let\tagform@\SL@tagform@}
    \fi
  \fi
  \@ifundefined{theIEEEsubequationdis}\relax % and \theequationdis
    {\SL@wrap@labeller{theIEEEsubequationdis}
     \SL@wrap@labeller{theequationdis}}
\fi
%    \end{macrocode}
%
% That's us.
%
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \Finale
\endinput