summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/crefthe/crefthe-doc.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2023-07-23 03:01:14 +0000
committerNorbert Preining <norbert@preining.info>2023-07-23 03:01:14 +0000
commit8e64fc98a1773bc22a0f010f106d56a028e48597 (patch)
tree29781e66044aca74e0a9fe7b15b9bedde97e5892 /macros/latex/contrib/crefthe/crefthe-doc.tex
parent05bb4f9ed131a04f54560a856dfbd7bc15981555 (diff)
CTAN sync 202307230301
Diffstat (limited to 'macros/latex/contrib/crefthe/crefthe-doc.tex')
-rw-r--r--macros/latex/contrib/crefthe/crefthe-doc.tex63
1 files changed, 56 insertions, 7 deletions
diff --git a/macros/latex/contrib/crefthe/crefthe-doc.tex b/macros/latex/contrib/crefthe/crefthe-doc.tex
index 44cd81fd5e..82d7460683 100644
--- a/macros/latex/contrib/crefthe/crefthe-doc.tex
+++ b/macros/latex/contrib/crefthe/crefthe-doc.tex
@@ -48,6 +48,7 @@
crefformat,
crefthe,crefthename,
Crefthe,Crefthename,
+ crefthevariantname,Crefthevariantname,
namecrefthe,namecrefsthe,
nameCrefthe,nameCrefsthe,
crefthemark,
@@ -116,12 +117,12 @@
\begin{document}
-\def\PackageVersion{2022/09/24}
+\def\PackageVersion{2023/07/22}
\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}
+\date{\TheDate{\PackageVersion}[only-year-month], in Beijing}
\maketitle
@@ -132,7 +133,7 @@
\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.
+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:
@@ -241,6 +242,38 @@ which would result in (provided that you have done \lstinline|\selectlanguage{fr
Voilà !
+\section{What about German}
+
+In German, there are four declensions: nominative (\texttt{Nominativ}), genitive (\texttt{Genitiv}), dative (\texttt{Dativ}) and accusative (\texttt{Akkusativ}), making the previously presented mechanism insufficient. For such situation, we introduce the command \lstinline|\crefthevariantname| to specify the referencing name for the correspond environment. Below is an example of usage:
+
+\begin{code}
+\crefthevariantname{theorem}
+ {
+ {Satz}{Sätze}
+ , Nominativ = [der]{Satz}[die]{Sätze}
+ , Genitiv = [des]{Satzes}[der]{Sätze}
+ , Dativ = [dem]{Satz}[den]{Sätzen}
+ , Akkusativ = [den]{Satz}[die]{Sätze}
+ }
+\end{code}
+
+The first line in the configuration is the default set of names when no variant is specified. It is recommended, though not required.
+
+After this, you may refer to a theorem via
+
+\begin{code}
+\crefthe[(*\meta{prep}*),variant=(*\meta{declension}*)]{(*\meta{label}*)}
+\end{code}
+
+You may also use the shortcuts (\texttt{nom.}, \texttt{gen.}, \texttt{dat.} and \texttt{akk.}), such as:
+
+\begin{code}
+\crefthe[(*\meta{prep}*),Nom]{(*\meta{label}*)} \crefthe[(*\meta{prep}*),Nom.]{(*\meta{label}*)}
+\crefthe[(*\meta{prep}*),nom]{(*\meta{label}*)} \crefthe[(*\meta{prep}*),nom.]{(*\meta{label}*)}
+\end{code}
+
+These four are all equivalent and you may choose one to use according to your preference.
+
\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
@@ -271,17 +304,33 @@ For those preset names defined with \lstinline|\crefname|\,/\,\lstinline|\Crefna
\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.
+\crefthepackage{} loads \textsf{cleveref} automatically and passes related options to it. All its commands, used without optional arguments, degenerate to those in \textsf{cleveref}. For example, \lstinline|\crefthe{...}|%
+will produce the same result as \lstinline|\cref{...}|, and \lstinline|\crefthename| shall behave the same as \lstinline|\crefname| if the definite articles are not specified. That said, you may 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|.
+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{Acknowledgement}
+
+There are so many people I wish to express my gratitude to during the development of this package, including:
+
+\begin{itemize}
+ \item Patrick Bideault, without whose advice and careful explanation, this package would probably never have been born. Merci !
+ \item Enrico Gregorio, Phelype Oleinik and Joseph Wright (in alphabetical order). They made valuable suggestions in the early development of this package and even edited some of the code themselves.
+ \item Jonathan P. Spratte, without whose help the German support would probably take much longer to complete.
+\end{itemize}
+
+
+% \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 \crefthepackage{} currently works for French, German, Italian, Portuguese (European and Brazilian) and Spanish --- certainly more languages would be added to this list in the future.
+ \item For now, you cannot specify the masculine/masculine/... of words. This means, for instance, that you cannot make the suffix adjective automatically adopted to the word when using \lstinline|\namecref| --- as an example, if you wish to say \textquote{la proposition suivante} (in French), you would have to write the feminine adjective manually. The situation should be improved with the introduction of a new key-value configuration system, which is currently on the todo-list.
+ 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}