%! TEX program = xelatex
\documentclass[classical]{einfart}

\linenumbers

\usepackage{ProjLib}

%%================================
%% 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 =
      {
        cref,crefname,
        Cref,Crefname,
        namecref,namecrefs,
        nameCref,nameCrefs,
        crefformat,
        crefthe,crefthename,
        Crefthe,Crefthename,
        namecrefthe,namecrefsthe,
        nameCrefthe,nameCrefsthe,
        crefthemark,
        crefthepatchname,
        selectlanguage,
      }
}
\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%
  }

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


\newcommand{\crefthepackage}{\textsf{crefthe}}

\begin{document}

\def\PackageVersion{2022/09/03}

\title{\crefthepackage{}\\\smallskip\itshape Cross referencing with proper definite articles}
\author{Jinwen XU}
\thanks{Corresponding to: \texttt{\crefthepackage{} \PackageVersion}}
\date{\TheDate{\PackageVersion}[only-year-month], in Paris}

\maketitle

\begin{abstract}
    \raggedleft
    The package \crefthepackage{} provides a command \lstinline|\crefthe| parallel to \textsf{cleveref}'s \lstinline|\cref| for handling definite articles properly (especially for the article contractions in some European languages).
\end{abstract}

\section{The motivation}

By default, with \textsf{cleveref}'s \lstinline|\cref| to reference theorem-like environments, the names do not contain definite articles. While this might be acceptable for English, it is 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.

However, even if we manually add the definite articles to the names, there would still be other problems. As an example, if we define the French names to be:

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

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

\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 automatically --- that is when \lstinline|\crefthe| comes into play.


\section{The usage}

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

Simply load the package with:

\begin{code}
\usepackage{crefthe}
\end{code}

\begin{tip}
    \begin{itemize}
        \item Since \crefthepackage{} uses \textsf{cleveref} internally, it should usually be placed at the last of your preamble, and notably, after \textsf{varioref} and \textsf{hyperref}.
        \item To handle article contractions correctly, \lstinline|\crefthe| shall detect the current language, thus you need to use packages such as \textsf{babel} or \textsf{polyglossia} to set your languages, and use commands like \lstinline|\selectlanguage| to select them appropriately.
    \end{itemize}
\end{tip}

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

Before everything, you need to define the names, which can be done with \lstinline|\crefthename|. Its syntax is similar to \lstinline|\crefname|, but now you can specify the definite articles, for example:

\begin{code}
\crefthename{theorem}[le]{théorème}[les]{théorèmes}
\end{code}

\begin{tip}
    The \lstinline|\crefthename|s should be placed in your preamble, otherwise the \lstinline|\cref| formats will not be set. These names can, however, be reset within the document body.
\end{tip}

Then you can use the command \lstinline|\crefthe| as follows:
\begin{itemize}[label=,leftmargin=1.25em,itemindent=-1.25em]
    \item \lstinline|\crefthe[|\meta{prep}\lstinline|]{|\meta{labels}\lstinline|}|
    \begin{itemize}
        \item This will pass the preposition \meta{prep} to the definite articles that follows. Its behavior depends on the current language (for example, in Spanish, \meta{prep} is passed only to the first definite article, while in French it is passed to everyone).
    \end{itemize}
    \item \lstinline|\crefthe-[|\meta{prep}\lstinline|]{|\meta{labels}\lstinline|}| and \lstinline|\crefthe+[|\meta{prep}\lstinline|]{|\meta{labels}\lstinline|}|
    \begin{itemize}
        \item In case the automatic version does not meet your needs, here are two manual ones. The \verb|-| version passes the preposition \meta{prep} only to the first definite article, while the \verb|+| version passes \meta{prep} to every definite article.
    \end{itemize}
\end{itemize}

\begin{tip}
    \begin{itemize}
        \item There is also a stared version \lstinline|\crefthe*| for generating the same referencing text without creating hyperlinks.
        \item The name-only relatives are also available: \lstinline|\namecrefthe| and \lstinline|\namecrefsthe|.
    \end{itemize}
\end{tip}

% 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|\crefthemark|, for example:

% \begin{code}
% \crefname{theorem}{\crefthemark{le} théorème}
%                   {\crefthemark{les} théorèmes}
% \end{code}


\section{Example}

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

\begin{code}
\crefthename{theorem}[le]{théorème}[les]{théorèmes}
\crefthename{proposition}[la]{proposition}[les]{propositions}
\end{code}

And the sentence shall be written as:

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

which would result in (provided that you have done \lstinline|\selectlanguage{french}|):

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

Voilà !

\section{Regarding the upper and lower cases}

As in \textsf{cleveref}, these commands have corresponding uppercased version: \lstinline|\Crefthename|,\linebreak \lstinline|\Crefthe|, \lstinline|\nameCrefthe| and \lstinline|\nameCrefsthe|, similar to \lstinline|\Crefname|, \lstinline|\Cref|, \lstinline|\nameCref|\linebreak and \lstinline|\nameCrefs|, reserved for using at the beginning of a sentence. \lstinline|\Crefthe| (and the name-only relatives) can handle case changing automatically: for example, with \lstinline|\Crefthe[À]{thm1,thm2,prop3}|, you will get something like

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

Of course you will have to define the \lstinline|\Crefthename|s separately, for example as:

\begin{code}
\Crefthename{theorem}[Le]{théorème}[Les]{théorèmes}
\Crefthename{proposition}[La]{proposition}[Les]{propositions}
\end{code}

\section{For writing multi-language documents}

To place hyperlinks at the correct place, \lstinline|\crefthename| touches the corresponding format macro \lstinline|\crefformat| internally, which makes the format language-dependent. If you are writing multi-language documents, you may consider putting \lstinline|\crefthename| inside your language configuration so as to reset it each time you select a new language.

\section{Dealing with existed \texttt{cref} / \texttt{Cref} names}

For those preset names defined with \lstinline|\crefname|\,/\,\lstinline|\Crefname|, such as the ones for \texttt{chapter}, \texttt{section} and \texttt{subsection}, etc., the optional argument of \lstinline|\crefthe|\,/\,\lstinline|\Crefthe| shall be useless: names defined with \lstinline|\crefthename|\,/\,\lstinline|\Crefthename| have a \lstinline|\crefthemark| marking the definite articles, which also deals with the given preposition ; without \lstinline|\crefthemark|, the preposition is simply ignored.

\lstinline|\crefthepatchname{|\meta{counters}\lstinline|}| is provided for this purpose. With this, an empty mark shall be added before the existed singular and plural names. However, it is still recommended to simply redefine the names with \lstinline|\crefthename|\,/\,\lstinline|\Crefthename|, especially in multilingual documents.

% For multilingual documents, you may need to add this to your language configuration so as to reapply it each time you select a new language.


\section{The relationship with \textsf{cleveref}}

\crefthepackage{} loads \textsf{cleveref} automatically and pass related options to it. All its commands, used without optional arguments, degenerate to those in \textsf{cleveref}. For example, \lstinline|\crefthe{...}| is the same as \lstinline|\cref{...}|, and \lstinline|\crefthename| is the same as \lstinline|\crefname| if the definite articles are not specified. That said, you can safely use the command \lstinline|\crefthe| everywhere in your document without causing extra trouble.

With the package option \packageoption{overwrite}, user commands in \textsf{cleveref} will be replaced by those offered here, thus you can simply write \lstinline|\cref| for \lstinline|\crefthe| -- and similarly with \lstinline|\Cref|, \lstinline|\crefname| and \lstinline|\Crefname|.


\clearpage

\section{Known issues}
\begin{itemize}
    \item \crefthepackage{} currently works for French, Italian, Portuguese (European and Brazilian) and Spanish, certainly more would be added to this list.
    \item The current mechanism does not work for German. The author plans to adopt a more refined approach in later versions in order to support the various situations in German. Meanwhile, you may consider the package \textsf{zref-clever}, which has a much more powerful and sophisticated interface for configuring cross referencing.
    \item The names of theorem-like environments are not provided here, you need to define them by yourself. However, users are encouraged to use the \ProjLib{} toolkit (more specifically, the internal package \textsf{create-theorem}), which already handles everything for you.
\end{itemize}

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


\end{document}