xcref.dtx

% \iffalse meta-comment
% -*- coding: utf-8 -*-
%
% File: xcref.dtx Copyright (C) 2019, 2020  Florent Rougon
%
% This work may be distributed and/or modified under the
% conditions of the LaTeX Project Public License, either version 1.3
% of this license or (at your option) any later version.
% The latest version of this license is in the file
%
%   http://www.latex-project.org/lppl.txt
%
% and version 1.3 or later is part of all distributions of LaTeX
% version 2005/12/01 or later.
%
% This work has the LPPL maintenance status `maintained'.
%
% The Current Maintainer of this work is Florent Rougon.
%
% This file is part of "xcref" (The Work in LPPL) and all files from
% this Work must be distributed together.
%
% -----------------------------------------------------------------------
%
%<*driver>
% Loading inputenc here to be sure this comes before csquotes (which is loaded
% by l3doc).
\RequirePackage[utf8]{inputenc}
\documentclass{l3doc}
% The next line is needed so that \GetFileInfo will be able to pick up
% version data
\usepackage{xcref}
\usepackage{xparse}
\usepackage{amsmath}
\usepackage[svgnames]{xcolor}

\hypersetup{colorlinks=true, anchorcolor=Lime, linkcolor=RoyalBlue,
            urlcolor=Crimson}

% Let's define a few commands and environments used in the documentation
\ExplSyntaxOn
\makeatletter

% l3doc's \file command currently causes errors (on TL 2019)
\RenewExpandableDocumentCommand \file { m }
  { \texttt{#1} }
\NewDocumentCommand \xcrefPGFOpt { m }
  { \pgfkeyRef{/xcref/#1} }
\NewDocumentCommand \xcrefPGFPath { m } % for PGF “directories”
  { \texttt{/xcref/#1} }
\NewDocumentCommand \xcrefPGFRoot { }
  { \texttt{/xcref} }
\NewDocumentCommand \TikZ { }
  {
    \group_begin:
    \upshape Ti\textit{k}Z
    \group_end:
  }
\NewDocumentCommand \pkgOpt { m }
  { \texttt{#1} }

% Essentially copied from l3doc's texnote environment
\NewDocumentEnvironment { codersnote } { }
  {
    \endgraf
    \vspace{3mm}
    \small\textbf{Coders~note:\space}
    \ignorespaces
  }
  {
    \vspace{3mm}
  }

% ****************************************************************************
% *                         The 'pgfkey' environment                         *
% ****************************************************************************
\definecolor { xcrefdoc-keyname-in-def } { HTML } { 9400d3 }
\definecolor { xcrefdoc-keyname-in-ref } { HTML } { 48467c }
\colorlet { xcrefdoc-keyvalue } { black }

% Wrap a few TeX primitives we need
\cs_new_protected:Npn \__xcrefdoc_penalty:n #1
  {
    \tex_penalty:D #1 \scan_stop:
  }

\cs_new_protected:Npn \__xcrefdoc_nobreak:
  {
    \__xcrefdoc_penalty:n { 10000 }
  }

\cs_new_protected:Npn \__xcrefdoc_set_interlinepenalty:n #1
  {
    \tex_interlinepenalty:D = #1 \scan_stop:
  }

\cs_new_protected:Npn \__xcrefdoc_set_endlinechar:n #1
  {
    \tex_endlinechar:D = #1 \scan_stop:
  }

\cs_new_protected:Npn \__xcrefdoc_append_to_everypar:n #1
  {
    \tex_everypar:D = \exp_after:wN
      {
        \__xcrefdoc_the:w \tex_everypar:D
        #1
      }
  }

\cs_set_eq:NN \__xcrefdoc_par: \tex_par:D
\cs_set_eq:NN \__xcrefdoc_parfillskip_skip \tex_parfillskip:D
\cs_set_eq:NN \__xcrefdoc_parindent_dim \tex_parindent:D
\cs_set_eq:NN \__xcrefdoc_ignorespaces: \tex_ignorespaces:D
\cs_set_eq:NN \__xcrefdoc_scantokens:n \tex_scantokens:D
\cs_set_eq:NN \__xcrefdoc_the:w \tex_the:D
\cs_set_eq:NN \__xcrefdoc_unpenalty: \tex_unpenalty:D

% Options for use in the second argument of the 'pgfkey' environment
\keys_define:nn { xcrefdoc/pgfkey }
  {
    annotation~format .code:n =
      {
         \cs_set:Npn \__xcrefdoc_pgfkey_format_annotation:n ##1 {#1}
      },
    annotation~format .value_required:n = true,
  }

% How to format the annotation for a key. What we call “annotation” here is
% a phrase such as “no default, initially empty”.
\cs_new_protected:Npn \__xcrefdoc_pgfkey_format_annotation:n #1
  { ( {#1} ) }

% This 'pgfkey' environment supports a syntax similar to the tcolorbox
% 'docKey' environment (from the tcolorbox 'documentation' library), however
% the options handled in the third argument of \xcrefdoc_pgfkey_start:Nnnnnnn
% are completely different, and so is the implementation. The star form means
% “don't add this key to the index”. See \xcrefdoc_pgfkey_start:Nnnnnnn for a
% description of the arguments.
\NewDocumentEnvironment { pgfkey } { }
  {
    % We want to be able to use | to describe alternatives in the arguments of
    % \xcrefdoc_pgfkey_start_env, which *appear* as the arguments of this
    % environment.
    \DeleteShortVerb \"
    \DeleteShortVerb \|
    \xcrefdoc_pgfkey_start_env
  }
  { \xcrefdoc_pgfkey_end: }

\NewDocumentEnvironment { pgfkey* } { }
  {
    \DeleteShortVerb \"
    \DeleteShortVerb \|
    \xcrefdoc_pgfkey_start_env *
  }
  { \xcrefdoc_pgfkey_end: }

\NewDocumentCommand \xcrefdoc_pgfkey_start_env { s O{} O{} O{} m m +m }
  {
    \xcrefdoc_pgfkey_start:Nnnnnnn #1 {#2} {#3} {#5} {#6} {#7} {#4}
  }

% #1: anchor name
% #2: text
\cs_new_protected:Npn \__xcrefdoc_hypertarget:nn #1#2
  {
    \hypertarget {#1} {#2}
  }

% #1: anchor name
% #2: text
\cs_new_protected:Npn \__xcrefdoc_hyperlink:nn #1#2
  {
    \hyperlink {#1} {#2}
  }

\cs_generate_variant:Nn \__xcrefdoc_hypertarget:nn { x }
\cs_generate_variant:Nn \__xcrefdoc_hyperlink:nn { x }

% Start a \list item; print a key name/path and the value syntax, if any
% #1: key name or path
% #2: key value
% #3: disambigution string (only useful if #1 is not a full path)
\cs_new_protected:Npn \xcrefdoc_pgfkey_start_item:nnn #1#2#3
  {
    \item []
    % Remove the \penalty 0 added (via \everypar) by \@item after \box\@labels
    \__xcrefdoc_append_to_everypar:n { \__xcrefdoc_unpenalty: }
    \group_begin:              % group ended in \xcrefdoc_pgfkey_start:Nnnnnnn
    \mode_leave_vertical:
    \__xcrefdoc_set_interlinepenalty:n { 10000 }
    \skip_zero:N \__xcrefdoc_parfillskip_skip
    \raisebox { 0.9\baselineskip } [ 0pt ] [ 0pt ]
      {
        \__xcrefdoc_hypertarget:xn { \tl_to_str:n { xcrefdoc@pgfkey@#1@#3 } }
          { }
      }
    \xcrefdoc_pgfkey_format_key:n {#1}
    \xcrefdoc_pgfkey_format_value:n {#2}
  }

\cs_new_protected:Npn \__xcrefdoc_pgfkey_verb_like:n #1
  {
    \cs_set_eq:Nc \do { @makeother }
    \dospecials
    % Make spaces behave normally, not like the “visible space”
    \char_set_catcode_space:n { `~ }
    \use:c { @noligs }
    % Neutralize the final end-of-line of the pseudo-file internally read by
    % \scantokens (of course, we assume that #1 consists of only one line).
    \__xcrefdoc_set_endlinechar:n { -1 }
    \__xcrefdoc_scantokens:n {#1}
  }

\cs_new_protected:Npn \xcrefdoc_pgfkey_format_key:n #1
  {
    \textcolor { xcrefdoc-keyname-in-def }
      {
        \ttfamily \bfseries
        \__xcrefdoc_pgfkey_verb_like:n {#1}
      }
  }

\cs_new_protected:Npn \xcrefdoc_pgfkey_format_value:n #1
  {
    \textcolor { xcrefdoc-keyvalue } { \ttfamily #1 }
  }

\cs_generate_variant:Nn \xcrefdoc_pgfkey_start_item:nnn { V }

% Assembled key path
\str_new:N \l__xcrefdoc_pgfkey_start_key_str

% Start macro for the 'pgfkey' environment.
%
% The technique used for the paragraph containing the key name/path, value and
% annotation is inspired by the \signed macro described in the TeXbook p. 106.
%
% #1: boolean variable (\c_true_bool or \c_false_bool). True means “don't
%     index” and corresponds to the star form of the 'pgfkey' environment.
% #2: key base path (a slash is automatically prepended if this is non-empty)
% #3: options (only 'annotation format' is supported for now)
% #4: key leaf name, relative to the base path
% #5: =\marg{value} or something like that (printed right after the key name)
% #6: annotation for the key (printed flush right to the margin)
% #7: disambiguation string used in the anchor name. This is useful in case the
%     key is not given by full path and might have the same name as another key.
\cs_new_protected:Npn \xcrefdoc_pgfkey_start:Nnnnnnn #1#2#3#4#5#6#7
  {
    \group_begin:
    \keys_set:nn { xcrefdoc/pgfkey } {#3}
    \list { }
      {
        \dim_set:Nn { \leftmargin } { 2.5em } % or leave this to the class?
        \dim_zero:N \rightmargin
        \dim_zero:N \labelwidth
        \dim_zero:N \labelsep
        \dim_set:Nn { \itemindent } { -\leftmargin }
        \dim_zero:N \listparindent
      }

    \str_set:Nx \l__xcrefdoc_pgfkey_start_key_str
      {
        \tl_if_blank:nTF {#2}
          { \tl_to_str:n {#4} }
          { \tl_to_str:n {/#2/#4} }
      }
    % Print the key and value syntax, if any
    \xcrefdoc_pgfkey_start_item:Vnn \l__xcrefdoc_pgfkey_start_key_str {#5} {#7}

    \bool_if:NF #1 { \xcrefdoc_pgfkey_add_to_index: }

    \__xcrefdoc_nobreak:
    \skip_horizontal:n { 0pt plus 1fil }
    % We prefer having the annotation on the same line as the key, but if the
    % key is extremely long, the annotation may be postponed to the next line.
    \__xcrefdoc_penalty:n { 50 }
    % Ensure some minimal horizontal space between the key and its annotation.
    \skip_horizontal:n { 2em }
    \hbox:n {}   % make sure the following \penalty and glue won't be discarded
    \__xcrefdoc_nobreak:
    \skip_horizontal:n { 0pt plus 1fil }
    \__xcrefdoc_pgfkey_format_annotation:n {#6}
    \__xcrefdoc_par:
    % End the group started in \xcrefdoc_pgfkey_start_item:n. This restores
    % \interlinepenalty and \parfillskip.
    \group_end:
    \__xcrefdoc_nobreak:
    \skip_vertical:n { 0.5ex plus .05ex }
    % This can be used to make sure the key description starts with no
    % paragraph indentation, in case one has chosen a non-zero \listparindent.
    % \group_begin:
    %   \dim_zero:N \__xcrefdoc_parindent_dim
    %   \mode_leave_vertical:
    % \group_end:
    % Reinstate the shortverb chars we disabled when starting the environment
    \MakeShortVerb \"
    \MakeShortVerb \|
    \__xcrefdoc_ignorespaces:
  }

\cs_new_protected:Npn \xcrefdoc_pgfkey_end:
  {
    \endlist
    \group_end:
  }

\prg_generate_conditional_variant:Nnn \tl_if_head_eq_meaning:nN { V } { T }
\cs_generate_variant:Nn \__codedoc_special_index_set:Nn { NV }

\str_new:N \l__xcrefdoc_pati_escaped_for_sorting_str
\tl_new:N \l__xcrefdoc_pati_escaped_for_typesetting_tl

% XXX We use two private macros of l3doc here (those named \__codedoc_*). This
% has been tested with l3doc released on 2019-10-24.
\cs_new_protected:Npn \xcrefdoc_pgfkey_add_to_index:
  {
    \str_set_eq:NN \l__xcrefdoc_pati_escaped_for_sorting_str
      \l__xcrefdoc_pgfkey_start_key_str
    % Escape special characters in the sort key used for indexing purposes
    \__codedoc_quote_special_char:N \l__xcrefdoc_pati_escaped_for_sorting_str
    % We'll do the same for the token list used for typesetting the entry, but
    % let's first replace space tokens by control spaces. As a consequence,
    % “visible spaces” won't be used for the PGF key in the index and long
    % keys may be broken across lines.
    \tl_set_eq:NN \l__xcrefdoc_pati_escaped_for_typesetting_tl
      \l__xcrefdoc_pgfkey_start_key_str
    \tl_replace_all:Nnn \l__xcrefdoc_pati_escaped_for_typesetting_tl { ~ }
      { \use:c { ~ } }
    % Now escape the special characters
    \__codedoc_special_index_set:NV \l__xcrefdoc_pati_escaped_for_typesetting_tl
      \l__xcrefdoc_pati_escaped_for_typesetting_tl

    % Drop a 'hypdoc' anchor (hyperlink target)
    \use:c { HD@target }
    % Add an index entry that contains a hyperlink pointing to the anchor.
    % This entry is sorted under the letter P, as stipulated by the first
    % argument. The PGF key is added as a sub-entry of the top-level entry
    % “PGF keys”.
    \xcrefdoc_add_to_index_aux:n
      {
        % Sort key for the top-level entry
        PGF~keys
        \actualchar
        % Markup for the top-level entry. Get a ':' with catcode 12 to be
        % super clean (it would still work without the call to \tl_to_str:n).
        PGF~keys \tl_to_str:n { : }
        \levelchar
      }

    % Prepare to add a second index entry for the same PGF key
    \str_set_eq:NN \l__xcrefdoc_pati_escaped_for_sorting_str
      \l__xcrefdoc_pgfkey_start_key_str
    % If the first token of \l__xcrefdoc_pati_escaped_for_sorting_str is a
    % slash character, remove it.
    \tl_if_head_eq_meaning:VNT \l__xcrefdoc_pati_escaped_for_sorting_str /
      {
        \str_set:Nx \l__xcrefdoc_pati_escaped_for_sorting_str
          { \str_tail:N \l__xcrefdoc_pati_escaped_for_sorting_str }
      }
    \__codedoc_quote_special_char:N \l__xcrefdoc_pati_escaped_for_sorting_str

    % Add an index entry sorted according to the “PGF key with its leading
    % slash removed” (e.g., sorted as xcref/capitalize if the PGF key is
    % /xcref/capitalize). There is no sub-entry this time.
    \xcrefdoc_add_to_index_aux:n { }
  }

% Add an index entry for a PGF key (\l__xcrefdoc_pati_escaped_for_sorting_str
% and \l__xcrefdoc_pati_escaped_for_typesetting_tl are used). The argument of
% \index, and thus also the argument of \xcrefdoc_add_to_index_aux:n, are
% subject to recursive expansion as in \protected@write \@indexfile {} {...}
% (this is done by \@wrindex).
%
% #1: tokens inserted at the beginning of the argument of \index
\cs_new_protected:Npn \xcrefdoc_add_to_index_aux:n #1
  {
    \index
      {
        #1
        \l__xcrefdoc_pati_escaped_for_sorting_str % sort key
        \actualchar
          { % LaTeX markup
            \token_to_str:N \verbatim@font \c_space_tl
            \l__xcrefdoc_pati_escaped_for_typesetting_tl
          }
        \encapchar
        % Produce the page number in 'main' style (underlined), with hyperlink.
        hdclindex { \__xcrefdoc_the:w \use:c { c@HD@hypercount } } { main }
      }
  }

% How to format references to PGF keys produced by \xcrefdoc_pgfkeyref:nn
%
% #1: key name or path
\cs_new_protected:Npn \xcrefdoc_format_pgfkeyref:n #1
  {
    \group_begin:
      \ttfamily \__xcrefdoc_pgfkey_verb_like:n {#1}
    \group_end:
  }

% Write a hyperref-based reference (link) to key #2. #1 is a disambiguation
% string for the anchor name.
\cs_new_protected:Npn \xcrefdoc_pgfkeyref:nn #1#2
  {
    \group_begin:
      \hypersetup { linkcolor = xcrefdoc-keyname-in-ref }
      \__xcrefdoc_hyperlink:xn { \tl_to_str:n { xcrefdoc@pgfkey@#2@#1 } }
        { \xcrefdoc_format_pgfkeyref:n {#2} }
    \group_end:
  }

% Reference a PGF key defined somewhere with the 'pgfkey' environment or its
% starred form. Since the full path to a key should be enough to identify it,
% specifying a non-empty optional argument should only be useful for keys that
% have been presented without the full path (which is probably a bad idea,
% except maybe with deep hierarchies in the pgfkeys namespace...).
%
% #1: disambiguation string for the anchor name
% #2: key name or path
\NewDocumentCommand \pgfkeyRef { O{} m }
  {
    \xcrefdoc_pgfkeyref:nn {#1} {#2}
  }
% End of the code for the 'pgfkey' environment and related commands

\makeatother
\ExplSyntaxOff

\DoNotIndex{\ , \bool_gset_false:N, \bool_gset_true:N, \bool_set_false:N,
  \bool_set_true:N, \bool_lazy_and:nnT, \bool_new:N, \bool_if:NTF,
  \char_set_catcode_space:n, \clist_map_inline:nn, \cs:w, \cs_end:,
  \cs_generate_variant:Nn, \cs_new_protected:Npn, \cs_set:Npn,
  \cs_set_eq:NN, \if_meaning:w, \else:, \fi:, \documentclass, \exp_after:wN,
  \exp_args:No, \exp_not:N, \exp_not:n, \ExplSyntaxOn, \ExplSyntaxOff,
  \forestset, \pgfplotsset, \tikzset, \group_begin:, \group_end:, \input,
  \int_new:N, \int_set:Nn, \l_keys_key_tl, \makeatletter, \makeatother,
  \msg_error:nn, \msg_error:nnn, \msg_error:nnV, \msg_info:nnn, \msg_new:nnn,
  \NeedsTeXFormat, \NewDocumentCommand, \pgfkeys, \pgfqkeys, \keys_define:nn,
  \prg_new_conditional:Npnn, \prg_return_false:, \prg_return_true:,
  \ProcessKeysOptions, \prop_const_from_keyval:Nn, \prop_get:NnNTF,
  \prop_get:NnNF, \prop_get:NVNT, \prop_get:NVNF, \prop_gput:Nnn,
  \prop_set_from_keyval:Nn, \prop_gset_from_keyval:Nn, \prop_map_inline:Nn,
  \prop_new:N, \ProvidesExplPackage, \relax, \RequirePackage, \robustify,
  \seq_clear:N, \seq_gclear:N, \seq_gput_right:Nn, \seq_gput_right:Nx,
  \seq_gput_right:NV, \seq_if_in:NnTF, \seq_if_in:NVF, \seq_item:Nn,
  \seq_map_function:NN, \seq_map_inline:Nn, \seq_new:N, \seq_pop_left:NN,
  \seq_put_right:Nn, \seq_put_right:Nx, \seq_put_right:NV,
  \seq_set_split:Nnn, \seq_set_split:NnV, \l_tmpa_seq, \space,
  \c_colon_str, \str_case:nnTF, \str_case:nnF, \str_case:VnF,
  \str_if_empty:NTF, \str_if_empty:NT, \str_if_eq:nnTF, \str_if_eq:VnT,
  \str_new:N, \str_set:Nn, \str_set:Nx, \@firstofone, \@ifpackageloaded,
  \@onlypreamble, \protected@xdef, \xcref@tmpa, \tl_clear:N,
  \tl_if_empty:NTF, \tl_if_empty:NF, \tl_new:N, \tl_put_left:Nn,
  \tl_put_left:NV, \tl_put_right:Nn, \tl_put_right:NV, \tl_replace_all:Nnn,
  \tl_set:Nn, \tl_set:No, \tl_set:Nx, \tl_set_eq:NN, \tl_to_str:n,
  \l_tmpa_tl, \token_to_str:N, \use:c, \use:n}

\begin{document}
  \DocInput{\jobname.dtx}
\end{document}
%</driver>
% \fi
%
% \GetFileInfo{xcref.sty}
%
% \title{^^A
%   \pkg{xcref} -- Extension of \pkg{cleveref} for non-English languages^^A
%   \thanks{This file describes \pkg{xcref}~\fileversion, last revised
%           \filedate.}^^A
% }
%
% \author{^^A
%  Florent Rougon^^A
%  \thanks{^^A
%    E-mail: \href{mailto:f.rougon@free.fr}{mailto:f.rougon@free.fr}^^A
%   }^^A
% }
%
% \date{Released \filedate}
%
% \maketitle
%
% \begin{abstract}
%   In non-English languages, words such as prepositions and articles need to
%   be adapted in function of the noun they are used with, as well as possibly
%   in function of \enquote{cases} such as nominative, accusative, dative, and
%   genitive as used in German. As far as I know, these are things that
%   \pkg{cleveref} does not allow to do in any practical way, short of
%   programming it. This package works on top of \pkg{cleveref} and, given
%   language-specific knowledge as well as additional user input (at least to
%   select a preposition), it makes it possible to produce references that
%   cope with the various forms of ancillary words such as articles and
%   prepositions, and don't break when the underlying noun is changed (for
%   instance, from chapter to section or theorem to proposition).
% \end{abstract}
%
% \tableofcontents
%
% \begin{documentation}
% \vspace{6ex}
% WARNING: this is an alpha release. Some interfaces may change if they prove
% to be suboptimal. The documentation isn't finished. The code has received
% reasonable testing but might still have bugs.
%
% \section{Introduction}
%
% Generating cross-references to chapters, sections, theorems, lemmas, etc. in
% English is easy, because it can be done in a very simple and mechanical way
% (\enquote{see chapter~1}, \enquote{as we saw in section~2}, \enquote{an
% important consequence of theorems~3 and~4}, etc.). However, it can be more
% difficult in other languages, especially when you expect that the types of
% your references may change: a section might become a chapter after some
% reorganization of your work; a theorem could be downgraded to a proposition,
% etc.
%
% The \pkg{cleveref} package makes it easy to change reference types and have
% the names adapted, however its approach is too simple to work well with
% languages such as French and German. For instance, in French, \enquote{la
% section} would have to become \enquote{le chapitre}, but you can't just use
% \cs{crefname} to tell \cs{cref} to use |la section|, |le chapitre|, etc. as
% the \emph{names} associated to the |section| and |chapter| reference types,
% because depending on the preposition that is used, you need various forms:
% \enquote{\`a la section}, \enquote{au chapitre}, \enquote{de la section},
% \enquote{du chapitre}, \enquote{d'apr\`es la section}, \enquote{d'apr\`es le
% chapitre}, etc. Exactly the same happens with \enquote{th\'eor\`eme} and
% \enquote{proposition} (these are French words). Fortunately, there is enough
% regularity in how these various forms are produced to allow writing code
% that automatically produces correct French with input such as
% |\xcref[french/preposition=d'après]{some-label}|.
%
% Note that convenience wrappers are provided to shorten the previous command
% (see section~\ref{sec:language-specific-convenience-wrappers} and the
% example files) and that several labels can be used in the same command, when
% one wishes \pkg{cleveref} to combine them; this works especially well when
% all such labels are of the same type.
%
% Other languages have rules of the same kind and can also be nicely
% accomodated. For instance, with the |ngerman| module, one can reference two
% propositions with the \enquote{nach} preposition using code such as:
% \begin{verbatim}
% \xcref[ngerman/preposition=nach]{some-prop,other-prop}
% \end{verbatim}
% (again, there are convenience wrappers to make this shorter).
% \pkg{xcref} knows that \enquote{nach} is always followed by the dative case,
% so it will produce reference text such as \enquote{nach den Propositionen
% 3~und~4}. With the \xcrefPGFOpt{ngerman/form} option (which has its
% counterpart in the \texttt{french} module), one can obtain variant forms: in
% the same conditions,
% \begin{verbatim}
% \xcref[ngerman/form=article+noun]{some-prop,other-prop}
% \end{verbatim}
% would yield \enquote{den Propositionen 3~und~4} and
% \begin{verbatim}
% \xcref[ngerman/form=noun]{some-prop,other-prop}
% \end{verbatim}
% would produce \enquote{Propositionen 3~und~4} (exactly the same options are
% available in the \texttt{french} module along with the initial value
% |prep+article+noun|, however this may not fit all languages, hence the use
% of the \xcrefPGFPath{ngerman} and \xcrefPGFPath{french} namespaces for the
% |form| option). In German, it is
% also possible, and very often necessary, to indicate which case to use
% among nominative, accusative, dative and genitive, since in many cases,
% understanding the sentence is required to choose the appropriate case. This
% can be done using the \xcrefPGFOpt{ngerman/case} option which can take the
% values |nom|, |acc|, |dat|, and |gen|.
%
% \section{Installation}
%
% \subsection{Code}
%
% Installation of \pkg{xcref} can be done with the following steps:
% \begin{enumerate}
% \item Go to the directory containing |build.lua| and |xcref.dtx|.
% \item
%   \begin{enumerate}
%   \item If you have |l3build| and agree to install \pkg{xcref} in the
%     appropriate place under |TEXMFHOME|, run the command |l3build install|.
%
%     If you want to use a different base directory, you can pass the
%     |--texmfhome| option (e.g., |--texmfhome=|\meta{your~choice}) after
%     |l3build install|. In order to see which files would be installed
%     without actually installing them, run |l3build install --dry-run|. See
%     |texdoc l3build| for more details.
%   \item Otherwise, run |tex xcref.ins| (or |pdftex xcref.ins|, etc.) in
%     order to extract |xcref.sty| and the |xcref-*.tex| language modules from
%     |xcref.dtx| to the current directory (unless you have a |docstrip.cfg|
%     file that says otherwise, of course). Then, install the extracted files
%     as usual in a place listed in your |TEXINPUTS| and refresh the
%     \enquote{filename database} of your \TeX{} distribution if needed.
%   \end{enumerate}
% \end{enumerate}
%
% Once these steps have been performed, you should be able to build this
% document yourself (see below) and compile the \texttt{*.tex} files in the
% \texttt{examples} directory.
%
% \subsection{Documentation}
%
% In order to build the documentation (\texttt{xcref.pdf}), you need to have
% |xcref.sty| somewhere in your |TEXINPUTS|. How to do so is explained in the
% previous section. We'll assume you've already done that. There are
% essentially two ways to build he documentation. In either case, the first
% thing to do is to go to the directory containing |build.lua| and
% |xcref.dtx|.
%
% \subsubsection*{With \texttt{l3build}}
%
% This is the easiest way: simply run |l3build doc|.
%
% \subsubsection*{Without \texttt{l3build}}
%
% Run a \LaTeX-based engine on |xcref.dtx|. You also need to use |makeindex|
% to generate the index. For instance, the following command sequence is
% likely to produce a correct \pkg{xcref} manual:
% \begin{verbatim}
% pdflatex xcref.dtx
% makeindex -s gind.ist -o xcref.ind xcref.idx
% pdflatex xcref.dtx
% pdflatex xcref.dtx
% makeindex -s gind.ist -o xcref.ind xcref.idx
% pdflatex xcref.dtx
% \end{verbatim}
%
% \subsubsection*{Choosing a different paper size}
%
% Note: the following won't work unless your |l3doc.cls| is from 2019-09-18 or
% later (see
% \href{https://github.com/latex3/latex3/commit/ef39a40f586f8bec2464b4610e0d99c0f6411b6d}{\LaTeX3 commit ef39a40f586f}).
%
% \medskip
% In case you want the documentation to be produced in A4 format, create a
% file named |l3doc.cfg| in the directory containing |xcref.dtx|, with the
% following contents:
% \begin{verbatim}
% \PassOptionsToClass{a4paper}{l3doc}
% \end{verbatim}
% then run |l3build doc| as usual.
%
% \subsubsection*{Removing  generated files}
%
% You can remove generated files (not only from the documentation build) with
% the |l3build clean| command. Note: this will remove |xcref.pdf| too.
%
% \section{Usage}
%
% \subsection{Package options}
% \label{sec:package-options}
%
% The \pkg{xcref} package accepts only one fixed option, namely
% \pkgOpt{languages}. The other options are names of language modules, such as
% |french| and |ngerman|. The \pkgOpt{languages} option accepts a
% comma-separated list of languages, therefore the following are equivalent:
% \begin{itemize}
% \item
% \begin{verbatim}
% \usepackage[french, ngerman]{xcref}
% \end{verbatim}
% \item
% \begin{verbatim}
% \usepackage[languages={french, ngerman}]{xcref}
% \end{verbatim}
% \item
% \begin{verbatim}
% \usepackage{xcref}
% \xcrefusemodules{french, ngerman}
% \end{verbatim}
% \end{itemize}
%
% Language modules are loaded in the specified order in each of these three
% examples, but no module is loaded twice. Therefore,
% \begin{verbatim}
% \usepackage[ngerman,french,ngerman]{xcref}
% \end{verbatim}
% will load the \texttt{ngerman} module followed by the \texttt{french} module
% and stop there.
%
% Unless you intend to write \pkg{xcref}-managed cross-references in several
% languages, you only need to load one language module, and its name can very
% well be picked from the \tn[no-index]{documentclass} options. The language
% in which cross-references are written in the document is not determined by
% the load order of language modules, but by the current \pkg{babel} language
% at that point in the document or by the \xcrefPGFOpt{lang} PGF key if
% specified (which then takes precedence over the current \pkg{babel}
% language).
%
% \subsection{PGF keys}
%
% The options defined in this section are managed by \pkg{pgfkeys}. In what
% follows, they will be referred to as \emph{PGF keys}, or simply \emph{keys}.
% These options can be used in:
% \begin{itemize}
% \item the optional argument of \cs{xcref} (first argument of \cs{xcref:nn});
% \item the argument of \cs{xcrefset} (and thus of \cs{xcref_set:n}).
% \end{itemize}
%
% \subsubsection{Generic}
%
% \begin{pgfkey}[xcref]{capitalize}{=true|false}{default \texttt{true},
%                                                initially \texttt{false}}
%   When set to |true|, causes references to start with a capital letter.
%   Capitalization can be inhibited for specific parts of a reference text
%   by means of macros listed via \pgfkeyRef{/xcref/functions for preventing
%   auto case change}.
% \end{pgfkey}
%
% \begin{pgfkey}[xcref]{hyperlinks}{=true|false}{default \texttt{true},
%                                                initially \texttt{true}}
%   When \pkg{hyperref} is loaded, the value |true| causes \pkg{xcref} to use
%   hyperlinks in references.
% \end{pgfkey}
%
% \begin{pgfkey}[xcref]{lang}{=\meta{language}}{no default, initially empty}
%   Determine the language in which references are to be typeset. This doesn't
%   cause \pkg{xcref} to change the current \pkg{babel} or \pkg{polyglossia}
%   language---this aspect is entirely up to you. \meta{language} should be
%   either empty or the name of an \pkg{xcref} language module, such as
%   |french| or |ngerman| (so far, these are \pkg{babel} language names and
%   this will remain so unless there is a good reason to depart from this
%   naming scheme). If \meta{language} is empty, the language to use is
%   autodetected whenever \pkg{xcref} is asked to typeset a reference. This is
%   done with the \pkg{iflang} package and uses the language that is current
%   at the point where the reference is typeset.
%
%   Except for the empty value, only languages corresponding to an existing
%   \pkg{xcref} language module can be used as \meta{language}. Language
%   modules are stored in files named \texttt{xcref-\meta{language}.tex} next
%   to \file{xcref.sty} in
%   |$TEXMF/tex/latex/xcref|. Their source code can be found by looking for
%   markers such as |%<*french-module>| and |%<*ngerman-module>| in
%   \file{xcref.dtx}. When \pkg{xcref} is loaded, the \texttt{seq} variable
%   \cs{g_xcref_available_language_modules_seq} contains all available
%   language modules, and \cs{g_xcref_loaded_language_modules_seq} contains
%   all those that have been loaded so far (see \pkg{l3seq} in
%   \href{http://mirrors.ctan.org/macros/latex/contrib/l3kernel/interface3.pdf}{\file{interface3.pdf}}).
% \end{pgfkey}
%
% \begin{pgfkey}[xcref]{functions for preventing auto case change}
%               {=\meta{macros}}{no default, initially \cs{xcrefNoCaseChange}}
%   List of macros that prevent automatic case change on particular pieces of
%   text when references are capitalized (see~\pgfkeyRef{/xcref/capitalize}).
%   \meta{macros} should be one or more control sequence tokens. Each of these
%   tokens should be the name of a macro that accepts one argument. When
%   \cs{text_titlecase:nn} is called to capitalize a reference, each such macro
%   present in the reference text protects its argument from changes by
%   \cs{text_titlecase:nn}.
%
%   Note that \cs{text_titlecase:nn} doesn't expand the macros listed in
%   \meta{macros}; it only uses them to detect which parts of a reference text
%   mustn't be modified. The macro calls will be left as is in the reference
%   text; thus, a reasonable behavior for a macro listed in \meta{macros} is
%   to simply expand to its only argument. This is precisely what
%   \cs{xcrefNoCaseChange} does, which is defined to behave exactly like
%   \cs{use:n}. That said, you are free to define and use macros that do
%   something else with their argument: you might want them to typeset it in a
%   special font, use a particular color, etc.
% \end{pgfkey}
%
% \begin{pgfkey}[xcref]{lang for capitalization func}{=\meta{macro}}
%               {no default, initially \cs{xcrefDefaultMappingForTextTitleCase}}
%   Change the function used by \pkg{xcref} to map language module names to
%   language codes suitable for use with \cs{text_titlecase:nn}. The function
%   in question is called when producing a capitalized reference. See the
%   documentation of \cs{xcref_lang_for_text_titlecase:n} for the requirements
%   that apply to such a function.
% \end{pgfkey}
%
% \subsubsection{\texttt{french} langage module}
%
% \begin{pgfkey}[xcref/french]{form}{=\meta{form}}
%               {no default, initially \texttt{prep+article+noun}}
%   Specifies which grammatical form to use for references. The available
%   choices are |noun|, |article+noun| and |prep+article+noun|, where |prep|
%   stands for \enquote{preposition}.
% \end{pgfkey}
%
% \begin{pgfkey}[xcref/french]{preposition}{=\meta{prep}}
%               {no default, initially empty}
%   Preposition to use in references. When non-empty, \meta{prep} overrides
%   the default preposition associated to the reference type.
% \end{pgfkey}
%
% ^^A The initial value is intentionally not specified. What would be a really
% ^^A good initial value? This seems difficult to answer.
% \begin{pgfkey}[xcref/french]{names table}{=\meta{data}}{no default}
%   Define how to write each reference type in French. \meta{data} must be a
%   comma-separated list of (key, value) pairs, where each pair has the form
%   \texttt{\meta{reftype}=\meta{value}}. Each \meta{reftype} must be a
%   reference type and the corresponding \meta{value} should consist in four
%   items (see below), the first two of which must be in LICR
%   form.\footnote{This implies that in the first two items of each
%   \meta{value}, you should use syntax such as \texttt{\textbackslash `e} or
%   \texttt{\textbackslash 'e} instead of \texttt{é} or \texttt{è}.} In each
%   \meta{value}, the first item is the \emph{default preposition} for
%   reference type \meta{reftype}. Here is an example where, for instance, the
%   default preposition for reference type |assertion| is defined to be
%   |d'apr\`es| (which is typeset as \enquote{d'après}):
% \begin{verbatim}
% \xcrefset{
%   french/.cd,
%   names table = {
%     problem     = {\`a}{le}{problème}{problèmes},
%     proposition = {\`a}{la}{proposition}{propositions},
%     assertion   = {d'apr\`es}{l'}{assertion}{assertions},
%     theorem     = {\`a}{le}{théorème}{théorèmes},
%     lemma       = {\`a}{le}{lemme}{lemmes},
%     definition  = {dans}{la}{définition}{définitions},
%   }
% }
% \end{verbatim}
% Note: \pkg{xcref} knows that in French,
% $\texttt{\textbackslash `a} + \texttt{le}$ results in
% \enquote{au} in singular form and in \enquote{aux} in plural form, that the
% plural form of definite article |l'| is |les|, etc.
% \end{pgfkey}
%
% ^^A Is the current initial value (not documented here) the definitive one?
% \begin{pgfkey}[xcref/french]{composition table for prepositions and articles}
%               {=\meta{data}}{no default}
%   Define how a given preposition combines with the definite articles |l'|,
%   |le| , |la| and |les|. \meta{data} must be a comma-separated list of (key,
%   value) pairs, where each pair has the form
%   \texttt{\meta{prep}=\meta{value}}. Each \meta{prep} must be a preposition in
%   LICR form (see above) and the corresponding \meta{value} should consist in
%   four items. These items respectively indicate how to combine preposition
%   \meta{prep} with the definite articles |l'|, |le| , |la| and |les|.
%   Example:
% \begin{verbatim}
% \xcrefset{
%   french/.cd,
%   composition table for prepositions and articles = {
%     \`a    = {à l'}{au }{à la }{aux },
%     de     = {de l'}{du }{de la }{des },
%   }
% }
% \end{verbatim}
% \end{pgfkey}
%
% \subsubsection{\texttt{ngerman} langage module}
%
% \begin{pgfkey}[xcref/ngerman]{form}{=\meta{form}}
%               {no default, initially \texttt{prep+article+noun}}
%   Specifies which grammatical form to use for references. The available
%   choices are |noun|, |article+noun|, |prep+noun| and |prep+article+noun|,
%   where |prep| stands for \enquote{preposition}.
% \end{pgfkey}
%
% \begin{pgfkey}[xcref/ngerman]{preposition}{=\meta{prep}}
%               {no default, initially empty}
%   Preposition to use in references. When non-empty, \meta{prep} overrides
%   the default preposition associated to the reference type.
% \end{pgfkey}
%
% \begin{pgfkey}[xcref/ngerman]{case}{=\meta{case}}
%               {no default, no initial value}
%   Specify which case to use among nominative, accusative, dative and
%   genitive. The corresponding values for \meta{case} are respectively |nom|,
%   |acc|, |dat| and |gen|. Since there is no initial value, you must set this
%   key one way or another when typesetting references with \pkg{xcref}'s
%   \texttt{ngerman} module. An easy way to do that is to decide on a default
%   case for some part or all of your document (say, dative) and declare it
%   like this (\cs{xcrefset} respects \TeX's grouping rules):
% \begin{verbatim}
% \xcrefset{ngerman/case=dat}
% \end{verbatim}
% \end{pgfkey}
%
% \begin{pgfkey}[xcref/ngerman]{names table}{=\meta{data}}{no default}
%   Define how to write each reference type in German. \meta{data} must be a
%   comma-separated list of (key, value) pairs, where each pair has the form
%   \texttt{\meta{reftype}=\meta{value}}. Each \meta{reftype} must be a
%   reference type and the corresponding \meta{value} should consist in five
%   items. More precisely, each \meta{value} should be of the form:
%   \begin{quote}^^A One could use \Arg, but that wouldn't be really correct...
%     |{|\meta{default-prep}|}{|^^A
%        \meta{nominative}|}{|^^A
%        \meta{accusative}|}{|^^A
%        \meta{dative}|}{|^^A
%        \meta{genitive}|}|
%   \end{quote}
%   where \meta{default-prep} defines the default preposition\footnote{In LICR
%   form: for instance, \texttt{f\textbackslash \textquotedbl ur}.} for
%   reference type \meta{reftype} and each of the \meta{nominative},
%   \meta{accusative}, \meta{dative} and \meta{genitive} placeholders should
%   be of the form
%   |{|\meta{article-sing}|}{|\meta{noun-sing}|}{|\meta{article-plur}|}{|\meta{noun-plur}|}|,
%   where the four metasyntactic variables represent the definite article and
%   noun to use for reference type \meta{reftype} in singular and plural
%   forms, respectively. Like the default preposition \meta{default-prep},
%   each of the eight definite articles must be in LICR form. Here
%   is an example where, for instance, the default preposition for reference
%   type |proposition| is defined to be |nach|:
% \begin{verbatim}
% \xcrefset{
%   ngerman/.cd,
%   names table = {
%     problem    = {in}{{das}{Problem}{die}{Probleme}}%
%                    {{das}{Problem}{die}{Probleme}}%
%                    {{dem}{Problem}{den}{Problemen}}%
%                    {{des}{Problems}{der}{Probleme}},
%     proposition= {nach}{{die}{Proposition}{die}{Propositionen}}%
%                    {{die}{Proposition}{die}{Propositionen}}%
%                    {{der}{Proposition}{den}{Propositionen}}%
%                    {{der}{Proposition}{der}{Propositionen}},
%     satz       = {nach}{{der}{Satz}{die}{Sätze}}%
%                    {{den}{Satz}{die}{Sätze}}%
%                    {{dem}{Satz}{den}{Sätzen}}%
%                    {{des}{Satzes}{der}{Sätze}},
%   }
% }
% \end{verbatim}
%   Note: \pkg{xcref} knows that in German, $\texttt{in} + \texttt{dem}$
%   results in \texttt{im}, etc. (if something like this has been forgotten by
%   the package author, it just needs to be added to
%   \cs{l_xcref_ngerman_article_and_prep_prop}).
%
%   There is an \emph{initial} value, but I'm not sure it is a great idea to
%   set it in stone now by documenting it here.
% \end{pgfkey}
%
% \begin{pgfkey}[xcref/ngerman]{prepositions always followed by the same case}
%               {=\meta{data}}{no default}
%   \meta{data} must be a comma-separated list of (key, value) pairs, where
%   each pair has the form \texttt{\meta{prep}=\meta{case}}. Each such pair
%   declares that preposition \meta{prep} is always followed by \meta{case}
%   (this overrides \xcrefPGFOpt{ngerman/case}). Each \meta{prep} must be
%   given in LICR form and each \meta{case} must be one of
%   \texttt{nominative}, \texttt{accusative}, \texttt{dative} and
%   \texttt{genitive}.
%
%   There is an \emph{initial} value, but I'm not sure it is a great idea to
%   set it in stone now by documenting it here.
% \end{pgfkey}
%
% \begin{pgfkey}[xcref/ngerman]{composition table for prepositions and articles}
%               {=\meta{data}}{no default}
%   Define how a given preposition combines with the definite article, in the
%   cases where simple concatenation with a space doesn't give the correct
%   result. For instance, |in dem = im| must be declared here if one wants to
%   have this contraction instead of \texttt{in dem}; on the other hand, since
%   \texttt{in der} can be obtained by simple concatenation, it doesn't need
%   to (and should not) be specified here.
%
%   \meta{data} must be a comma-separated list of (key, value) pairs, where
%   each pair has the form \texttt{\meta{key}=\meta{value}}. Each \meta{key}
%   must be written in LICR form.\footnote{For instance, should you want to
%   use the preposition \enquote{für} inside a \meta{key}, it would have to be
%   written as \texttt{f\textbackslash \textquotedbl ur}, not \texttt{für}.}
%   As an example, the initial value of \xcrefPGFOpt{ngerman/composition table
%   for prepositions and articles} at the time of this writing is equivalent
%   to the following setting:
% \begin{verbatim}
% \xcrefset{
%   ngerman/.cd,
%   composition table for prepositions and articles = {
%     an dem = am,
%     in dem = im,
%     von dem = vom,
%     zu dem = zum,
%     zu der = zur,
%     bei dem = beim,
%   }
% }
% \end{verbatim}
%   While this is currently the initial value, it may be unwise to expect it
%   to always remain the same---I wrote this initial setting and am not a
%   native German speaker, thus the initial setting might receive improvements
%   in the future. If you want to be preserved from future changes, specify
%   the desired value yourself in your documents (possibly in a personal style
%   file) using an |\xcrefset| call as shown above.
% \end{pgfkey}
%
% \subsection{Generic macros}
%
% \begin{function}{\xcrefusemodules, \xcref_use_modules:n,
%                  \xcref_use_module:n, \xcref_use_module:V}
%   \begin{syntax}
%     \cs{xcrefusemodules}|{|\meta{language_1},\ldots,\meta{language_n}|}|
%     \cs{xcref_use_modules:n} |{|\meta{language_1},\ldots,\meta{language_n}|}|
%     \cs{xcref_use_module:n} \Arg{language}
%   \end{syntax}
%   Add the specified languages to the list of requested language-specific
%   modules. Example values for the language metasyntactic variables are
%   \texttt{french} and \texttt{ngerman}. These commands can only be used in
%   the preamble.
% \end{function}
%
% \begin{function}{\xcref, \xcref:nn}
%   \begin{syntax}
%     \cs{xcref}\oarg{options}\marg{comma-separated list of references}
%     \cs{xcref:nn} \Arg{options} \Arg{comma-separated list of references}
%   \end{syntax}
%   \pkg{xcref}'s equivalent of \cs{cref}, \cs{Cref} and starred forms of
%   these.
%
%   The \meta{options} are processed with \pkg{pgfkeys} with a default path of
%   \xcrefPGFRoot. The references are passed as is to \cs{cref} or \cs{Cref},
%   depending on the value of \xcrefPGFOpt{capitalize} (a starred form is
%   called if the \xcrefPGFOpt{hyperlinks} option is |false| and
%   \pkg{hyperref} is loaded).
%
%   Spaces around unbraced commas and equal signs are ignored in
%   \meta{options} because this argument is processed by \pkg{pgfkeys}, but
%   they are \emph{not} ignored in \meta{comma-separated list of references}
%   (this is the behavior of \pkg{cleveref}).
% \end{function}
%
% \begin{function}{\xcrefset, \xcref_set:n}
%   \begin{syntax}
%     \cs{xcrefset}\marg{key-value assignments}
%     \cs{xcref_set:n} \Arg{key-value assignments}
%   \end{syntax}
%   Set PGF keys related to \pkg{xcref}. For now, these keys only influence
%   \cs{xcref}. The \meta{key-value assignments} are comma-separated
%   assignments such as |ngerman/case=acc|. These commands are analogous to
%   \cs[no-index]{tikzset} from the \TikZ\ package, \cs[no-index]{forestset}
%   from \pkg{forest}, \cs[no-index]{pgfplotsset} from \pkg{pgfplots}, etc.
%   For instance, the command
% \begin{verbatim}
% \xcrefset{ngerman/case=acc}
% \end{verbatim}
% is equivalent to
% \begin{verbatim}
% \pgfkeys{/xcref/ngerman/case=acc}
% \end{verbatim}
% and has the effect of calling the \xcrefPGFOpt{ngerman/case} PGF key with
% the value |acc|.
% \end{function}
%
% \begin{function}{\xcrefNoCaseChange}
%   \begin{syntax}
%     \cs{xcrefNoCaseChange}\marg{text}
%   \end{syntax}
%   Locally inhibit conversion in the second argument of
%   \cs{text_titlecase:nn}. When references are automatically captitalized,
%   \cs{text_titlecase:nn} is called and can cause various, \emph{a priori}
%   non-first characters in the texts eventually passed to \cs{Crefname}, to
%   be changed to lowercase. In some cases, this is undesirable (for instance,
%   in German, nouns always start with a capital letter; converting a noun to
%   lowercase would be a mistake). For such situations, \cs{xcrefNoCaseChange},
%   or any user-specified macro passed to
%   \xcrefPGFOpt{functions for preventing auto case change},
%   can be used in the texts that are destined to be passed to \cs{Crefname}:
%   it \enquote{protects} its argument against any action from
%   \cs{text_titlecase:nn}. For example, \file{xcref-ngeman.tex} uses this
%   technique to protect everything after the first word of a capitalized
%   reference.
%
%   The macro call isn't removed by \cs{text_titlecase:nn}, therefore if you
%   want such protection macros that do \enquote{funny things} (contrary to
%   \cs{xcrefNoCaseChange} which returns its argument unchanged), it is
%   possible by passing your own macro names to
%   \xcrefPGFOpt{functions for preventing auto case change}.
% \end{function}
%
% \begin{function}{\xcref@tabacckludge}
%   \begin{syntax}
%     \cs{xcref@tabacckludge}\meta{accent}\meta{character token}
%   \end{syntax}
%   Variant of \cs{@tabacckludge} that doesn't expand inside \tn{edef},
%   \cs{text_titlecase:nn}, etc. (it is \tn{protected}). Apart from this
%   aspect, it works like \cs{@tabacckludge} and avoids problems due to the
%   fact that the \env{tabbing} environment redefines \tn{'}, \tn{`} and
%   \tn{=} (see the \pkg{inputenc} documentation).
%
%   This command is useful in \texttt{xcref.sty} and its language-specific
%   modules, but in documents, users can use \pkg{inputenc} and for instance
%   accented characters encoded in \mbox{UTF-8} instead; this works as well
%   and is usually more readable (the reason why we need
%   \cs{xcref@tabacckludge} here is that we refrain from loading
%   \pkg{inputenc} ourselves).
% \end{function}
%
% \subsection{Language-specific convenience wrappers}
% \label{sec:language-specific-convenience-wrappers}
%
% \subsubsection{\texttt{french} langage module}
%
% \begin{function}{\xcreffrenchgenericwrapper}
%   \begin{syntax}
%     \cs{xcreffrenchgenericwrapper} \Arg{generic options} \Arg{language-specific options}
%   \end{syntax}
%   XXX documentation needed
% \end{function}
%
% \begin{function}{\xcreffrenchwrapper, \xcreffrenchWrapper}
%   \begin{syntax}
%     \cs{xcreffrenchwrapper} \Arg{language-specific options}
%     \cs{xcreffrenchWrapper} \Arg{language-specific options}
%   \end{syntax}
%   XXX documentation needed
% \end{function}
%
% \subsubsection{\texttt{ngerman} langage module}
%
% \begin{function}{\xcrefngermangenericwrapper}
%   \begin{syntax}
%     \cs{xcrefngermangenericwrapper} \Arg{generic options} \Arg{lang-specific options}
%   \end{syntax}
%   XXX documentation needed
% \end{function}
%
% \begin{function}{\xcrefngermanwrapper, \xcrefngermanWrapper}
%   \begin{syntax}
%     \cs{xcrefngermanwrapper} \Arg{language-specific options}
%     \cs{xcrefngermanWrapper} \Arg{language-specific options}
%   \end{syntax}
%   XXX documentation needed
% \end{function}
%
% \subsection{Defining how references are to be printed}
% \label{sec:defining-how-references-are-to-be-printed}
%
% The commands in this section can be seen as analogous to \cs{crefname} and
% \cs{Crefname}; their arguments are usually a bit more complex than those of
% \cs{crefname} and \cs{Crefname}, though, since they can do more subtle
% language-specific work than what the \pkg{cleveref} commands allow out of
% the box. Another important difference with the \pkg{cleveref} commands is
% that the commands presented in this section can only be used in the
% preamble.
%
% \subsubsection{\texttt{french} langage module}
%
% \begin{function}{\xcreffrenchSetNamesTableEntry}
%   \begin{syntax}
%     \cs{xcreffrenchSetNamesTableEntry} \Arg{reftype} \Arg{prep} \Arg{article} \Arg{singular} \Arg{plural}
%   \end{syntax}
%   Define how to print references of type \meta{reftype}. This function
%   associates four token lists to reference type \meta{reftype}, which could
%   be something such as |section|, |chapter| or |theorem|:
%   \begin{itemize}
%   \item a default preposition in LICR form, for instance |d'apr\`es|;
%   \item a definite article for the singular form, among |l'|, |le| and |la|;
%   \item the singular form of the corresponding noun (e.g., |théorème|);
%   \item the plural form of the same noun (e.g., |théorèmes|).
%   \end{itemize}
%   This function can only be used in the preamble and overrides any previous
%   setting for the same reference type.
% \end{function}
%
% \subsubsection{\texttt{ngerman} langage module}
%
% \begin{function}{\xcrefngermanSetNamesTableEntry}
%   \begin{syntax}
%     \cs{xcrefngermanSetNamesTableEntry} \Arg{reftype} \Arg{prep} \Arg{nominative} \Arg{accusative} \Arg{dative} \Arg{genitive}
%   \end{syntax}
%   Define how to print references of type \meta{reftype}. This function
%   associates five token lists to reference type \meta{reftype}, which could
%   be something such as |section|, |chapter| or |theorem|:
%   \begin{itemize}
%   \item a default preposition in LICR form, for instance |f\"ur|;
%   \item \meta{nominative}, \meta{accusative}, \meta{dative} and
%     \meta{genitive} forms as specified below.
%   \end{itemize}
%   Each of the \meta{nominative}, \meta{accusative}, \meta{dative} and
%   \meta{genitive} arguments should be of the form
%   |{|\meta{article-sing}|}{|\meta{noun-sing}|}{|\meta{article-plur}|}{|\meta{noun-plur}|}|,
%   where the four metasyntactic variables represent the definite article and
%   noun to use for reference type \meta{reftype} in singular and plural forms,
%   respectively.
%
%   This function can only be used in the preamble and overrides any previous
%   setting for the same reference type.
% \end{function}
%
% \section{Code-level functions}
%
% \subsection{Generic}
%
% \begin{function}{\xcref_lang_for_text_titlecase:n,
%                  \xcref_lang_for_text_titlecase:V,
%                  \xcref_lang_for_text_titlecase_default:n,
%                  \xcrefDefaultMappingForTextTitleCase}
%   \begin{syntax}
%     \cs{xcref_lang_for_text_titlecase:n} \Arg{language}
%     \cs{xcref_lang_for_text_titlecase_default:n} \Arg{language}
%     \cs{xcrefDefaultMappingForTextTitleCase} \marg{language}
%   \end{syntax}
%   When references have to be capitalized (cf.~\xcrefPGFOpt{capitalize}), the
%   \pkg{expl3} function \cs{text_titlecase:nn} is used. This function accepts
%   a \enquote{language code} argument to adapt to each language, because this
%   process can vary depending on the language (for instance, it appears that
%   in Dutch, capitalisation of \texttt{ij} at the beginning of mixed cased
%   text produces \texttt{IJ} rather than \texttt{Ij}). However, the language
%   codes used by \cs{text_titlecase:nn} don't coincide with \pkg{xcref}'s
%   language-specific module names---which currently are identical to
%   \pkg{babel} language names. Therefore, \pkg{xcref} uses a function, namely
%   \cs{xcref_lang_for_text_titlecase:n}, to map \pkg{xcref} language module
%   names to suitable language codes for use with \cs{text_titlecase:nn}. By
%   default, this function is \tn{let}-equal to
%   \cs{xcref_lang_for_text_titlecase_default:n}, or
%   \cs{xcrefDefaultMappingForTextTitleCase} in the \LaTeXe{} naming style. It
%   accepts one argument which must be an \pkg{xcref} language module name
%   (e.g., \texttt{ngerman}) and expands (as in \tn{edef}) to a language code
%   suitable for use with \cs{text_titlecase:nn}.
%
%   Should the mapping provided by \cs{xcref_lang_for_text_titlecase_default:n}
%   be incomplete, you should probably contact the package maintainer and
%   suggest an update. However, it is also possible to change the meaning of
%   \cs{xcref_lang_for_text_titlecase:n} (\emph{i.e.,} redefine it) in order to
%   use the mapping function of your choice. For this, simply use the
%   \xcrefPGFOpt{lang for capitalization func} option to point to the
%   expandable macro of your choice.
% \end{function}
%
% \subsection{Language-specific}
%
% \subsubsection{From the \texttt{french} module}
%
% \begin{function}{\xcref_french_set_names_table_entry:nnnnn}
%   \begin{syntax}
%     \cs{xcref_french_set_names_table_entry:nnnnn} \Arg{reftype} \Arg{prep} \Arg{article} \Arg{singular} \Arg{plural}
%   \end{syntax}
%   This is the code-level counterpart of \cs{xcreffrenchSetNamesTableEntry}.
% \end{function}
%
% \begin{function}{\xcref_french_assemble_prep_and_article:nnN,
%                  \xcref_french_assemble_prep_and_article:VnN,
%                  \xcref_french_assemble_prep_and_article:VVN}
%   \begin{syntax}
%     \cs{xcref_french_assemble_prep_and_article:nnN} \Arg{preposition} \Arg{article} \meta{tl~var}
%   \end{syntax}
%   Assemble a preposition and a definite article. In some cases,
%   this means combining them into a single word. Any accented characters in
%   \meta{preposition} must be in LICR form. \meta{article} has to be
%   one of |l'|, |le|, |la| and |les|. The result is stored in \meta{tl~var};
%   in case it is incorrect, it is likely that more exceptions need to be
%   added to \cs{g__xcref_french_prep_and_article_prop}.
% \end{function}
%
% \subsubsection{From the \texttt{ngerman} module}
%
% \begin{function}{\xcref_ngerman_set_names_table_entry:nnnnnn}
%   \begin{syntax}
%     \cs{xcref_ngerman_set_names_table_entry:nnnnnn} \Arg{reftype} \Arg{prep} \Arg{nominative} \Arg{accusative} \Arg{dative} \Arg{genitive}
%   \end{syntax}
%   This is the code-level counterpart of \cs{xcrefngermanSetNamesTableEntry}.
% \end{function}
%
% \begin{function}{\xcref_ngerman_assemble_prep_and_article:nnN,
%                  \xcref_ngerman_assemble_prep_and_article:VVN}
%   \begin{syntax}
%     \cs{xcref_ngerman_assemble_prep_and_article:nnN} \Arg{preposition} \Arg{article} \meta{tl~var}
%   \end{syntax}
%   Assemble a preposition and a definite article. In some cases, this means
%   combining them into a single word. In case
%   \meta{preposition}\textvisiblespace\meta{article} is a key of
%   \cs{l__xcref_ngerman_article_and_prep_prop} (with eventual accented
%   characters in LICR form), the result is the corresponding value;
%   otherwise, the result is
%   \meta{preposition}\textvisiblespace\meta{article}. In any case, it is
%   stored in \meta{tl~var}.
% \end{function}
%
% \section{Public variables}
%
% \begin{variable}{\g_xcref_available_language_modules_seq}
%   List of the available language-specific modules. Example items are
%   \texttt{french} and \texttt{ngerman}. Each of these is made of
%   character tokens with category code~12 only (other).
% \end{variable}
%
% \begin{variable}{\g_xcref_loaded_language_modules_seq}
%   List of the language-specific modules that have been loaded. Each element
%   is a \pkg{babel} language name, is not allowed to contain any space and
%   only contains character tokens of category code~12.
% \end{variable}
%
% \end{documentation}
%
%
% \section{Development repository}
% \label{sec:development-repository}
%
% The Git repository containing the \pkg{xcref} source code is located at
% \url{https://github.com/frougon/xcref}.
%
% \begin{implementation}
%
% \section{\pkg{xcref} Implementation}
% \label{sec:implementation}
%
% \subsection{\file{xcref.sty}}
%
% \pkg{DocStrip} start guard for \file{xcref.sty}.
%    \begin{macrocode}
%<*package>
%    \end{macrocode}
%
% Identify the internal prefix (\LaTeX3 \pkg{DocStrip} convention).
%    \begin{macrocode}
%<@@=xcref>
%    \end{macrocode}
%
%    \begin{macrocode}
\NeedsTeXFormat{LaTeX2e}[1995/12/01]
\RequirePackage{expl3}
\RequirePackage{l3keys2e}
\RequirePackage{xparse}
\RequirePackage{etoolbox}
\RequirePackage{iflang}
\RequirePackage{pgfkeys}
\RequirePackage{cleveref}
%    \end{macrocode}
% \pkg{xcref} is an \pkg{expl3}-based package, declare its metadata.
%    \begin{macrocode}
\ProvidesExplPackage{xcref}{2019-09-19}{0.1a}
                    {Extension of cleveref for non-English languages}
%    \end{macrocode}
%
% \subsubsection{\pkg{expl3} messages}
%
% Messages emitted by \file{xcref.sty}:
%    \begin{macrocode}
\msg_new:nnn { xcref } { loading-language-module }
  { Loading~language~module~'\exp_not:n {#1}'. }
\msg_new:nnn { xcref } { unable-to-determine-language }
  { Unable~to~determine~the~language. }
%    \end{macrocode}
%
% \subsubsection{Variables}
%
% \begin{variable}{\g_xcref_available_language_modules_seq}
%   List of the available language-specific modules. For consistency with
%   \cs{g_xcref_loaded_language_modules_seq}, each item is obtained with
%   \cs[no-index]{tl_to_str:n}.
%    \begin{macrocode}
\seq_new:N \g_xcref_available_language_modules_seq

\clist_map_inline:nn { french, ngerman }
  {
    \seq_gput_right:Nx \g_xcref_available_language_modules_seq
      { \tl_to_str:n {#1} }
  }
%    \end{macrocode}
% \end{variable}
% \begin{variable}{\g_xcref_loaded_language_modules_seq}
%   List of the loaded language-specific modules.
%    \begin{macrocode}
\seq_new:N \g_xcref_loaded_language_modules_seq
%    \end{macrocode}
% \end{variable}
% \begin{variable}{\l_@@_selected_lang_str}
%   Name of the currently-selected language for \pkg{xcref}. It must be the
%   name of a language-specific module.
%    \begin{macrocode}
\str_new:N \l_@@_selected_lang_str
%    \end{macrocode}
% \end{variable}
% \begin{variable}{\l_@@_use_hyperlinks_bool}
% Whether to use hyperlinks in references generated by \pkg{xcref} when
% \pkg{hyperref} is loaded.
%    \begin{macrocode}
\bool_new:N \l_@@_use_hyperlinks_bool
%    \end{macrocode}
% \end{variable}
% \begin{variable}{\l_@@_case_change_exclude_tl}
%   List of commands (control sequence tokens) that indicate contents which
%   mustn't be affected by an automatic case change (when
%   \cs{text_titlecase:nn} is used to automatically capitalize text, before
%   passing it to \cs{Crefname}). See the documentation of
%   \cs{xcrefNoCaseChange}.
%    \begin{macrocode}
\tl_new:N \l_@@_case_change_exclude_tl
%    \end{macrocode}
% \end{variable}
% \begin{variable}{\l_@@_capitalize_bool}
%   Whether to write references in capitalized form (first letter in
%   uppercase, the rest in lowercase\footnote{Well, this can be subtler than
%   that depending on the language---see the documentation of
%   \cs[no-index]{text_titlecase:nn}.}).
%    \begin{macrocode}
\bool_new:N \l_@@_capitalize_bool
%    \end{macrocode}
% \end{variable}
% \begin{variable}{\g_@@_hyperref_loaded_bool}
%   Whether \pkg{hyperref} is loaded.
%    \begin{macrocode}
\bool_new:N \g_@@_hyperref_loaded_bool
%    \end{macrocode}
% \end{variable}
%
% \subsubsection{Interaction with \pkg{hyperref}}
%
% Remember if \pkg{hyperref} is loaded: if so and if the
% \xcrefPGFOpt{hyperlinks} option is false, we'll have to use the starred form
% of \cs{cref} and \cs{Cref}.
%    \begin{macrocode}
\AtBeginDocument
  {
    \@ifpackageloaded { hyperref }
      { \bool_gset_true:N \g_@@_hyperref_loaded_bool }
      { \bool_gset_false:N \g_@@_hyperref_loaded_bool }
  }
%    \end{macrocode}
%
% \subsubsection{Loading of langage-specific modules}
%
% \begin{macro}{\xcref_use_module:n, \xcref_use_module:V}
%   \begin{arguments}
%     \item name of a language-specific module
%   \end{arguments}
%   Load a langage-specific module unless it is already loaded. One subtlety
%   here: if a language name such as \texttt{french} is passed as a
%   \tn[no-index]{documentclass} option, it arrives here in |#1| with
%   character tokens of category code~12. However, the same option passed to
%   the \pkg{xcref} package would cause |#1| to contain character tokens of
%   category code~11. Thus, we use \cs[no-index]{tl_to_str:n} on |#1| to
%   normalize this input (the elements of
%   \cs{g_xcref_loaded_language_modules_seq} are therefore made of character
%   tokens of category code~12, since they can't contain any space).
%    \begin{macrocode}
\cs_new_protected:Npn \xcref_use_module:n #1
  {
    \tl_set:Nx \l_tmpa_tl { \tl_to_str:n {#1} }

    \seq_if_in:NVF \g_xcref_loaded_language_modules_seq \l_tmpa_tl
      {
        \@@_load_module:n {#1}
        \seq_gput_right:NV \g_xcref_loaded_language_modules_seq \l_tmpa_tl
      }
  }

\@onlypreamble \xcref_use_module:n
\cs_generate_variant:Nn \xcref_use_module:n { V }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\xcref_use_modules:n, \xcrefusemodules}
%   \begin{arguments}
%     \item comma-separated list of language-specific module names
%   \end{arguments}
%    \begin{macrocode}
\cs_new_protected:Npn \xcref_use_modules:n #1
  {
    \clist_map_inline:nn {#1} { \xcref_use_module:n {##1} }
  }

\NewDocumentCommand \xcrefusemodules { m }
  {
    \xcref_use_modules:n {#1}
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_load_module:n}
%   \tn[no-index]{input} the specified language-specific module. This is done
%   under the \enquote{traditional} category code régime for \LaTeXe{}
%   packages.
%   \begin{arguments}
%     \item language name corresponding to the module
%   \end{arguments}
%    \begin{macrocode}
\cs_new_protected:Npn \@@_load_module:n #1
  {
    \makeatletter
    \msg_info:nnn { xcref } { loading-language-module } {#1}
    \input { xcref-#1.tex }
    \makeatother
  }
%    \end{macrocode}
% \end{macro}
%
% \subsubsection{Main code}
%
% \begin{macro}{\@@_set_to_licr_form:Nn}
%   Get the LICR form of a token list representing text.
%   \begin{arguments}
%     \item token list variable
%     \item token list representing text
%   \end{arguments}
%   Set |#1| to the LICR form of |#2| (the assignment is local). This is very
%   important when comparing strings using non-ASCII characters, because for
%   instance, |über| is not the same token list in the |latin1| and |utf8|
%   encodings (\pkg{inputenc} side). To overcome this difficulty, when we need
%   to compare pure-text user input that could contain non-ASCII characters to
%   keys (e.g., of a mapping as implemented in \pkg{l3prop}), we use the LICR
%   as a normalized form.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_set_to_licr_form:Nn #1#2
  {
    \group_begin:
%    \end{macrocode}
% Remove the \cs{IeC} \pkg{inputenc} macro (only used to protect control words
% written to files such as \file{.aux} and \file{.toc}) in order to retrieve
% the LICR object corresponding to |#2|.
%    \begin{macrocode}
    \cs_set_eq:NN \IeC \@firstofone % see the inputenc documentation (or code)
    \protected@xdef \xcref@tmpa {#2}
    \group_end:
%    \end{macrocode}
% Not using \cs[no-index]{tl_set_eq:NN} here, because that would mean relying
% on implementation details of token list variables.
%    \begin{macrocode}
    \tl_set:No #1 { \xcref@tmpa }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\xcref@tabacckludge}
%   \tn{protected} variant of \cs{@tabacckludge}. We need this for text that
%   is going to be transformed by \cs{text_titlecase:nn}.
%    \begin{macrocode}
\cs_set_eq:NN \xcref@tabacckludge \@tabacckludge
\robustify { \xcref@tabacckludge }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_protect_accent_macros_from_tabbing:N}
%   Replace \tn{'}, \tn{`} and \tn{=} for safe use inside \env{tabbing}.
%   \begin{arguments}
%     \item token list variable
%   \end{arguments}
%   Replace \tn{'}, \tn{`} and \tn{=} in |#1| with \cs{xcref@tabacckludge}
%   followed by |'|, |`| or |=|, respectively. This is necessary in case the
%   replaced commands were meant to produce accented characters and the
%   material in |#1| is going to occur inside a \env{tabbing} environment.
%   Indeed, \env{tabbing} redefines \tn{'}, \tn{`} and \tn{=} to do completely
%   different things from the corresponding TeX commands (see the
%   \pkg{inputenc} documentation and the \LaTeX{} book).
%    \begin{macrocode}
\cs_new_protected:Npn \@@_protect_accent_macros_from_tabbing:N #1
  {
    \tl_replace_all:Nnn #1 { \' } { \xcref@tabacckludge ' }
    \tl_replace_all:Nnn #1 { \` } { \xcref@tabacckludge ` }
    \tl_replace_all:Nnn #1 { \= } { \xcref@tabacckludge = }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_call_lang_setup_func:nN, \@@_call_lang_setup_func:VN}
%   Call the main function of a language-specific module.
%   \begin{arguments}
%     \item name of a language-specific module
%     \item sequence variable containing the reference types to configure
%   \end{arguments}
%    \begin{macrocode}
\cs_new_protected:Npn \@@_call_lang_setup_func:nN #1#2
  {
    \use:c { @@_#1_setup_cref_names:N } #2
  }
%    \end{macrocode}
% Define a variant of this function:
%    \begin{macrocode}
\cs_generate_variant:Nn \@@_call_lang_setup_func:nN { V }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_autodetect_lang_unless_explicit:}
%   Use the current language if not explicitly selected for \pkg{xcref}. May
%   be used to map several \pkg{babel} languages to the same \pkg{xcref}
%   language-specific (backend) module (note: the mapping is only used when
%   the language is autodetected; explicit selection with \pkg{xcref} doesn't
%   use it).
%    \begin{macrocode}
\cs_new_protected:Npn \@@_autodetect_lang_unless_explicit:
  {
    \str_if_empty:NT \l_@@_selected_lang_str
      {
        \str_set:Nx \l_@@_selected_lang_str
          {
            \IfLanguageName { english } { english } { }
            \IfLanguageName { french } { french } { }
            \IfLanguageName { ngerman } { ngerman } { }
          }
        \str_if_empty:NT \l_@@_selected_lang_str
          { \msg_error:nn { xcref } { unable-to-determine-language } }
      }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{variable}{\l_@@_xcref_reference_types_seq}
%   Types of all references in the second argument of \cs{xcref:nn}.
%   Duplicates are not added; thus, the number of elements stored in this
%   variable is less than or equal to the number of references in the second
%   argument of \cs{xcref:nn}.
%    \begin{macrocode}
\seq_new:N \l_@@_xcref_reference_types_seq
%    \end{macrocode}
% \end{variable}
%
% \begin{macro}{\xcref:nn, \xcref}
%   \pkg{xcref}'s wrapper for \cs{cref}, \cs{Cref}, \cs{cref*} and \cs{Cref*}.
%   \begin{arguments}
%   \item options processed with \pkg{pgfkeys} using a default path of
%     \xcrefPGFRoot
%   \item comma-separated list of references passed as is to \cs{cref},
%     \cs{Cref}, \cs{cref*} or \cs{Cref*} depending on the values of the
%     \xcrefPGFOpt{capitalize} and \xcrefPGFOpt{hyperlinks} options
%   \end{arguments}
%   Basically, this first calls \cs{crefname}, \cs{Crefname} and
%   \cs{@crefdefineallformats} for each type pertaining to a reference in
%   |#2|. Then the appropriate \cs{cref}-like command is called. All this is
%   done inside a group (\cs{crefname} and friends act locally).
%    \begin{macrocode}
\cs_new_protected:Npn \xcref:nn #1#2
  {
    \group_begin:
    \xcref_set:n {#1}
    \@@_autodetect_lang_unless_explicit:

    \@@_set_to_reference_types:Nn \l_@@_xcref_reference_types_seq {#2}
    \@@_call_lang_setup_func:VN \l_@@_selected_lang_str
                                \l_@@_xcref_reference_types_seq

    \@@_call_cref:Nxn \l_@@_capitalize_bool
      {
        \bool_lazy_and:nnT { \g_@@_hyperref_loaded_bool }
                           { ! \l_@@_use_hyperlinks_bool }
                           { * }
      }
      {#2}
    \group_end:
  }

\NewDocumentCommand \xcref { O{} m }
  {
    \xcref:nn {#1} {#2}
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_call_cref:Nnn, \@@_call_cref:Nxn}
%   Call \cs{cref}, \cs{Cref} or their starred forms.
%   \begin{arguments}
%   \item boolean variable indicating whether to capitalize
%   \item star or empty
%   \item list of references in the format supported by \cs{cref} and friends
%     (spaces around the comma separators are \emph{not} ignored)
%   \end{arguments}
%    \begin{macrocode}
\cs_new_protected:Npn \@@_call_cref:Nnn #1#2#3
  {
    \use:c { \bool_if:NTF #1 { C } { c } ref } #2 {#3}
  }

\cs_generate_variant:Nn \@@_call_cref:Nnn { Nx }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_call_crefname:nnn, \@@_call_crefname:nVV}
%   Simple \pkg{expl3} wrapper for \cs{crefname}.
%   \begin{arguments}
%   \item reference type (e.g., \texttt{chapter}, \texttt{section},
%     \texttt{theorem}, \texttt{lemma}, etc.)
%   \item singular form
%   \item plural form
%   \end{arguments}
%    \begin{macrocode}
\cs_new_protected:Npn \@@_call_crefname:nnn #1#2#3
  {
    \crefname {#1} {#2} {#3}
  }

\cs_generate_variant:Nn \@@_call_crefname:nnn { nVV }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_call_Crefname:nnn, \@@_call_Crefname:nVV}
%   Simple \pkg{expl3} wrapper for \cs{Crefname}.
%   \begin{arguments}
%   \item reference type (see \cs{xcref_call_crefname:nnn} for examples)
%   \item singular form
%   \item plural form
%   \end{arguments}
%    \begin{macrocode}
\cs_new_protected:Npn \@@_call_Crefname:nnn #1#2#3
  {
    \Crefname {#1} {#2} {#3}
  }

\cs_generate_variant:Nn \@@_call_Crefname:nnn { nVV }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_call_crefdefineallformats:n}
%   Call \cs{@crefdefineallformats} for the specified type.
%   \begin{arguments}
%   \item reference type
%   \end{arguments}
%    \begin{macrocode}
\cs_new_protected:Npn \@@_call_crefdefineallformats:n #1
  {
    \@crefdefineallformats {#1}
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}[pTF]{\@@_ref_defined:n}
%   Test whether the specified reference is defined for \pkg{cleveref}.
%   \begin{arguments}
%   \item reference (\emph{i.e.,} a label)
%   \end{arguments}
%    \begin{macrocode}
\prg_new_conditional:Npnn \@@_ref_defined:n #1 { p, T, F, TF }
  {
    \exp_after:wN \if_meaning:w \cs:w r@#1@cref \cs_end: \relax
      \prg_return_false:
    \else:
      \prg_return_true:
    \fi:
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_call_cref_gettype:nN}
%   Use \cs{cref@gettype} to retrieve the type of a reference.
%   \begin{arguments}
%   \item reference (\emph{i.e.,} a label)
%   \item token list variable (receives the result)
%   \end{arguments}
%   This can only be used for references that have already been defined by
%   \cs{newlabel} (\emph{i.e.,} they have been read from the \texttt{.aux}
%   file: \cs{r@\meta{reference}@cref} is not \tn[no-index]{let}-equal to
%   \tn[no-index]{relax}).
%    \begin{macrocode}
\cs_new_protected:Npn \@@_call_cref_gettype:nN #1#2
  {
    \cref@gettype {#1} {#2}
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_set_to_reference_types:Nn}
%   Extract the list of reference types from a comma list of references.
%   \begin{arguments}
%   \item sequence variable
%   \item comma list of references
%   \end{arguments}
%   Store in |#1| the types of all references listed in |#2|, eliminating
%   duplicates. |#1| is assigned locally.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_set_to_reference_types:Nn #1#2
  {
    \seq_clear:N #1
    \clist_map_inline:nn {#2}
      {
        \@@_ref_defined:nT {##1}
          {
            \@@_call_cref_gettype:nN {##1} \l_tmpa_tl
            \seq_if_in:NVF #1 \l_tmpa_tl
              { \seq_put_right:NV #1 \l_tmpa_tl }
          }
      }
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\xcref_set:n, \xcrefset}
%   Set PGF keys related to \pkg{xcref}.
%   \begin{arguments}
%   \item comma-separated list of PGF keys
%   \end{arguments}
%    \begin{macrocode}
\cs_new_protected:Npn \xcref_set:n #1
  {
    \pgfqkeys { /xcref } {#1}
  }

\NewDocumentCommand \xcrefset { m }
  {
    \xcref_set:n {#1}
  }
%    \end{macrocode}
% \end{macro}
%
% \subsubsection{Helper macros used with \cs{text_titlecase:nn}}
%
% \begin{macro}{\xcrefNoCaseChange}
%   Locally inhibit conversion when used in the second argument of
%   \cs{text_titlecase:nn}.
%   \begin{arguments}
%   \item a token list (\emph{a priori} representing text) to
%   \enquote{protect} from changes by \cs{text_titlecase:nn}
%   \end{arguments}
%   This function (the control sequence token) can be passed to
%   \xcrefPGFOpt{functions for preventing auto case change} in order to tell
%   the underlying \cs{text_titlecase:nn} operation not to modify some
%   particular tokens (of a reference name for instance). We set it to the
%   identity function.
%    \begin{macrocode}
\cs_new_protected:Npn \xcref_no_case_change:n #1
  {
    #1
  }

\cs_new_eq:NN \xcrefNoCaseChange \xcref_no_case_change:n
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\xcref_lang_for_text_titlecase:n,
%               \xcref_lang_for_text_titlecase:V,
%               \xcref_lang_for_text_titlecase_default:n,
%               \xcrefDefaultMappingForTextTitleCase}
%   \cs{xcref_lang_for_text_titlecase_default:n} is the default mapping from
%   \pkg{xcref} language names to language codes suitable for use with
%   \cs{text_titlecase:nn}. Users may use \xcrefPGFOpt{lang for capitalization
%   func} in order to point to a different mapping function in case
%   \cs{xcref_lang_for_text_titlecase_default:n} doesn't do what they want.
%   Calling this key simply redefines \cs{xcref_lang_for_text_titlecase:n} to
%   point to the specified macro. At any time, the current mapping is given by
%   \cs{xcref_lang_for_text_titlecase:n}.
%   \cs{xcref_lang_for_text_titlecase_default:n} is the initial
%   (\enquote{default}) mapping function.
%   \cs{xcrefDefaultMappingForTextTitleCase} is just another name for this
%   function that complies with the \LaTeXe{} naming conventions.
%   \begin{arguments}
%   \item an \pkg{xcref} language name
%   \end{arguments}
%    \begin{macrocode}
\cs_new:Npn \xcref_lang_for_text_titlecase_default:n #1
  {
    \str_case:nnF {#1}
      {
        { azerbaijani } { az }
        { dutch } { nl }
        { lithuanian } { lt }
        { ngerman } { de-alt }
        { turkish } { tr }
      }
      {#1}                      % pass through for all other cases
  }

\cs_new_eq:NN \xcref_lang_for_text_titlecase:n
              \xcref_lang_for_text_titlecase_default:n
\cs_new_eq:NN \xcrefDefaultMappingForTextTitleCase
              \xcref_lang_for_text_titlecase_default:n

\cs_generate_variant:Nn \xcref_lang_for_text_titlecase:n { V }
%    \end{macrocode}
% \end{macro}
%
% \subsubsection{Factory for convenience \cs{xcref} front-ends}
%
% \begin{macro}{\@@_create_language_specific_wrapper:Nn}
%   Create convenience front-end macros to \cs{xcref} for the specified
%   language. See the language-specific modules for examples of use.
%   \begin{arguments}
%   \item name of the language-specific module used by the created macros---as
%     specified by the following arguments
%   \item name of the generic language-specific code-level macro to create
%   \item name of its document-level counterpart (it can be useful to users
%     who wish to create custom front-ends \cs{xcref})
%   \item name of the language-specific document-level front-end macro that
%     uses |capitalize=false|
%   \item name of the language-specific document-level front-end macro that
%     uses |capitalize=true|
%   \end{arguments}
%    \begin{macrocode}
\cs_new_protected:Npn \@@_create_language_specific_wrapper:nNNNN #1#2#3#4#5
  {
    \cs_new_protected:Npn #2 ##1##2
      {
        \xcref:nn { ##1, lang=#1, #1/.cd, ##2 }
      }

    \NewDocumentCommand #3 { m m }
      {
        #2 {##1} {##2}
      }

    \NewDocumentCommand #4 { O{} }
      {
        #2 {capitalize=false} {##1}
      }

    \NewDocumentCommand #5 { O{} }
      {
        #2 {capitalize=true} {##1}
      }
  }
%    \end{macrocode}
% \end{macro}
%
% \subsubsection{PGF key definitions}
%
% The following PGF keys can be set with \cs{xcrefset} as will as in the first
% argument of \cs{xcref:nn}.
%    \begin{macrocode}
\xcref_set:n
  {
    capitalize/.is~choice,
    capitalize/true/.code = { \bool_set_true:N \l_@@_capitalize_bool },
    capitalize/false/.code = { \bool_set_false:N \l_@@_capitalize_bool },
    capitalize/.default = true, % when the key is used with no value
    capitalize = false,         % initial value
    %
    hyperlinks/.is~choice,
    hyperlinks/true/.code = { \bool_set_true:N \l_@@_use_hyperlinks_bool },
    hyperlinks/false/.code = { \bool_set_false:N \l_@@_use_hyperlinks_bool },
    hyperlinks/.default = true, % when the key is used with no value
    hyperlinks = true,          % initial value
%    \end{macrocode}
% Used with \cs{text_titlecase:nn} which prepares the arguments of \cs{Crefname}
%    \begin{macrocode}
    functions~for~preventing~auto~case~change/.value~required,
    functions~for~preventing~auto~case~change/.code =
      { \tl_set:Nn \l_@@_case_change_exclude_tl {#1} },
%    \end{macrocode}
% The initial setting only contains one macro:
%    \begin{macrocode}
    functions~for~preventing~auto~case~change = \xcrefNoCaseChange,
%    \end{macrocode}
% The language to use will be autodetected with \pkg{iflang}, unless it is
% explicitly specified using this option.
%    \begin{macrocode}
    lang/.value~required,
    lang/.code = { \str_set:Nn \l_@@_selected_lang_str {#1} },
    lang = {},                  % initial value: autodetect
%    \end{macrocode}
% Function mapping \pkg{xcref} language module names to language codes used by
% \cs{text_titlecase:nn}.
%    \begin{macrocode}
    lang~for~capitalization~func/.value~required,
    lang~for~capitalization~func/.code = {
      \cs_set_eq:NN \xcref_lang_for_text_titlecase:n #1 },
%    \end{macrocode}
% It would be nice to be able to use |.unknown/.code| so that unrecognized
% options |foo| are interpreted as being |preposition=foo|, however this is
% not satisfactory because \cs[no-index]{pgfkeys} appears to expand tokens
% when looking for key names. There is no such problem with \pkg{l3keys}, but
% \pkg{pgfkeys} has other advantages...
%    \begin{macrocode}
  }
%    \end{macrocode}
%
% \subsubsection{Package options}
%
% Define the package options using \pkg{l3keys}.
%    \begin{macrocode}
\keys_define:nn { xcref }
  {
    languages .code:n = \xcref_use_modules:n {#1},
  }
%    \end{macrocode}
% Explicitly define the name of each supported language module as a package
% option. This way, if such an option (e.g., \texttt{ngerman}) was given to
% \tn[no-index]{documentclass}, \cs[no-index]{ProcessKeysOptions} will pass it
% to \pkg{xcref}.
%    \begin{macrocode}
\seq_map_inline:Nn \g_xcref_available_language_modules_seq
  {
    \keys_define:nn { xcref }
      { #1 .code:n = \xcref_use_module:V \l_keys_key_tl }
  }
%    \end{macrocode}
%
% Process \LaTeXe-style package options. This uses \pkg{l3keys2e}, see
% \url{https://tex.stackexchange.com/a/371754/73317} for explanations.
%    \begin{macrocode}
\ProcessKeysOptions { xcref }
%    \end{macrocode}
% This ends the code for \file{xcref.sty}.
%    \begin{macrocode}
%</package>
%    \end{macrocode}
%
% \subsection{Module \file{xcref-french.tex}}
%
% \pkg{DocStrip} start guard for \file{xcref-french.tex}.
%    \begin{macrocode}
%<*french-module>
%    \end{macrocode}
% Switch to the category code régime suitable for \pkg{expl3} code.
%    \begin{macrocode}
\ExplSyntaxOn
%    \end{macrocode}
%
% \subsubsection{\pkg{expl3} messages}
%
%    \begin{macrocode}
\msg_new:nnn { xcref } { french-requested-use-of-unknown-definite-article }
  { (french)~Unknown~definite~article:~'\exp_not:n {#1}'. }
\msg_new:nnn { xcref }
  { french-definite-article-not-in-c_@@_french_article_prop }
  { (french)~Bug:~definite~article~not~in~\token_to_str:N
    \c_@@_french_article_prop \c_colon_str \space '\exp_not:n {#1}'. }
\msg_new:nnn { xcref } { french-requested-use-of-undefined-type }
  { (french)~Requested~use~of~undefined~reference~type:~'\exp_not:n {#1}'. }
\msg_new:nnn { xcref } { french-unknown-prefix-form }
  { (french)~Unknown~form~for~the~part~preceding~the~
    \token_to_str:N \namecref \c_colon_str \space '\exp_not:n {#1}'. }
%    \end{macrocode}
%
% \subsubsection{Variables}
%
% \begin{variable}{\l_@@_french_selected_form_str}
%   Specifies how references are to be produced, in grammatical terms. There
%   are three possible values: |noun|, |article+noun| and |prep+article+noun|,
%   where |prep| stands for \enquote{preposition}.
%    \begin{macrocode}
\str_new:N \l_@@_french_selected_form_str
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l_@@_french_selected_preposition_tl}
%   The selected preposition, if any. When non-empty, this variable overrides
%   the default preposition associated to the reference type.
%    \begin{macrocode}
\tl_new:N \l_@@_french_selected_preposition_tl
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\g_@@_french_names_prop}
%   French language-specific data on reference names: for each name, the
%   default preposition, definite article to use, singular and plural forms.
%   The first two \meta{items} of each value of the property list must use the
%   LICR representation.
%
%   We use \cs{xcref@tabacckludge} in \emph{output text} instead of
%   \cs{@tabacckludge} because things can go wrong when \cs{text_titlecase:nn}
%   expands \cs{@tabacckludge} in its second argument (try with
%   \verb|\@tabacckludge`a|). Regarding the use of \cs{@tabacckludge} itself,
%   see the documentation of \pkg{inputenc}. Note that it is not really
%   necessary here, because we are going to automatically do the corresponding
%   replacements downstream to be on the safe side, but it will help in case
%   someone uses data from this variable and forgets to systematically replace
%   \tn{'}, \tn{`} and \tn{=} by commands that behave as expected inside a
%   \env{tabbing} environment.
%    \begin{macrocode}
\prop_new:N \g_@@_french_names_prop

\prop_gset_from_keyval:Nn \g_@@_french_names_prop
  {
    problem    = {\`a}{le}{probl\xcref@tabacckludge`eme}
                 {probl\xcref@tabacckludge`emes},
    proposition= {\`a}{la}{proposition}{propositions},
    assertion  = {d'apr\`es}{l'}{assertion}{assertions},
    theorem    = {\`a}{le}{th\xcref@tabacckludge'eor\xcref@tabacckludge`eme}
                 {th\xcref@tabacckludge'eor\xcref@tabacckludge`emes},
    lemma      = {\`a}{le}{lemme}{lemmes},
    definition = {dans}{la}{d\xcref@tabacckludge'efinition}
                 {d\xcref@tabacckludge'efinitions},
  }
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\g_@@_french_types_seq}
%   \cs{g_@@_french_types_seq} will be set up to contain the list of keys in
%   \cs{g_@@_french_names_prop} (this will be done from the
%   \cs{AtBeginDocument} hook).
%    \begin{macrocode}
\seq_new:N \g_@@_french_types_seq
%    \end{macrocode}
% \end{variable}
%
% Change the category code of spaces inside the following group so that they
% behave as in plain \TeX{} and \LaTeXe{}.
%    \begin{macrocode}
\group_begin:
  \char_set_catcode_space:n { `~ }
%    \end{macrocode}
%
% \begin{variable}{\g_@@_french_prep_and_article_prop}
%   Mapping describing how prepositions and definite articles combine in
%   French. The keys must use the LICR representation. \cs{xcref@tabacckludge}
%   is not really necessary here, because we are going to do the corresponding
%   replacements downstream to be on the safe side---but it is safer in case
%   someone uses data from this variable and forgets to systematically replace
%   \tn{'}, \tn{`} and \tn{=} by commands that behave as expected inside a
%   \env{tabbing} environment.
%    \begin{macrocode}
  \prop_new:N \g_@@_french_prep_and_article_prop
  \prop_gset_from_keyval:Nn \g_@@_french_prep_and_article_prop
    {
      \`a    = {\xcref@tabacckludge`a l'}{au }{\xcref@tabacckludge`a la }{aux }
    }
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\c_@@_french_article_prop}
%   This mapping allows one to always get proper spacing between an article
%   and the following noun---which sometimes is \enquote{no space} (cf.~the
%   case of |l'|).
%    \begin{macrocode}
  \prop_const_from_keyval:Nn \c_@@_french_article_prop
    { l'  = {l'}, le  = {le }, la  = {la }, les = {les } }
%    \end{macrocode}
% \end{variable}
%    \begin{macrocode}
\group_end:
%    \end{macrocode}
%
% \subsubsection{PGF keys}
%
% Note that the \xcrefPGFOpt{french/names table} key can only be set in the
% preamble. The initial value of \cs{l_@@_french_selected_preposition_tl} is
% empty (see above).
%
%    \begin{macrocode}
\pgfqkeys { /xcref/french }
  {
    form/.is~choice,
    form/noun/.code = { \str_set:Nn \l_@@_french_selected_form_str {noun} },
    form/article+noun/.code =
             { \str_set:Nn \l_@@_french_selected_form_str {article+noun} },
    form/prep+article+noun/.code =
             { \str_set:Nn \l_@@_french_selected_form_str {prep+article+noun} },
    form = prep+article+noun,   % set the initial value
    %
    preposition/.value~required,
    preposition/.code = {
      \@@_set_to_licr_form:Nn \l_@@_french_selected_preposition_tl {#1} },
    %
    names~table/.code = { \@@_french_set_names_table:n {#1} },
    %
    composition~table~for~prepositions~and~articles/.code = {
      \prop_gset_from_keyval:Nn \g_@@_french_prep_and_article_prop {#1} },
  }
%    \end{macrocode}
%
% \subsubsection{Main code}
%
%    \begin{macrocode}
\int_new:N \l_@@_fapaa_index_int
\tl_new:N \l_@@_fapaa_prepart_tl
%    \end{macrocode}
%
% \begin{macro}{\xcref_french_assemble_prep_and_article:nnN,
%               \xcref_french_assemble_prep_and_article:VnN,
%               \xcref_french_assemble_prep_and_article:VVN}
%   Assemble a preposition and a definite article.
%   \begin{arguments}
%   \item preposition (key of \cs{g_@@_french_prep_and_article_prop})
%   \item definite article among |l'|, |le|, |la| and |les|
%   \item token list variable where the result is to be stored
%   \end{arguments}
%    \begin{macrocode}
\cs_new_protected:Npn \xcref_french_assemble_prep_and_article:nnN #1#2#3
  {
    \prop_get:NnNTF \g_@@_french_prep_and_article_prop {#1}
                    \l_@@_fapaa_prepart_tl
      {
        \seq_set_split:NnV \l_tmpa_seq { } \l_@@_fapaa_prepart_tl
        \int_set:Nn \l_@@_fapaa_index_int
          {
            \str_case:nnF {#2}
              {
                { l' } { 1 }
                { le } { 2 }
                { la } { 3 }
                { les } { 4 }
              }
              {
                \msg_error:nnn { xcref }
                  { french-requested-use-of-unknown-definite-article } {#2}
              }
          }

        \tl_set:Nx #3 { \seq_item:Nn \l_tmpa_seq { \l_@@_fapaa_index_int } }
      }
      {
        \prop_get:NnNF \c_@@_french_article_prop {#2} \l_tmpa_tl
          {
            \msg_error:nnn { xcref }
              { french-definite-article-not-in-c_@@_french_article_prop } {#2}
          }

        \tl_set:Nn #3 { #1~ }
        \tl_put_right:NV #3 \l_tmpa_tl
      }

    \@@_protect_accent_macros_from_tabbing:N #3
    \@@_protect_accent_macros_from_tabbing:N #3
  }

\cs_generate_variant:Nn \xcref_french_assemble_prep_and_article:nnN { V }
\cs_generate_variant:Nn \xcref_french_assemble_prep_and_article:nnN { VV }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_french_set_names_table:n}
%   Set \cs{g_@@_french_names_prop} to the given value.
%   \begin{arguments}
%   \item valid value for an \pkg{l3prop} object
%   \end{arguments}
%   This function can only be used in the preamble because the list of keys is
%   computed at |\begin{document}| time and stored in
%   \cs{g_@@_french_types_seq}.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_french_set_names_table:n #1
  {
    \prop_gset_from_keyval:Nn \g_@@_french_names_prop {#1}
  }

\@onlypreamble \@@_french_set_names_table:n
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\xcref_french_set_names_table_entry:nnnnn,
%               \xcreffrenchSetNamesTableEntry}
%   Set one $(\text{key}, \text{value})$ pair in \cs{g_@@_french_names_prop}.
%   \begin{arguments}
%   \item reference type
%   \item default preposition, in LICR form
%   \item definite article for the singular form, among |l'|, |le| and |la|
%   \item singular form of the noun corresponding to the reference type
%   \item plural form of the same noun
%   \end{arguments}
%   This function can only be used in the preamble because it modifies
%   \cs{g_@@_french_names_prop} and the list of keys in this property list is
%   computed at |\begin{document}| time (stored in \cs{g_@@_french_types_seq}).
%    \begin{macrocode}
\cs_new_protected:Npn \xcref_french_set_names_table_entry:nnnnn #1#2#3#4#5
  {
    \prop_gput:Nnn \g_@@_french_names_prop {#1} { {#2} {#3} {#4} {#5} }
  }

\@onlypreamble \xcref_french_set_names_table_entry:nnnnn

\NewDocumentCommand \xcreffrenchSetNamesTableEntry { m m m m m }
  {
    \xcref_french_set_names_table_entry:nnnnn {#1} {#2} {#3} {#4} {#5}
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_french_setup_cref_names:N}
%   Call \cs{crefname}, \cs{Crefname} and \cs{@crefdefineallformats} for each
%   reference type in |#1|.
%   \begin{arguments}
%   \item sequence variable containing reference types
%   \end{arguments}
%   This is the main entry point of the language-specific module.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_french_setup_cref_names:N #1
  {
    \seq_map_function:NN #1 \@@_french_setup_cref_names_mapfunc:n
  }
%    \end{macrocode}
% \end{macro}
%
% \medskip
% Prepare the terrain for \cs{@@_french_setup_cref_names_mapfunc:n}.
%    \begin{macrocode}
\cs_generate_variant:Nn \text_titlecase:nn { VV }
\cs_generate_variant:Nn \msg_error:nnn { nnV }
\cs_generate_variant:Nn \str_case:nnF { V }
%    \end{macrocode}
% Used to store data extracted from \cs{g_@@_french_names_prop} corresponding
% to the selected reference type.
%    \begin{macrocode}
\tl_new:N \l_@@_fscnm_type_data_tl
\seq_new:N \l_@@_fscnm_type_data_seq
%    \end{macrocode}
% Selected preposition.
%    \begin{macrocode}
\tl_new:N \l_@@_fscnm_prep_tl
%    \end{macrocode}
% Singular form of the definite article normally used with the selected
% reference type.
%    \begin{macrocode}
\tl_new:N \l_@@_fscnm_article_tl
%    \end{macrocode}
% What to insert before a reference name (these contain the whole prefix:
% empty, article or preposition plus article, depending on the value of
% \xcrefPGFOpt{french/form}).
%    \begin{macrocode}
\tl_new:N \l_@@_fscnm_prefix_sing_tl
\tl_new:N \l_@@_fscnm_prefix_plur_tl
%    \end{macrocode}
% The whole strings passed to \cs{crefname} and \cs{Crefname}.
%    \begin{macrocode}
\tl_new:N \l_@@_fscnm_singular_tl
\tl_new:N \l_@@_fscnm_plural_tl
%    \end{macrocode}
% Language code for use with \cs{text_titlecase:nn}.
%    \begin{macrocode}
\tl_new:N \l_@@_fscnm_lang_tl
%    \end{macrocode}
%
% \begin{macro}{\@@_french_setup_cref_names_mapfunc:n}
%   Call \cs{crefname}, \cs{Crefname} and \cs{@crefdefineallformats} for the
%   specified reference type.
%   \begin{arguments}
%   \item reference type (e.g., |chapter|, |section|, |theorem|, etc.)
%   \end{arguments}
%    \begin{macrocode}
\cs_new_protected:Npn \@@_french_setup_cref_names_mapfunc:n #1
  {
    \prop_get:NnNF \g_@@_french_names_prop {#1} \l_@@_fscnm_type_data_tl
      {
        \msg_error:nnn { xcref } { french-requested-use-of-undefined-type } {#1}
      }

    \seq_set_split:NnV \l_@@_fscnm_type_data_seq { }
                       \l_@@_fscnm_type_data_tl
    \seq_pop_left:NN \l_@@_fscnm_type_data_seq \l_@@_fscnm_prep_tl
%    \end{macrocode}
% Override the default preposition for reference type |#1| if one was
% explicitly specified.
%    \begin{macrocode}
    \tl_if_empty:NF \l_@@_french_selected_preposition_tl
      {
        \tl_set_eq:NN \l_@@_fscnm_prep_tl \l_@@_french_selected_preposition_tl
      }
    \seq_pop_left:NN \l_@@_fscnm_type_data_seq \l_@@_fscnm_article_tl
    \seq_pop_left:NN \l_@@_fscnm_type_data_seq \l_@@_fscnm_singular_tl
    \seq_pop_left:NN \l_@@_fscnm_type_data_seq \l_@@_fscnm_plural_tl

    \str_case:VnF \l_@@_french_selected_form_str
      {
        { prep+article+noun }
        {
          \xcref_french_assemble_prep_and_article:VVN \l_@@_fscnm_prep_tl
            \l_@@_fscnm_article_tl \l_@@_fscnm_prefix_sing_tl
          \xcref_french_assemble_prep_and_article:VnN \l_@@_fscnm_prep_tl
            { les } \l_@@_fscnm_prefix_plur_tl
        }
        { article+noun }
        {
          \prop_get:NVNF \c_@@_french_article_prop \l_@@_fscnm_article_tl
                         \l_@@_fscnm_prefix_sing_tl
            {
              \msg_error:nnV { xcref }
                { french-definite-article-not-in-c_@@_french_article_prop }
                \l_@@_fscnm_article_tl
            }
          \tl_set:Nn \l_@@_fscnm_prefix_plur_tl { les~ }
        }
        { noun }
        {
          \tl_clear:N \l_@@_fscnm_prefix_sing_tl
          \tl_clear:N \l_@@_fscnm_prefix_plur_tl
        }
      }
      {
        \msg_error:nnV { xcref } { french-unknown-prefix-form }
          \l_@@_french_selected_form_str
      }

    \tl_put_left:NV \l_@@_fscnm_singular_tl \l_@@_fscnm_prefix_sing_tl
    \tl_put_left:NV \l_@@_fscnm_plural_tl \l_@@_fscnm_prefix_plur_tl
%    \end{macrocode}
% Make sure \cs{xcref@tabacckludge} is used to protect \tn{'}, \tn{`} and
% \tn{=} from the \env{tabbing} environment, which redefines them (see the
% \pkg{inputenc} documentation).
%    \begin{macrocode}
    \@@_protect_accent_macros_from_tabbing:N \l_@@_fscnm_singular_tl
    \@@_protect_accent_macros_from_tabbing:N \l_@@_fscnm_plural_tl
%    \end{macrocode}
% Set up the non-capitalized forms.
%    \begin{macrocode}
    \@@_call_crefname:nVV {#1} \l_@@_fscnm_singular_tl \l_@@_fscnm_plural_tl
%    \end{macrocode}
% This influences the behavior of \cs{text_titlecase:nn}.
%    \begin{macrocode}
    \tl_set_eq:NN \l_text_case_exclude_arg_tl \l_@@_case_change_exclude_tl
%    \end{macrocode}
% Prepare for the language-specific case conversion.
%    \begin{macrocode}
    \tl_set:Nx \l_@@_fscnm_lang_tl
      { \xcref_lang_for_text_titlecase:V \l_@@_selected_lang_str }
    \tl_set:Nx \l_@@_fscnm_singular_tl
      { \text_titlecase:VV \l_@@_fscnm_lang_tl \l_@@_fscnm_singular_tl }
    \tl_set:Nx \l_@@_fscnm_plural_tl
      { \text_titlecase:VV \l_@@_fscnm_lang_tl \l_@@_fscnm_plural_tl }
%    \end{macrocode}
% Set up the capitalized forms.
%    \begin{macrocode}
    \@@_call_Crefname:nVV {#1} \l_@@_fscnm_singular_tl \l_@@_fscnm_plural_tl
%    \end{macrocode}
% Call \cs{@crefdefineallformats} to define all things derived from the
% \cs{crefname} and \cs{Crefname} calls we just did (for instance, this will
% call \cs{crefmultiformat}, which in turn will define
% \cs{cref@\meta{type}@format@first}, among others). This is likely to be
% slow.
%    \begin{macrocode}
    \@@_call_crefdefineallformats:n {#1}
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_french_generic_wrapper:nn, \xcreffrenchgenericwrapper,
%               \xcreffrenchwrapper, \xcreffrenchWrapper}
% Create convenience \cs{xcref} wrappers for \texttt{french}.
%    \begin{macrocode}
\@@_create_language_specific_wrapper:nNNNN { french }
  \@@_french_generic_wrapper:nn \xcreffrenchgenericwrapper
  \xcreffrenchwrapper \xcreffrenchWrapper
%    \end{macrocode}
% \end{macro}
% Fill the list of known types (\cs{g_@@_french_types_seq}) with the keys of
% \cs{g_@@_french_names_prop}. Since we only do this here, this implies that
% \xcrefPGFOpt{french/names table} can only be set in the preamble (otherwise,
% \cs{g_@@_french_types_seq} and \cs{g_@@_french_names_prop} would become
% out of sync).
%    \begin{macrocode}
\AtBeginDocument
  {
    \seq_gclear:N \g_@@_french_types_seq
    \prop_map_inline:Nn \g_@@_french_names_prop
      { \seq_gput_right:Nn \g_@@_french_types_seq {#1} }
  }
%    \end{macrocode}
% Switch off the \pkg{expl3} category code régime.
%    \begin{macrocode}
\ExplSyntaxOff
%    \end{macrocode}
% \pkg{DocStrip} end guard for \file{xcref-french.tex}.
%    \begin{macrocode}
%</french-module>
%    \end{macrocode}
%
% \subsection{Module \file{xcref-ngerman.tex}}
%
% \pkg{DocStrip} start guard for \file{xcref-ngerman.tex}.
%    \begin{macrocode}
%<*ngerman-module>
%    \end{macrocode}
% Switch to the category code régime suitable for \pkg{expl3} code.
%    \begin{macrocode}
\ExplSyntaxOn
%    \end{macrocode}
%
% \subsubsection{\pkg{expl3} messages}
%
%    \begin{macrocode}
\msg_new:nnn { xcref } { ngerman-requested-use-of-undefined-type }
  { (ngerman)~Requested~use~of~undefined~reference~type:~'\exp_not:n {#1}'. }

\msg_new:nnn { xcref } { ngerman-unable-to-determine-the-case }
  { (ngerman)~Unable~to~determine~the~case~to~use~(nominative,~etc.) }

\msg_new:nnn { xcref }
  { ngerman-unexpected-case-name-when-trying-to-find-index }
  { (ngerman)~Bug:~unexpected~case~name~when~doing~lookup~in~\token_to_str:N
    \c_@@_ngerman_case_idx_prop \c_colon_str \space '\exp_not:n {#1}'. }

\msg_new:nnn { xcref } { ngerman-unknown-prefix-form }
  { (ngerman)~Unknown~form~for~the~part~preceding~the~
    \token_to_str:N \namecref \c_colon_str \space '\exp_not:n {#1}'. }
%    \end{macrocode}
%
% \subsubsection{Variables}
%
% \begin{variable}{\l_@@_ngerman_selected_form_str}
%   Specifies how references are to be produced, in grammatical terms. There
%   are four possible values: |noun|, |article+noun|, |prep+noun| and
%   |prep+article+noun|, where |prep| stands for \enquote{preposition}.
%    \begin{macrocode}
\str_new:N \l_@@_ngerman_selected_form_str
%    \end{macrocode}
% \end{variable}
%
% \begin{variable}{\l_@@_ngerman_selected_preposition_tl}
%   The selected preposition, if any. When non-empty, this variable overrides
%   the default preposition associated to the reference type.
%    \begin{macrocode}
\tl_new:N \l_@@_ngerman_selected_preposition_tl
%    \end{macrocode}
% \end{variable}
%
% Indices corresponding to the order of the cases in
% \cs{g_@@_ngerman_names_prop}
%    \begin{macrocode}
\prop_const_from_keyval:Nn \c_@@_ngerman_case_idx_prop
  {
    nominative = 1,
    accusative = 2,
    dative     = 3,
    genitive   = 4
  }
%    \end{macrocode}
% Can be changed by users via \xcrefPGFOpt{ngerman/names table}. This is global
% because we don't want to compute \cs{g_@@_ngerman_types_seq} (containing the
% list of keys in \cs{g_@@_ngerman_names_prop}) all the time. The prepositions
% and articles in this variable must be written in LICR representation (for
% instance, use |\"uber| but not |über| nor |{\"u}ber|).
%
% In case you would need \tn{'}, \tn{`} or \tn{=} in the nouns
% (\enquote{Problem}, \enquote{Probleme}, etc.), you may want to use
% \cs{xcref@tabacckludge} followed by |'|, |`| or |=| instead (see
% \cs{g_@@_french_names_prop} in the \texttt{french} module for examples).
%    \begin{macrocode}
\prop_new:N \g_@@_ngerman_names_prop
\prop_gset_from_keyval:Nn \g_@@_ngerman_names_prop
  {
    problem    = {in}{{das}{Problem}{die}{Probleme}}%
                   {{das}{Problem}{die}{Probleme}}%
                   {{dem}{Problem}{den}{Problemen}}%
                   {{des}{Problems}{der}{Probleme}},
    proposition= {nach}{{die}{Proposition}{die}{Propositionen}}%
                   {{die}{Proposition}{die}{Propositionen}}%
                   {{der}{Proposition}{den}{Propositionen}}%
                   {{der}{Proposition}{der}{Propositionen}},
    satz       = {nach}{{der}{Satz}{die}{S\"atze}}%
                   {{den}{Satz}{die}{S\"atze}}%
                   {{dem}{Satz}{den}{S\"atzen}}%
                   {{des}{Satzes}{der}{S\"atze}},
    theorem    = {nach}{{das}{Theorem}{die}{Theoreme}}%
                   {{das}{Theorem}{die}{Theoreme}}%
                   {{dem}{Theorem}{den}{Theoremen}}%
                   {{des}{Theorems}{der}{Theoreme}},
    lemma      = {nach}{{das}{Lemma}{die}{Lemmata}}%
                   {{das}{Lemma}{die}{Lemmata}}%
                   {{dem}{Lemma}{den}{Lemmata}}%
                   {{des}{Lemmas}{der}{Lemmata}},
    definition = {nach}{{die}{Definition}{die}{Definitionen}}%
                   {{die}{Definition}{die}{Definitionen}}%
                   {{der}{Definition}{den}{Definitionen}}%
                   {{der}{Definition}{der}{Definitionen}},
  }
%    \end{macrocode}
% Will contain the list of keys in \cs{g_@@_ngerman_names_prop} (computed
% \cs{AtBeginDocument})
%    \begin{macrocode}
\seq_new:N \g_@@_ngerman_types_seq
%    \end{macrocode}
% Authorized values: |nominative|, |accusative|, |dative|, |genitive|.
%    \begin{macrocode}
\str_new:N \l_@@_ngerman_selected_case_str
%    \end{macrocode}
% With some prepositions, the case is perfectly determined. This mapping thus
% takes precedence over whatever was set via the PGF key \xcrefPGFOpt{ngerman/case}.
% It can be modified by users via
% \xcrefPGFOpt{ngerman/prepositions always followed by the same case}. The keys
% must be written in LICR representation.
%    \begin{macrocode}
\prop_new:N \l_@@_ngerman_case_for_prep_prop
\prop_set_from_keyval:Nn \l_@@_ngerman_case_for_prep_prop
  {
    bis   = accusative,
    durch = accusative,
    f\"ur = accusative,
    gegen = accusative,
    ohne  = accusative,
    um    = accusative,
    aus   = dative,
    bei   = dative,
    mit   = dative,
    nach  = dative,
    seit  = dative,
    von   = dative,
    zu    = dative,
%    \end{macrocode}
% Prepositions normally followed by the genitive case seem to often have
% exceptions; thus, I prefer letting a native German speaker decide what
% is correct to include here.
%    \begin{macrocode}
  }
%    \end{macrocode}
% Some prepositions and articles can merge. This mapping can be modified by
% users via \xcrefPGFOpt{ngerman/composition table for prepositions and articles}.
% The keys must be written in LICR representation.
%    \begin{macrocode}
\prop_new:N \l_@@_ngerman_article_and_prep_prop
\prop_set_from_keyval:Nn \l_@@_ngerman_article_and_prep_prop
  {
    an~dem = am,
    in~dem = im,
    von~dem = vom,
    zu~dem = zum,
    zu~der = zur,
    bei~dem = beim,
  }
%    \end{macrocode}
%
% \subsubsection{PGF keys}
%
% Note that the \xcrefPGFOpt{ngerman/names table} key can only be set in the
% preamble. The initial value of \cs{l_@@_ngerman_selected_preposition_tl} is
% empty (see above).
%
%    \begin{macrocode}
\pgfqkeys { /xcref/ngerman }
  {
    form/.is~choice,
    form/noun/.code = { \str_set:Nn \l_@@_ngerman_selected_form_str {noun} },
    form/article+noun/.code =
            { \str_set:Nn \l_@@_ngerman_selected_form_str {article+noun} },
    form/prep+noun/.code =
            { \str_set:Nn \l_@@_ngerman_selected_form_str {prep+noun} },
    form/prep+article+noun/.code =
            { \str_set:Nn \l_@@_ngerman_selected_form_str {prep+article+noun} },
    form = prep+article+noun,   % set the initial value
    %
    preposition/.value~required,
    preposition/.code = {
      \@@_set_to_licr_form:Nn \l_@@_ngerman_selected_preposition_tl {#1} },
    case/.is~choice,
    case/nom/.code = { \str_set:Nn \l_@@_ngerman_selected_case_str
                                   { nominative } },
    case/acc/.code = { \str_set:Nn \l_@@_ngerman_selected_case_str
                                   { accusative } },
    case/dat/.code = { \str_set:Nn \l_@@_ngerman_selected_case_str
                                   { dative } },
    case/gen/.code = { \str_set:Nn \l_@@_ngerman_selected_case_str
                                   { genitive } },
    names~table/.code = { \@@_ngerman_set_names_table:n {#1} },
    prepositions~always~followed~by~the~same~case/.code = {
      \prop_set_from_keyval:Nn \l_@@_ngerman_case_for_prep_prop {#1} },
    composition~table~for~prepositions~and~articles/.code = {
      \prop_set_from_keyval:Nn \l_@@_ngerman_article_and_prep_prop {#1} },
  }
%    \end{macrocode}
%
% \subsubsection{Main code}
%
% \begin{macro}{\xcref_ngerman_assemble_prep_and_article:nnN,
%               \xcref_ngerman_assemble_prep_and_article:VVN}
%   Assemble a preposition and an article.
%   \begin{arguments}
%   \item preposition
%   \item article
%   \item token list variable where the result is stored
%   \end{arguments}
%    \begin{macrocode}
\cs_new_protected:Npn \xcref_ngerman_assemble_prep_and_article:nnN #1#2#3
  {
    \prop_get:NnNF \l_@@_ngerman_article_and_prep_prop { #1~#2 } #3
      {
        \tl_set:Nn #3 { #1~#2 }
      }

    \@@_protect_accent_macros_from_tabbing:N #3
    \@@_protect_accent_macros_from_tabbing:N #3
  }

\cs_generate_variant:Nn \xcref_ngerman_assemble_prep_and_article:nnN { VV }
%    \end{macrocode}
% \end{macro}
% \begin{macro}{\@@_ngerman_set_names_table:n}
%   Set the \cs{g_@@_ngerman_names_prop} mapping to the given value.
%   \begin{arguments}
%   \item valid value for an \pkg{l3prop} object
%   \end{arguments}
%   This function can only be used in the preamble because the list of keys is
%   computed at |\begin{document}| time and stored in
%   \cs{g_@@_ngerman_types_seq}.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_ngerman_set_names_table:n #1
  {
    \prop_gset_from_keyval:Nn \g_@@_ngerman_names_prop {#1}
  }

\@onlypreamble \@@_ngerman_set_names_table:n
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\xcref_ngerman_set_names_table_entry:nnnnnn,
%               \xcrefngermanSetNamesTableEntry}
%   Set one $(\text{key}, \text{value})$ pair in \cs{g_@@_ngerman_names_prop}.
%   \begin{arguments}
%   \item reference type
%   \item default preposition, in LICR form
%   \item \meta{nominative}
%   \item \meta{accusative}
%   \item \meta{dative}
%   \item \meta{genitive}
%   \end{arguments}
%   Each of the \meta{nominative}, \meta{accusative}, \meta{dative} and
%   \meta{genitive} arguments should be of the form
%   |{|\meta{article-sing}|}{|\meta{noun-sing}|}{|\meta{article-plur}|}{|\meta{noun-plur}|}|,
%   where the four metasyntactic variables represent the definite article and
%   noun to use for reference type |#1| in singular and plural forms,
%   respectively.
%
%   This function can only be used in the preamble because it modifies
%   \cs{g_@@_ngerman_names_prop} and the list of keys in this property list is
%   computed at |\begin{document}| time (stored in \cs{g_@@_ngerman_types_seq}).
%    \begin{macrocode}
\cs_new_protected:Npn \xcref_ngerman_set_names_table_entry:nnnnnn #1#2#3#4#5#6
  {
    \prop_gput:Nnn \g_@@_ngerman_names_prop {#1} { {#2} {#3} {#4} {#5} {#6} }
  }

\@onlypreamble \xcref_ngerman_set_names_table_entry:nnnnnn

\NewDocumentCommand \xcrefngermanSetNamesTableEntry { m m m m m m }
  {
    \xcref_ngerman_set_names_table_entry:nnnnnn {#1} {#2} {#3} {#4} {#5} {#6}
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_ngerman_setup_cref_names:N}
%   Call \cs{crefname}, \cs{Crefname} and \cs{@crefdefineallformats} for each
%   reference type in |#1|.
%   \begin{arguments}
%   \item sequence variable containing reference types
%   \end{arguments}
%   This is the main entry point of the language-specific module.
%    \begin{macrocode}
\cs_new_protected:Npn \@@_ngerman_setup_cref_names:N #1
  {
    \seq_map_function:NN #1 \@@_ngerman_setup_cref_names_mapfunc:n
  }
%    \end{macrocode}
% \end{macro}
%
% \medskip
% Prepare the terrain for \cs{@@_ngerman_setup_cref_names_mapfunc:n}.
%    \begin{macrocode}
\cs_generate_variant:Nn \text_titlecase:nn { VV }
\cs_generate_variant:Nn \msg_error:nnn { nnV }
\cs_generate_variant:Nn \str_case:nnF { V }
%    \end{macrocode}
% Used to store data extracted from \cs{g_@@_ngerman_names_prop} corresponding
% to the selected reference type.
%    \begin{macrocode}
\tl_new:N \l_@@_gscnm_type_data_tl
\seq_new:N \l_@@_gscnm_type_data_seq
%    \end{macrocode}
% Used to store data for the selected case (one \meta{item} with index 2, 3,
% 4, or 5 in the values from \cs{g_@@_ngerman_names_prop}).
%    \begin{macrocode}
\tl_new:N \l_@@_gscnm_case_data_tl
\seq_new:N \l_@@_gscnm_case_data_seq
%    \end{macrocode}
% Selected preposition.
%    \begin{macrocode}
\tl_new:N \l_@@_gscnm_prep_tl
%    \end{macrocode}
% Value obtained from \cs{c_@@_ngerman_case_idx_prop}.
%    \begin{macrocode}
\tl_new:N \l_@@_gscnm_case_idx_tl
%    \end{macrocode}
% Singular and plural forms of the article.
%    \begin{macrocode}
\tl_new:N \l_@@_gscnm_article_sing_tl
\tl_new:N \l_@@_gscnm_article_plur_tl
%    \end{macrocode}
% What to insert before a reference name such as Abschnitt, Theorem, etc.
% (these contain the whole prefix: empty, article or preposition plus article,
% depending on the value of \xcrefPGFOpt{ngerman/form}).
%    \begin{macrocode}
\tl_new:N \l_@@_gscnm_prefix_sing_tl
\tl_new:N \l_@@_gscnm_prefix_plur_tl
%    \end{macrocode}
% The whole strings passed to \cs{crefname} and \cs{Crefname}.
%    \begin{macrocode}
\tl_new:N \l_@@_gscnm_singular_tl
\tl_new:N \l_@@_gscnm_plural_tl
%    \end{macrocode}
% Language for use with \cs{text_titlecase:nn}.
%    \begin{macrocode}
\tl_new:N \l_@@_gscnm_lang_tl
%    \end{macrocode}
% \begin{macro}{\@@_ngerman_setup_cref_names_mapfunc:n}
%   Call \cs{crefname}, \cs{Crefname} and \cs{@crefdefineallformats} for the
%   specified reference type.
%   \begin{arguments}
%   \item reference type (e.g., |chapter|, |section|, |theorem|, etc.)
%   \end{arguments}
%    \begin{macrocode}
\cs_new_protected:Npn \@@_ngerman_setup_cref_names_mapfunc:n #1
  {
    \prop_get:NnNF \g_@@_ngerman_names_prop {#1} \l_@@_gscnm_type_data_tl
      {
        \msg_error:nnn { xcref } { ngerman-requested-use-of-undefined-type }
                       {#1}
      }

    \seq_set_split:NnV \l_@@_gscnm_type_data_seq { } \l_@@_gscnm_type_data_tl
    \seq_pop_left:NN \l_@@_gscnm_type_data_seq \l_@@_gscnm_prep_tl
%    \end{macrocode}
% Override the default preposition for type |#1| if one was explicitly
% specified.
%    \begin{macrocode}
    \tl_if_empty:NF \l_@@_ngerman_selected_preposition_tl
      {
        \tl_set_eq:NN \l_@@_gscnm_prep_tl \l_@@_ngerman_selected_preposition_tl
      }
%    \end{macrocode}
% If the selected form has a preposition and that preposition is always
% followed by a particular case (e.g., |dative|), use it. This may seem strange
% to store the \enquote{new} case in \cs{l_@@_ngerman_selected_case_str}, but
% this variable will recover its previous value as soon as the group opened by
% \cs{xcref:nn} ends.
%    \begin{macrocode}
    \bool_lazy_any:nT
      {
        { \str_if_eq_p:Vn \l_@@_ngerman_selected_form_str { prep+noun } }
        { \str_if_eq_p:Vn \l_@@_ngerman_selected_form_str { prep+article+noun } }
      }
      {
        \prop_get:NVNT \l_@@_ngerman_case_for_prep_prop
                       \l_@@_gscnm_prep_tl \l_tmpa_tl
          { \str_set:Nx \l_@@_ngerman_selected_case_str { \l_tmpa_tl } }
      }

    \prop_get:NVNF \c_@@_ngerman_case_idx_prop
      \l_@@_ngerman_selected_case_str \l_@@_gscnm_case_idx_tl
      {
        \str_if_empty:NTF \l_@@_ngerman_selected_case_str
          { \msg_error:nn { xcref } { ngerman-unable-to-determine-the-case } }
          {
            \msg_error:nnV { xcref }
              { ngerman-unexpected-case-name-when-trying-to-find-index }
              \l_@@_ngerman_selected_case_str
          }
      }
%    \end{macrocode}
% Get data (initially coming from \cs{g_@@_ngerman_names_prop})
% corresponding to the selected case (|nominative|, |accusative|, etc.).
%    \begin{macrocode}
    \tl_set:Nx \l_@@_gscnm_case_data_tl
      { \seq_item:Nn \l_@@_gscnm_type_data_seq { \l_@@_gscnm_case_idx_tl } }

    \seq_set_split:NnV \l_@@_gscnm_case_data_seq { } \l_@@_gscnm_case_data_tl
    \seq_pop_left:NN \l_@@_gscnm_case_data_seq \l_@@_gscnm_article_sing_tl
    \seq_pop_left:NN \l_@@_gscnm_case_data_seq \l_@@_gscnm_singular_tl
    \seq_pop_left:NN \l_@@_gscnm_case_data_seq \l_@@_gscnm_article_plur_tl
    \seq_pop_left:NN \l_@@_gscnm_case_data_seq \l_@@_gscnm_plural_tl
%    \end{macrocode}
% Compute the \enquote{prefix} token list (what comes before the noun).
%    \begin{macrocode}
    \str_case:VnF \l_@@_ngerman_selected_form_str
      {
        { prep+article+noun }
        {
          \xcref_ngerman_assemble_prep_and_article:VVN \l_@@_gscnm_prep_tl
            \l_@@_gscnm_article_sing_tl \l_@@_gscnm_prefix_sing_tl
          \xcref_ngerman_assemble_prep_and_article:VVN \l_@@_gscnm_prep_tl
            \l_@@_gscnm_article_plur_tl \l_@@_gscnm_prefix_plur_tl
        }
        { prep+noun }
        {
          \tl_set_eq:NN \l_@@_gscnm_prefix_sing_tl \l_@@_gscnm_prep_tl
          \tl_set_eq:NN \l_@@_gscnm_prefix_plur_tl \l_@@_gscnm_prep_tl
        }
        { article+noun }
        {
          \tl_set_eq:NN \l_@@_gscnm_prefix_sing_tl \l_@@_gscnm_article_sing_tl
          \tl_set_eq:NN \l_@@_gscnm_prefix_plur_tl \l_@@_gscnm_article_plur_tl
        }
        { noun }
        {
          \tl_clear:N \l_@@_gscnm_prefix_sing_tl
          \tl_clear:N \l_@@_gscnm_prefix_plur_tl
        }
      }
      {
        \msg_error:nnV { xcref } { ngerman-unknown-prefix-form }
          \l_@@_ngerman_selected_form_str
      }
%    \end{macrocode}
% Make sure that when we use \cs{text_titlecase:nn} to prepare for
% \cs{Crefname}, the case of the noun won't be affected (we don't want nouns
% to become all-lowercase in German!).
%    \begin{macrocode}
    \tl_set:Nx \l_@@_gscnm_singular_tl
      { \exp_not:N \xcrefNoCaseChange
        { \exp_args:No \exp_not:n { \l_@@_gscnm_singular_tl } } }
    \tl_set:Nx \l_@@_gscnm_plural_tl
      { \exp_not:N \xcrefNoCaseChange
        { \exp_args:No \exp_not:n { \l_@@_gscnm_plural_tl } } }
%    \end{macrocode}
% Assemble the prefix and the noun.
%    \begin{macrocode}
    \tl_if_empty:NF \l_@@_gscnm_prefix_sing_tl
      {
        \tl_put_left:Nn \l_@@_gscnm_singular_tl { ~ }
        \tl_put_left:NV \l_@@_gscnm_singular_tl \l_@@_gscnm_prefix_sing_tl
      }
    \tl_if_empty:NF \l_@@_gscnm_prefix_plur_tl
      {
        \tl_put_left:Nn \l_@@_gscnm_plural_tl { ~ }
        \tl_put_left:NV \l_@@_gscnm_plural_tl \l_@@_gscnm_prefix_plur_tl
      }
%    \end{macrocode}
% Make sure \cs{xcref@tabacckludge} is used to protect \tn{'}, \tn{`} and
% \tn{=} from the \env{tabbing} environment, which redefines them (see the
% \pkg{inputenc} documentation).
%    \begin{macrocode}
    \@@_protect_accent_macros_from_tabbing:N \l_@@_gscnm_singular_tl
    \@@_protect_accent_macros_from_tabbing:N \l_@@_gscnm_plural_tl
%    \end{macrocode}
% Set up the non-capitalized forms.
%    \begin{macrocode}
    \@@_call_crefname:nVV {#1} \l_@@_gscnm_singular_tl \l_@@_gscnm_plural_tl
%    \end{macrocode}
% This influences the behavior of \cs{text_titlecase:nn}.
%    \begin{macrocode}
    \tl_set_eq:NN \l_text_case_exclude_arg_tl \l_@@_case_change_exclude_tl
%    \end{macrocode}
% Prepare for the language-specific case conversion.
%    \begin{macrocode}
    \tl_set:Nx \l_@@_gscnm_lang_tl
      { \xcref_lang_for_text_titlecase:V \l_@@_selected_lang_str }
    \tl_set:Nx \l_@@_gscnm_singular_tl
      { \text_titlecase:VV \l_@@_gscnm_lang_tl \l_@@_gscnm_singular_tl }
    \tl_set:Nx \l_@@_gscnm_plural_tl
      { \text_titlecase:VV \l_@@_gscnm_lang_tl \l_@@_gscnm_plural_tl }
%    \end{macrocode}
% Set up the capitalized forms.
%    \begin{macrocode}
    \@@_call_Crefname:nVV {#1} \l_@@_gscnm_singular_tl \l_@@_gscnm_plural_tl
%    \end{macrocode}
% Call \cs{@crefdefineallformats} to define all things derived from the
% \cs{crefname} and \cs{Crefname} calls we just did (for instance, this will
% call \cs{crefmultiformat}, which in turn will define
% \cs{cref@\meta{type}@format@first}, among others). This is likely to be
% slow.
%    \begin{macrocode}
    \@@_call_crefdefineallformats:n {#1}
  }
%    \end{macrocode}
% \end{macro}
%
% \begin{macro}{\@@_ngerman_generic_wrapper:nn, \xcrefngermangenericwrapper,
%               \xcrefngermanwrapper, \xcrefngermanWrapper}
% Create convenience \cs{xcref} wrappers for \texttt{ngerman}.
%    \begin{macrocode}
\@@_create_language_specific_wrapper:nNNNN { ngerman }
  \@@_ngerman_generic_wrapper:nn \xcrefngermangenericwrapper
  \xcrefngermanwrapper \xcrefngermanWrapper
%    \end{macrocode}
% \end{macro}
% Fill the list of known types (\cs{g_@@_ngerman_types_seq}) with the keys of
% \cs{g_@@_ngerman_names_prop}. Since we only do this here, this implies that
% \xcrefPGFOpt{ngerman/names table} can only be set in the preamble (otherwise,
% \cs{g_@@_ngerman_types_seq} and \cs{g_@@_ngerman_names_prop} would become
% out of sync).
%    \begin{macrocode}
\AtBeginDocument
  {
    \seq_gclear:N \g_@@_ngerman_types_seq
    \prop_map_inline:Nn \g_@@_ngerman_names_prop
      { \seq_gput_right:Nn \g_@@_ngerman_types_seq {#1} }
  }
%    \end{macrocode}
% Switch off the \pkg{expl3} category code régime.
%    \begin{macrocode}
\ExplSyntaxOff
%    \end{macrocode}
% \pkg{DocStrip} end guard for \file{xcref-ngerman.tex}.
%    \begin{macrocode}
%</ngerman-module>
%    \end{macrocode}
%
% \end{implementation}
%
% \PrintIndex