summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/multifootnote/multifootnote-doc.tex
blob: c1c6516a953b3378033fb5450179b6a1f859e5a1 (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
\documentclass[classical]{einfart}

\usepackage{ProjLib}

\usepackage[left indent]{multifootnote}

%%================================
%% For typesetting code
%%================================
\usepackage{listings}
\usepackage{xcolor}
\usepackage{setspace}
\definecolor{code-main}{RGB}{70,130,180}
\definecolor{code-expl3}{RGB}{240,50,60}
\definecolor{code-option}{RGB}{40,110,20}
\definecolor{code-keys}{RGB}{100,130,150}
\definecolor{code-comment}{RGB}{20,120,80}
\definecolor{code-background}{gray}{0.99}
\lstset{
    language = [LaTeX]TeX,
    basicstyle = \ttfamily,
    keywordstyle = \color{code-main},
    commentstyle = \color{code-comment},
    showstringspaces = false,
    breaklines = true,
    frame = lines,
    backgroundcolor = \color{code-background},
    flexiblecolumns = true,
    escapeinside = {(*}{*)},
    alsoletter = {_,:},
    % numbers = left,
    % firstnumber = last,
    numberstyle = \scriptsize\ttfamily,
    stepnumber = 1,
    numbersep = 5pt,
}
\newcommand{\meta}[1]{$\langle${\normalfont\itshape#1}$\rangle$}
\lstset{% LaTeX2 commands
    classoffset = 0,
    texcsstyle =* \color{code-main},
    moretexcs =
      {
        multifootnotetext,
        multifootnotemark,
        multifootnotetag,
        multifootnotetagtext,
        multifootnote,
        footnotenumber,
        footnotetag,
      }
}
\lstset{% LaTeX3 commands
    classoffset = 1,
    texcsstyle =* \color{code-expl3},
    moretexcs =
      {
      }
}
\lstnewenvironment{code}{\setstretch{1.05}\LocallyStopLineNumbers}{\ResumeLineNumbers\vspace{-.3\baselineskip}\vspace{-.5\parskip}}
\lstnewenvironment{code*}{\setstretch{1.05}\lstset{numbers=left}\LocallyStopLineNumbers}{\ResumeLineNumbers\vspace{-.3\baselineskip}\vspace{-.5\parskip}}

\newcommand{\packageoption}[1]{\texttt{\textcolor{code-option}{#1}}}
\newcommand{\commandoption}[1]{\texttt{\textcolor{code-keys}{#1}}}

%%================================
%% tip
%%================================
\usepackage[many]{tcolorbox}
\newenvironment{tip}[1][Tip]
  {%
    \LocallyStopLineNumbers%
    \begin{tcolorbox}[breakable,
        enhanced,
        width = \textwidth,
        colback = paper, colbacktitle = paper,
        colframe = gray!50, boxrule=0.2mm,
        coltitle = black,
        fonttitle = \sffamily,
        attach boxed title to top left = {yshift=-\tcboxedtitleheight/2, xshift=.5cm},
        boxed title style = {boxrule=0pt, colframe=paper},
        before skip = 3mm,
        after skip = 3mm,
        top = 2.5mm,
        bottom = 1.5mm,
        title={\scshape\sffamily #1}]%
  }
  {%
    \end{tcolorbox}%
    \ResumeLineNumbers%
  }


\newcommand{\multifootnotepackage}{{\normalfont\textsf{multifootnote}}}

\begin{document}

\def\PackageVersion{2022/05/31}

\title{\multifootnotepackage{}\\\smallskip\itshape Multiple numbers for the same footnote}
\author{Jinwen XU}
\thanks{Corresponding to: \texttt{\multifootnotepackage{} \PackageVersion}}
\date{\TheDate{\PackageVersion}[only-year-month], in Paris}

\maketitle

\begin{abstract}
    \raggedleft
    The package \multifootnotepackage{} provides two groups of commands for \\generating footnotes with multiple numbers (or marks, if you prefer).
\end{abstract}


\vspace*{-.5\baselineskip}

\section{How to load it}

You can simply load the current package with:

\begin{code}
\usepackage[(*\meta{options}*)]{multifootnote}
\end{code}

\medskip
It has the following options:
\begin{itemize}[label=,leftmargin=1.25em,itemindent=-1.25em]
    \item \packageoption{left align}
        \begin{itemize}
            \item Align the footnotes to the left.
            \item Alternative names: \packageoption{left-align} \,$|$\, \packageoption{leftalign}
        \end{itemize}
    \item \packageoption{left indent} or \packageoption{left indent} \lstinline|=| \meta{length}
        \begin{itemize}
            \item Similar to \packageoption{left align}, but with an indentation \meta{length}, default to be \texttt{1.5em}.
            \item Alternative names: \packageoption{left-indent} \,$|$\, \packageoption{leftindent}
        \end{itemize}
\end{itemize}

\section{How to use it}

Here are two approaches for producing a footnote with multiple numbers, and in either of them, there are two commands involved.

\subsection{First approach}

This approach is more or less traditional, with one command to produce the footnote mark and another the text.
\begin{itemize}
    \item \lstinline|\multifootnotemark[|\meta{label}\lstinline|]|
    \begin{itemize}
        \item This command is for producing the footnote marks.
        \item \meta{label} cannot contain commas. However, colon \textquote{\texttt{:}} and semicolon \textquote{\texttt{;}} are allowed.
        \item Alternative name: \lstinline|\footnotenumber[|\meta{label}\lstinline|]|.
    \end{itemize}
    \item \lstinline|\multifootnotetext[|\meta{list of labels}\lstinline|]{|\meta{footnote text}\lstinline|}|
    \begin{itemize}
        \item This command is for producing the footnote text.
        \item \meta{list of labels} is a list of labels that you specified with \lstinline|\multifootnotemark[|\meta{label}\lstinline|]|, separated with commas, like this: \commandoption{fn1,fn2,fn3}.
        \item It should not be too far away from the corresponding marks.
        \item Alternative name: \lstinline|\multifootnote[|\meta{list of labels}\lstinline|]{|\meta{footnote text}\lstinline|}|.
    \end{itemize}
\end{itemize}

\subsection{Second approach}

This approach is considered more convenient, with one command to specify the \meta{tag} while printing the footnote mark, and another to print the footnote text for this group.
\begin{itemize}
    \item \lstinline|\multifootnotetag{|\meta{tag}\lstinline|}| or \lstinline|\multifootnotetag{|\meta{list of tags}\lstinline|}|
    \begin{itemize}
        \item This command is for producing the footnote marks.
        \item \meta{tag} cannot contain commas. However, colon \textquote{\texttt{:}} and semicolon \textquote{\texttt{;}} are allowed.
        \item \meta{list of tags} is a list of tags, separated with commas, like this: \commandoption{fntag1,fntag2,fntag3}.
        \item Alternative name: \lstinline|\footnotetag{|\meta{tag}\lstinline|}| or \lstinline|\footnotetag{|\meta{list of tags}\lstinline|}|.
    \end{itemize}
    \item \lstinline|\multifootnotetagtext[|\meta{tag}\lstinline|]{|\meta{footnote text}\lstinline|}|
    \begin{itemize}
        \item This command is for producing the footnote text.
        \item It should not be too far away from the corresponding marks.
        \item Alternative name: \lstinline|\multifootnote[|\meta{tag}\lstinline|]{|\meta{footnote text}\lstinline|}|.
    \end{itemize}
\end{itemize}

\begin{tip}
    \lstinline|\multifootnote| appears in both approaches for producing footnote text: it shall be interpreted as \lstinline|\multifootnotetext| if the optional argument is a comma-separated list, and as \lstinline|\multifootnotetagtext| if not. See the examples below.
\end{tip}

\bigskip
\begin{center}
    \itshape
    If you're feeling confused, don't worry. Let's now take a look at some examples.
\end{center}


\section{Examples}

Here are two examples of usage, with the package option \textquote{\packageoption{left indent}} enabled.

\subsection{The first approach}

\medskip
\begin{code}
Lorem ipsum\footnotenumber[(*\commandoption{fn1}*)] dolor\footnotenumber[(*\commandoption{fn2}*)] sit amet\footnotenumber[(*\commandoption{fn3}*)], consectetur\footnotenumber[(*\commandoption{fn4}*)] adipiscing elit\footnotenumber[(*\commandoption{fn5}*)].
\multifootnote[(*\commandoption{fn1,fn2,fn5}*)]{This is a footnote for demonstration.}
\multifootnote[(*\commandoption{fn1,fn3,fn4}*)]{This is another footnote for demonstration.}
\end{code}

Result:

\fbox{Lorem ipsum\footnotenumber[fn1] dolor\footnotenumber[fn2] sit amet\footnotenumber[fn3], consectetur\footnotenumber[fn4] adipiscing elit\footnotenumber[fn5].}
\multifootnote[fn1,fn2,fn5]{This is a footnote for demonstration.}
\multifootnote[fn1,fn3,fn4]{This is another footnote for demonstration.}

\subsection{The second approach}

\medskip
\begin{code}
Lorem ipsum\footnotetag{(*\commandoption{fntag1,fntag2}*)} dolor\footnotetag{(*\commandoption{fntag1}*)} sit amet\footnotetag{(*\commandoption{fntag2}*)}, consectetur\footnotetag{(*\commandoption{fntag2}*)} adipiscing elit\footnotetag{(*\commandoption{fntag1}*)}.
\multifootnote[(*\commandoption{fntag1}*)]{This is a footnote for demonstration.}
\multifootnote[(*\commandoption{fntag2}*)]{This is another footnote for demonstration.}
\end{code}

Result:

\fbox{Lorem ipsum\footnotetag{fntag1,fntag2} dolor\footnotetag{fntag1} sit amet\footnotetag{fntag2}, consectetur\footnotetag{fntag2} adipiscing elit\footnotetag{fntag1}.}
\multifootnote[fntag1]{This is a footnote for demonstration.}
\multifootnote[fntag2]{This is another footnote for demonstration.}

\begin{tip}
    The second approach is more recommended, as it involves fewer labels, and you shall not need to worry about the order of footnote marks in \lstinline|\multifootnote|.
\end{tip}

\begin{tip}[Attention]
    Notice that in the first approach, \meta{label} appears as an optional argument of \lstinline|\footnotenumber[|\meta{label}\lstinline|]| (thus square brackets); while in the second approach, \meta{tag} is a mandatory argument of \lstinline|\footnotetag{|\meta{tag}\lstinline|}| (thus curly brackets).
\end{tip}


\bigskip
\section{Acknowledgement}

This package arises from a question (\href{https://tex.stackexchange.com/q/645330}{\texttt{645330}}) on \texttt{TeX.StackExchange}. The author thanks user \href{https://tex.stackexchange.com/users/270985}{\textsf{@Bolzano}} for bringing up the question of producing such footnotes.

The author thanks \href{https://tex.stackexchange.com/users/2388}{\textsf{Ulrike Fischer}} for the code for fixing the broken hyperlinks generated by the first approach, and user \href{https://tex.stackexchange.com/users/73317}{\textsf{@frougon}} for his kind and helpful suggestions and comments.

The author also wishes to thank user \href{https://tex.stackexchange.com/users/213149}{\textsf{@antshar}} for proposing the second approach. The code is surprisingly simple but works just as fine as that of the first approach.

\section{Known issues}

\begin{itemize}
    % \item When package \textsf{hyperref} is loaded, hyperlinks to those footnotes generated by the commands here cannot point to the correct place.
    \item \multifootnotepackage{} is not compatible with the package \textsf{footnotebackref}.
\end{itemize}

\medskip
If you run into any issue or have ideas for improvement, feel free to discuss on:
\begin{center}
    \url{https://github.com/Jinwen-XU/multifootnote/issues}
\end{center}
or email me via \href{mailto:ProjLib@outlook.com}{\texttt{ProjLib@outlook.com}}.

\end{document}