summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/ccref/ccref-doc.tex
blob: 992ff0f181f861b10bf0e18674fc932a5607cebf (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
%! TEX program = xelatex
\documentclass[classical]{einfart}

\linenumbers

\usepackage{ProjLib}

%%================================
%% For typesetting code
%%================================
\usepackage{listings}
\definecolor{maintheme}{RGB}{70,130,180}
\definecolor{forestgreen}{RGB}{21,122,81}
\definecolor{lightergray}{gray}{0.99}
\lstset{language=[LaTeX]TeX,
    keywordstyle=\color{maintheme},
    basicstyle=\ttfamily,
    commentstyle=\color{forestgreen}\ttfamily,
    stringstyle=\rmfamily,
    showstringspaces=false,
    breaklines=true,
    frame=lines,
    backgroundcolor=\color{lightergray},
    flexiblecolumns=true,
    escapeinside={(*}{*)},
    % numbers=left,
    numberstyle=\scriptsize, stepnumber=1, numbersep=5pt,
    % firstnumber=last,
}
\providecommand{\meta}[1]{$\langle${\normalfont\itshape#1}$\rangle$}
\lstset{moretexcs=%
    {
        cref,crefname,
        ccref,ccmarkart,
    }
}
\lstnewenvironment{code}%
{\setstretch{1.07}\LocallyStopLineNumbers%
\setkeys{lst}{columns=fullflexible,keepspaces=true}%
}
{\ResumeLineNumbers\vspace{-.5\baselineskip}}
\lstnewenvironment{code*}%
{\setstretch{1.07}\LocallyStopLineNumbers%
\setkeys{lst}{numbers=left,columns=fullflexible,keepspaces=true}%
}
{\ResumeLineNumbers}

%%================================
%% 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 = 0.3cm,
        after skip = 0.3cm,
        top = 3mm,
        bottom = 3mm,
        title={\scshape\sffamily #1}]%
}{\end{tcolorbox}\ResumeLineNumbers}

\newenvironment{demo}{%
    \LocallyStopLineNumbers%
    \begin{tcolorbox}[enhanced jigsaw,pad at break*=1mm,breakable,
        left=4mm,right=4mm,top=1mm,bottom=1mm,
        colback=gray!5!paper,boxrule=0pt,frame hidden,
        borderline west={1.5mm}{0mm}{gray!55!paper},arc=.7mm]%
}{\end{tcolorbox}\ResumeLineNumbers}



\newcommand{\ccrefpackage}{\textsf{ccref}}

\begin{document}

\title{\ccrefpackage{} - cleveref with proper definite articles}
\author{Jinwen XU}
\date{October 2021, in Paris}

\maketitle

\begin{abstract}
    \raggedleft
    The package \ccrefpackage{} is aimed at helping \lstinline|\cref| addressing the definite articles properly (especially for the article contractions in many European languages).
\end{abstract}

\section{The motivation}

By default, when using \textsf{cleveref}'s \lstinline|\cref| to reference theorem-like environments, the names do not contain definite articles. This may be acceptable for English, but certainly not good enough for languages such as French, Italian, Portuguese, Spanish, etc. -- in these cases there shall be grammatical errors and would give you a strong feeling that it is machine-generated.

As an example, if we define the French names to be:

\begin{code}
\crefname{theorem}{le théorème}{les théorème}
\crefname{proposition}{la proposition}{les propositions}
\end{code}

then when one writes (which means ``\emph{We can deduce this from ...}'' in French)

\begin{code}
On peut le déduire de \cref{thm1,thm2,prop3}.
\end{code}

the result would be

\begin{demo}
    On peut le déduire \textbf{de les} théorèmes 1 et 2 et \textbf{la} proposition 3.
\end{demo}

which is wrong, as the correct result should be:

\begin{demo}
    On peut le déduire \textbf{des} théorèmes 1 et 2 et \textbf{de la} proposition 3.
\end{demo}

\lstinline|\cref| cannot handle such cases correctly --- and that is when \lstinline|\ccref| comes into play.


\section{The usage}

\subsection[How to load it]{How to load it\,?}

Simply load the package with

\begin{code}
\usepackage{ccref}
\end{code}

\begin{tip}
    \begin{itemize}\small
        \item \ccrefpackage{} uses \textsf{cleveref} internally, thus it should usually be placed at the last of your preamble.
        \item To handle article contractions correctly, \lstinline|\ccref| shall detect the current language, thus you need to use packages such as \textsf{babel} or \textsf{polyglossia} to set your languages appropriately.
    \end{itemize}
\end{tip}

\subsection[How to use it]{How to use it\,?}

Then you can use the command \lstinline|\ccref| as follows:
\begin{itemize}
    \item \lstinline|\ccref[|\meta{prep}\lstinline|]{|\meta{labels}\lstinline|}|
    \begin{itemize}
        \item This will pass the preposition \meta{prep} to the first definite article.
    \end{itemize}
    \item \lstinline|\ccref*[|\meta{prep}\lstinline|]{|\meta{labels}\lstinline|}|
    \begin{itemize}
        \item This will pass the preposition \meta{prep} to every definite article.
    \end{itemize}
\end{itemize}

However, before using it, you should first define the \lstinline|\crefname|s carefully. The definite article in \lstinline|\crefname|s needs to be marked manually using \lstinline|\ccmarkart|, for example:

\begin{code}
\crefname{theorem}{\ccmarkart{le} théorème}{\ccmarkart{les} théorème}
\end{code}


\section{Example}

Let us come back to the example at the beginning, now you can do this:

\begin{code}
\crefname{theorem}{\ccmarkart{le} théorème}
                  {\ccmarkart{les} théorème}
\crefname{proposition}{\ccmarkart{le} proposition}
                      {\ccmarkart{les} propositions}
\end{code}

And the sentence shall be written as\footnote{Here the stared version is used because we want the preposition ``de'' to be passed to every definite article.}:

\begin{code}
On peut le déduire \ccref*[de]{thm1,thm2,prop3}.
\end{code}

which would result in:

\begin{demo}
    On peut le déduire \textbf{des} théorèmes 1 et 2 et \textbf{de la} proposition 3.
\end{demo}

As another example, with

\begin{code}
Pensez \ccref*[à]{thm1,thm2,prop3}.
\end{code}

one would get something like:

\begin{demo}
    Pensez \textbf{aux} théorèmes 1 et 2 et \textbf{à la} proposition 3.
\end{demo}



\section{Known issues}
\begin{itemize}
    \item \ccrefpackage{} currently only works for French, Italian, Portuguese (both European and Brazilian) and Spanish, certainly more would be added to this list.
    \item In the case that the initial letter of \meta{prep} is capitalized, \ccrefpackage{} cannot yet handle the case changes automatically. However, this should be a rare occurrence.
    \item The names of theorem-like environments are not provided --- for the moment you need to define them all by yourself. However, users are encouraged to use the \ProjLib{} toolkit, which already handles everything for you.
\end{itemize}


\end{document}