summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/ccref/ccref-doc.tex
diff options
context:
space:
mode:
Diffstat (limited to 'macros/latex/contrib/ccref/ccref-doc.tex')
-rw-r--r--macros/latex/contrib/ccref/ccref-doc.tex210
1 files changed, 210 insertions, 0 deletions
diff --git a/macros/latex/contrib/ccref/ccref-doc.tex b/macros/latex/contrib/ccref/ccref-doc.tex
new file mode 100644
index 0000000000..992ff0f181
--- /dev/null
+++ b/macros/latex/contrib/ccref/ccref-doc.tex
@@ -0,0 +1,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}