diff options
Diffstat (limited to 'macros/latex/contrib/ccref/ccref-doc.tex')
-rw-r--r-- | macros/latex/contrib/ccref/ccref-doc.tex | 210 |
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} |