% arara: lualatex % arara: bib2gls: { group: on, options: [ "--replace-quotes" ] } % arara: lualatex % arara: bib2gls: { group: on, options: [ "--replace-quotes" ] } if found ("log", "Glossary entry `sym.") % arara: lualatex % arara: lualatex if found ("log", "Rerun to") % This document requires glossaries v4.51, glossaries-extra v1.50 % and nlctuserguide.sty v1.09. If they haven't already % been uploaded to CTAN, they will be in a few days. \documentclass[titlepage=false,oneside, fontsize=12pt,captions=tableheading]{scrbook} \usepackage [ floats, %debug=showwrgloss ] {nlctuserguide} \usepackage{glossary-table} \glsxtrnewgls{opt.envvar.}{\envvar} \defsemanticcmd[style2]{\envvarfmt}{\texttt}{} \defsemanticcmd[style1]{\langtagfmt}{\texttt}{} \glsaddstoragekey{dialect}{}{\dialect} \glsaddstoragekey{isotag}{}{\isotag} \glsaddstoragekey{langtag}{}{\langtag} \glsxtrprovidestoragekey{tags}{}{} \glsxtrprovidestoragekey{region}{}{} \glsaddstoragekey{numeric}{}{\numerictag} \glsxtrprovidestoragekey{alpha3}{}{} \newcommand{\optisotag}[1]{\isotag{opt.#1}} \newcommand{\iso}[1]{\glslink{opt.#1}{\optfmt{\optisotag{#1}}}} \newcommand{\numericcode}[1]{\glslink{opt.#1}{\glsxtrusefield{opt.#1}{numeric}}} \newcommand{\tklscript}[1]{\glslink{TrackLangScriptCode}{\csfmt{TrackLangScript#1}}} \newcommand{\tklcaptions}[1]{\glslink{captionsdialect}{\csfmt{captions#1}}} \newcommand{\tkldate}[1]{\glslink{datedialect}{\csfmt{date#1}}} \newcommand{\ldf}[2]{% \glslink{file.prefix-localeid.ldf}{\filefmt{#1\dhyphen #2.ldf}}} \newcommand{\localefile}[1]{% \glslink{file.prefix-localeid.ldf}{\metafilefmt{#1\dhyphen}{localeid}{.ldf}}} \newcommand{\localemetafile}[1]{% \glslink{file.prefix-localeid.ldf}{\metametafilefmt{}{#1}{\dhyphen}{localeid}{.ldf}}} \newcommand{\localemetametafile}[2]{% \glslink{file.prefix-localeid.ldf}{\metametafilefmt{}{#1}{\dhyphen}{#2}{.ldf}}} \newcommand{\fnregion}{\fnsym*{2}} \renewcommand{\filetag}[1]{} \renewcommand{\nlctuserguidecustomentryaliases}{% isolangregion=index, rootlang=index, noniso=index, isocode=index, region=index, script=index } \nlctuserguidegls[selection=all] { \def\genvvar#1#2{% \glsbibwriteentry{option}{opt.envvar.#1}{% \field{name}{\envvarfmt{#1}}\parent{idx.envvar}#2}}% \gidxpl{envvar}{\field{text}{environment variable}} % predefined ISO language-region tags % \gisolangtag{xx}{XX}{dialect}{options} \def\gisolangtag#1#2#3#4{% \glsbibwriteentry{isolangregion}{opt.#1-#2}{% \name{\optfmt{#1-#2}}% \field{langtag}{#1}\field{region}{#2}% \field{isotag}{#1-#2}% \field{dialect}{#3}#4}% }% % \gisolangtagwithvar{xx}{XX}{variant}{dialect}{options} \def\gisolangtagwithvar#1#2#3#4#5{% \glsbibwriteentry{isolangregion}{opt.#1-#2-#3}{% \name{\optfmt{#1-#2-#3}}% \field{langtag}{#1}\field{region}{#2}% \field{isotag}{#1-#2-#3}% \field{dialect}{#4}#5}% }% % predefined root language labels % \grootlangtag{language}{iso tag}{options} \def\grootlangtag#1#2#3{% \glsbibwriteentry{rootlang}{opt.#1}{% \name{\optfmt{#1}}% \field{dialect}{#1}% \field{langtag}{#2}% \field{isotag}{#2}#3}% \glsbibwriteentry{isocode}{opt.#2}{\name{\optfmt{#2}}\field{alias}{opt.#1}}% }% % \grootlangsametag{language}{options} \def\grootlangsametag#1#2{% \glsbibwriteentry{rootlang}{opt.#1}{% \name{\optfmt{#1}}% \field{dialect}{#1}% \field{langtag}{#1}% \field{isotag}{#1}#2}% }% % \grootlangtagwithreg{language}{lang}{region}{options} \def\grootlangtagwithreg#1#2#3#4{% \glsbibwriteentry{rootlang}{opt.#1}{% \field{name}{\optfmt{#1}\fnregion} \field{text}{\optfmt{#1}} \field{region}{#3} \field{dialect}{#1}% \field{langtag}{#2} \field{isotag}{#2-#3}#4}% \glsbibwriteentry{isocode}{opt.#2}{\name{\optfmt{#2}}\field{alias}{opt.#1}}% } % predefined non-iso dialects % \gdialecttag{dialect}{tag}{options} \def\gdialecttag#1#2#3{% \glsbibwriteentry{noniso}{opt.#1}{% \name{\optfmt{#1}}% \field{dialect}{#1}% \field{isotag}{\optisotag{#2}}% \field{tags}{\optfmt{\optisotag{#2}}}#3}% }% % \gdialecttagsuppl{dialect}{tag}{suppl}{options} \def\gdialecttagsuppl#1#2#3#4{% \glsbibwriteentry{noniso}{opt.#1}{% \name{\optfmt{#1}}% \field{dialect}{#1}% \field{isotag}{\optisotag{#2}-#3}% \field{tags}{\optfmt{\optisotag{#2}-#3}}#4}% }% % \gdialecttagwithmap{dialect}{tag}{mapped}{options} \def\gdialecttagwithmap#1#2#3#4{% \glsbibwriteentry{noniso}{opt.#1}{% \field{dialect}{#1}% \field{isotag}{\optisotag{#2}}% \field{tags}{\optfmt{\optisotag{#2}} / \optfmt{#3}}#4}% }% % \gdialecttagsupplwithmap{dialect}{tag}{suppl}{mapped}{options} \def\gdialecttagsupplwithmap#1#2#3#4#5{% \glsbibwriteentry{noniso}{opt.#1}{% \name{\optfmt{#1}}% \field{dialect}{#1}% \field{isotag}{\optisotag{#2}-#3}% \field{tags}{\optfmt{\optisotag{#2}-#3} / \opt{#4}}#5}% }% % \gdialecttagwithreg{dialect}{lang}{region}{options} \def\gdialecttagwithreg#1#2#3#4{% \glsbibwriteentry{noniso}{opt.#1}{% \field{name}{\optfmt{#1}\fnregion } \field{text}{\optfmt{#1}} \field{region}{#3} \field{dialect}{#1}% \field{isotag}{\langtag{opt.#2}-#3}% \field{tags}{\optfmt{\langtag{opt.#2}-#3}}#4 }% }% % \gdialecttagwithmapandreg{dialect}{tag}{region}{mapped}{options} \def\gdialecttagwithmapandreg#1#2#3#4#5{% \glsbibwriteentry{noniso}{opt.#1}{% \field{name}{\optfmt{#1}\fnregion } \field{text}{\optfmt{#1}} \field{region}{#3} \field{dialect}{#1}% \field{isotag}{\optisotag{#2}-#3}% \field{tags}{\optfmt{\langtag{opt.#2}-#3} / \opt{#4}}#5}% }% % \gregion{numeric}{2-alpha}{3-alpha}{options} \def\gregion#1#2#3#4{% \glsbibwriteentry{region}{opt.#2}{% \field{name}{\optfmt{#2}} \field{numeric}{#1}\field{alpha3}{#3} #4}% }% % \gscript{alpha}{numeric}{name}{direction}{parent}{options} \def\gscript#1#2#3#4#5#6{% \glsbibwriteentry{script}{opt.#1}{% \field{name}{\optfmt{#1}} \field{numeric}{#2}\field{user2}{#4}\field{description}{#3} #6}% }% % COMMANDS % \AnyTrackedLanguages \gcmd{Any\-Track\-ed\-Lan\-guages} { \providedby{\file{tracklang.tex} v1.0+} \syntax{\margm{true}\margm{false}} \desc{expands to \meta{true} if there are any tracked languages, otherwise expands to \meta{false}} } % \IfTrackedLanguage \gcmd{If\-Track\-ed\-Lan\-guage} { \providedby{\file{tracklang.tex} v1.0+} \syntax{\margm{language-label}\margm{true}\margm{false}} \desc{does \meta{true} if the language identified by \meta{language-label} has been tracked, otherwise does \meta{false}} } % \IfTrackedDialect \gcmd{If\-Track\-ed\-Di\-alect} { \providedby{\file{tracklang.tex} v1.0+} \syntax{\margm{dialect-label}\margm{true}\margm{false}} \desc{does \meta{true} if the dialect identified by \meta{dialect-label} has been tracked, otherwise does \meta{false}} } % \IfTrackedLanguageFileExists \gcmd{If\-Track\-ed\-Lan\-guage\-File\-Exists} { \providedby{\file{tracklang.tex} v1.0+} \syntax{\margm{dialect}\margm{prefix}\margm{suffix}\margm{true code}\margm{false code}} \desc{does \code{\gls{SetCurrentTrackedDialect}\margm{dialect}} and if the dialect is recognised, then determines if the file \filefmt{\meta{prefix}\meta{tag}\meta{suffix}} exists. If it does, \gls{CurrentTrackedTag} is set to \meta{tag} and \meta{true} is done, otherwise \meta{false} is done} } % \CurrentTrackedTag \gcmd{Current\-Track\-ed\-Tag} { \providedby{\file{tracklang.tex} v1.0+} \desc{expands to the current tracked tag} } % \ifTrackLangShowWarnings \gcond{if\-Track\-Lang\-Show\-Warnings} { \initval{\cmd{iftrue}} \providedby{\file{tracklang.tex} v1.3+} \desc{conditional that indicates whether or not to show warnings} } % \TrackLangShowWarningsfalse \gcmd{Track\-Lang\-Show\-Warnings\-false} { \providedby{\file{tracklang.tex} v1.3+} \desc{sets \gls{ifTrackLangShowWarnings} to false} } % \TrackLangShowWarningstrue \gcmd{Track\-Lang\-Show\-Warnings\-true} { \providedby{\file{tracklang.tex} v1.3+} \desc{sets \gls{ifTrackLangShowWarnings} to true} } % \ifTrackLangShowInfo \gcond{if\-Track\-Lang\-Show\-Info} { \initval{\cmd{iftrue}} \providedby{\file{tracklang.tex} v1.3+} \desc{conditional that indicates whether or not to show information messages} } % \ifTrackLangShowVerbose \gcond{if\-Track\-Lang\-Show\-Verbose} { \initval{\cmd{iffalse}} \providedby{\file{tracklang.tex} v1.4+} \desc{conditional that indicates whether or not to show verbose messages} } % \TrackLangQueryEnv \gcmd{Track\-Lang\-Query\-Env} { \providedby{\file{tracklang.tex} v1.3+} \desc{attempts to obtain locale information from the \envvar{LCALL} environment variable via the \idx{shellescape} or, with \LuaTeX, \gls{directlua}} } % \TrackLangQueryOtherEnv \gcmd{Track\-Lang\-Query\-Other\-Env} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{env-name}} \desc{attempts to obtain locale information from the \envvar{LCALL} environment variable and then by the \meta{env-name} environment variable via the \idx{shellescape} or, with \LuaTeX, \gls{directlua}} } % \TrackLangParseFromEnv \gcmd{Track\-Lang\-Parse\-From\-Env} { \providedby{\file{tracklang.tex} v1.3+} \desc{attempts to obtain locale information from the expansion of \gls{TrackLangEnv}} } % \TrackLangEnv \gcmd{Track\-Lang\-Env} { \note{user defined} \desc{may be defined using the same format as \envvar{LCALL} before using \gls{TrackLangParseFromEnv} to skip the environment variable query} } % \TrackLangEnvLang \gcmd{Track\-Lang\-Env\-Lang} { \providedby{\file{tracklang.tex} v1.3+} \desc{set by \gls{TrackLangParseFromEnv} to the language code} } % \TrackLangEnvTerritory \gcmd{Track\-Lang\-Env\-Territory} { \providedby{\file{tracklang.tex} v1.3+} \desc{set by \gls{TrackLangParseFromEnv} to the \idx{territory}} } % \TrackLangEnvCodeSet \gcmd{Track\-Lang\-Env\-Code\-Set} { \providedby{\file{tracklang.tex} v1.3+} \desc{set by \gls{TrackLangParseFromEnv} to the \idx{code-set}} } % \TrackLangEnvModifier \gcmd{Track\-Lang\-Env\-Modifier} { \providedby{\file{tracklang.tex} v1.3+} \desc{set by \gls{TrackLangParseFromEnv} to the \idx{modifier}} } % \ForEachTrackedLanguage \gcmd{For\-Each\-Track\-ed\-Lan\-guage} { \providedby{\file{tracklang.tex} v1.0+} \syntax{\margm{cs}\margm{body}} \desc{iterates through the list of tracked languages. On each iteration \meta{cs} is set to the language tag and \meta{body} is performed} } % \ForEachTrackedDialect \gcmd{For\-Each\-Track\-ed\-Di\-alect} { \providedby{\file{tracklang.tex} v1.0+} \syntax{\margm{cs}\margm{body}} \desc{iterates through the list of tracked dialects. On each iteration \meta{cs} is set to the dialect tag and \meta{body} is performed} } % \TrackLangNewLanguage \gcmd{Track\-Lang\-New\-Lan\-guage} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{language label}\margm{639-1 code}\margm{639-2 (T)}% \margm{639-2 (B)}\margm{639-3}\margm{3166-1}\margm{default script}} \desc{identifies a new language that may be tracked. Apart from \meta{language label}, the other arguments may be empty if the information is unavailable} } % \TrackLangIfKnownLang \gcmd{Track\-Lang\-If\-Known\-Lang} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{language}\margm{true}\margm{false}} \desc{does \meta{true} if \meta{language} is known (but not necessarily tracked), otherwise does \meta{false}} } % \TrackLangIfKnownIsoTwoLetterLang \gcmd{Track\-Lang\-If\-Known\-Iso\-Two\-Letter\-Lang} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{language}\margm{true}\margm{false}} \desc{does \meta{true} if \meta{language} has an \idxn{639-1} code (but is not necessarily tracked), otherwise does \meta{false}} } % \TrackLangGetKnownIsoTwoLetterLang \gcmd{Track\-Lang\-Get\-Known\-Iso\-Two\-Letter\-Lang} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{language}} \desc{expands to the \idxn{639-1} language code associated with \meta{language}} } % \TrackLangIfKnownIsoThreeLetterLang \gcmd{Track\-Lang\-If\-Known\-Iso\-Three\-Letter\-Lang} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{language}\margm{true}\margm{false}} \desc{does \meta{true} if \meta{language} has an \idxn{639-2} code (but is not necessarily tracked), otherwise does \meta{false}} } % \TrackLangGetKnownIsoThreeLetterLang \gcmd{Track\-Lang\-Get\-Known\-Iso\-Three\-Letter\-Lang} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{language}} \desc{expands to the \idxn{639-2} language code associated with \meta{language}} } % \TrackLangIfKnownIsoThreeLetterLangB \gcmd{Track\-Lang\-If\-Known\-Iso\-Three\-Letter\-LangB} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{language}\margm{true}\margm{false}} \desc{does \meta{true} if \meta{language} has an \idxn{639-2B} code (but is not necessarily tracked), otherwise does \meta{false}} } % \TrackLangGetKnownIsoThreeLetterLangB \gcmd{Track\-Lang\-Get\-Known\-Iso\-Three\-Letter\-LangB} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{language}} \desc{expands to the \idxn{639-2B} language code associated with \meta{language}} } % \IfTrackedLanguageHasIsoCode \gcmd{If\-Track\-ed\-Lan\-guage\-Has\-Iso\-Code} { \providedby{\file{tracklang.tex} v1.0+} \syntax{\margm{code type}\margm{label}\margm{true}\margm{false}} \desc{does \meta{true} if the given language or dialect has a corresponding \idx{ISO} code of the given type, otherwise does \meta{false}} } % \IfTrackedIsoCode \gcmd{If\-Track\-ed\-Iso\-Code} { \providedby{\file{tracklang.tex} v1.0+} \syntax{\margm{code type}\margm{code}\margm{true}\margm{false}} \desc{does \meta{true} if the given \idx{ISO} code has been defined otherwise does \meta{false}} } % \TrackLangIfKnownLangFromIso \gcmd{Track\-Lang\-If\-Known\-Lang\-From\-Iso} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{ISO code}\margm{true}\margm{false}} \desc{does \meta{true} if the given language code (\idx{639-1} or \idx{639-2} or \idx{639-3}) is recognised (but not necessarily tracked), otherwise does \meta{false}} } % \TrackLangGetKnownLangFromIso \gcmd{Track\-Lang\-Get\-Known\-Lang\-From\-Iso} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{ISO code}} \desc{expands to the root language label from the given \idx{ISO} code (\idx{639-1} or \idx{639-2} or \idx{639-3})} } % \TrackLangIfHasKnownCountry \gcmd{Track\-Lang\-If\-Has\-Known\-Coun\-try} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{language}\margm{true}\margm{false}} \desc{does \meta{true} if the given language has an \idxn{3166-1} country code (but is not necessarily tracked), otherwise does \meta{false}} } % \TrackLangGetKnownCountry \gcmd{Track\-Lang\-Get\-Known\-Coun\-try} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{language}} \desc{expands to the \idxn{3166-1} country code for the given language} } % \TrackLangGetDefaultScript \gcmd{Track\-Lang\-Get\-Default\-Script} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{language}} \desc{expands to the default script for the given language} } % \TrackLangIfHasDefaultScript \gcmd{Track\-Lang\-If\-Has\-Default\-Script} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{language}\margm{true}\margm{false}} \desc{does \meta{true} if the given language has a default script (but is not necessarily tracked), otherwise does \meta{false}} } % \AddTrackedDialect \gcmd{Add\-Track\-ed\-Di\-alect} { \providedby{\file{tracklang.tex} v1.0+} \syntax{\margm{dialect label}\margm{root language label}} \desc{tracks a dialect. This command defines \gls{TrackLangLastTrackedDialect} to provide a convenient way to reference the last dialect to be tracked} } % \AddTrackedLanguage \gcmd{Add\-Track\-ed\-Lan\-guage} { \providedby{\file{tracklang.tex} v1.0+} \syntax{\margm{root language label}} \desc{shortcut for \code{\gls{AddTrackedDialect}\margm{root language label}\margm{root language label}}} } % \AddTrackedIsoLanguage \gcmd{Add\-Track\-ed\-Iso\-Lan\-guage} { \providedby{\file{tracklang.tex} v1.0+} \syntax{\margm{code type}\margm{code}\margm{language}} \desc{adds a mapping between the given \idx{ISO} code and language name} } % \TrackedLanguageFromIsoCode \gcmd{Tracked\-Lan\-guage\-From\-Iso\-Code} { \providedby{\file{tracklang.tex} v1.0+} \syntax{\margm{code type}\margm{code}} \desc{expands to a comma-separated list of language or dialect labels associated with the given code} } % \TrackedIsoCodeFromLanguage \gcmd{Track\-ed\-Iso\-Code\-From\-Lan\-guage} { \providedby{\file{tracklang.tex} v1.0+} \syntax{\margm{code type}\margm{label}} \desc{expands to the code associated with the given language or dialect identified by \meta{label}} } % \TrackedLanguageFromDialect \gcmd{Track\-ed\-Lan\-guage\-From\-Di\-alect} { \providedby{\file{tracklang.tex} v1.0+} \syntax{\margm{dialect}} \desc{expands to the language from the given dialect} } % \TrackedDialectsFromLanguage \gcmd{Tracked\-Di\-alects\-From\-Lan\-guage} { \providedby{\file{tracklang.tex} v1.0+} \syntax{\margm{root language label}} \desc{expands to a comma-separated list of the tracked dialects with the given language} } % \TwoLetterIsoCountryCode \gcmd{Two\-Letter\-Iso\-Coun\-try\-Code} { \providedby{\file{tracklang.tex} v1.0+} \desc{expands to \idx{3166-1} (should not be redefined)} } % \TwoLetterIsoLanguageCode \gcmd{Two\-Letter\-Iso\-Lan\-guage\-Code} { \providedby{\file{tracklang.tex} v1.0+} \desc{expands to \idx{639-1} (should not be redefined)} } % \ThreeLetterIsoLanguageCode \gcmd{Three\-Letter\-Iso\-Lan\-guage\-Code} { \providedby{\file{tracklang.tex} v1.0+} \desc{expands to \idx{639-2} (should not be redefined)} } % \ThreeLetterExtIsoLanguageCode \gcmd{Three\-Letter\-Ext\-Iso\-Lan\-guage\-Code} { \providedby{\file{tracklang.tex} v1.3+} \desc{expands to \idx{639-3} (should not be redefined)} } % \SetTrackedDialectModifier \gcmd{Set\-Track\-ed\-Di\-alect\-Mod\-i\-fier} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{dialect}\margm{value}} \desc{sets the modifier for the given \meta{dialect} to \meta{value}} } % \GetTrackedDialectModifier \gcmd{Get\-Track\-ed\-Di\-alect\-Mod\-i\-fier} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{dialect}} \desc{expands to the modifier for the given dialect} } % \IfHasTrackedDialectModifier \gcmd{If\-Has\-Track\-ed\-Di\-alect\-Mod\-i\-fier} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{dialect}\margm{true}\margm{false}} \desc{expands to \meta{true} if there's a modifier for the given dialect, otherwise expands to \meta{false}} } % \SetTrackedDialectScript \gcmd{Set\-Track\-ed\-Di\-alect\-Script} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{dialect}\margm{value}} \desc{sets the script for \meta{dialect} to \meta{value}} } % \GetTrackedDialectScript \gcmd{Get\-Track\-ed\-Di\-alect\-Script} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{dialect}} \desc{expands to the script for \meta{dialect}} } % \IfHasTrackedDialectScript \gcmd{If\-Has\-Track\-ed\-Di\-alect\-Script} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{dialect}\margm{true}\margm{false}} \desc{expands to \meta{true} if there's a script for \meta{dialect}, otherwise expands to \meta{false}} } % \IfTrackedDialectIsScriptCs \gcmd{If\-Track\-ed\-Di\-alect\-Is\-Script\-Cs} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{dialect}\margm{cs}\margm{true}\margm{false}} \desc{if the given tracked dialect has an associated script and that script code matches the replacement text for the control sequence \meta{cs} then do \meta{true} otherwise to \meta{false}. If the tracked dialect doesn't have an associated script then the default script for the root language is tested} } % \SetTrackedDialectVariant \gcmd{Set\-Track\-ed\-Di\-alect\-Vari\-ant} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{dialect}\margm{value}} \desc{sets the modifier for \meta{dialect} to \meta{value}} } % \GetTrackedDialectVariant \gcmd{Get\-Track\-ed\-Di\-alect\-Vari\-ant} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{dialect}} \desc{expands to the modifier for \meta{dialect}} } % \IfHasTrackedDialectVariant \gcmd{If\-Has\-Track\-ed\-Di\-alect\-Vari\-ant} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{dialect}\margm{true}\margm{false}} \desc{expands to \meta{true} if there's a modifier for \meta{dialect}, otherwise expands to \meta{false}} } % \SetTrackedDialectSubLang \gcmd{Set\-Track\-ed\-Di\-alect\-Sub\-Lang} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{dialect}\margm{value}} \desc{sets the sub-language for \meta{dialect} to \meta{value}} } % \GetTrackedDialectSubLang \gcmd{Get\-Track\-ed\-Di\-alect\-Sub\-Lang} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{dialect}} \desc{expands to the sub-language for \meta{dialect}} } % \IfHasTrackedDialectSubLang \gcmd{If\-Has\-Track\-ed\-Di\-alect\-Sub\-Lang} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{dialect}\margm{true}\margm{false}} \desc{expands to \meta{true} if there's a sub-language for \meta{dialect}, otherwise expands to \meta{false}} } % \SetTrackedDialectAdditional \gcmd{Set\-Track\-ed\-Di\-alect\-Ad\-di\-tional} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{dialect}\margm{value}} \desc{sets the extra information for \meta{dialect} to \meta{value}} } % \GetTrackedDialectAdditional \gcmd{Get\-Track\-ed\-Di\-alect\-Ad\-di\-tional} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{dialect}} \desc{expands to the extra information for \meta{dialect}} } % \IfHasTrackedDialectAdditional \gcmd{If\-Has\-Track\-ed\-Di\-alect\-Ad\-di\-tional} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{dialect}\margm{true}\margm{false}} \desc{expands to \meta{true} if there's extra information for \meta{dialect}, otherwise expands to \meta{false}} } % \GetTrackedLanguageTag \gcmd{Get\-Track\-ed\-Lan\-guage\-Tag} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{dialect}} \desc{gets the language tag for \meta{dialect}} } % \SetCurrentTrackedDialect \gcmd{Set\-Current\-Track\-ed\-Di\-alect} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{dialect}} \desc{sets the current tracked dialect} } % \CurrentTrackedDialect \gcmd{Current\-Track\-ed\-Dialect} { \providedby{\file{tracklang.tex} v1.3+} \desc{defined by \gls{SetCurrentTrackedDialect} to the dialect label, which may be the supplied \meta{dialect} label or the mapped label or, if \meta{dialect} is a root language label, the last tracked dialect for the given root language} } % \CurrentTrackedLanguage \gcmd{Current\-Track\-ed\-Language} { \providedby{\file{tracklang.tex} v1.3+} \desc{defined by \gls{SetCurrentTrackedDialect} to the associated root language label} } % \CurrentTrackedDialectModifier \gcmd{Current\-Track\-ed\-Di\-alect\-Modifier} { \providedby{\file{tracklang.tex} v1.3+} \desc{defined by \gls{SetCurrentTrackedDialect} to the associated modifier (may be empty)} } % \CurrentTrackedDialectVariant \gcmd{Current\-Track\-ed\-Di\-alect\-Variant} { \providedby{\file{tracklang.tex} v1.3+} \desc{defined by \gls{SetCurrentTrackedDialect} to the associated variant (may be empty)} } % \CurrentTrackedDialectScript \gcmd{Current\-Track\-ed\-Di\-alect\-Script} { \providedby{\file{tracklang.tex} v1.3+} \desc{defined by \gls{SetCurrentTrackedDialect} to the script associated with the dialect, or to the default script for the language} } % \CurrentTrackedDialectSubLang \gcmd{Current\-Track\-ed\-Di\-alect\-Sub\-Lang} { \providedby{\file{tracklang.tex} v1.3+} \desc{defined by \gls{SetCurrentTrackedDialect} to the sub language associated with the dialect (may be empty)} } % \CurrentTrackedDialectAdditional \gcmd{Current\-Track\-ed\-Di\-alect\-Ad\-di\-tional} { \providedby{\file{tracklang.tex} v1.3+} \desc{defined by \gls{SetCurrentTrackedDialect} to the additional part associated with the dialect (may be empty)} } % \CurrentTrackedLanguageTag \gcmd{Current\-Track\-ed\-Lan\-guage\-Tag} { \providedby{\file{tracklang.tex} v1.3+} \desc{defined by \gls{SetCurrentTrackedDialect} to the language tag that identifies the dialect or \iso{undetermined} if no match} } % \CurrentTrackedRegion \gcmd{Current\-Track\-ed\-Region} { \providedby{\file{tracklang.tex} v1.3+} \desc{defined by \gls{SetCurrentTrackedDialect} to the \idxn{3166-1} region code associated with the dialect (may be empty)} } % \CurrentTrackedIsoCode \gcmd{Current\-Track\-ed\-Iso\-Code} { \providedby{\file{tracklang.tex} v1.3+} \desc{defined by \gls{SetCurrentTrackedDialect} to the \idxn{639-1} or \idx{639-2} or \idx{639-3} language code (may be empty)} } % \AddTrackedLanguageIsoCodes \gcmd{Add\-Track\-ed\-Lan\-guage\-Iso\-Codes} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{root language label}} \desc{adds the \idxn{639-1}, \idx{639-2} and \idx{639-3} codes, which must have previously been declared using \gls{TrackLangNewLanguage}} } % \AddTrackedCountryIsoCode \gcmd{Add\-Track\-ed\-Coun\-try\-Iso\-Code} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{language}} \desc{adds the \idxn{3166-1} code} } % \GetTrackedDialectFromLanguageTag \gcmd{Get\-Track\-ed\-Di\-alect\-From\-Lan\-guage\-Tag} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{tag}\margm{cs}} \desc{finds the tracked dialect that matches the given language tag and stores the dialect label in \meta{cs}. If no match found, \meta{cs} will be empty} } % \TrackedDialectClosestSubMatch \gcmd{Track\-ed\-Dialect\-Closest\-Sub\-Match} { \providedby{\file{tracklang.tex} v1.3.6+} \desc{defined by \gls{GetTrackedDialectFromLanguageTag} to the closest match} } % \TrackPredefinedDialect \gcmd{Track\-Pre\-de\-fined\-Di\-alect} { \providedby{\file{tracklang.tex} v1.0+} \syntax{\margm{dialect label}} \desc{tracks a predefined language or dialect} } % \TrackLangIfAlphaNumericChar \gcmd{Track\-Lang\-If\-Alpha\-Numeric\-Char} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{tag}\margm{true}\margm{false}} \desc{does \meta{true} if the argument is a single alphanumeric character otherwise does \meta{false}} } % \TrackLangIfLanguageTag \gcmd{Track\-Lang\-If\-Lan\-guage\-Tag} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{tag}\margm{true}\margm{false}} \desc{does \meta{true} if the argument is a language tag otherwise does \meta{false}} } % \TrackLangIfRegionTag \gcmd{Track\-Lang\-If\-Region\-Tag} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{tag}\margm{true}\margm{false}} \desc{does \meta{true} if the argument is a region tag otherwise does \meta{false}} } % \TrackLangIfScriptTag \gcmd{Track\-Lang\-If\-Script\-Tag} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{tag}\margm{true}\margm{false}} \desc{does \meta{true} if the argument is a script tag otherwise does \meta{false}} } % \TrackLangIfVariantTag \gcmd{Track\-Lang\-If\-Vari\-ant\-Tag} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{tag}\margm{true}\margm{false}} \desc{does \meta{true} if the argument is a variant tag otherwise does \meta{false}} } % \TrackLanguageTag \gcmd{Track\-Lan\-guage\-Tag} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{tag}} \desc{parse \meta{tag}, which should be a regular, well-formed RFC 5646 language tag (not an irregular grandfather tag) and track the dialect} } % \TrackIfKnownLanguage \gcmd{Track\-If\-Known\-Lan\-guage} { \providedby{\file{tracklang.tex} v1.3.9+} \syntax{\margm{tag}\margm{success code}\margm{fail code}} \desc{as \gls{TrackLanguageTag} but does \meta{fail code} if the tag doesn't contain a valid language code. If successful, does \meta{success code} after tracking the language} } % \TrackLangAddExtraRegionFile \gcmd{Track\-Lang\-Add\-Extra\-Region\-File} { \providedby{\file{tracklang.tex} v1.4+} \syntax{\margm{file}} \desc{adds \meta{file} to the list of extra region code files that should be input by \file{tracklang-region-codes.tex}} } % \TrackLangAddExtraScriptFile \gcmd{Track\-Lang\-Add\-Extra\-Script\-File} { \providedby{\file{tracklang.tex} v1.4+} \syntax{\margm{file}} \desc{adds \meta{file} to the list of files that should be input by \file{tracklang-scripts.tex}} } % \TrackLangFromEnv \gcmd{Track\-Lang\-From\-Env} { \providedby{\file{tracklang.tex} v1.3+} \desc{queries environment variable if \gls{TrackLangEnv} not already set, parses \gls{TrackLangEnv} if it has been set, and adds the dialect if it's recognised} } % \TrackLocale \gcmd{Track\-Locale} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{locale}} \desc{tracks the dialect identified by the given \meta{locale}, which may either be a predefined language\slash dialect or in the same format as \gls{TrackLangEnv}} } % \TrackLangProvidePredefinedLanguage \gcmd{Track\-Lang\-Provide\-Pre\-de\-fined\-Lan\-guage} { \providedby{\file{tracklang.tex} v1.4+} \syntax{\margm{language label}} \desc{sets up a language label for use with \gls{TrackPredefinedDialect}} } % \TrackLangDeclareLanguageOption \gcmd{Track\-Lang\-Declare\-Lan\-guage\-Op\-tion} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{language name}\margm{639-1 code}\margm{639-2 (T)}\margm{639-2 (B)}\margm{639-3}\margm{3166-1}\margm{default script}} \desc{defines a new root language that's declared as an option} } % \TrackLangProvidePredefinedDialect \gcmd{Track\-Lang\-Provide\-Pre\-de\-fined\-Di\-alect} { \providedby{\file{tracklang.tex} v1.4+} \syntax{\margm{dialect label}\margm{root language label}\margm{3166-1 code}\margm{modifier}\margm{variant}\margm{map}\margm{script}} \desc{defines a predefined dialect label that can be used by \gls{TrackPredefinedDialect}} } % \TrackLangDeclareDialectOption \gcmd{Track\-Lang\-Declare\-Di\-alect\-Op\-tion} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{dialect}\margm{root language}\margm{3166-1 code}\margm{modifier}\margm{variant}\margm{map}\margm{script}} \desc{defines a predefined dialect label that can be used by \gls{TrackPredefinedDialect}} } % \TrackLangProvidesResource \gcmd{Track\-Lang\-Provides\-Resource} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{tag}\oargm{version info}} \desc{analogous to \gls{ProvidesFile}} } % \TrackLangEncodingName \gcmd{Track\-Lang\-Encoding\-Name} { \providedby{\file{tracklang.tex} v1.6.1+} \desc{expands to \gls{inputencodingname} if it has been defined or \code{utf8} otherwise} } % \TrackLangAddToHook \gcmd{Track\-Lang\-Add\-To\-Hook} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{code}\margm{type}} \desc{for use within resource files, this can be used to add \meta{code} to the appropriate hook} } % \TrackLangAddToCaptions \gcmd{Track\-Lang\-Add\-To\-Captions} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{code}} \desc{a shortcut that just does \code{\gls{TrackLangAddToHook}\margm{code}\marg{captions}}} } % \TrackLangRedefHook \gcmd{Track\-Lang\-Re\-def\-Hook} { \providedby{\file{tracklang.tex} v1.4+} \syntax{\margm{code}\margm{type}} \desc{similar to \gls{TrackLangAddToHook} but redefines the hook rather than appending to it} } % \TrackLangRequireResource \gcmd{Track\-Lang\-Require\-Resource} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{tag}} \desc{loads the appropriate \ext{ldf} file if it hasn't already been loaded} } % \TrackLangRequireResourceOrDo \gcmd{Track\-Lang\-Require\-Resource\-Or\-Do} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{tag}\margm{code1}\margm{code2}} \desc{as \gls{TrackLangRequireResource} but does \meta{code1} if the file is now loaded or \meta{code2} if the file has already been loaded} } % \TrackLangRequestResource \gcmd{Track\-Lang\-Request\-Resource} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{tag}\margm{not found code}} \desc{as \gls{TrackLangRequireResource} but does \meta{not found code} if the file doesn't exist} } % \TrackLangRequireDialect \gcmd{Track\-Lang\-Require\-Di\-alect} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\oargm{load code}\margm{pkgname}\margm{dialect}} \desc{loads the dialect for the given package} } % \TrackLangRequireDialectPrefix \gcmd{Track\-Lang\-Require\-Di\-alect\-Prefix} { \providedby{\file{tracklang.tex} v1.3+} \desc{defined by \gls{TrackLangRequireDialect}} } % \SetTrackedDialectLabelMap \gcmd{Set\-Track\-ed\-Di\-alect\-Label\-Map} { \providedby{\file{tracklang.tex} v1.3+} \syntax{\margm{tracklang-label}\margm{hook-label}} \desc{defines a mapping between a \sty{tracklang} dialect label and the corresponding dialect label used by a language hook, such as \gls{captionsdialect}} } % \TrackLangLastTrackedDialect \gcmd{Track\-Lang\-Last\-Track\-ed\-Dialect} { \providedby{\file{tracklang.tex} v1.3+} \desc{expands to the label of the last tracked dialect} } % COMMANDS: INTERNAL % \@tracklang@declareoption \gcmd{@track\-lang\-@\-declare\-option} { \providedby{\sty{tracklang} v1.1+} \syntax{\margm{dialect}} \desc{provided by \file{tracklang.sty} to declare \meta{dialect} as a package option that tracks \meta{dialect}. Provided by \file{tracklang.tex}, if not already defined, to ignore its argument} } % \@tracklang@for \gcmd{@track\-lang\-@\-for} { \providedby{\file{tracklang.tex} v1.0+} \syntax{\meta{cs}:=\meta{list}\cmd{do}\margm{body}} \desc{as \LaTeX's \gls{@for}} } % \@tracklang@prelangpkgcheck@hook \gcmd{@track\-lang\-@\-pre\-lang\-pkg\-check\-@\-hook} { \desc{if defined before \file{tracklang.sty} v1.3.8+ is loaded, this command will be done after package options have been processed but before the check for language packages, such as \sty{babel} and \sty{polyglossia}} } % COMMANDS: tracklang-region-codes.tex % \TrackLangAlphaIIToNumericRegion \gcmd{Track\-Lang\-Alpha\-II\-To\-Numeric\-Region} { \providedby{\file{tracklang-region-codes.tex} v1.3+} \syntax{\margm{alpha-2 code}} \desc{expands to the numeric code corresponding to the given alpha-2 code} } % \TrackLangNumericToAlphaIIRegion \gcmd{Track\-Lang\-Numeric\-To\-Alpha\-II\-Region} { \providedby{\file{tracklang-region-codes.tex} v1.3+} \syntax{\margm{numeric code}} \desc{expands to the alpha-2 code corresponding to the given numeric code} } % \TrackLangIfKnownAlphaIIRegion \gcmd{Track\-Lang\-If\-Known\-Alpha\-II\-Region} { \providedby{\file{tracklang-region-codes.tex} v1.3+} \syntax{\margm{alpha-2 code}\margm{true}\margm{false}} \desc{expands to \meta{true} if there's a known mapping for the given alpha-2 \idx{region} code, otherwise expands to \meta{false}} } % \TrackLangIfKnownNumericRegion \gcmd{Track\-Lang\-If\-Known\-Numeric\-Region} { \providedby{\file{tracklang-region-codes.tex} v1.3+} \syntax{\margm{numeric code}\margm{true}\margm{false}} \desc{expands to \meta{true} if there's a known mapping for the given numeric \idx{region} code, otherwise expands to \meta{false}} } % \TrackLangAlphaIIIToNumericRegion \gcmd{Track\-Lang\-Alpha\-III\-To\-Numeric\-Region} { \providedby{\file{tracklang-region-codes.tex} v1.3+} \syntax{\margm{alpha-3 code}} \desc{expands to the numeric code corresponding to the given alpha-3 code} } % \TrackLangNumericToAlphaIIIRegion \gcmd{Track\-Lang\-Numeric\-To\-Alpha\-III\-Region} { \providedby{\file{tracklang-region-codes.tex} v1.3+} \syntax{\margm{numeric code}} \desc{expands to the alpha-3 code corresponding to the given numeric code} } % \TrackLangIfKnownAlphaIIIRegion \gcmd{Track\-Lang\-If\-Known\-Alpha\-III\-Region} { \providedby{\file{tracklang-region-codes.tex} v1.3+} \syntax{\margm{alpha-3 code}\margm{true}\margm{false}} \desc{expands to \meta{true} if there's a known mapping for the given \meta{alpha-3 code}, otherwise expands to \meta{false}} } % \TrackLangRegionMap \gcmd{Track\-Lang\-Region\-Map} { \providedby{\file{tracklang-region-codes.tex} v1.3+} \syntax{\margm{numeric}\margm{alpha-2}\margm{alpha-3}} \desc{establishes a mapping between a numeric \idx{region} code and alpha-2 and alpha-3 codes} } % COMMANDS: tracklang-scripts.tex % \TrackLangScriptMap \gcmd{Track\-Lang\-Script\-Map} { \providedby{\file{tracklang-scripts.tex} v1.3+} \syntax{\margm{letter code}\margm{numeric code}\margm{script name}\margm{direction}\margm{parent script}} \desc{defines a mapping between an alpha code and a numeric code} } % \TrackLangScriptAlphaToNumeric \gcmd{Track\-Lang\-Script\-Alpha\-To\-Numeric} { \providedby{\file{tracklang-scripts.tex} v1.3+} \syntax{\margm{alpha code}} \desc{expands to the numeric script code corresponding to the given alpha code} } % \TrackLangScriptIfKnownAlpha \gcmd{Track\-Lang\-Script\-If\-Known\-Alpha} { \providedby{\file{tracklang-scripts.tex} v1.3+} \syntax{\margm{alpha code}\margm{true}\margm{false}} \desc{expands to \meta{true} if there's a known mapping for the given alpha script code otherwise expands to \meta{false}} } % \TrackLangScriptNumericToAlpha \gcmd{Track\-Lang\-Script\-Numeric\-To\-Alpha} { \providedby{\file{tracklang-scripts.tex} v1.3+} \syntax{\margm{numeric code}} \desc{expands to the alpha script code corresponding to the given numeric code} } % \TrackLangScriptIfKnownNumeric \gcmd{Track\-Lang\-Script\-If\-Known\-Numeric} { \providedby{\file{tracklang-scripts.tex} v1.3+} \syntax{\margm{numeric code}\margm{true}\margm{false}} \desc{expands to \meta{true} if there's a known mapping for the given numeric script code otherwise expands to \meta{false}} } % \TrackLangScriptAlphaToName \gcmd{Track\-Lang\-Script\-Alpha\-To\-Name} { \providedby{\file{tracklang-scripts.tex} v1.3+} \syntax{\margm{alpha code}} \desc{expands to the name associated with the given alpha script code} } % \TrackLangScriptAlphaToDir \gcmd{Track\-Lang\-Script\-Alpha\-To\-Dir} { \providedby{\file{tracklang-scripts.tex} v1.3+} \syntax{\margm{alpha code}} \desc{expands to the direction associated with the given alpha script code} } % \TrackLangScriptSetParent \gcmd{Track\-Lang\-Script\-Set\-Parent} { \providedby{\file{tracklang-scripts.tex} v1.3+} \syntax{\margm{alpha code}\margm{parent alpha code}} \desc{sets the parent for the given alpha script code} } % \TrackLangScriptGetParent \gcmd{Track\-Lang\-Script\-Get\-Parent} { \providedby{\file{tracklang-scripts.tex} v1.3+} \syntax{\margm{alpha code}} \desc{expands to the parent of the given alpha script code} } % \TrackLangScriptIfHasParent \gcmd{Track\-Lang\-Script\-If\-Has\-Parent} { \providedby{\file{tracklang-scripts.tex} v1.3+} \syntax{\margm{alpha code}\margm{true}\margm{false}} \desc{expands to \meta{true} if the given alpha script code has a parent otherwise expands to \meta{false}} } % \TrackLangScript \gcmdmeta{Track\-Lang\-Script}{Code}{} { \providedby{\file{tracklang-scripts.tex} v1.3+} \desc{set by \gls{TrackLangScriptMap} to the associated alpha code \meta{Code}} } % FILES \gfile{track\-lang.tex}{}% tracklang.tex \gfile{track\-lang.sty}% tracklang.sty {\field{alias}{pkg.tracklang}}% \gfile{track\-lang\dhyphen scripts.sty}% tracklang-scripts.sty {\field{alias}{pkg.tracklang-scripts}}% \gfile{tracklang\dhyphen region\dhyphen codes.tex}{}% tracklang-region-codes.tex \gfile{tracklang\dhyphen scripts.tex}{}% tracklang-scripts.tex \gfile{tex\-os\-query.tex}{}% texosquery.tex \gfile{tex\-os\-query.cfg}{}% texosquery.cfg \gfilemetameta{}{prefix}{\dhyphen}{localeid}{.ldf}{} % -.ldf % FILE EXTENSIONS \gext{tex}{}% .tex \gext{ldf}{}% .ldf \gext{log}{}% .log % PACKAGES \gpkg{track\-lang}{\common}% tracklang \gpkg{track\-lang\dhyphen scripts}{}% tracklang-scripts \gpkg{tex\-os\-query}{}% texosquery \gpkg{poly\-glossia}{}% polyglossia.sty \gpkg{babel}{}% babel.sty \gpkg{translator}{}% translator.sty \gpkg{shell\-esc}{}% shellesc.sty \gpkg{ngerman}{}% ngerman.sty \gpkg{german}{}% german.sty \gpkg{glossaries}{}% glossaries.sty \gpkg{etool\-box}{}% etoolbox.sty \gpkg{date\-time2}{}% datetime2.sty \gpkg{input\-enc}{}% inputenc.sty % Example packages \gfile{animals.sty}{}% animals.sty \gfile{regions.sty}{}% regions.sty \gfile{alien.sty}{}% alien.sty \gpkg{alien}{\field{alias}{file.alien.sty}} % environment variables \genvvar{LC\dsb ALL}{}% LC_ALL \genvvar{LANG}{}% LANG \genvvar{LC\dsb MONETARY}{}% LC_MONETARY % TERMS \gterm{shellescape} { \name{shell escape} \desc{\TeX\ has the ability to run \idx{cli} applications while it's typesetting a document. Whilst this is a convenient way of using tools to help build the document, it's a security risk. To help protect users from arbitrary\dash and potentially dangerous\dash code from begin executed, \TeX\ has a restricted mode, where only trusted applications are allowed to run. This is usually the default mode, but your \TeX\ installation may be set up so that the shell escape is disabled by default. The unrestricted mode allows you to run any application from the shell escape. Take care about enabling this option. If you receive a document or package from an untrusted source, first run \TeX\ with the shell escape disabled or in restricted mode and search the \ext+{log} file for \qt{runsystem} before using the unrestricted mode. Note that \LuaLaTeX\ additionally requires the \sty{shellesc} package} } \gtermacr{cli}{CLI}{command-line interface}% {% \desc{an application that doesn't have a graphical user interface. That is, an application that doesn't have any windows, buttons or menus and can be run in \dickimawhref{latex/novices/html/terminal.html}{a command prompt or terminal}}% }% % INDEX ONLY % COMMANDS - GENERAL \gcmd{input\-encoding\-name}{}% \inputencodingname \gcmd{Input\-If\-File\-Exists}{}% \InputIfFileExists \gcmd{direct\-lua}{}% \directlua \gcmd{babel\-provide}{}% \babelprovide \gcmd{bbl\-@\-loaded}{}% \bbl@loaded \gcmd{select\-language}{}% \selectlanguage \gcmd{input}{}% \input \gcmd{Require\-Package}{}% \RequirePackage \gcmd{Declare\-Option}{}% \DeclareOption \gcmdmeta{captions}{dialect}{}{}% \captions \gcmdmeta{date}{dialect}{}{}% \date \gcmd{Provides\-File}{}% \ProvidesFile \gcmd{xpg\-@\-bcp\-@\-loaded}{}% \xpg@bcp@loaded \gcmd{xpg\-@\-loaded}{}% \xpg@loaded \gcmd{trans\-@\-languages}{}% \trans@languages \gcmd{lan\-guage\-name}{}% \languagename \gcmd{TeX\-OS\-Query\-Lang\-Tag}{}% \TeXOSQueryLangTag \gcmd{TeX\-OS\-Query\-Locale}{}% \TeXOSQueryLocale \gcmd{@for}{} \gcmd{@nil}{} \gcmd{At\-Begin\-Doc\-u\-ment}{}% \AtBeginDocument % APPLICATIONS \gapp{tex\-os\-query}{}% texosquery \gapp{kpse\-which}{}% kpsewhich \gapp{etex}{}% etex \gapp{tex}{}% tex \gapp{pdflatex}{}% pdflatex % PUNCTUATION \gpunc{atletter}% @ as a letter {\name{\code{@} (catcode 11)}\field{text}{\code{@}}}% \gpunc{atmod}% @ separates modifier {\name{\code{@} (modifier)}\field{text}{\code{@}}}% \gpunc{hyphensep}% - in tag {\name{\code{-} (separator)}\field{text}{\code{-}}}% \gpunc{underscoresep}% _ in tag {\name{\code{\_} (separator)}\field{text}{\code{\_}}}% \gpunc{dotsep}% . separates code-set {\name{\code{.}\ (code-set)}\field{text}{\code{.}}}% \gpunc{dollarenv}% ${ENV VAR} {\name{\code{\$} (environment variable)}\field{text}{\code{\$}}} \gpunc{escbsl}% \\ {\name{\code{\glsbackslash\glsbackslash} (escaped backslash)} \field{text}{\code{\glsbackslash\glsbackslash}} } % INDEX ONLY TERMS \gidx{code-set}{} \gidx{modifier}{} \gidx{variant}{} \gidx{territory}{} \gidx{region}{\field{alias}{idx.territory}} \gidx{script}{} \gidx{BCP47}{\name{BCP~47}} % ISO CODES \gidx{639-1}{\name{ISO \mbox{639-1}}\field{text}{\mbox{639-1}}} \gidx{639-2}{\name{ISO \mbox{639-2}}\field{text}{\mbox{639-2}}} \gidx{639-2B}{\parent{idx.639-2}% \name{ISO \mbox{639-2} (B)}% \field{text}{\mbox{639-2} (B)}} \gidx{639-2T}{\parent{idx.639-2}% \name{ISO \mbox{639-2} (T)}% \field{text}{\mbox{639-2} (T)}} \gidx{639-3}{\name{ISO \mbox{639-3}}\field{text}{\mbox{639-3}}} \gidx{3166-1}{\name{ISO \mbox{3166-1}}\field{text}{\mbox{3166-1}}} \gidx{15924}{\name{ISO 15924}\field{text}{15924}} % ABBREVIATIONS \gacr{ISO}{ISO}{International Organization for Standardization}{\common} \gacr{POSIX}{POSIX}{Portable Operating System Interface}{} % SWITCHES \glongswitchpunc{shell\dhyphen escape}{} % PREDEFINED ISO LANGUAGE-REGION TAGS \gisolangtag{en}{US}{american}{} \gisolangtag{en}{GB}{british}{} \gisolangtag{en}{AU}{australian}{} \gisolangtag{en}{NZ}{newzealand}{} \gisolangtag{en}{CA}{canadian}{} \gisolangtag{fr}{CA}{canadien}{} \gisolangtag{fr}{BE}{belgique}{} \gisolangtag{pt}{BR}{brazilian}{} \gisolangtag{it}{HR}{istriacountyitalian}{} \gisolangtag{nl}{BE}{flemish}{} \gisolangtag{fr}{FR}{france}{} \gisolangtag{de}{DE}{germanDE}{} \gisolangtag{de}{BE}{belgiangerman}{} \gisolangtag{en}{GG}{guernseyenglish}{} \gisolangtag{fr}{GG}{guernseyfrench}{} \gisolangtag{it}{IT}{italy}{} \gisolangtag{mt}{MT}{maltamaltese}{} \gisolangtag{en}{MT}{maltaenglish}{} \gisolangtag{en}{IM}{isleofmanenglish}{} \gisolangtag{en}{JE}{jerseyenglish}{} \gisolangtag{fr}{JE}{jerseyfrench}{} \gisolangtag{nl}{NL}{netherlands}{} \gisolangtag{pt}{PT}{portugal}{} \gisolangtag{it}{SM}{sanmarino}{} \gisolangtag{sl}{SI}{slovenia}{} \gisolangtag{it}{SI}{sloveneistriaitalian}{} \gisolangtag{es}{ES}{spainspanish}{} \gisolangtag{es}{AR}{argentinespanish}{} \gisolangtag{es}{BO}{bolivianspanish}{} \gisolangtag{es}{CL}{chilianspanish}{} \gisolangtag{es}{CO}{columbianspanish}{} \gisolangtag{es}{CR}{costaricanspanish}{} \gisolangtag{es}{CU}{cubanspanish}{} \gisolangtag{es}{DO}{dominicanspanish}{} \gisolangtag{es}{EC}{ecudorianspanish}{} \gisolangtag{es}{SV}{elsalvadorspanish}{} \gisolangtag{es}{GT}{guatemalanspanish}{} \gisolangtag{es}{HN}{honduranspanish}{} \gisolangtag{es}{MX}{mexicanspanish}{} \gisolangtag{es}{NI}{nicaraguanspanish}{} \gisolangtag{es}{PA}{panamaspanish}{} \gisolangtag{es}{PY}{paraguayspanish}{} \gisolangtag{es}{PE}{peruvianspanish}{} \gisolangtag{es}{PR}{puertoricospanish}{} \gisolangtag{es}{UY}{uruguayspanish}{} \gisolangtag{es}{VE}{venezuelanspanish}{} \gisolangtag{de}{CH}{swissgerman}{} \gisolangtag{fr}{CH}{swissfrench}{} \gisolangtag{it}{CH}{swissitalian}{} \gisolangtag{rm}{CH}{swissromansh}{} \gisolangtag{it}{VA}{vatican}{} \gisolangtag{ga}{IE}{IEirish}{} \gisolangtag{ga}{GB}{GBirish}{} \gisolangtag{en}{IE}{IEenglish}{} \gisolangtagwithvar{de}{AT}{1996}{naustrian}{} \gisolangtag{de}{AT}{austrian}{} \gisolangtag{id}{IN}{bahasa}{} \gisolangtag{ms}{MY}{malay}{} \gisolangtag{hr}{HR}{croatia}{} \gisolangtagwithvar{de}{DE}{1996}{ngermanDE}{} \gisolangtagwithvar{de}{CH}{1996}{nswissgerman}{} \gisolangtag{hu}{HU}{hungarian}{} \gisolangtag{gd}{GB}{GBscottish}{} \gisolangtag{cy}{GB}{GBwelsh}{} % PREDEFINED ROOT LANGUAGE TAGS \grootlangtag{abkhaz}{ab}{} \grootlangtag{afar}{aa}{} \grootlangtag{afrikaans}{af}{} \grootlangtag{akan}{ak}{} \grootlangtag{albanian}{sq}{} \grootlangtagwithreg{amharic}{am}{ET}{} \grootlangtag{anglosaxon}{ang}{} \grootlangtag{apache}{apa}{} \grootlangtag{arabic}{ar}{} \grootlangtagwithreg{aragonese}{an}{ES}{} \grootlangtag{armenian}{hy}{} \grootlangtag{assamese}{as}{} \grootlangtag{asturian}{ast}{} \grootlangtag{avaric}{av}{} \grootlangtag{avestan}{ae}{} \grootlangtag{aymara}{ay}{} \grootlangtag{azerbaijani}{az}{} \grootlangtagwithreg{bahasai}{id}{IN}{} \grootlangtagwithreg{bahasam}{ms}{MY}{} \grootlangtagwithreg{bambara}{bm}{ML}{} \grootlangtag{bashkir}{ba}{} \grootlangtag{basque}{eu}{} \grootlangtag{belarusian}{be}{} \grootlangtag{bengali}{bn}{} \grootlangtag{berber}{ber}{} \grootlangtag{bihari}{bh}{} \grootlangtagwithreg{bislama}{bi}{VU}{} \grootlangtagwithreg{bokmal}{nb}{NO}{} \grootlangtag{bosnian}{bs}{} \grootlangtagwithreg{breton}{br}{FR}{} \grootlangtag{bulgarian}{bg}{} \grootlangtag{burmese}{my}{} \grootlangtag{catalan}{ca}{} \grootlangtag{chamorro}{ch}{} \grootlangtag{chechen}{ce}{} \grootlangtag{chichewa}{ny}{} \grootlangtag{chinese}{zh}{} \grootlangtag{churchslavonic}{cu}{} \grootlangtagwithreg{chuvash}{cv}{RU}{} \grootlangtag{coptic}{cop}{} \grootlangtagwithreg{cornish}{kw}{GB}{} \grootlangtag{corsican}{co}{} \grootlangtag{cree}{cr}{} \grootlangtag{croatian}{hr}{} \grootlangtag{czech}{cs}{} \grootlangtag{danish}{da}{} \grootlangtagwithreg{divehi}{dv}{MV}{} \grootlangtag{dutch}{nl}{} \grootlangtagwithreg{dzongkha}{dz}{BT}{} \grootlangtagwithreg{easternpunjabi}{pa}{IN}{} \grootlangtag{english}{en}{} \grootlangtag{esperanto}{eo}{} \grootlangtag{estonian}{et}{} \grootlangtag{ewe}{ee}{} \grootlangtag{faroese}{fo}{} \grootlangtag{farsi}{fa}{} \grootlangtagwithreg{fijian}{fj}{FJ}{} \grootlangtag{finnish}{fi}{} \grootlangtag{french}{fr}{} \grootlangtagwithreg{friulan}{fur}{IT}{} \grootlangtag{fula}{ff}{} \grootlangtag{galician}{gl}{} \grootlangtagwithreg{ganda}{lg}{UG}{} \grootlangtag{georgian}{ka}{} \grootlangtag{german}{de}{} \grootlangtag{greek}{el}{} \grootlangtag{guarani}{gn}{} \grootlangtag{gujarati}{gu}{} \grootlangtagwithreg{haitian}{ht}{HT}{} \grootlangtag{hausa}{ha}{} \grootlangtag{hebrew}{he}{} \grootlangtag{herero}{hz}{} \grootlangtag{hindi}{hi}{} \grootlangtagwithreg{hirimotu}{ho}{PG}{} \grootlangtagwithreg{icelandic}{is}{IS}{} \grootlangtag{ido}{io}{} \grootlangtag{igbo}{ig}{} \grootlangtag{interlingua}{ia}{} \grootlangtag{interlingue}{ie}{} \grootlangtag{inuktitut}{iu}{} \grootlangtag{inupiaq}{ik}{} \grootlangtag{irish}{ga}{} \grootlangtag{italian}{it}{} \grootlangtag{japanese}{ja}{} \grootlangtag{javanese}{jv}{} \grootlangtag{kalaallisut}{kl}{} \grootlangtagwithreg{kannada}{kn}{IN}{} \grootlangtag{kanuri}{kr}{} \grootlangtagwithreg{kashmiri}{ks}{IN}{} \grootlangtag{kazakh}{kk}{} \grootlangtag{khmer}{km}{} \grootlangtag{kikuyu}{ki}{} \grootlangtag{kinyarwanda}{rw}{} \grootlangtag{kirundi}{rn}{} \grootlangtagwithreg{komi}{kv}{RU}{} \grootlangtag{kongo}{kg}{} \grootlangtag{korean}{ko}{} \grootlangtag{kurdish}{ku}{} \grootlangtag{kwanyama}{kj}{} \grootlangtag{kyrgyz}{ky}{} \grootlangtag{lao}{lo}{} \grootlangtag{latin}{la}{} \grootlangtag{latvian}{lv}{} \grootlangtag{limburgish}{li}{} \grootlangtag{lingala}{ln}{} \grootlangtag{lithuanian}{lt}{} \grootlangtagwithreg{lsorbian}{dsb}{DE}{} \grootlangtagwithreg{lubakatanga}{lu}{CD}{} \grootlangtag{luxembourgish}{lb}{} \grootlangtag{macedonian}{mk}{} \grootlangtag{magyar}{hu}{} \grootlangtag{malagasy}{mg}{} \grootlangtagwithreg{malayalam}{ml}{IN}{} \grootlangtag{maltese}{mt}{} \grootlangtagwithreg{manx}{gv}{IM}{} \grootlangtagwithreg{maori}{mi}{NZ}{} \grootlangtagwithreg{marathi}{mr}{IN}{} \grootlangtagwithreg{marshallese}{mh}{MH}{} \grootlangtag{mongolian}{mn}{} \grootlangtagwithreg{nauruan}{na}{NR}{} \grootlangtagwithreg{navajo}{nv}{US}{} \grootlangtag{ndonga}{ng}{} \grootlangtag{nepali}{ne}{} \grootlangtag{nko}{nqo}{} \grootlangtag{northernndebele}{nd}{} \grootlangtagwithreg{nynorsk}{nn}{NO}{} \grootlangtag{norsk}{no}{} \grootlangtag{northernsotho}{nso}{} \grootlangtagwithreg{nuosu}{ii}{CN}{} \grootlangtag{occitan}{oc}{} \grootlangtag{ojibwe}{oj}{} \grootlangtag{oromo}{om}{} \grootlangtag{oriya}{or}{} \grootlangtag{ossetian}{os}{} \grootlangtag{pali}{pi}{} \grootlangtag{pashto}{ps}{} \grootlangtagwithreg{piedmontese}{pms}{IT}{} \grootlangtag{polish}{pl}{} \grootlangtag{portuges}{pt}{} \grootlangtag{quechua}{qu}{} \grootlangtag{romanian}{ro}{} \grootlangtagwithreg{romansh}{rm}{CH}{} \grootlangtag{russian}{ru}{} \grootlangtag{samin}{se}{} \grootlangtag{sanskrit}{sa}{} \grootlangtag{samoan}{sm}{} \grootlangtag{sango}{sg}{} \grootlangtagwithreg{sardinian}{sc}{IT}{} \grootlangtag{scottish}{gd}{} \grootlangtag{serbian}{sr}{} \grootlangtag{shona}{sn}{} \grootlangtag{sindhi}{sd}{} \grootlangtagwithreg{sinhalese}{si}{LK}{} \grootlangtag{slovak}{sk}{} \grootlangtag{slovene}{sl}{} \grootlangtag{somali}{so}{} \grootlangtagwithreg{southernndebele}{nr}{ZA}{} \grootlangtag{southernsotho}{st}{} \grootlangtag{spanish}{es}{} \grootlangtag{sudanese}{su}{} \grootlangtag{swahili}{sw}{} \grootlangtag{swati}{ss}{} \grootlangtag{swedish}{sv}{} \grootlangtag{syriac}{syr}{} \grootlangtagwithreg{tagalog}{tl}{PH}{} \grootlangtagwithreg{tahitian}{ty}{PF}{} \grootlangsametag{tai}{} \grootlangtag{tajik}{tg}{} \grootlangtag{tamil}{ta}{} \grootlangtag{tatar}{tt}{} \grootlangtagwithreg{telugu}{te}{IN}{} \grootlangtagwithreg{thai}{th}{TH}{} \grootlangtag{tibetan}{bo}{} \grootlangtag{tigrinya}{ti}{} \grootlangtagwithreg{tonga}{to}{TO}{} \grootlangtag{tsonga}{ts}{} \grootlangtag{tswana}{tn}{} \grootlangtag{turkish}{tr}{} \grootlangtag{turkmen}{tk}{} \grootlangtagwithreg{twi}{tw}{GH}{} \grootlangtagwithreg{ukrainian}{uk}{UA}{} \grootlangtag{undetermined}{und}{} \grootlangtag{urdu}{ur}{} \grootlangtagwithreg{usorbian}{hsb}{DE}{} \grootlangtagwithreg{uyghur}{ug}{CN}{} \grootlangtag{uzbek}{uz}{} \grootlangtagwithreg{venda}{ve}{ZA}{} \grootlangtag{vietnamese}{vi}{} \grootlangtag{volapuk}{vo}{} \grootlangtag{walloon}{wa}{} \grootlangtag{welsh}{cy}{} \grootlangtagwithreg{westernfrisian}{fy}{NL}{} \grootlangtag{wolof}{wo}{} \grootlangtag{xhosa}{xh}{} \grootlangtag{yiddish}{yi}{} \grootlangtag{yoruba}{yo}{} \grootlangtagwithreg{zhuang}{za}{CN}{} \grootlangtag{zulu}{zu}{} % PREDEFINED NON-ISO DIALECTS \gdialecttag{acadian}{french}{} \gdialecttagwithreg{american}{english}{US}{} \gdialecttagwithreg{australian}{english}{AU}{} \gdialecttagwithreg{austrian}{german}{AT}{} \gdialecttagwithreg{naustrian}{german}{AT-1996}{} \gdialecttagwithreg{bahasa}{bahasai}{IN}{} \gdialecttagwithreg{brazil}{portuges}{BR}{} \gdialecttagwithreg{brazilian}{portuges}{BR}{} \gdialecttagwithreg{british}{english}{GB}{} \gdialecttagwithreg{canadian}{english}{CA}{} \gdialecttagwithreg{canadien}{french}{CA}{} \gdialecttagwithreg{croatia}{croatian}{HR}{} \gdialecttagwithreg{istriacountycroatian}{croatian}{HR}{} \gdialecttagwithreg{istriacountyitalian}{italian}{HR}{} \gdialecttagwithreg{netherlands}{dutch}{NL}{} \gdialecttag{persian}{farsi}{} \gdialecttagwithreg{flemish}{dutch}{BE}{} \gdialecttag{francais}{french}{} \gdialecttag{frenchb}{french}{} \gdialecttagwithreg{france}{french}{FR}{} \gdialecttagwithreg{belgique}{french}{BE}{} \gdialecttagwithreg{belgiangerman}{german}{BE}{} \gdialecttagwithmapandreg{nbelgiangerman}{german}{BE-1996}{ngerman}{} \gdialecttagwithreg{friulian}{friulan}{IT}{} \gdialecttagwithreg{friulano}{friulan}{IT}{} \gdialecttagwithreg{furlan}{friulan}{IT}{} \gdialecttag{kurmanji}{kurdish}{} \gdialecttag{galicien}{galician}{} \gdialecttag{deutsch}{german}{} \gdialecttagsuppl{ngerman}{german}{1996}{} \gdialecttagsupplwithmap{ngermanb}{german}{1996}{ngerman}{} \gdialecttag{germanb}{german}{} \gdialecttagwithmapandreg{ngermanDE}{german}{DE-1996}{ngerman}{} \gdialecttagwithreg{germanDE}{german}{DE}{} \gdialecttagwithreg{hungarian}{magyar}{HU}{} \gdialecttagwithreg{indon}{bahasai}{IN}{} \gdialecttagwithreg{indonesian}{bahasai}{IN}{} \gdialecttag{gaeilge}{irish}{} \gdialecttagwithreg{IEirish}{irish}{IE}{} \gdialecttagwithreg{GBirish}{irish}{GB}{} \gdialecttagwithmapandreg{IEenglish}{english}{IE}{british}{} \gdialecttagwithreg{italy}{italian}{IT}{} \gdialecttagwithreg{vatican}{italian}{VA}{} \gdialecttagwithreg{sanmarino}{italian}{SM}{} \gdialecttagwithreg{sloveneistriaitalian}{italian}{SI}{} \gdialecttagwithmapandreg{jerseyenglish}{english}{JE}{british}{} \gdialecttagwithreg{jerseyfrench}{french}{JE}{} \gdialecttagwithmapandreg{guernseyenglish}{english}{GG}{british}{} \gdialecttagwithreg{guernseyfrench}{french}{GG}{} \gdialecttag{latein}{latin}{} \gdialecttagwithreg{lowersorbian}{lsorbian}{DE}{} \gdialecttagwithreg{malay}{bahasam}{MY}{} \gdialecttagwithreg{meyalu}{bahasam}{MY}{} \gdialecttagwithreg{maltamaltese}{maltese}{MT}{} \gdialecttagwithmapandreg{maltaenglish}{english}{MT}{british}{} \gdialecttagwithreg{newzealand}{english}{NZ}{} \gdialecttagwithmapandreg{isleofmanenglish}{english}{IM}{british}{} \gdialecttagwithreg{norwegian}{norsk}{NO}{} \gdialecttagwithreg{piemonteis}{piedmontese}{IT}{} \gdialecttag{polutonikogreek}{greek}{} \gdialecttag{polutoniko}{greek}{} \gdialecttag{portuguese}{portuges}{} \gdialecttagwithreg{portugal}{portuges}{PT}{} \gdialecttag{romansch}{romansh}{} \gdialecttag{rumantsch}{romansh}{} \gdialecttag{romanche}{romansh}{} \gdialecttag{russianb}{russian}{} \gdialecttag{gaelic}{scottish}{} \gdialecttagwithreg{GBscottish}{scottish}{GB}{} \gdialecttagsuppl{serbianc}{serbian}{Cyrl}{} \gdialecttagsuppl{serbianl}{serbian}{Latn}{} \gdialecttag{slovenian}{slovene}{} \gdialecttagwithmapandreg{slovenia}{slovene}{SI}{slovenian}{} \gdialecttagwithmapandreg{sloveneistriaslovenian}{slovene}{SI}{slovenian}{} \gdialecttagwithreg{spainspanish}{spanish}{ES}{} \gdialecttagwithreg{argentinespanish}{spanish}{AR}{} \gdialecttagwithreg{bolivianspanish}{spanish}{BO}{} \gdialecttagwithreg{chilianspanish}{spanish}{CL}{} \gdialecttagwithreg{columbianspanish}{spanish}{CO}{} \gdialecttagwithreg{costaricanspanish}{spanish}{CR}{} \gdialecttagwithreg{cubanspanish}{spanish}{CU}{} \gdialecttagwithreg{dominicanspanish}{spanish}{DO}{} \gdialecttagwithreg{ecudorianspanish}{spanish}{EC}{} \gdialecttagwithreg{elsalvadorspanish}{spanish}{SV}{} \gdialecttagwithreg{guatemalanspanish}{spanish}{GT}{} \gdialecttagwithreg{honduranspanish}{spanish}{HN}{} \gdialecttagwithreg{mexicanspanish}{spanish}{MX}{} \gdialecttagwithreg{nicaraguanspanish}{spanish}{NI}{} \gdialecttagwithreg{panamaspanish}{spanish}{PA}{} \gdialecttagwithreg{paraguayspanish}{spanish}{PY}{} \gdialecttagwithreg{peruvianspanish}{spanish}{PE}{} \gdialecttagwithreg{puertoricospanish}{spanish}{PR}{} \gdialecttagwithreg{uruguayspanish}{spanish}{UY}{} \gdialecttagwithreg{venezuelanspanish}{spanish}{VE}{} \gdialecttagwithreg{swissgerman}{german}{CH}{} \gdialecttagwithmapandreg{nswissgerman}{german}{CH-1996}{ngerman}{} \gdialecttagwithreg{swissfrench}{french}{CH}{} \gdialecttagwithreg{swissitalian}{italian}{CH}{} \gdialecttagwithreg{swissromansh}{romansh}{CH}{} \gdialecttagwithreg{UKenglish}{english}{GB}{} \gdialecttagwithreg{ukraineb}{ukrainian}{UA}{} \gdialecttagwithreg{ukraine}{ukrainian}{UA}{} \gdialecttagwithreg{uppersorbian}{usorbian}{DE}{} \gdialecttagwithreg{USenglish}{english}{US}{} \gdialecttag{valencian}{catalan}{} \gdialecttag{valencien}{catalan}{} \gdialecttag{cymraeg}{welsh}{} \gdialecttagwithreg{GBwelsh}{welsh}{GB}{} \gdialecttag{nil}{undetermined}{} % PREDEFINED REGIONS \gregion{004}{AF}{AFG}{}% \gregion{248}{AX}{ALA}{}% \gregion{008}{AL}{ALB}{}% \gregion{012}{DZ}{DZA}{}% \gregion{016}{AS}{ASM}{}% \gregion{020}{AD}{AND}{}% \gregion{024}{AO}{AGO}{}% \gregion{660}{AI}{AIA}{}% \gregion{010}{AQ}{ATA}{}% \gregion{028}{AG}{ATG}{}% \gregion{032}{AR}{ARG}{}% \gregion{051}{AM}{ARM}{}% \gregion{533}{AW}{ABW}{}% \gregion{036}{AU}{AUS}{}% \gregion{040}{AT}{AUT}{}% \gregion{031}{AZ}{AZE}{}% \gregion{044}{BS}{BHS}{}% \gregion{048}{BH}{BHR}{}% \gregion{050}{BD}{BGD}{}% \gregion{052}{BB}{BRB}{}% \gregion{112}{BY}{BLR}{}% \gregion{056}{BE}{BEL}{}% \gregion{084}{BZ}{BLZ}{}% \gregion{204}{BJ}{BEN}{}% \gregion{060}{BM}{BMU}{}% \gregion{064}{BT}{BTN}{}% \gregion{068}{BO}{BOL}{}% \gregion{535}{BQ}{BES}{}% \gregion{070}{BA}{BIH}{}% \gregion{072}{BW}{BWA}{}% \gregion{074}{BV}{BVT}{}% \gregion{076}{BR}{BRA}{}% \gregion{086}{IO}{IOT}{}% \gregion{096}{BN}{BRN}{}% \gregion{100}{BG}{BGR}{}% \gregion{854}{BF}{BFA}{}% \gregion{108}{BI}{BDI}{}% \gregion{132}{CV}{CPV}{}% \gregion{116}{KH}{KHM}{}% \gregion{120}{CM}{CMR}{}% \gregion{124}{CA}{CAN}{}% \gregion{136}{KY}{CYM}{}% \gregion{140}{CF}{CAF}{}% \gregion{148}{TD}{TCD}{}% \gregion{152}{CL}{CHL}{}% \gregion{156}{CN}{CHN}{}% \gregion{162}{CX}{CXR}{}% \gregion{166}{CC}{CCK}{}% \gregion{170}{CO}{COL}{}% \gregion{174}{KM}{COM}{}% \gregion{180}{CD}{COD}{}% \gregion{178}{CG}{COG}{}% \gregion{184}{CK}{COK}{}% \gregion{188}{CR}{CRI}{}% \gregion{384}{CI}{CIV}{}% \gregion{191}{HR}{HRV}{}% \gregion{192}{CU}{CUB}{}% \gregion{531}{CW}{CUW}{}% \gregion{196}{CY}{CYP}{}% \gregion{203}{CZ}{CZE}{}% \gregion{208}{DK}{DNK}{}% \gregion{262}{DJ}{DJI}{}% \gregion{212}{DM}{DMA}{}% \gregion{214}{DO}{DOM}{}% \gregion{218}{EC}{ECU}{}% \gregion{818}{EG}{EGY}{}% \gregion{222}{SV}{SLV}{}% \gregion{226}{GQ}{GNQ}{}% \gregion{232}{ER}{ERI}{}% \gregion{233}{EE}{EST}{}% \gregion{231}{ET}{ETH}{}% \gregion{238}{FK}{FLK}{}% \gregion{234}{FO}{FRO}{}% \gregion{242}{FJ}{FJI}{}% \gregion{246}{FI}{FIN}{}% \gregion{250}{FR}{FRA}{}% \gregion{254}{GF}{GUF}{}% \gregion{258}{PF}{PYF}{}% \gregion{260}{TF}{ATF}{}% \gregion{266}{GA}{GAB}{}% \gregion{270}{GM}{GMB}{}% \gregion{268}{GE}{GEO}{}% \gregion{276}{DE}{DEU}{}% \gregion{288}{GH}{GHA}{}% \gregion{292}{GI}{GIB}{}% \gregion{300}{GR}{GRC}{}% \gregion{304}{GL}{GRL}{}% \gregion{308}{GD}{GRD}{}% \gregion{312}{GP}{GLP}{}% \gregion{316}{GU}{GUM}{}% \gregion{320}{GT}{GTM}{}% \gregion{831}{GG}{GGY}{}% \gregion{324}{GN}{GIN}{}% \gregion{624}{GW}{GNB}{}% \gregion{328}{GY}{GUY}{}% \gregion{332}{HT}{HTI}{}% \gregion{334}{HM}{HMD}{}% \gregion{336}{VA}{VAT}{}% \gregion{340}{HN}{HND}{}% \gregion{344}{HK}{HKG}{}% \gregion{348}{HU}{HUN}{}% \gregion{352}{IS}{ISL}{}% \gregion{356}{IN}{IND}{}% \gregion{360}{ID}{IDN}{}% \gregion{364}{IR}{IRN}{}% \gregion{368}{IQ}{IRQ}{}% \gregion{372}{IE}{IRL}{}% \gregion{833}{IM}{IMN}{}% \gregion{376}{IL}{ISR}{}% \gregion{380}{IT}{ITA}{}% \gregion{388}{JM}{JAM}{}% \gregion{392}{JP}{JPN}{}% \gregion{832}{JE}{JEY}{}% \gregion{400}{JO}{JOR}{}% \gregion{398}{KZ}{KAZ}{}% \gregion{404}{KE}{KEN}{}% \gregion{296}{KI}{KIR}{}% \gregion{408}{KP}{PRK}{}% \gregion{410}{KR}{KOR}{}% \gregion{414}{KW}{KWT}{}% \gregion{417}{KG}{KGZ}{}% \gregion{418}{LA}{LAO}{}% \gregion{428}{LV}{LVA}{}% \gregion{422}{LB}{LBN}{}% \gregion{426}{LS}{LSO}{}% \gregion{430}{LR}{LBR}{}% \gregion{434}{LY}{LBY}{}% \gregion{438}{LI}{LIE}{}% \gregion{440}{LT}{LTU}{}% \gregion{442}{LU}{LUX}{}% \gregion{446}{MO}{MAC}{}% \gregion{807}{MK}{MKD}{}% \gregion{450}{MG}{MDG}{}% \gregion{454}{MW}{MWI}{}% \gregion{458}{MY}{MYS}{}% \gregion{462}{MV}{MDV}{}% \gregion{466}{ML}{MLI}{}% \gregion{470}{MT}{MLT}{}% \gregion{584}{MH}{MHL}{}% \gregion{474}{MQ}{MTQ}{}% \gregion{478}{MR}{MRT}{}% \gregion{480}{MU}{MUS}{}% \gregion{175}{YT}{MYT}{}% \gregion{484}{MX}{MEX}{}% \gregion{583}{FM}{FSM}{}% \gregion{498}{MD}{MDA}{}% \gregion{492}{MC}{MCO}{}% \gregion{496}{MN}{MNG}{}% \gregion{499}{ME}{MNE}{}% \gregion{500}{MS}{MSR}{}% \gregion{504}{MA}{MAR}{}% \gregion{508}{MZ}{MOZ}{}% \gregion{104}{MM}{MMR}{}% \gregion{516}{NA}{NAM}{}% \gregion{520}{NR}{NRU}{}% \gregion{524}{NP}{NPL}{}% \gregion{528}{NL}{NLD}{}% \gregion{540}{NC}{NCL}{}% \gregion{554}{NZ}{NZL}{}% \gregion{558}{NI}{NIC}{}% \gregion{562}{NE}{NER}{}% \gregion{566}{NG}{NGA}{}% \gregion{570}{NU}{NIU}{}% \gregion{574}{NF}{NFK}{}% \gregion{580}{MP}{MNP}{}% \gregion{578}{NO}{NOR}{}% \gregion{512}{OM}{OMN}{}% \gregion{586}{PK}{PAK}{}% \gregion{585}{PW}{PLW}{}% \gregion{275}{PS}{PSE}{}% \gregion{591}{PA}{PAN}{}% \gregion{598}{PG}{PNG}{}% \gregion{600}{PY}{PRY}{}% \gregion{604}{PE}{PER}{}% \gregion{608}{PH}{PHL}{}% \gregion{612}{PN}{PCN}{}% \gregion{616}{PL}{POL}{}% \gregion{620}{PT}{PRT}{}% \gregion{630}{PR}{PRI}{}% \gregion{634}{QA}{QAT}{}% \gregion{638}{RE}{REU}{}% \gregion{642}{RO}{ROU}{}% \gregion{643}{RU}{RUS}{}% \gregion{646}{RW}{RWA}{}% \gregion{652}{BL}{BLM}{}% \gregion{654}{SH}{SHN}{}% \gregion{659}{KN}{KNA}{}% \gregion{662}{LC}{LCA}{}% \gregion{663}{MF}{MAF}{}% \gregion{666}{PM}{SPM}{}% \gregion{670}{VC}{VCT}{}% \gregion{882}{WS}{WSM}{}% \gregion{674}{SM}{SMR}{}% \gregion{678}{ST}{STP}{}% \gregion{682}{SA}{SAU}{}% \gregion{686}{SN}{SEN}{}% \gregion{688}{RS}{SRB}{}% \gregion{690}{SC}{SYC}{}% \gregion{694}{SL}{SLE}{}% \gregion{702}{SG}{SGP}{}% \gregion{534}{SX}{SXM}{}% \gregion{703}{SK}{SVK}{}% \gregion{705}{SI}{SVN}{}% \gregion{090}{SB}{SLB}{}% \gregion{706}{SO}{SOM}{}% \gregion{710}{ZA}{ZAF}{}% \gregion{239}{GS}{SGS}{}% \gregion{728}{SS}{SSD}{}% \gregion{724}{ES}{ESP}{}% \gregion{144}{LK}{LKA}{}% \gregion{729}{SD}{SDN}{}% \gregion{740}{SR}{SUR}{}% \gregion{744}{SJ}{SJM}{}% \gregion{748}{SZ}{SWZ}{}% \gregion{752}{SE}{SWE}{}% \gregion{756}{CH}{CHE}{}% \gregion{760}{SY}{SYR}{}% \gregion{158}{TW}{TWN}{}% \gregion{762}{TJ}{TJK}{}% \gregion{834}{TZ}{TZA}{}% \gregion{764}{TH}{THA}{}% \gregion{626}{TL}{TLS}{}% \gregion{768}{TG}{TGO}{}% \gregion{772}{TK}{TKL}{}% \gregion{776}{TO}{TON}{}% \gregion{780}{TT}{TTO}{}% \gregion{788}{TN}{TUN}{}% \gregion{792}{TR}{TUR}{}% \gregion{795}{TM}{TKM}{}% \gregion{796}{TC}{TCA}{}% \gregion{798}{TV}{TUV}{}% \gregion{800}{UG}{UGA}{}% \gregion{804}{UA}{UKR}{}% \gregion{784}{AE}{ARE}{}% \gregion{826}{GB}{GBR}{}% \gregion{581}{UM}{UMI}{}% \gregion{840}{US}{USA}{}% \gregion{858}{UY}{URY}{}% \gregion{860}{UZ}{UZB}{}% \gregion{548}{VU}{VUT}{}% \gregion{862}{VE}{VEN}{}% \gregion{704}{VN}{VNM}{}% \gregion{092}{VG}{VGB}{}% \gregion{850}{VI}{VIR}{}% \gregion{876}{WF}{WLF}{}% \gregion{732}{EH}{ESH}{}% \gregion{887}{YE}{YEM}{}% \gregion{894}{ZM}{ZMB}{}% \gregion{716}{ZW}{ZWE}{}% % PREDEFINED SCRIPTS \gscript{Adlm}{166}{Adlam}{RL}{}{} \gscript{Afak}{439}{Afaka}{varies}{}{} \gscript{Aghb}{239}{Caucasian Albanian}{LR}{}{} \gscript{Ahom}{338}{Ahom, Tai Ahom}{LR}{}{} \gscript{Arab}{160}{Arabic}{RL}{}{} \gscript{Aran}{161}{Arabic (Nastaliq variant)}{RL}{}{} \gscript{Armi}{124}{Imperial Aramaic}{RL}{}{} \gscript{Armn}{230}{Armenian}{LR}{}{} \gscript{Avst}{134}{Avestan}{RL}{}{} \gscript{Bali}{360}{Balinese}{LR}{}{} \gscript{Bamu}{435}{Bamum}{LR}{}{} \gscript{Bass}{259}{Bassa Vah}{LR}{}{} \gscript{Batk}{365}{Batak}{LR}{}{} \gscript{Beng}{334}{Bhaiksuki}{LR}{}{} \gscript{Blis}{550}{Blissymbols}{varies}{}{} \gscript{Bopo}{285}{Bopomofo}{LR}{}{} \gscript{Brah}{300}{Brahmi}{LR}{}{} \gscript{Brai}{570}{Braille}{LR}{}{} \gscript{Bugi}{367}{Buginese}{LR}{}{} \gscript{Buhd}{372}{Buhid}{LR}{}{} \gscript{Cakm}{349}{Chakma}{LR}{}{} \gscript{Cans}{440}{Unified Canadian Aboriginal Syllabics}{LR}{}{} \gscript{Cari}{201}{Carian}{LR}{}{} \gscript{Cham}{358}{Cham}{LR}{}{} \gscript{Cher}{445}{Cherokee}{LR}{}{} \gscript{Cirt}{291}{Cirth}{varies}{}{} \gscript{Copt}{204}{Coptic}{LR}{}{} \gscript{Cprt}{403}{Cypriot}{RL}{}{} \gscript{Cyrl}{220}{Cyrillic}{LR}{}{} \gscript{Cyrs}{221}{Cyrillic (Old Church Slavonic variant)}{varies}{}{} \gscript{Deva}{315}{Devanagari (Nagari)}{LR}{}{} \gscript{Dsrt}{250}{Deseret (Mormon)}{LR}{}{} \gscript{Dupl}{755}{Duployan shorthand, Duployan stenography}{LR}{}{} \gscript{Egyd}{070}{Egyptian demotic}{RL}{}{} \gscript{Egyh}{060}{Egyptian hieratic}{RL}{}{} \gscript{Egyp}{050}{Egyptian hieroglyphs}{LR}{}{} \gscript{Elba}{226}{Elbasan}{LR}{}{} \gscript{Ethi}{430}{Ethiopic (Ge'ez)}{LR}{}{} \gscript{Geok}{241}{Khutsuri (Asomtavruli and Nuskhuri)}{LR}{}{} \gscript{Geor}{240}{Georgian (Mkhedruli)}{LR}{}{} \gscript{Glag}{225}{Glagolitic}{LR}{}{} \gscript{Goth}{206}{Gothic}{LR}{}{} \gscript{Gran}{343}{Grantha}{LR}{}{} \gscript{Grek}{200}{Greek}{LR}{}{} \gscript{Gujr}{320}{Gujarati}{LR}{}{} \gscript{Guru}{310}{Gurmukhi}{LR}{}{} \gscript{Hanb}{503}{Han with Bopomofo (alias for Han + Bopomofo)}{LR}{}{} \gscript{Hang}{286}{Hangul}{LR}{}{} \gscript{Hani}{500}{Han (Hanzi, Kanji, Hanja)}{LR}{}{} \gscript{Hano}{371}{Hanunoo}{LR}{}{} \gscript{Hans}{501}{Han (Simplified variant)}{varies}{}{} \gscript{Hant}{502}{Han (Traditional variant)}{varies}{}{} \gscript{Hatr}{127}{Hatran}{RL}{}{} \gscript{Hebr}{125}{Hebrew}{RL}{}{} \gscript{Hira}{410}{Hiragana}{LR}{}{} \gscript{Hluw}{080}{Anatolian Hieroglyphs (Luwian Hieroglyphs, Hittite Hieroglyphs)}{LR}{}{} \gscript{Hmng}{450}{Pahawh Hmong}{LR}{}{} \gscript{Hrkt}{412}{Japanese syllabaries (alias for Hiragana + Katakana)}{varies}{}{} \gscript{Hung}{176}{Old Hungarian (Hungarian Runic)}{RL}{}{} \gscript{Inds}{610}{Indus (Harappan)}{RL}{}{} \gscript{Ital}{210}{Old Italic (Etruscan, Oscan, etc.)}{LR}{}{} \gscript{Jamo}{284}{Jamo (alias for Jamo subset of Hangul)}{LR}{}{} \gscript{Java}{361}{Javanese}{LR}{}{} \gscript{Jpan}{413}{Japanese (alias for Han + Hiragana + Katakana)}{varies}{}{} \gscript{Jurc}{510}{Jurchen}{LR}{}{} \gscript{Kali}{357}{Kayah Li}{LR}{}{} \gscript{Kana}{411}{Katakana}{LR}{}{} \gscript{Khar}{305}{Kharoshthi}{RL}{}{} \gscript{Khmr}{355}{Khmer}{LR}{}{} \gscript{Khoj}{322}{Khojki}{LR}{}{} \gscript{Kitl}{505}{Khitan large script}{LR}{}{} \gscript{Kits}{288}{Khitan small script}{TB}{}{} \gscript{Knda}{345}{Kannada}{LR}{}{} \gscript{Kore}{287}{Korean (alias for Hangul + Han)}{LR}{}{} \gscript{Kpel}{436}{Kpelle}{LR}{}{} \gscript{Kthi}{317}{Kaithi}{LR}{}{} \gscript{Lana}{351}{Tai Tham (Lanna)}{LR}{}{} \gscript{Laoo}{356}{Lao}{LR}{}{} \gscript{Latf}{217}{Latin (Fraktur variant)}{varies}{}{} \gscript{Latg}{216}{Latin (Gaelic variant)}{LR}{}{} \gscript{Latn}{215}{Latin}{LR}{}{} \gscript{Leke}{364}{Leke}{LR}{}{} \gscript{Lepc}{335}{Lepcha}{LR}{}{} \gscript{Limb}{336}{Limbu}{LR}{}{} \gscript{Lina}{400}{Linear A}{LR}{}{} \gscript{Linb}{401}{Linear B}{LR}{}{} \gscript{Lisu}{399}{Lisu (Fraser)}{LR}{}{} \gscript{Loma}{437}{Loma}{LR}{}{} \gscript{Lyci}{202}{Lycian}{LR}{}{} \gscript{Lydi}{116}{Lydian}{RL}{}{} \gscript{Mahj}{314}{Mahajani}{LR}{}{} \gscript{Mand}{140}{Mandaic, Mandaean}{RL}{}{} \gscript{Mani}{139}{Manichaean}{RL}{}{} \gscript{Marc}{332}{Marchen}{LR}{}{} \gscript{Maya}{090}{Mayan hieroglyphs}{varies}{}{} \gscript{Mend}{438}{Mende Kikakui}{RL}{}{} \gscript{Merc}{101}{Meroitic Cursive}{RL}{}{} \gscript{Mero}{100}{Meroitic Hieroglyphs}{RL}{}{} \gscript{Mlym}{347}{Malayalam}{LR}{}{} \gscript{Modi}{324}{Modi}{LR}{}{} \gscript{Mong}{145}{Mongolian}{TB}{}{} \gscript{Moon}{218}{Moon (Moon code, Moon script, Moon type)}{varies}{}{} \gscript{Mroo}{199}{Mro, Mru}{LR}{}{} \gscript{Mtei}{337}{Meitei Mayek (Meithei, Meetei)}{LR}{}{} \gscript{Mult}{323}{Multani}{LR}{}{} \gscript{Mymr}{350}{Myanmar (Burmese)}{LR}{}{} \gscript{Narb}{106}{Old North Arabian (Ancient North Arabian)}{RL}{}{} \gscript{Nbat}{159}{Nabataean}{RL}{}{} \gscript{Newa}{333}{Newa, Newar, Newari}{LR}{}{} \gscript{Nkgb}{420}{Nakhi Geba}{LR}{}{} \gscript{Nkoo}{165}{N'Ko}{RL}{}{} \gscript{Nshu}{499}{Nushu}{LR}{}{} \gscript{Ogam}{212}{Ogham}{varies}{}{} \gscript{Olck}{261}{Ol Chiki}{LR}{}{} \gscript{Orkh}{175}{Old Turkic, Orkhon Runic}{RL}{}{} \gscript{Orya}{327}{Oriya}{LR}{}{} \gscript{Osge}{219}{Osage}{LR}{}{} \gscript{Osma}{260}{Osmanya}{LR}{}{} \gscript{Palm}{126}{Palmyrene}{RL}{}{} \gscript{Pauc}{263}{Pau Cin Hau}{LR}{}{} \gscript{Perm}{227}{Old Permic}{LR}{}{} \gscript{Phag}{331}{Phags-pa}{TB}{}{} \gscript{Phli}{131}{Inscriptional Pahlavi}{RL}{}{} \gscript{Phlp}{132}{Psalter Pahlavi}{RL}{}{} \gscript{Phlv}{133}{Book Pahlavi}{RL}{}{} \gscript{Phnx}{115}{Phoenician}{RL}{}{} \gscript{Piqd}{293}{Klingon (KLI plqaD)}{LR}{}{} \gscript{Plrd}{282}{Miao (Pollard)}{LR}{}{} \gscript{Prti}{130}{Inscriptional Parthian}{RL}{}{} \gscript{Qaaa}{900}{Reserved for private use (start)}{varies}{}{} \gscript{Qaai}{908}{Private use}{varies}{}{} \gscript{Qabx}{949}{Reserved for private use (end)}{varies}{}{} \gscript{Rjng}{363}{Rejang (Redjang, Kaganga)}{LR}{}{} \gscript{Roro}{620}{Rongorongo}{varies}{}{} \gscript{Runr}{211}{Runic}{LR}{}{} \gscript{Samr}{123}{Samaritan}{RL}{}{} \gscript{Sara}{292}{Sarati}{varies}{}{} \gscript{Sarb}{105}{Old South Arabian}{RL}{}{} \gscript{Saur}{344}{Saurashtra}{LR}{}{} \gscript{Sgnw}{095}{SignWriting}{TB}{}{} \gscript{Shaw}{281}{Shavian (Shaw)}{LR}{}{} \gscript{Shrd}{319}{Sharada}{LR}{}{} \gscript{Sidd}{302}{Siddham}{LR}{}{} \gscript{Sind}{318}{Khudawadi, Sindhi}{LR}{}{} \gscript{Sinh}{348}{Sinhala}{LR}{}{} \gscript{Sora}{398}{Sora Sompeng}{LR}{}{} \gscript{Sund}{362}{Sundanese}{LR}{}{} \gscript{Sylo}{316}{Syloti Nagri}{LR}{}{} \gscript{Syrc}{135}{Syriac}{RL}{}{} \gscript{Syre}{138}{Syriac (Estrangelo variant)}{RL}{}{} \gscript{Syrj}{137}{Syriac (Western variant)}{RL}{}{} \gscript{Syrn}{136}{Syriac (Eastern variant)}{RL}{}{} \gscript{Tagb}{373}{Tagbanwa}{LR}{}{} \gscript{Takr}{321}{Takri}{LR}{}{} \gscript{Tale}{353}{Tai Le}{LR}{}{} \gscript{Talu}{354}{New Tai Lue}{LR}{}{} \gscript{Taml}{346}{Tamil}{LR}{}{} \gscript{Tang}{520}{Tangut}{LR}{}{} \gscript{Tavt}{359}{Tai Viet}{LR}{}{} \gscript{Telu}{340}{Telugu}{LR}{}{} \gscript{Teng}{290}{Tengwar}{LR}{}{} \gscript{Tfng}{120}{Tifinagh (Berber)}{LR}{}{} \gscript{Tglg}{370}{Tagalog (Baybayin, Alibata)}{LR}{}{} \gscript{Thaa}{170}{Thaana}{RL}{}{} \gscript{Thai}{352}{Thai}{LR}{}{} \gscript{Tibt}{330}{Tibetan}{LR}{}{} \gscript{Tirh}{326}{Tirhuta}{LR}{}{} \gscript{Ugar}{040}{Ugaritic}{LR}{}{} \gscript{Vaii}{470}{Vai}{LR}{}{} \gscript{Visp}{280}{Visible Speech}{LR}{}{} \gscript{Wara}{262}{Warang Citi (Varang Kshiti)}{LR}{}{} \gscript{Wole}{480}{Woleai}{RL}{}{} \gscript{Xpeo}{030}{Old Persian}{LR}{}{} \gscript{Xsux}{020}{Cuneiform, Sumero-Akkadian}{LR}{}{} \gscript{Yiii}{460}{Yi}{LR}{}{} \gscript{Zinh}{994}{Inherited script}{inherited}{}{} \gscript{Zmth}{995}{Mathematical notation}{LR}{}{} \gscript{Zsym}{996}{Symbols}{varies}{}{} \gscript{Zsye}{993}{Symbols (emoji variant)}{varies}{}{} \gscript{Zxxx}{997}{Unwritten documents}{varies}{}{} \gscript{Zyyy}{998}{Undetermined script}{varies}{}{} \gscript{Zzzz}{999}{Uncoded script}{varies}{}{} } \title{tracklang.sty v1.6.1: tracking language options} \author{Nicola L.C. Talbot\\[10pt] Dickimaw Books\\ \href{https://www.dickimaw-books.com/}{\nolinkurl{dickimaw-books.com}}} \date{2022-12-13 } \newcommand{\refoptstables}{\tablesref{tab:isoopts,tab:rootlangopts,tab:nonisoopts}} \begin{document} \maketitle \htmlavailable \begin{abstract} The \sty+{tracklang} package is provided for package developers who want a simple interface to find out which languages the user has requested through packages such as \sty{babel} and \sty{polyglossia}. \emph{This package doesn't provide any translations.} Its purpose is simply to track which languages have been requested by the user. Generic \TeX\ code is in \file{tracklang.tex} for non-\LaTeX\ users. If the \idx{shellescape} is enabled or \gls{directlua} is available, this package may also be used to query the \envvar{LCALL} or \envvar{LANG} environment variable (see \sectionref{sec:langsty}). Windows users, who don't have the locale stored in environment variables, can use \app{texosquery} in combination with \sty{tracklang}. (Similarly if \envvar{LCALL} or \envvar{LANG} don't contain sufficient information.) In order to use \app{texosquery} through the restricted \idx{shellescape}, you must have at least Java~8 and set up \file{texosquery.cfg} appropriately. (See the \app{texosquery} manual for further details.) \end{abstract} The fundamental aim of this generic package is to be able to effectively say: \begin{quote} The user (that is, the \emph{document} author) wants to use dialects \langtagfmt{xx-XX}, \langtagfmt{yy-YY-Scrp}, etc in their document. Any packages used by their document that provide multilingual or region-dependent support should do whatever is required to activate the settings for those languages and regions (or warn the user that there's no support). \end{quote} Naturally, this is only of use if the locale-sensitive packages use \sty{tracklang} to pick up this information, which is entirely up to the package authors, but at the moment there's no standard method for packages to detect the required language and region. The aim of \sty{tracklang} is to provide that method. In particular, the emphasis is on using \idx+{ISO} language and region codes rather than hard-coding the various language labels used by different language packages. Related articles: \tugboat{Localisation of \TeX\ documents: \styfmt{tracklang}.} {2016}{37}{3}{http://www.tug.org/TUGboat/tb37-3/tb117talbot.pdf}, \dickimawhref{latex/tracklang}{Localisation with \filefmt{tracklang.tex}}, and \faqspkg{tracklang}. \frontmatter \tableofcontents \listoftables \mainmatter \part{User Guide} \chapter{Introduction} \label{sec:intro} When I'm developing a package that provides multilingual support (for example, \sty{glossaries}) it's cumbersome trying to work out if the user has requested translations for fixed text. This usually involves checking if \sty{babel} or \sty{translator} or \sty{polyglossia} has been loaded and, if so, what language settings have been used. The result can be a tangled mass of conditional code. The alternative is to tell users to add the language as a~document class option, which they may or may not want to do, or to tell them to supply the language settings to every package they load that provides multilingual support, which users are even less likely to want to do. The \sty{tracklang} package tries to neaten this up by working out as much of this information as possible for you and providing a command that iterates through the loaded languages. This way, you can just iterate through the list of tracked languages and, for each language, either define the translations or warn the user that there's no translation for that language. This package works best with \sty{ngerman} and \sty{german} (since it's a simple test to determine if they have been loaded) and recent versions of \sty{polyglossia} (which conveniently provides \gls{xpg@bcp@loaded}) or when the language options are specified in the document class option list. It works fairly well with \sty{translator} but will additionally assume the root language was also requested when a dialect is specified. So, for example, \begin{codebox} \cmd{usepackage}[\opt{british}]\marg{translator} \cmd{usepackage}\marg{tracklang} \end{codebox} is equivalent to \begin{compactcodebox} \cmd{usepackage}[\opt{british}]\marg{translator} \cmd{usepackage}[\opt{english},\opt{british}]\marg{tracklang} \end{compactcodebox} This means that \gls{ForEachTrackedDialect} will iterate through the list \qt{\opt{english},\opt{british}} instead of just \qt{\opt{british}}, which can result in some redundancy. Unfortunately I can't find any way of detecting a list of languages loaded through \sty{babel}['s] new \gls{babelprovide} command. As far as I can tell, the only stored list is in \gls{bbl@loaded} which only contains the languages loaded through package options. If the \sty{ngerman} package has been loaded, \sty{tracklang} effectively does: \begin{compactcodebox} \gls{TrackPredefinedDialect}\marg{\opt{ngerman}} \end{compactcodebox} Similarly, if the \sty{german} package has been loaded, \sty{tracklang} effectively does \begin{compactcodebox} \gls{TrackPredefinedDialect}\marg{\opt{german}} \end{compactcodebox} If any document class or package options are passed to \sty{tracklang}, then \sty{tracklang} won't bother checking for \sty{babel}, \sty{translator}, \sty{ngerman}, \sty{german} or \sty{polyglossia}. So, if the above example is changed to: \begin{codebox} \cmd{documentclass}[\opt{british}]\marg{article} \cmd{usepackage}\marg{translator} \cmd{usepackage}\marg{tracklang} \end{codebox} then the dialect list will just consist of \qt{\opt{british}} rather than \qt{\opt{english},\opt{british}}. This does, however, mean that if the user mixes class and package options, only the class options will be detected. For example: \begin{codebox} \cmd{documentclass}[\opt{british}]\marg{article} \cmd{usepackage}[\opt{french}]\marg{babel} \cmd{usepackage}\marg{tracklang} \end{codebox} In this case, only the \opt{british} option will be detected. The user can therefore use the document class option (or \sty{tracklang} package option) to override the dialect and set the country code (where provided). For example: \begin{codebox} \cmd{documentclass}[\opt{es-MX}]\marg{article} \cmd{usepackage}[\opt{spanish}]\marg{babel} \cmd{usepackage}\marg{tracklang} \end{codebox} This sets the dialect to \opt{mexicanspanish} and the root language to \opt{spanish}. Predefined dialects are listed in \refoptstables. These may be passed in the document class options or used in \gls{TrackPredefinedDialect}, as illustrated above. \Sectionref{sec:summary} provides brief examples of use for those who want a general overview before reading the more detailed sections. \Sectionref{sec:generic} describes generic commands for identifying the document languages. \Sectionref{sec:user} is for package writers who want to add multilingual support to their package and need to know which settings the user has requested through language packages like \sty{babel}. \Sectionref{sec:langsty} is for developers of language definition packages who want to help other package writers to detect what languages have been requested. \printunsrttable [ type=index, block-style=name-other, other=dialect, toctitle={Predefined ISO Language-Region Dialects}, title={Predefined \idx+{ISO} Language-Region Dialects. (\idx{ISO} tag or dialect label may be used as a package option or with \gls{TrackPredefinedDialect})}, label={tab:isoopts}, postamble={Other combinations need to be set with \gls{TrackLocale} or \gls{TrackLanguageTag}}, init={% \renewcommand{\glstableNameTarget}[1]{\inlineglsdef[optdef]{##1}}% \let\glstableOtherFmt\optfmt \renewcommand{\glstablenameheader}{ISO Tag}% \renewcommand{\glstableotherheader}{Dialect Label}% \renewcommand{\glstableiffilter}[3]{\glsifcategory{##1}{isolangregion}{##3}{##2}}% } ] \printunsrttable [ type=index, header=false,rules=false,blocksep={},clearpage, block-style=name,blocks=3, other=isotag, toctitle={Predefined Root Languages}, title={Predefined Root Languages. (\fnregion Has an associated territory.) The corresponding tag obtained with \code{\gls{GetTrackedLanguageTag}\margm{dialect}} is shown in parentheses}, label={tab:rootlangopts}, init={\let\glstableOtherFmt\optfmt \renewcommand{\glstableNameTarget}[1]{\inlineglsdef[optdef]{##1}}% \renewcommand{\glstableiffilter}[3]{\glsifcategory{##1}{rootlang}{##3}{##2}}% } ] \printunsrttable [ type=index, block-style=name,rules=false,header=false,blocksep={},clearpage, other=tags,par=ragged, toctitle={Predefined Non-ISO Dialects}, title={Predefined Non-ISO Dialects. (\fnregion Has an associated territory.) The corresponding language tag obtained with \code{\gls{GetTrackedLanguageTag}\margm{dialect}} is shown in parentheses. If the dialect has a corresponding mapping for the closest matching non-root language \gls{captionsdialect} or \gls{datedialect}, this is also included after the tag following a slash.}, label={tab:nonisoopts}, init={% \renewcommand{\glstableiffilter}[3]{\glsifcategory{##1}{noniso}{##3}{##2}}% \renewcommand{\glstableNameTarget}[1]{\inlineglsdef[optdef]{##1}}% } ] \chapter{Summary of Use} \label{sec:summary} There are three levels of use: \begin{enumerate} \item document level (code used by document authors); \item locale-sensitive package level (code for package authors who need to know what languages or locale the document is using, such as \sty{glossaries} to translate commands like \cmd{descriptionname} or \sty{datetime2} to provide localised formats or time zone information); \item language set-up level (code for packages that set up the document languages, such as \sty{babel} or \sty{polyglossia}). \end{enumerate} \section{Document Level} \label{sec:summary-doc} Document level use can be divided into generic \TeX\ use (\sectionref{sec:tex}) and \LaTeX-specific use (\sectionref{sec:latex}). \subsection{Generic \texorpdfstring{\TeX}{TeX}} \label{sec:tex} This section is for generic \TeX\ use. The \sty+{tracklang} files are loaded with \gls{input}. See \sectionref{sec:latex} for \LaTeX\ use. A Unix-like user wants the locale information picked up from the locale environment variable (the \ext+{tex} extension may be omitted): \begin{codebox*} \gls{input} \file{tracklang.tex} \comment{v1.3} \gls{TrackLangFromEnv} \comment{load packages that use tracklang for localisation} \end{codebox*} A Windows user wants the locale information picked up from the operating system (again the \ext{tex} extension may be omitted): \begin{codebox*} \gls{input} \file{texosquery.tex} \gls{input} \file{tracklang.tex} \comment{v1.3} \gls{TrackLangFromEnv} \comment{load packages that use tracklang for localisation} \end{codebox*} Or (\sty{texosquery} v1.2) \begin{codebox*} \gls{input} \file{texosquery.tex} \comment{v1.2} \gls{input} \file{tracklang.tex} \comment{v1.3} \codepar \gls{TeXOSQueryLangTag}\marg{\cmd{langtag}} \gls{TrackLanguageTag}\marg{\cmd{langtag}} \comment{load packages that use tracklang for localisation} \end{codebox*} A Unix-like user who may or may not have \app{texosquery} setup to run in the \idx{shellescape}: \begin{codebox*} \gls{input} \file{texosquery.tex} \gls{input} \file{tracklang.tex} \comment{v1.3} \codepar \cmd{ifx}\gls{TeXOSQueryLangTag}\cmd{undefined} \gls{TrackLangFromEnv} \cmd{else} \gls{TeXOSQueryLangTag}\marg{\cmd{langtag}} \gls{TrackLanguageTag}\marg{\cmd{langtag}} \cmd{fi} \comment{load packages that use tracklang for localisation} \end{codebox*} A user is writing in Italy in Armenian with a Latin \idx{script} (\opt{Latn}) and the arevela \idx{variant}: \begin{codebox*} \gls{input} \file{tracklang.tex} \comment{v1.3} \gls{TrackLanguageTag}\marg{hy-Latn-IT-arevela} \comment{load packages that use tracklang for localisation} \end{codebox*} A user is writing in English in the UK: \begin{codebox*} \gls{input} \file{tracklang.tex} \gls{TrackPredefinedDialect}\marg{british} \comment{load packages that use tracklang for localisation} \end{codebox*} Find out information about the current language (supplied in \gls{languagename}): \begin{codebox*} \gls{SetCurrentTrackedDialect}\marg{\gls{languagename}} Dialect: \gls{CurrentTrackedDialect}. Language: \gls{CurrentTrackedLanguage}. ISO Code: \gls{CurrentTrackedIsoCode}. Region: \gls{CurrentTrackedRegion}. Modifier: \gls{CurrentTrackedDialectModifier}. Variant: \gls{CurrentTrackedDialectVariant}. Script: \gls{CurrentTrackedDialectScript}. Sub-Lang: \gls{CurrentTrackedDialectSubLang}. Additional: \gls{CurrentTrackedDialectAdditional}. Language Tag: \gls{CurrentTrackedLanguageTag}. \end{codebox*} Additional information about the \idx{script} can be obtained by also loading \sty{tracklang-scripts}: \begin{codebox*} \gls{input} \file{tracklang-scripts.tex} \end{codebox*} The name, numeric code and direction can now be obtained: \begin{codebox*} Name: \gls{TrackLangScriptAlphaToName}\marg{\gls{CurrentTrackedDialectScript}}. Numeric: \gls{TrackLangScriptAlphaToNumeric}\marg{\gls{CurrentTrackedDialectScript}}. Direction: \gls{TrackLangScriptAlphaToDir}\marg{\gls{CurrentTrackedDialectScript}}. \end{codebox*} Test for a specific \idx{script} (in this case \opt{Latn}): \begin{codebox*} Latin? \cmd{ifx}\gls{CurrentTrackedDialectScript}\tklscript{Latn} Yes \cmd{else} No \cmd{fi} \end{codebox*} \subsection{\texorpdfstring{\LaTeX}{LaTeX}} \label{sec:latex} This section is for \LaTeX\ use. See \sectionref{sec:tex} for generic \TeX\ use. With newer versions of \sty{polyglossia}, where \gls{xpg@bcp@loaded} is defined, you just need to make sure the languages are set before \sty{tracklang} is loaded: \begin{codebox*} \cmd{documentclass}\marg{article} \cmd{usepackage}\marg{polyglossia} \cmd{setmainlanguage}[variant=uk]\marg{english} \comment{load packages that use tracklang for localisation} \end{codebox*} For older versions of \sty{polyglossia} where the regional information is required, use recognised class options: \begin{codebox*} \cmd{documentclass}[\opt{en-GB}]\marg{article} \cmd{usepackage}\marg{polyglossia} \cmd{setmainlanguage}[variant=uk]\marg{english} \comment{load packages that use tracklang for localisation} \end{codebox*} For \sty{babel} users where the supplied \sty{babel} dialect label is sufficient, and is passed either through the document class or package options, there's no need to do anything special: \begin{codebox*} \cmd{documentclass}[\opt{british},\opt{canadien}]\marg{article} \cmd{usepackage}[T1]\marg{fontenc} \cmd{usepackage}\marg{babel} \comment{load packages that use tracklang for localisation} \end{codebox*} If the region is important but there's no \sty{babel} dialect that represents it, there are several options. The first method is to use the class options recognised by \sty{tracklang} and the root language labels when loading \sty{babel}: \begin{codebox*} \cmd{documentclass}[\opt{en-IE},\opt{ga-IE}]\marg{article} \cmd{usepackage}[english,irish]\marg{babel} \comment{load packages that use tracklang for localisation} \end{codebox*} Another method with \sty{babel} is to use \gls{TrackLanguageTag} and map the new dialect label to the nearest matching \gls{captionsdialect}: \begin{codebox*} \cmd{documentclass}\marg{article} \codepar \cmd{usepackage}\marg{tracklang}\comment{v1.3} \gls{TrackLanguageTag}\marg{\opt{en-MT}} \gls{SetTrackedDialectLabelMap}\marg{\gls{TrackLangLastTrackedDialect}}\marg{\opt{UKenglish}} \codepar \cmd{usepackage}[UKenglish]\marg{babel} \comment{load packages that use tracklang for localisation} \end{codebox*} This ensures that the \tklcaptions{UKenglish} hook is detected by the localisation packages. This mapping isn't needed for \sty{polyglossia} as the caption hooks use the root language label. This mapping also isn't needed if \opt{british} is used instead of \opt{UKenglish} since the \opt{en-MT} (\opt{maltaenglish}) predefined dialect automatically sets up a mapping to \opt{british}. (The default mappings are shown in \tableref{tab:nonisoopts}.) There's no support for \gls{babelprovide}. If you are using \gls{babelprovide}, you will need to use the class option or \gls{TrackLanguageTag} as above. \section{Locale-Sensitive Packages} \label{sec:summary-localepkg} Let's suppose you are developing a package called \filefmt{mypackage.sty} or \filefmt{mypackage.tex} and you want to find out what languages the document author has requested. (See also: \dickimawhref{latex/tracklang/otherpkg.shtml}{Using \filefmt{tracklang.tex} in Packages with Localisation Features}.) Generic \TeX\ use (the \ext{tex} extension may be omitted): \begin{codebox*} \gls{input} \file{tracklang.tex} \end{codebox*} (Most of the commands used in this section require at least \sty{tracklang} version 1.3 but 1.4 is better if you want to include the \idx{script} tag in the \ext+{ldf} files.) Note that \file{tracklang.tex} has a check to determine if it's already been loaded, so you don't need to worry about that. \LaTeX\ use: \begin{codebox*} \gls{RequirePackage}\marg{tracklang}[2019/11/30]\comment{at least v1.4} \end{codebox*} This will picked up any language options supplied in the document class options and will also detect if \sty{babel} or \sty{polyglossia} have been loaded. (\LaTeX) If you want to allow the user to set the locale in the package options: \begin{codebox*} \gls{DeclareOption}*\marg{\gls{TrackLanguageTag}\marg{\cmd{CurrentOption}}} \end{codebox*} This means the user can do, say, \begin{codebox} \cmd{usepackage}[hy-Latn-IT-arevela]\marg{mypackage} \end{codebox} With at least version 1.4, it's better to use \gls{TrackIfKnownLanguage}: \begin{codebox} \gls{DeclareOption}*\marg{\comment{} \gls{TrackIfKnownLanguage}\marg{\cmd{CurrentOption}}\comment{} \marg{\comment{successful} \cmd{PackageInfo}\marg{mypackage}\marg{Tracking language `\cmd{CurrentOption}'}\comment{} }\comment{} \marg{\comment{failed} \cmd{PackageError}\marg{mypackage}\comment{} \marg{Unknown language specification `\cmd{CurrentOption}'}\comment{} \marg{You need to supply either a known dialect label or a valid language tag}\comment{} }\comment{} } \end{codebox} \begin{information} The rest of the example package in this section uses generic code. If you are using \LaTeX, it's better to replace \cmd{def} and \cmd{ifx} with more appropriate \LaTeX\ commands. \end{information} If you want to fetch the locale information from the operating system when the user hasn't requested a language: \begin{codebox*} \gls{AnyTrackedLanguages} \marg{} \marg{\comment{fetch locale information from the operating system} \cmd{ifx}\gls{TeXOSQueryLangTag}\cmd{undefined} \comment{texosquery v1.2 not available} \gls{TrackLangFromEnv} \cmd{else} \comment{texosquery v1.2 available} \gls{TeXOSQueryLangTag}\marg{\cmd{langtag}} \gls{TrackLanguageTag}\marg{\cmd{langtag}} \cmd{fi} } \end{codebox*} Set up the defaults if necessary: \begin{codebox} \cmd{def}\cmd{fooname}\marg{Foo} \cmd{def}\cmd{barname}\marg{Bar} \end{codebox} Now load the resource files: \begin{codebox*} \gls{AnyTrackedLanguages} \marg{\comment{} \gls{ForEachTrackedDialect}\marg{\cmd{thisdialect}}\marg{\comment{} \gls{TrackLangRequireDialect}\marg{mypackage}\marg{\cmd{thisdialect}}\comment{} }\comment{} } \marg{}\comment{no tracked languages, default already set up} \end{codebox*} Each resource file has the naming scheme \file{prefix-localeid.ldf}\glsadd{ext.ldf}. In this example, the \meta{prefix} is \filefmt{mypackage}. The \meta{localeid} part may be the language or dialect label (for example, \opt{english} or \opt{british}) or a combination of the \idx{ISO} language and region codes (for example, \opt{en-GB} or \iso{english} or \optfmt{GB}). As from version 1.4, \meta{localeid} may also include the \idx{script} or \idx{variant}. (See the definition of \gls{IfTrackedLanguageFileExists} \pref{pg:filesearch} for further details.) The simplest scheme is to use the root language label (not the dialect label) for the base language settings and use the \idx+{ISO} codes for regional support. For example, the file \ldf{mypackage}{english}: \begin{codebox*} \comment{identify this file:} \gls{TrackLangProvidesResource}\marg{english}[2016/10/06 v1.0] \codepar \gls{TrackLangAddToCaptions}\marg{\comment{} \cmd{def}\cmd{fooname}\marg{Foo}\comment{} \cmd{def}\cmd{barname}\marg{Bar}\comment{} } \end{codebox*} This sets up appropriate the \gls{captionsdialect} hook (if it's found). For other hooks, such as \gls{datedialect}, use \gls{TrackLangAddToHook} or \gls{TrackLangRedefHook} instead. With pre-v1.4 versions of \sty{tracklang}, the \idx{script} isn't included in the file search. If it's needed then either require at least v1.4 or have a base \ext{ldf} file that tries to load a version for the particular \idx{script} (which can be accessed with \gls{CurrentTrackedDialectScript}). Here's an example for a language with different writing systems. The resource file for Serbian \ldf{mypackage}{serbian}: \begin{codebox*} \comment{identify file:} \gls{TrackLangProvidesResource}\marg{serbian}[2016/10/06 v1.0] \codepar \gls{TrackLangRequestResource}\marg{serbian-\gls{CurrentTrackedDialectScript}} \marg{}\comment{file not found, do something sensible here} \end{codebox*} The file \ldf{mypackage}{serbian-Latn} sets up the Latin \idx{script} (\opt{Latn}): \begin{codebox*} \gls{TrackLangProvidesResource}\marg{serbian-Latn}[2016/10/06 v1.0] \codepar \gls{TrackLangAddToCaptions}\marg{\comment{} \cmd{def}\cmd{fooname}\marg{...}\comment{provide appropriate Latin translations} \cmd{def}\cmd{barname}\marg{...}\comment{} } \end{codebox*} The file \ldf{mypackage}{serbian-Cyrl} sets up the Cyrillic \idx{script} (\opt{Cyrl}): \begin{codebox*} \gls{TrackLangProvidesResource}\marg{serbian-Cyrl}[2016/10/06 v1.0] \codepar \gls{TrackLangAddToCaptions}\marg{\comment{} \cmd{def}\cmd{fooname}\marg{...}\comment{provide appropriate Cyrillic translations} \cmd{def}\cmd{barname}\marg{...}\comment{} } \end{codebox*} With v1.4+ you just need \ldf{mypackage}{sr-Latn} and \ldf{mypackage}{sr-Cyrl} for the regionless versions. \section{Language Packages} \label{sec:summary-langpkg} Let's suppose now you're the developer of a package that sets up the language, hyphenation patterns and so on. It would be really helpful to the locale-sensitive packages in \sectionref{sec:summary-localepkg} to know what languages the document author has requested. You can use the \sty{tracklang} package to identify this information by tracking the requested localisation, so that other packages can have a consistent way of querying it. (See also: \dickimawhref{latex/tracklang/langpkg.shtml}{Integrating \filefmt{tracklang.tex} into Language Packages}.) Generic use: \begin{codebox} \gls{input} tracklang \end{codebox} Alternative \LaTeX\ use: \begin{codebox} \gls{RequirePackage}\marg{tracklang}[2019/11/30]\comment{v1.4} \end{codebox} Unlike \gls{input}, \gls{RequirePackage} will allow \sty{tracklang} to pick up the document class options, but using \gls{RequirePackage} will also trigger the tests for known language packages. (If you want to find out if \sty{tracklang} has already been loaded and locales have already been tracked, you can use the same code as in the previous section.) When a user requests a particular language through your package, the simplest way of letting \sty{tracklang} know about it is to use \gls{TrackPredefinedDialect} or \gls{TrackLanguageTag}. For example, if the user requests \opt{british}, that's a predefined dialect so you can just do: \begin{codebox} \gls{TrackPredefinedDialect}\marg{\opt{british}} \end{codebox} Alternatively \begin{codebox} \gls{TrackLanguageTag}\marg{\opt{en-GB}} \end{codebox} If your package uses caption hooks, then you can set up a mapping between \sty{tracklang}'s internal dialect label and your caption label. For example, let's suppose the closest match to English used in Malta (\opt{en-MT}) is the dialect \opt{UKenglish} (for example, the date format is similar between GB and MT): \begin{codebox} \gls{TrackLanguageTag}\marg{\opt{en-MT}} \gls{SetTrackedDialectLabelMap}\marg{\gls{TrackLangLastTrackedDialect}}\marg{\opt{UKenglish}} \cmd{def}\tklcaptions{UKenglish}\marg{\comment{} \cmd{def}\cmd{contentsname}\marg{Contents}\comment{} \comment{...} } \end{codebox} (The predefined \opt{maltaenglish} option provided by \sty{tracklang} automatically sets the mapping to \opt{british}, but the above method will change that mapping to \opt{UKenglish}.) This now means that \gls{TrackLangAddToHook} and \gls{TrackLangRedefHook} commands can find your language hooks. You don't need the map if your dialect label is the same as \sty{tracklang}'s root language label for that locale. For example: \begin{codebox} \gls{TrackLanguageTag}\marg{\opt{en-MT}} \cmd{def}\tklcaptions{english}\marg{\comment{} \cmd{def}\cmd{contentsname}\marg{Contents}\comment{} \comment{...} } \end{codebox} When the user switches language through commands like \gls{selectlanguage} it would be useful to also use \code{\gls{SetCurrentTrackedDialect}\margm{dialect}} to make it easier for the document author or locale-sensitive packages to pick up the current locale. The \meta{dialect} argument may be \sty{tracklang}'s internal dialect label or the dialect label you assigned with \gls{SetTrackedDialectLabelMap}. It may also be the root language label, in which case \sty{tracklang} will search for the last dialect to be tracked with that language. For example: \begin{codebox} \cmd{def}\gls{selectlanguage}\#1\marg{\comment{} \gls{SetCurrentTrackedDialect}\marg{\#1}\comment{} \comment{set up hyphenation patterns etc} } \end{codebox} See the example in \sectionref{sec:summary-doc} or the example in \dickimawhref{latex/tracklang/langpkg.shtml}{Integrating \filefmt{tracklang.tex} into Language Packages}. \chapter{Generic Use} \label{sec:generic} For plain \TeX\ you can input \file{tracklang.tex}: \begin{codebox} \gls{input} tracklang \end{codebox} or for \TeX\ formats that have an argument form for \gls{input}: \begin{codebox} \gls{input}\marg{tracklang} \end{codebox} As from version 1.3, you don't need to change the category code of \idx{atletter} before loading \file{tracklang.tex} as it will automatically be changed to 11 and switched back at the end (if required). The \LaTeX\ package \file{tracklang.sty} inputs the generic \TeX\ code in \file{tracklang.tex}, but before it does so it defines \cmddef{@tracklang@declareoption} to \begin{compactcodebox*} \gls{DeclareOption}\margm{dialect}\marg{\gls{TrackPredefinedDialect}\margm{dialect}} \end{compactcodebox*} If \gls{@tracklang@declareoption} isn't defined when \file{tracklang.tex} is input, it will be defined to ignore its argument. This means that all the predefined languages and dialects (\refoptstables) automatically become package options, so the \file{tracklang.sty} package can pick up document class options and add them to \sty{tracklang}'s internal list of tracked document languages. If you're not using \LaTeX, this option isn't available although you can redefine \gls{@tracklang@declareoption} to use something analogous to \gls{DeclareOption}, if appropriate. Otherwise, the document languages need to be explicitly identified (using any of the following commands) so that \sty{tracklang} knows about them. \cmddef{TrackPredefinedDialect} This will add the predefined dialect and its associated \idx{ISO} codes to the list of tracked document languages. The \meta{dialect label} may be any of those listed in \refoptstables. For example: \begin{codebox} \gls{input} tracklang \gls{TrackPredefinedDialect}\marg{\opt{british}} \end{codebox} is the Plain \TeX\ alternative to: \begin{codebox} \cmd{documentclass}[\opt{british}]\marg{article} \cmd{usepackage}\marg{tracklang} \end{codebox} Note that it's impractical to define every possible language and region combination as it would significantly slow the time taken to load \sty{tracklang} so, after version~1.3, I don't intend adding any new predefined dialects. As from version 1.3, if you want to track a dialect that's not predefined by \sty{tracklang}, then you can use: \cmddef{TrackLocale} If \meta{locale} is a recognised dialect, this is equivalent to using \gls{TrackPredefinedDialect}, otherwise \meta{locale} needs to be in one the following formats: \begin{itemize} \item \meta{\idx{ISO} lang} \item \meta{\idx{ISO} lang}\idx{atmod}\meta{modifier} \item \meta{\idx{ISO} lang}\idx{hyphensep}\meta{\idx{ISO} country} \item \meta{\idx{ISO} lang}\idx{hyphensep}\meta{\idx{ISO} country}\idx{atmod}\meta{modifier} \end{itemize} where \meta{\idx{ISO} lang} is the \idxn{639-1} or \idx{639-2} code identifying the language (lower case), \meta{\idx{ISO} country} is the \idx{3166-1} \idx{ISO} code identifying the \idx{territory} (upper case) and \meta{modifier} is the \idx{modifier} or \idx{variant}. The hyphen (\idx{hyphensep}) may be replaced by an underscore character (\idx{underscoresep}). \Idx{code-set} information in the form \code{\idx{dotsep}\meta{codeset}} may optionally appear before the \idx{modifier}. For example, \code{de\idx{hyphensep}DE\idx{dotsep}utf8\idx{atmod}new} (\idx{modifier} is \optfmt{new}) or \code{en\idx{hyphensep}GB\idx{dotsep}utf8} (\idx{modifier} is missing). The \idx{code-set} will be ignored if present, but it won't interfere with the parsing. For example: \begin{codebox} \gls{TrackLocale}\marg{de\idx{hyphensep}NA\idx{atmod}new} \end{codebox} indicates German in Namibia using the new spelling. \begin{important} If a language has different \idxn{639-2T} and \idx{639-2B} codes, then the \qt{T} form should be used. (So for the above example, \code{deu} may be used instead of \code{de}, but \code{ger} won't be recognised.) \end{important} Alternatively, you can use \cmddef{TrackLanguageTag} where \meta{tag} is a regular, well-formed language tag or a recognised dialect label. (Irregular grandfather tags aren't recognised.) This command will fully expand \meta{tag}. A warning is issued if the tag is empty. If you want to first check that \meta{tag} includes a valid language code, then you can instead use: \cmddef{TrackIfKnownLanguage} This will only track \meta{tag} (and then do \meta{success code}) if \meta{tag} starts with a valid language code (or is a predefined dialect) otherwise it will do \meta{fail code}. Both \gls{TrackLanguageTag} and \gls{TrackIfKnownLanguage} will check if \meta{tag} is a predefined option. (This saves parsing the tag if it's recognised.) For example: \begin{codebox} \gls{TrackLanguageTag}\marg{hy-Latn-IT-arevela} Latn-ME: \gls{TrackIfKnownLanguage}\marg{Latn-ME}\marg{success}\marg{fail}. brazilian: \gls{TrackIfKnownLanguage}\marg{brazilian}\marg{success}\marg{fail}. \end{codebox} This will track \optfmt{hy-Latn-IT-arevela} and \opt{brazilian} (\optfmt{pt-BR}) but not \optfmt{Latn-ME} (because it doesn't contain a valid language code) even though it's a valid \idx{script} and country code. The above is just for illustrative purposes. Typically the language tracking isn't performed within the document text. The \sty{datetime2} package assumes that any unknown package option is a language identifier. It could simply do: \begin{compactcodebox} \gls{TrackLanguageTag}\marg{\cmd{CurrentOption}} \end{compactcodebox} but users can make mistakes sometimes and this won't provide any helpful information if they, for example, misspelt a package option or forgot the \qt{\meta{key}=} part of a \keyval\ setting. Instead (as from v1.5.5) \sty{datetime2} now does: \begin{compactcodebox} \gls{TrackIfKnownLanguage}\marg{\cmd{CurrentOption}} \marg{...}\comment{known language} \marg{\cmd{PackageError}\marg{...}\marg{...}\marg{...}} \end{compactcodebox} This will now give the user some guidance. If \meta{tag} contains a sub-language tag, this will be set as the \idx{639-3} code for the \emph{dialect} label. Note that this is different to the root language codes which are set using the language label. For example: \begin{codebox} \gls{TrackLanguageTag}\marg{zh-cmn-Hans-CN} \end{codebox} creates a new dialect with the label \code{zh\-cmn\-Hans\-CN}. The root language \opt{chinese} has the \idx{639-1} code \optfmt{zh} and the dialect \code{zh\-cmn\-Hans\-CN} has the \idxn{639-3} code \optfmt{cmn}. \begin{codebox} ISO 639-1: \gls{TrackedIsoCodeFromLanguage}\marg{639-1}\marg{chinese}. ISO 639-3: \gls{TrackedIsoCodeFromLanguage}\marg{639-3}\marg{zhcmnHansCN}. \end{codebox} Version 1.2 of \sty{texosquery} provides the command \gls{TeXOSQueryLangTag}, which may be used to fetch the operating system's regional information as a language tag. These commands can be used as follows: \begin{codebox} \gls{input} tracklang \comment{v1.3} \gls{input} texosquery \comment{v1.2} \codepar \gls{TeXOSQueryLangTag}\marg{\cmd{langtag}} \gls{TrackLanguageTag}\marg{\cmd{langtag}} \end{codebox} (If the \idx{shellescape} is disabled, \cmd{langtag} will be empty, which will trigger a~warning but no errors.) Some of the predefined root language options listed in \tableref{tab:rootlangopts} have an associated region (denoted by \fnregion). If \gls{TrackLocale} is used with just the language \idx{ISO} code, no region is tracked for that language. For example \begin{codebox} \gls{TrackLocale}\marg{\opt{manx}} \end{codebox} will track the \optfmt{IM} (Isle of Man) \idxn{3166-1} code but \begin{codebox} \gls{TrackLocale}\marg{gv} \end{codebox} won't track the region. Similarly for \gls{TrackLanguageTag}. (New to version 1.3.) There's a similar command to \gls{TrackLocale} that doesn't take an argument: \cmddef{TrackLangFromEnv} If the \idx{shellescape} has been enabled or \gls{directlua} is available, this will try to get the language information from the system environment variables \envvar{LCALL} or \envvar{LANG} and, if successful, track that. Since \sty{tracklang} is neither able to look up the \idx{POSIX} locale tables nor interpret file locales, if the result is \code{C} or \code{POSIX} or starts with a forward slash \code{/} then the locale value is treated as empty. \begin{important} Not all operating systems use environment variables for the system locale information. For example, Windows stores the locale information in the registry. In which case, consider using \sty{texosquery}. \end{important} If the operating system locale can't be obtained from environment variables, then \sty{tracklang} will use \gls{TeXOSQueryLocale} as a fallback if \sty{texosquery} has been loaded. Since \sty{texosquery} requires both the \idx{shellescape} and the Java runtime environment, \sty{tracklang} doesn't automatically load it. Plain \TeX\ example: \begin{codebox} \gls{input} texosquery \gls{input} tracklang \gls{TrackLangFromEnv} \end{codebox} Document build: \begin{terminal} \app{etex} \switch{shell-escape} \meta{filename} \end{terminal} \LaTeX\ example: \begin{codebox} \cmd{usepackage}\marg{texosquery} \cmd{usepackage}\marg{tracklang} \gls{TrackLangFromEnv} \end{codebox} Document build: \begin{terminal} \app{pdflatex} \switch{shell-escape} \meta{filename} \end{terminal} If the locale can't be determined, there will be warning messages. These can be suppressed using \cmddef{TrackLangShowWarningsfalse} or switched back on again using \cmddef{TrackLangShowWarningstrue} For example, I have the environment variable \envvar{LANG} set to \code{en\idx{underscoresep}GB\idx{dotsep}utf8} on my Linux system so instead of \begin{codebox} \gls{TrackPredefinedDialect}\marg{\opt{british}} \end{codebox} I can use \begin{codebox} \gls{TrackLangFromEnv} \end{codebox} With \LaTeX\ documents I can do \begin{codebox} \cmd{documentclass}\marg{article} \cmd{usepackage}\marg{tracklang} \gls{TrackLangFromEnv} \end{codebox} However, this only helps subsequently loaded packages that use \sty{tracklang} to determine the required regional settings. For example: \begin{codebox} \cmd{documentclass}\marg{article} \cmd{usepackage}\marg{tracklang} \gls{TrackLangFromEnv} \cmd{usepackage}[useregional]\marg{datetime2} \end{codebox} In my case, with the \envvar{LANG} environment variable set to \code{en\idx{underscoresep}GB\idx{dotsep}utf8} and the \idx{shellescape} enabled, this automatically switches on the \opt{en-GB} date style. Naturally this doesn't help locale-sensitive packages that don't use \sty{tracklang}. The \gls{TrackLangFromEnv} command also incidentally sets \gls{TrackLangEnv} to the value of the environment variable or empty if the query was unsuccessful (for example, the \idx{shellescape} is unavailable). If the command: \cmddef{TrackLangEnv} is already defined before \gls{TrackLangFromEnv} is used, then the environment variable won't be queried and the value of \gls{TrackLangEnv} will be parsed instead. \begin{important} The parser which splits the locale string into its component parts first tries splitting on the underscore \idx{underscoresep} with its usual category code~8, then tries splitting on a hyphen \idx{hyphensep} with category code~12, and then tries splitting on the underscore \idx{underscoresep} with category code~12. \end{important} For example: \begin{codebox} \cmd{def}\gls{TrackLangEnv}\marg{en-GB} \gls{TrackLangFromEnv} \end{codebox} This doesn't perform a \idx{shellescape} since \gls{TrackLangEnv} is already defined. In this case, you may just as well use: \begin{codebox} \gls{TrackLocale}\marg{en-GB} \end{codebox} (unless you happen to additionally require the component commands that are set by \gls{TrackLangFromEnv}, see below.) If the \idx{shellescape} is unavailable (for example, your \TeX\ installation prohibits it), you can set this value when you invoke \TeX. For example, if the document file is called \filefmt{myDoc.tex} (and it's in Plain \TeX): \begin{terminal} \app{tex} "\idx{escbsl}def\idx{escbsl}\glscsname{TrackLangEnv}\marg{\idx{dollarenv}\envvar{LANG}}\idx{escbsl}\glscsname{input} myDoc" \end{terminal} The \gls{TrackLangFromEnv} command also happens to store the component parts of the environment variable value in the following commands. (These aren't provided by \gls{TrackLocale}.) If the information is unavailable, the relevant commands will be set to empty. The language code is stored in: \cmddef{TrackLangEnvLang} The \idx{territory} (if present) is stored in: \cmddef{TrackLangEnvTerritory} The \idx{code-set} (if present) is stored in: \cmddef{TrackLangEnvCodeSet} The \idx{modifier} (if present) is stored in: \cmddef{TrackLangEnvModifier} If you want to query the language environment, but don't want to track the result, you can just use: \cmddef{TrackLangQueryEnv} This only tries to fetch the value of the language environment variable (and use \sty{texosquery} as a fallback, if it has been loaded). It doesn't try to parse the result. The result is stored in \gls{TrackLangEnv} (empty if unsuccessful). Unlike \gls{TrackLangFromEnv}, this doesn't check if \gls{TrackLangEnv} already exists. A warning will occur if the shell escape is unavailable. For systems that store the locale information in environment variables, this is more efficient than using \sty{texosquery}'s \gls{TeXOSQueryLocale} command (which is what's used as the fallback). The above queries \envvar{LCALL} and, if that is unsuccessful, then queries \envvar{LANG} (before optionally falling back on \sty{texosquery}). If you want another environment variable tried after \envvar{LCALL} and before \envvar{LANG}, you can instead use: \cmddef{TrackLangQueryOtherEnv} For example, to also query \envvar{LCMONETARY}: \begin{codebox} \gls{TrackLangQueryOtherEnv}\marg{\envvar{LCMONETARY}} \end{codebox} Since this sets \gls{TrackLangEnv}, you can use it before \gls{TrackLangFromEnv}. For example: \begin{codebox} \gls{TrackLangQueryOtherEnv}\marg{\envvar{LCMONETARY}} \gls{TrackLangFromEnv} \end{codebox} Remember that if you only want to do the \idx{shellescape} if \gls{TrackLangEnv} hasn't already been defined, you can test for this first: \begin{codebox} \cmd{ifx}\gls{TrackLangEnv}\cmd{undefined} \gls{TrackLangQueryOtherEnv}\marg{\envvar{LCMONETARY}} \cmd{fi} \gls{TrackLangFromEnv} \end{codebox} It's also possible to just parse the value of \gls{TrackLangEnv} without tracking the result using: \cmddef{TrackLangParseFromEnv} This is like \gls{TrackLangFromEnv} but assumes that \gls{TrackLangEnv} has already been set and doesn't track the result. The component parts are stored as for \gls{TrackLangFromEnv}. Example (Plain \TeX): \begin{codebox} \gls{input} tracklang \codepar \cmd{def}\gls{TrackLangEnv}\marg{fr\idx{hyphensep}BE\idx{dotsep}utf8\idx{atmod}euro} \codepar \gls{TrackLangParseFromEnv} \codepar Language: \gls{TrackLangEnvLang}. Territory: \gls{TrackLangEnvTerritory}. Codeset: \gls{TrackLangEnvCodeSet}. Modifier: \gls{TrackLangEnvModifier}. Any tracked languages? \gls{AnyTrackedLanguages}\marg{Yes}\marg{No}. \end{codebox} This produces: \begin{resultbox} Language: fr. Territory: BE. Codeset: utf8. Modifier: euro. Any tracked languages? No. \end{resultbox} Compare this with: \begin{codebox} \gls{input} tracklang \codepar \cmd{def}\gls{TrackLangEnv}\marg{fr\idx{hyphensep}BE\idx{dotsep}utf8\idx{atmod}euro} \codepar \gls{TrackLangFromEnv} \codepar Language: \gls{TrackLangEnvLang}. Territory: \gls{TrackLangEnvTerritory}. Codeset: \gls{TrackLangEnvCodeSet}. Modifier: \gls{TrackLangEnvModifier}. Any tracked languages? \gls{AnyTrackedLanguages}\marg{Yes}\marg{No}. Tracked dialect(s):\comment{} \gls{ForEachTrackedDialect}\marg{\cmd{thisdialect}}\marg{\cmd{space}\cmd{thisdialect}}. \end{codebox} This produces: \begin{resultbox} Language: fr. Territory: BE. Codeset: utf8. Modifier: euro. Any tracked languages? Yes. Tracked dialect(s): belgique. \end{resultbox} If \gls{TrackLangFromEnv} doesn't recognise the given language and territory combination, it will define a new dialect and add that. For example, \sty{tracklang} doesn't recognise \code{en-BE}, so the sample document below defines a new dialect labelled \code{enBEeuro}: \begin{codebox} \gls{input} tracklang \codepar \cmd{def}\gls{TrackLangEnv}\marg{en\idx{hyphensep}BE\idx{dotsep}utf8\idx{atmod}euro} \codepar \gls{TrackLangFromEnv} \codepar Language: \gls{TrackLangEnvLang}. Territory: \gls{TrackLangEnvTerritory}. Codeset: \gls{TrackLangEnvCodeSet}. Modifier: \gls{TrackLangEnvModifier}. Any tracked languages? \gls{AnyTrackedLanguages}\marg{Yes}\marg{No}. Tracked dialect(s):\comment{} \gls{ForEachTrackedDialect}\marg{\cmd{thisdialect}}\marg{\cmd{space}\cmd{thisdialect}}. \end{codebox} This now produces: \begin{resultbox} Language: en. Territory: BE. Codeset: utf8. Modifier: euro. Any tracked languages? Yes. Tracked dialect(s): enBEeuro. \end{resultbox} \chapter{Supplementary Packages} \label{sec:supplpkgs} In addition to the main \file{tracklang.tex} file and \file{tracklang.sty} \LaTeX\ wrapper, the \sty{tracklang} package also provides supplementary files for region and script mappings. \filedef{tracklang-region-codes.tex} This file is only loaded if a mapping is required between numeric and alphabetic \idx{region} codes. If \gls{TrackLanguageTag} encounters a numeric \idx{region} code, it will automatically input \file{tracklang-region-codes.tex}, if it hasn't already been input. This file provides the following commands. \cmddef{TrackLangAlphaIIToNumericRegion} Expands to the numeric code corresponding to the given alpha-2 code or empty if no mapping has been supplied. \cmddef{TrackLangNumericToAlphaIIRegion} Expands to the alpha-2 code corresponding to the given numeric code or empty if no mapping has been supplied. \cmddef{TrackLangIfKnownAlphaIIRegion} Expands to \meta{true} if there's an alpha-2 to numeric \idx{region} code mapping, otherwise expands to \meta{false}. \cmddef{TrackLangIfKnownNumericRegion} Expands to \meta{true} if there's a numeric to alpha-2 \idx{region} code mapping, otherwise expands to \meta{false}. \cmddef{TrackLangAlphaIIIToNumericRegion} Expands to the numeric code corresponding to the given alpha-3 code or empty if no mapping has been supplied. \cmddef{TrackLangNumericToAlphaIIIRegion} Expands to the alpha-3 code corresponding to the given numeric code or empty if no mapping has been supplied. \cmddef{TrackLangIfKnownAlphaIIIRegion} Expands to \meta{true} if there's an alpha-3 to numeric \idx{region} code mapping, otherwise expands to \meta{false}. Mappings are established with: \cmddef{TrackLangRegionMap} Predefined mappings are listed in \tableref{tab:regionmappings}. When \file{tracklang-region-codes.tex} is input, it can load additional files that provide supplementary mappings. \cmddef{TrackLangAddExtraRegionFile} This command adds the supplied \meta{file} to the list of extra region code files that should be input by \file{tracklang-region-codes.tex}, unless \file{tracklang-region-codes.tex} has already been input, in which case \meta{file} will be input straight away. \filedef{tracklang-scripts.tex} The \sty{tracklang-scripts} package provides information about \idxn{15924} scripts. The file isn't automatically loaded. If you want to use any of the commands provided in it you need to input it. Plain \TeX: \begin{codebox} \gls{input} tracklang-scripts \end{codebox} There's a simple wrapper package \file{tracklang-scripts.sty} for \LaTeX\ users: \begin{codebox} \cmd{usepackage}\marg{tracklang-scripts} \end{codebox} \cmddef{TrackLangScriptMap} Defines a mapping. The first argument is the four letter alpha code, such as \opt{Latn} or \opt{Cyrl}. The second argument is the numeric code. The third argument is the script's name, for example \qt{Imperial Aramaic}. The fourth argument is the direction, which may be one of: \optfmt{LR} (left-to-right), \optfmt{RL} (right-to-left), \optfmt{TB} (top-to-bottom), \optfmt{varies} or \optfmt{inherited}. The \meta{parent} argument is for the parent writing system, which may be left blank (currently unsupported). This command defines: \cmddef{TrackLangScriptCode} which expands to \meta{Code} for use with \gls{IfTrackedDialectIsScriptCs}. See \tableref{tab:scriptmappings} for a summary of all the mappings that are provided by the file \file{tracklang-scripts.tex}. \cmddef{TrackLangScriptAlphaToNumeric} Expands to the numeric code corresponding to the given alpha code or empty if no mapping. \cmddef{TrackLangScriptIfKnownAlpha} Expands to \meta{true} if there is a known alpha to numeric mapping or \meta{false} otherwise. \cmddef{TrackLangScriptNumericToAlpha} Expands to the alpha code corresponding to the given numeric code or empty if no mapping. \cmddef{TrackLangScriptIfKnownNumeric} Expands to \meta{true} if there is a known numeric to alpha mapping or \meta{false} otherwise. \cmddef{TrackLangScriptAlphaToName} Expands to the name corresponding to the given alpha code or empty if no mapping. \cmddef{TrackLangScriptAlphaToDir} Expands to the direction corresponding to the given alpha code or empty if no mapping. \cmddef{TrackLangScriptSetParent} Sets the parent for the given alpha code. \cmddef{TrackLangScriptGetParent} Expands to the parent for the given alpha code or empty if no mapping. \cmddef{TrackLangScriptIfHasParent} Expands to \meta{true} if the given alpha code has a parent or to \meta{false} otherwise. Note that if a parent is explicitly set to empty with \gls{TrackLangScriptSetParent} then it will be considered defined, but if the \meta{parent} argument was empty in \gls{TrackLangScriptMap}, then it will be undefined. \cmddef{TrackLangAddExtraScriptFile} This command adds \meta{file} to the list of extra script files that should be input by \file{tracklang-scripts.tex}, unless \file{tracklang-scripts.tex} has already been input, in which case \meta{file} will be input straight away. \chapter{Detecting the User's Requested Languages} \label{sec:user} The \sty{tracklang} package tries to track the loaded languages and the option names used to identify those languages. For want of a better term, the language option names are referred to as dialects even if they're only a synonym for the language rather than an actual dialect. For example, if the user has requested \opt{british}, the \emph{root language} label is \opt{english} and the dialect is \opt{british}, whereas if the user requested \opt{UKenglish}, the root language label is \opt{english} and the dialect is \opt{UKenglish}. The exceptions to this are the \sty{tracklang} package options that have been specified in the form \meta{iso lang}-\meta{iso country} (listed in \tableref{tab:rootlangopts}). For example, the package option \iso{british} behaves as though the user requested the package option \opt{british}. If \gls{TrackLocale} or \gls{TrackLangFromEnv} are used and the locale isn't recognised a new dialect is created with the label formed from the \idx{ISO} codes (and \idx{modifier}, if present). Similarly for \gls{TrackLanguageTag} a new dialect is created with a label that's essentially the language tag without the hyphen separators. For example, \begin{codebox} \gls{TrackLocale}\marg{xx\idx{hyphensep}YY} \end{codebox} will add a new dialect with the label \code{xxYY}, \begin{codebox} \gls{TrackLocale}\marg{xx\idx{hyphensep}YY\idx{atmod}mod} \end{codebox} will add a new dialect with the label \code{xxYYmod} and \begin{codebox} \gls{TrackLanguageTag}\marg{xx-Latn-YY} \end{codebox} will add a new dialect with the label \code{xxLatnYY}. \begin{important} If \gls{TrackLocale} or \gls{TrackLangFromEnv} find a \idx{modifier}, the value will be sanitized to allow it to be used as a label. If the modifier is set explicitly using \gls{SetTrackedDialectModifier}, no sanitization is performed. \end{important} In addition to the root language label and the dialect identifier, many of the language options also have corresponding \idx{ISO} codes. In most cases there is an \idxn{639-1} or an \idxn{639-2} code (or both), and in some cases there is an \idxn{3166-1} code identifying the dialect \idx{region}. Where a language has different \idxn{639-2T} and \idx{639-2B} codes, the \qt{T} version is assumed. When the \file{tracklang.sty} \LaTeX\ package is loaded, it first attempts to find the language options through the package options supplied to \sty{tracklang}. This means that any languages that have been supplied in the document class options should get identified (provided that the document class has used the standard option declaration mechanism). If no languages have been supplied in this way, \file{tracklang.sty} then attempts to identify language settings in the following order: \begin{enumerate} \item if \gls{bbl@loaded} is defined (\sty{babel}), \sty{tracklang} will iterate over each label in that command definition; \item if \gls{trans@languages} is defined (\sty{translator}), \sty{tracklang} will iterate over each label in that command definition; \item if \sty{ngerman} has been loaded, the \opt{ngerman} dialect will be tracked; \item if \sty{german} has been loaded, the \opt{german} root language will be tracked; \item if \sty{polyglossia} has been loaded: \begin{enumerate} \item if \gls{xpg@bcp@loaded} has been defined, \sty{tracklang} will iterate over the \idx{BCP47} tags in that command definition; \item if \gls{xpg@loaded} has been defined, \sty{tracklang} will iterate over each language label in that command definition; \item \sty{tracklang} will iterate over all \sty{tracklang} options and test if the root language has been loaded. \end{enumerate} \end{enumerate} Note that this references internal commands provided by other packages. Of these, only the \sty{polyglossia} commands are documented in the package manual, and so are the only ones that can be relied on. Each identified language and dialect is added to the \emph{tracked language} and \emph{tracked dialect} lists. Note that the tracked language and tracked dialect are labels rather than proper nouns. If a~dialect label is identical to its root language label, the label will appear in both lists. You can check whether or not any languages have been detected using: \cmddef{AnyTrackedLanguages} This will do \meta{true} if one or more languages have been tracked otherwise it will do \meta{false}. (Each detected dialect will automatically have the root language label added to the tracked language list, if it's not already present.) If you want to find out if any of the tracked dialects matches a particular language tag, you can use: \cmddef{GetTrackedDialectFromLanguageTag} If successful, the supplied control sequence \meta{cs} is set to the dialect label, otherwise \meta{cs} is set to empty. The test is for an exact match on the root language, \idx{script}, sub-language, \idx{variant} and \idx{region}. The control sequence \meta{cs} will be empty if none of the tracked dialects matches all five of those elements. (If the script isn't given explicitly, the default for that language is assumed.) In the event that \meta{cs} is empty, you can now (as from v1.3.6) get the closest match with: \cmddef{TrackedDialectClosestSubMatch} (which is set by \gls{GetTrackedDialectFromLanguageTag}). This will be empty if no tracked dialects match on the root language or if there's a tracked dialect label that exactly matches the label formed by concatenating the language code, sub-language, \idx{script}, \idx{region}, \idx{modifier} and \idx{variant}. For example (Plain \TeX): \begin{codebox} \gls{input} tracklang \gls{TrackLanguageTag}\marg{en-826} Has en-Latn-GB been tracked? \gls{GetTrackedDialectFromLanguageTag}\marg{en-Latn-GB}\marg{\cmd{thisdialect}}\comment{} \cmd{ifx}\cmd{thisdialect}\cmd{empty} No! \cmd{else} Yes! Dialect label: \cmd{thisdialect}. \cmd{fi} \cmd{bye} \end{codebox} This matches because the \idx{territory} code \numericcode{GB} is recognised as equivalent to the code \opt{GB}, and the default \idx{script} for \opt{english} is \opt{Latn}. In this case, the dialect label is \opt{british}. Note that this doesn't require the use of \gls{TrackLanguageTag} to track the dialect. It also works if the dialect has been tracked using other commands, such as \gls{TrackLocale}. Here's an example that doesn't have an exact match, but does have a partial match: \begin{codebox} \gls{input} tracklang \gls{TrackLanguageTag}\marg{de-CH-1996} Has de-DE-1996 been tracked? \gls{GetTrackedDialectFromLanguageTag}\marg{de-DE-1996}\marg{\cmd{thisdialect}}\comment{} \cmd{ifx}\cmd{thisdialect}\cmd{empty} No! \cmd{ifx}\gls{TrackedDialectClosestSubMatch}\cmd{empty} No match on root language. \cmd{else} Closest match: \gls{TrackedDialectClosestSubMatch}. \cmd{fi} \cmd{else} Yes! Dialect label: \cmd{thisdialect}. \cmd{fi} \cmd{bye} \end{codebox} In this case the result is: \begin{resultbox} Has de-DE-1996 been tracked? No! Closest match: nswissgerman. \end{resultbox} You can iterate through each tracked dialect using: \cmddef{ForEachTrackedDialect} At the start of each iteration, this sets the control sequence \meta{cs} to the tracked dialect and does \meta{body}. You can iterate through each tracked language using: \cmddef{ForEachTrackedLanguage} At the start of each iteration, this sets the control sequence \meta{cs} to the tracked language and does \meta{body}. The above for-loops use the same internal mechanism as \LaTeX's \gls{@for} loop. Since this isn't defined by \TeX, a similar command (\inlineglsdef{@tracklang@for}) will be defined that works in the same way. The provided control sequence \meta{cs} is updated at the start of each iteration to the current element. The loop is terminated when this control sequence is set to \gls{@nil}. This special control sequence should never been used as it's just a marker and isn't actually defined. If you get an error message stating that \gls{@nil} is undefined, then it's most likely due to a loop control sequence being used outside the loop. This can occur if the loop contains code that isn't expanded until later. For example, if the loop code includes \gls{AtBeginDocument}, you need to ensure that the loop control sequence is expanded before being added to the hook. You can test if a root language has been detected using: \cmddef{IfTrackedLanguage} where \meta{language-label} is the language label. If true, this does \meta{true} otherwise it does \meta{false}. You can test if a particular dialect has been detected using: \cmddef{IfTrackedDialect} where \meta{dialect-label} is the dialect label. If the root language was explicitly specified, then it will also be detected as a dialect. For example: \begin{codebox} \cmd{documentclass}[\opt{british},\opt{dutch}]\marg{article} \codepar \cmd{usepackage}\marg{tracklang} \codepar \cbeg{document} ``english'' \gls{IfTrackedDialect}\marg{english}\marg{has}\marg{hasn't} been specified. \codepar ``british'' \gls{IfTrackedDialect}\marg{british}\marg{has}\marg{hasn't} been specified. \codepar ``flemish'' \gls{IfTrackedDialect}\marg{flemish}\marg{has}\marg{hasn't} been specified. \codepar ``dutch'' \gls{IfTrackedDialect}\marg{dutch}\marg{has}\marg{hasn't} been specified. \codepar ``english'' or an English variant \gls{IfTrackedLanguage}\marg{english}\marg{has}\marg{hasn't} been specified. \cend{document} \end{codebox} This produces: \begin{resultbox} ``english'' hasn't been specified. ``british'' has been specified. ``flemish'' hasn't been specified. ``dutch'' has been specified. ``english'' or an English variant has been specified. \end{resultbox} You can find the root language label for a given tracked dialect using: \cmddef{TrackedLanguageFromDialect} If \meta{dialect} hasn't been defined this does nothing otherwise it expands to the root language label. You can find the tracked dialects from a given root language using: \cmddef{TrackedDialectsFromLanguage} This will expand to a~comma-separated list of dialect labels if the root language label has been defined, otherwise it does nothing. You can test if a language or dialect has a corresponding \idx+{ISO} code using: \cmddef{IfTrackedLanguageHasIsoCode} where \meta{code type} is the type of \idx{ISO} code (for example, \idx{639-1} for root languages or \idx{3166-1} for regional dialects), and \meta{label} is the language or dialect label. Note that the \idx{639-3} may be set for the dialect rather than root language for sub-languages parsed using \gls{TrackLanguageTag}. Alternatively, you can test if a particular \idx{ISO} code has been defined using: \cmddef{IfTrackedIsoCode} where \meta{code type} is again the type of \idx{ISO} code (for example, \idx{639-1} or \idx{3166-1}), and \meta{code} is the particular code (for example, \opt{en} for \idxn{639-1} or \opt{GB} for \idxn{3166-1}). You can fetch the language (or dialect) label associated with a given \idx{ISO} code using: \cmddef{TrackedLanguageFromIsoCode} This does nothing if the given \meta{code} for the given \idx{ISO} \meta{code type} has not been defined, otherwise it expands a~comma-separated list of language or dialect labels. You can fetch the \idx{ISO} code for a given code type using: \cmddef{TrackedIsoCodeFromLanguage} where \meta{label} is the language or dialect label and \meta{code type} is the \idx{ISO} code type (for example, \idx{639-1} or \idx{3166-1}). Unlike \gls{TrackedLanguageFromIsoCode}, this command only expands to a single label rather than a~comma-separated list. The above commands do nothing in the event of an unknown code or code type, so if you accidentally get the wrong code type, you won't get an error. If you're unsure of the code type, you can use the following commands: \cmddef{TwoLetterIsoCountryCode} This expands to \idx{3166-1} and is used for the two-letter country codes. \cmddef{TwoLetterIsoLanguageCode} This expands to \idx{639-1} and is used for the two-letter root language codes. \cmddef{ThreeLetterIsoLanguageCode} This expands to \idx{639-2} and is used for the three-letter root language codes. \cmddef{ThreeLetterExtIsoLanguageCode} This expands to \idx{639-3}. This code is only used for a root language if there's no \idx{639-1} or \idx{639-2} code. It may also be used for a dialect if a sub-language part has been set in the language tag parsed by \gls{TrackLanguageTag}. The \cmd{Get\ldots} commands below are designed to be expandable. If the supplied \meta{dialect} is unrecognised they expand to empty. Remember that the dialect must first be identified as a tracked language for it to be recognised. As from v1.3, the language tag for a given dialect can be obtained using: \cmddef{GetTrackedLanguageTag} where \meta{dialect} is the label identifying the dialect. Uses the \opt{und} (undetermined) code for unknown languages. As from v1.3, each tracked dialect may also have an associated modifier, which can be fetched using: \cmddef{GetTrackedDialectModifier} where \meta{dialect} is the label identifying the dialect. This value is typically obtained by parsing a \idx{POSIX} locale identifier with \gls{TrackLocale} or \gls{TrackLangFromEnv} but may be set explicitly. (See \sectionref{sec:langsty} for setting this value. Likewise for the following commands.) You can test if a dialect has an associated \idx{modifier} using: \cmddef{IfHasTrackedDialectModifier} If the dialect has an associated \idx{modifier} this does \meta{true} otherwise it does \meta{false}. For example: \begin{codebox} \cmd{documentclass}[\opt{british},\opt{francais},\opt{american},\opt{canadian},\opt{canadien},\opt{dutch}]\marg{article} \codepar \cmd{usepackage}\marg{tracklang} \codepar \cbeg{document} Languages: \gls{ForEachTrackedLanguage}\marg{\cmd{ThisLanguage}}\marg{\cmd{ThisLanguage}\cmd{space} (ISO \gls{TwoLetterIsoLanguageCode}: ``\gls{TrackedIsoCodeFromLanguage}\marg{\gls{TwoLetterIsoLanguageCode}}\marg{\cmd{ThisLanguage}}''). } \codepar Dialects: \gls{ForEachTrackedDialect}\marg{\cmd{ThisDialect}}\marg{\cmd{ThisDialect}\cmd{space} (\gls{IfTrackedLanguageHasIsoCode}\marg{\gls{TwoLetterIsoCountryCode}}\marg{\cmd{ThisDialect}}\comment{} \marg{ISO \gls{TwoLetterIsoCountryCode}: ``\gls{TrackedIsoCodeFromLanguage}\marg{\gls{TwoLetterIsoCountryCode}}\marg{\cmd{ThisDialect}}''}% \marg{no specific region}; root: \gls{TrackedLanguageFromDialect}\marg{\cmd{ThisDialect}}). } \codepar Language for ISO \gls{TwoLetterIsoCountryCode}\cmd{ }``GB'': \gls{TrackedLanguageFromIsoCode}\marg{\gls{TwoLetterIsoCountryCode}}\marg{GB}. \codepar Language for ISO \gls{TwoLetterIsoCountryCode}\cmd{ }``CA'': \gls{TrackedLanguageFromIsoCode}\marg{\gls{TwoLetterIsoCountryCode}}\marg{CA}. \codepar Country ISO \gls{TwoLetterIsoCountryCode}\cmd{ }code for ``canadian'': \gls{TrackedIsoCodeFromLanguage}\marg{\gls{TwoLetterIsoCountryCode}}\marg{canadian}. \cend{document} \end{codebox} This produces: \begin{resultbox} Languages: english (ISO 639-1: ``en''). french (ISO 639-1: ``fr''). dutch (ISO 639-1: ``nl''). Dialects: american (ISO 3166-1: ``US''; root: english). british (ISO 3166-1: ``GB''; root: english). canadian (ISO 3166-1: ``CA''; root: english). canadien (ISO 3166-1: ``CA''; root: french). dutch (no specific region; root: dutch). francais (no specific region; root: french). Language for ISO 3166-1 ``GB'': british. Language for ISO 3166-1 ``CA'': canadian,canadien. Country ISO 3166-1 code for ``canadian'': CA. \end{resultbox} As from v1.3, each tracked dialect may also have an associated variant, which can be fetched using: \cmddef{GetTrackedDialectVariant} where \meta{dialect} is the label identifying the dialect. This value is typically obtained by parsing a language tag with \gls{TrackLanguageTag} but may be set explicitly. You can test if a dialect has an associated variant using: \cmddef{IfHasTrackedDialectVariant} As from v1.3, each tracked dialect may also have an associated script, which can be fetched using: \cmddef{GetTrackedDialectScript} where \meta{dialect} is the label identifying the dialect. You can test if a dialect has an associated script using: \cmddef{IfHasTrackedDialectScript} If the dialect has an associated script this does \meta{true} otherwise it does \meta{false}. This information is provided for language packages that need to know what script is required, but there's no guarantee that the script will actually be set in the document. Similarly for all the other attributes described here. Note that the script should be a recognised four-letter \idxn{15924} code, such as \opt{Latn} or \opt{Cyrl}. If a~dialect doesn't have an associated script then the default for the root language should be assumed. For example, \opt{Latn} for English dialects or \opt{Cyrl} for Russian dialects. The default script for known languages can be obtained using: \cmddef{TrackLangGetDefaultScript} Most root languages have a default script, but there are a few without one as it may depend on region, politics or ideology. There's a convenient expandable command for testing the script: \cmddef{IfTrackedDialectIsScriptCs} This tests if the given tracked dialect has an associated script and compares the value with the replacement text of \meta{cs}. If the dialect hasn't been explicitly assigned a script, then test is performed against the default script for the root language. The supplementary package \sty{tracklang-scripts} provides some additional commands relating to writing systems, including commands in the form \gls{TrackLangScriptCode} where \meta{Code} is the \idxn{15924} four-letter code. If the dialect doesn't have an associated script, \meta{false} is done. This package isn't loaded automatically, so you'll need to explicitly load it. The generic code is in \file{tracklang-scripts.tex}: \begin{codebox} \gls{input} tracklang-scripts \end{codebox} There's a convenient \LaTeX\ wrapper \file{tracklang-scripts.sty}: \begin{codebox} \cmd{usepackage}\marg{tracklang-scripts} \end{codebox} See \sectionref{sec:supplpkgs} for further details of that package. For example, the following defines a command to check if the given dialect should use a Latin \idx{script}: \begin{codebox} \gls{input} tracklang-scripts \cmd{def}\cmd{islatin}\#1\#2\#3\marg{\comment{} \gls{IfTrackedDialectIsScriptCs}\marg{\#1}\marg{\tklscript{Latn}}\marg{\#2}\marg{\#3}\comment{} } \end{codebox} \begin{important} Note that the \idx{script} value doesn't mean that the document is actually using that script. It means that this is the user's \emph{desired} script, but whether that \idx{script} is actually set relies on the appropriate settings in the relevant language package (such as \sty{polyglossia}['s] \optfmt{script} key). \end{important} As from v1.3, each tracked dialect may also have a sub-language identifier (for example, \optfmt{arevela}), which can be fetched using: \cmddef{GetTrackedDialectSubLang} where \meta{dialect} is the label identifying the dialect. You can test if a dialect has an associated sub-tag using: \cmddef{IfHasTrackedDialectSubLang} If the dialect has an associated sub-tag this does \meta{true} otherwise it does \meta{false}. As from v1.3, each tracked dialect may also have additional information, which can be fetched using: \cmddef{GetTrackedDialectAdditional} where \meta{dialect} is the label identifying the dialect. You can test if a dialect has additional information using: \cmddef{IfHasTrackedDialectAdditional} If the dialect has additional information this does \meta{true} otherwise it does \meta{false}. Most packages that implement multilingual support have a~set of language definition files for each supported language or dialect. It may be that only the root language is needed, if there are no variations between that language's dialect (for the purposes of that package), or it may be that separate definition files are required for each dialect. However it can be awkward trying to map the requested dialect or language label to the file name. Should, say, the file containing the French code be called \metametafilefmt{}{prefix}{\dhyphen french\dhyphen }{suffix}{} or \metametafilefmt{}{prefix}{\dhyphen frenchb\dhyphen }{suffix}{} or \metametafilefmt{}{prefix}{\dhyphen francais\dhyphen}{suffix}{}? Should, say, the file containing the British English code be called \metametafilefmt{}{prefix}{\dhyphen british\dhyphen }{suffix}{} or \metametafilefmt{}{prefix}{\dhyphen UKenglish\dhyphen }{suffix}{}? If you want to modularise the language support for your package so that each language module has a different maintainer will the maintainers know what tag to use for their language? \label{pg:filesearch}To help with this, \sty{tracklang} provides: \cmddef{IfTrackedLanguageFileExists} This attempts to find the file called \meta{prefix}\meta{localeid}\meta{suffix} where \meta{localeid} is determined from \meta{dialect} (see below). If the file is found then \cmddef{CurrentTrackedTag} is set to \meta{localeid} and \meta{true code} is done, otherwise \meta{false code} is done. If this command is empty, then the dialect hasn't been detected. If the dialect has been detected, but no file can be found, then \gls{CurrentTrackedTag} is set to the final attempt at determining \meta{localeid}. There's a convenient shortcut command new to version 1.3: \cmddef{TrackLangRequireDialect} which uses \gls{IfTrackedLanguageFileExists} to input the resource file if found. The prefix is given by \meta{pkgname}\code{-} and the suffix is \code{.\ext+{ldf}}. A warning is issued if no resource file is found. Note that while it makes sense for \meta{pkgname} to be the same as the base name of the package that uses these resource files, they don't have to be the same. This command additionally defines: \cmddef{TrackLangRequireDialectPrefix} to \meta{pkgname}, which allows the prefix to be picked up by resource file commands, such as \gls{TrackLangProvidesResource} and \gls{TrackLangRequireResource}. (See below.) The optional argument \meta{load code} is the code that actually inputs the required file. This defaults to \begin{codebox} \gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedTag}} \end{codebox} The \gls{IfTrackedLanguageFileExists} command sets up the current tracked dialect with: \begin{compactcodebox*} \gls{SetCurrentTrackedDialect}\marg{dialect} \end{compactcodebox*} which enables the following commands that may be used within \meta{true code} or \meta{false code}: \cmddef{CurrentTrackedDialect} Expands to the dialect label. \cmddef{CurrentTrackedLanguage} If the dialect hasn't been detected, this command will be empty, otherwise it will expand to the root language label (which may be the same as the dialect label). \cmddef{CurrentTrackedRegion} If the dialect hasn't been detected, this command will be empty. If the dialect has been assigned an \idxn{3166-1} code, \gls{CurrentTrackedRegion} will expand to that code, otherwise it will be empty. \cmddef{CurrentTrackedIsoCode} If the dialect hasn't been detected, this command will be empty. Otherwise it may be empty or it may expand to the \idxn{639-1} or \idxn{639-2} or \idxn{639-3} code. \cmddef{CurrentTrackedDialectModifier} The dialect's modifier or empty if not set. (This is set but not used in the set of possible \meta{localeid} values.) \cmddef{CurrentTrackedDialectVariant} The dialect's variant or empty if not set. \cmddef{CurrentTrackedDialectSubLang} The dialect's sub-language code or empty if not set. \cmddef{CurrentTrackedDialectAdditional} The dialect's additional information or empty if not set. \cmddef{CurrentTrackedLanguageTag} The dialect's language tag. Take care not to confuse this with \gls{CurrentTrackedTag}. \cmddef{CurrentTrackedDialectScript} The dialect's script. If the dialect doesn't have the script set, the default script for the language is used instead. \gls{IfTrackedLanguageFileExists} behaves as follows: \begin{itemize} \item If no dialect with the given label has been detected, the condition evaluates to \emph{false} and \gls{CurrentTrackedTag} is empty. \item If a dialect with the given label has been detected, then: \begin{itemize} \item For each possible \meta{localeid} in an ordered set of tags determined by the dialect label (see below), the first file matching \meta{prefix}\meta{localeid}\meta{suffix} that's found on \TeX's path results in the condition evaluating to \emph{true} and \gls{CurrentTrackedTag} is set to the current \meta{localeid} in the set. The rest of the set of possible values of \meta{localeid} is skipped. \item If no file matching \meta{prefix}\meta{localeid}\meta{suffix} is found on \TeX's path, then the condition evaluates to \emph{false} and \gls{CurrentTrackedTag} is set to the final \meta{localeid} in the set (the language label). \end{itemize} \end{itemize} The ordered set of possible values of \meta{localeid} is determined from the given dialect. \begin{important} The ordering has changed in version 1.4, which now also includes the \idx{script} and \idx{variant}. This new ordering should typically make the more common combinations closer to the start of the search. \end{important} The possible values of \meta{localeid} are listed below in the order of priority used by \gls{IfTrackedLanguageFileExists}. Note that the set may contain repetitions (for example, if the dialect label is the same as the root language label). If an item contains an element that hasn't been set (such as the \idxn{639-3} code or a sub-language \meta{sublang} or \idx{variant}) then that item is skipped. \begin{enumerate} \item \meta{localeid} is just the value of \gls{CurrentTrackedLanguageTag}. \item \meta{localeid} is just the dialect label. \item \meta{localeid} is \meta{ISO~639-1}\code{-}\meta{sublang}\code{-}\meta{script}\code{-}\meta{region}. \item \meta{localeid} is \meta{ISO~639-1}\code{-}\meta{script}\code{-}\meta{region}. \item \meta{localeid} is \meta{ISO~639-1}\code{-}\meta{sublang}\code{-}\meta{region} (if there's no script or if the script is the default for the given language). \meta{ISO~639-1}\code{-}\meta{region} (if there's no script or if the script is the default for the given language). \item \meta{localeid} is \meta{ISO~639-1}\code{-}\meta{sublang}\code{-}\meta{script}. \item \meta{localeid} is \meta{ISO~639-1}\code{-}\meta{script}. \item \meta{localeid} is \meta{ISO~639-1}\code{-}\meta{sublang}. \item \meta{localeid} is just \meta{ISO~639-1}. \item \meta{localeid} is \meta{ISO~639-2}\code{-}\meta{sublang}\code{-}\meta{script}\code{-}\meta{region}. \item \meta{localeid} is \meta{ISO~639-2}\code{-}\meta{script}\code{-}\meta{region}. \item \meta{localeid} is \meta{ISO~639-2}\code{-}\meta{sublang}\code{-}\code{region} (if there's no script or if the script is the default for the given language). \meta{ISO~639-2}\code{-}\meta{region} (if there's no script or if the script is the default for the given language). \item \meta{localeid} is \meta{ISO~639-2}\code{-}\meta{sublang}\code{-}\meta{script}. \item \meta{localeid} is \meta{ISO~639-2}\code{-}\meta{script}. \item \meta{localeid} is \meta{ISO~639-2}\code{-}\meta{sublang}. \item \meta{localeid} is just \meta{ISO~639-2}. \item \meta{localeid} is \meta{ISO~639-3}\code{-}\meta{sublang}\code{-}\meta{script}\code{-}\meta{region}. \item \meta{localeid} is \meta{ISO~639-3}\code{-}\meta{script}\code{-}\meta{region}. \item \meta{localeid} is \meta{ISO~639-3}\code{-}\meta{sublang}\code{-}\meta{region} (if there's no script or if the script is the default for the given language). \meta{ISO~639-3}\code{-}\meta{region} (if there's no script or if the script is the default for the given language). \item \meta{localeid} is \meta{ISO~639-3}\code{-}\meta{sublang}\code{-}\meta{script}. \item \meta{localeid} is \meta{ISO~639-3}\code{-}\meta{script}. \item \meta{localeid} is \meta{ISO~639-3}\code{-}\meta{sublang}. \item \meta{localeid} is just \meta{ISO~639-3}. \item \meta{localeid} is just \meta{region}. \item \meta{localeid} is \meta{ISO~639-1}\code{-}\meta{sublang}\code{-}\meta{variant} or \meta{ISO~639-1}\code{-}\meta{variant} if \meta{sublang} is missing. \item \meta{localeid} is \meta{ISO~639-2}\code{-}\meta{sublang}\code{-}\meta{variant} or \meta{ISO~639-2}\code{-}\meta{variant} if \meta{sublang} is missing. \item \meta{localeid} is \meta{ISO~639-3}\code{-}\meta{sublang}\code{-}\meta{variant} or \meta{ISO~639-3}\code{-}\meta{variant} if \meta{sublang} is missing. \item \meta{localeid} is just the value of \gls{CurrentTrackedLanguage} (the root language label). \end{enumerate} For example (pre v1.3): \begin{codebox} \gls{AnyTrackedLanguages} \marg{\comment{} \gls{ForEachTrackedDialect}\marg{\cmd{ThisDialect}}\comment{} \marg{\comment{try to load the language file for this dialect} \gls{IfTrackedLanguageFileExists}\marg{\cmd{ThisDialect}}\comment{} \marg{mypackage-}\comment{file prefix} \marg{.ldf}\comment{file suffix} \marg{\gls{input} mypackage-\gls{CurrentTrackedTag}.ldf}\comment{file found} \marg{\comment{file not found} \cmd{PackageWarning}\marg{mypackage}\marg{No support for language `\cmd{ThisDialect}'}\comment{} }\comment{} }\comment{} } \marg{\comment{no languages detected so use defaults} } \end{codebox} With version 1.3 onwards, this can be written more concisely as: \begin{codebox} \gls{AnyTrackedLanguages} \marg{\comment{} \gls{ForEachTrackedDialect}\marg{\cmd{ThisDialect}}\comment{} \marg{\comment{try to load the language file for this dialect} \gls{TrackLangRequireDialect}\marg{mypackage}\marg{\cmd{ThisDialect}}\comment{} }\comment{} } \marg{\comment{no languages detected so use defaults} } \end{codebox} which additionally enables the \sty{tracklang} version 1.3 commands described below, such as \gls{TrackLangRequireResource}. \plabel{pg.britishfilesearch}% If, for example, \cmd{ThisDialect} is \opt{british}, then the file search will be in the order: \begin{enumerate} \item \ldf{mypackage}{en-GB} (language tag) \item \ldf{mypackage}{british} (dialect label) \item \ldf{mypackage}{en-Latn-GB} (\idx{639-1} language code, \idx{script}, \idx{region}) \item \ldf{mypackage}{en-GB} (\idx{639-1} language code, \idx{region}) \item \ldf{mypackage}{en-Latn} (\idx{639-1} language code, \idx{script}) \item \ldf{mypackage}{en} (\idx{639-1} language code) \item \ldf{mypackage}{eng-Latn-GB} (\idx{639-2} language code, \idx{script}, \idx{region}) \item \ldf{mypackage}{eng-GB} (\idx{639-2} language code, \idx{region}) \item \ldf{mypackage}{eng-Latn} (\idx{639-2} language code, \idx{script}) \item \ldf{mypackage}{eng} (\idx{639-2} language code) \item \ldf{mypackage}{GB} (\idx{region}) \item \ldf{mypackage}{english} (language label) \end{enumerate} If, for example, \cmd{ThisDialect} is \opt{naustrian}, then the file search will be in the order: \begin{enumerate} \item \ldf{mypackage}{de-AT-1996} (language tag) \item \ldf{mypackage}{naustrian} (dialect label) \item \ldf{mypackage}{de-Latn-AT} (\idx{639-1} language code, \idx{script}, \idx{region}) \item \ldf{mypackage}{de-AT} (\idx{639-1} language code, \idx{region}) \item \ldf{mypackage}{de-Latn} (\idx{639-1} language code, \idx{script}) \item \ldf{mypackage}{de} (\idx{639-1} language code) \item \ldf{mypackage}{deu-Latn-AT} (\idx{639-2} language code, \idx{script}, \idx{region}) \item \ldf{mypackage}{deu-AT} (\idx{639-2} language code, \idx{region}) \item \ldf{mypackage}{deu-Latn} (\idx{639-2} language code, \idx{script}) \item \ldf{mypackage}{deu} (\idx{639-2} language code) \item \ldf{mypackage}{AT} (\idx{region}) \item \ldf{mypackage}{de-1996} (\idx{639-1} language code, \idx{variant}) \item \ldf{mypackage}{deu-1996} (\idx{639-2} language code, \idx{variant}) \item \ldf{mypackage}{german} (language label) \end{enumerate} If, for example, \cmd{ThisDialect} is \opt{francais}, then the file search will be in the order: \begin{enumerate} \item \ldf{mypackage}{fr} (language tag) \item \ldf{mypackage}{francais} (dialect label) \item \ldf{mypackage}{fr-Latn} (\idx{639-1} language code, \idx{script}) \item \ldf{mypackage}{fr} (\idx{639-1} language code) \item \ldf{mypackage}{fra-Latn} (\idx{639-2} language code, \idx{script}) \item \ldf{mypackage}{fra} (\idx{639-2} language code) \item \ldf{mypackage}{french} (language) \end{enumerate} This is because the predefined \opt{francais} option has no region assigned to it. Be careful if the dialect label is the actual root language. For example, if \cmd{ThisDialect} is \opt{french}, then the file search will be in the order: \begin{enumerate} \item \ldf{mypackage}{fr} (language tag) \item \ldf{mypackage}{french} (dialect label) \item \ldf{mypackage}{fr-Latn} (\idx{639-1} language code, \idx{script}) \item \ldf{mypackage}{fr} (\idx{639-1} language code) \item \ldf{mypackage}{fra-Latn} (\idx{639-2} language code, \idx{script}) \item \ldf{mypackage}{fra} (\idx{639-2} language code) \item \ldf{mypackage}{french} (language) \end{enumerate} Note that the last try will always fail in this case since if the file exists, it will be found on the second try. If the dialect label is identical to the root language label then it means that all associated information is the default for that language. For example, in the above case of \opt{french}, the script is \opt{Latn} and the region is unspecified. The root language label can therefore be used as the fallback in the event of no other match but for the specific case where the dialect is identical to the root language then all unnecessary file name checks can be skipped. If you're only providing support for the root languages (pre v1.3): \begin{codebox} \gls{AnyTrackedLanguages} \marg{\comment{} \gls{ForEachTrackedLanguage}\marg{\cmd{ThisLanguage}}\comment{} \marg{\comment{try to load the language file for this root language} \gls{IfTrackedLanguageFileExists}\marg{\cmd{ThisLanguage}}\comment{} \marg{mypackage-}\comment{file prefix} \marg{.ldf}\comment{file suffix} \marg{\gls{input} mypackage-\gls{CurrentTrackedTag}.ldf}\comment{file found} \marg{\comment{file not found} \cmd{PackageWarning}\marg{mypackage}\marg{No support for language `\cmd{ThisLanguage}'}\comment{} }\comment{} }\comment{} } \marg{\comment{no languages detected so use defaults} } \end{codebox} With version 1.3 onwards, this can be written more concisely as: \begin{codebox} \gls{AnyTrackedLanguages} \marg{\comment{} \gls{ForEachTrackedLanguage}\marg{\cmd{ThisLanguage}}\comment{} \marg{\comment{try to load the language file for this root language} \gls{TrackLangRequireDialect}\marg{mypackage}\marg{\cmd{ThisLanguage}}\comment{} }\comment{} } \marg{\comment{no languages detected so use defaults} } \end{codebox} which additionally enables the commands described below. Note that in this case, if more than one dialect for the same language has been tracked, only the hooks for the last dialect for that language will be adjusted, so it's usually best to iterate over the dialects. The following \cmd{TrackLang\ldots Resource\ldots} commands may only be used in resource files that are loaded using \gls{TrackLangRequireDialect}. An error will occur if the file is input through some other method. Within the resource file \localemetafile{pkgname}, you can identify the file using (new to version 1.3): \cmddef{TrackLangProvidesResource} where \meta{tag} is the locale identifier. If \gls{ProvidesFile} is defined (through the \LaTeX\ kernel) this is used, otherwise a simplified generic alternative is used that's suitable for other \TeX\ formats. The resource file can load another resource file \localemetametafile{pkgname}{tag}, using (new to version 1.3): \cmddef{TrackLangRequireResource} For example, the dialect file \ldf{foo}{en-GB} might need to load the root language resource file \ldf{foo}{english}: \begin{codebox} \comment{(In file \ldf{foo}{en-GB})} \comment{Declare this regional file:} \gls{TrackLangProvidesResource}\marg{en-GB} \comment{load root language file \ldf{foo}{english}:} \gls{TrackLangRequireResource}\marg{english} \end{codebox} If \ldf{foo}{english} is also identified with \gls{TrackLangProvidesResource}, this will ensure that it's only loaded once. It may be that you want to load a file depending on the input encoding. The \sty{inputenc} package defines \gls{inputencodingname}, but this is only used with \pdfLaTeX. To avoid repeated tests to determine whether or not \gls{inputencodingname} has been defined, you can use: \cmddef{TrackLangEncodingName} This will expand to \code{utf8} if \gls{inputencodingname} hasn't been defined, otherwise it will expand to \gls{inputencodingname}. For example: \begin{codebox} \gls{InputIfFileExists}\marg{foo-\gls{TrackLangEncodingName}.ldf} \marg{\comment{support available for the document encoding} } \marg{\comment{no support for the document encoding} } \end{codebox} If you require the resource file and want to perform \meta{code1} if it's loaded at this point or \meta{code2} if it's already been loaded then you can use: \cmddef{TrackLangRequireResourceOrDo} If you want to load a resource file if it exists (without an error if it doesn't exist), then you can use \cmddef{TrackLangRequestResource} If the file doesn't exist, \meta{not found code} is done. \begin{important} Note that these \cmd{\ldots Resource\ldots} commands are only permitted within the resource files. They are internally enabled through \gls{TrackLangRequireDialect}. \end{important} The above restriction on the resource files loaded through \gls{TrackLangRequireDialect}, and the fact that it internally uses \gls{IfTrackedLanguageFileExists}, means that commands like \gls{CurrentTrackedLanguage} or \gls{CurrentTrackedDialect} may be used in those files. This means that the name of the captions hook can be obtained through them. (Remember that the file \ldf{foo}{en-GB} might have been loaded with, say, the \opt{british} dialect or with the synonymous \opt{UKenglish} dialect or with a dialect label that doesn't have a corresponding caption hook, such as \optfmt{enGBLatn}.) The \sty{polyglossia} package has language caption hooks in the form \tklcaptions{\meta{language}} (where \meta{language} is the root language label) whereas \sty{babel} has dialect captions hooks in the form \gls{captionsdialect} (where \meta{dialect} is the dialect label). This leads to a rather cumbersome set of conditionals: \begin{compactcodebox} \cmd{ifcsundef}\marg{captions\gls{CurrentTrackedLanguage}} \marg{\comment{} \cmd{ifcsundef}\marg{captions\gls{CurrentTrackedDialect}}\comment{} \marg{}\comment{} \marg{\comment{} \cmd{csgappto}\marg{captions\gls{CurrentTrackedDialect}}\marg{\comment{} \comment{code to append to hook} }\comment{} }\comment{} }\comment{} \marg{\comment{} \cmd{csgappto}\marg{captions\gls{CurrentTrackedLanguage}}\marg{\comment{} \comment{code to append to hook} }\comment{} } \comment{do code now to initialise} \end{compactcodebox} Note that the above has been simplified through the use of \sty{etoolbox} commands, which isn't suitable for generic use. It also doesn't query the mapping from \sty{tracklang}['s] dialect label to the closest matching \sty{babel} dialect label. Instead, \sty{tracklang} provides a command to perform this set of conditionals using generic code: \cmddef{TrackLangAddToHook} where \meta{code} is the code to append to the \meta{type} hook. This always performs \meta{code} after testing for the hook in case the hook is undefined or has already been called (for example, \sty{ngerman} uses \tklcaptions{ngerman} when the package is loaded, not at the start of the document). Note that this command is enabled through \gls{TrackLangRequireDialect} so should only be used inside resource files. Since \optfmt{captions} is a commonly used hook type, there's a~shortcut command provided: \cmddef{TrackLangAddToCaptions} This is equivalent to \begin{compactcodebox} \gls{TrackLangAddToHook}\margm{code}\marg{captions} \end{compactcodebox} There may be some hooks, such as \gls{datedialect}, that need redefining rather than appending to, so there's an analogous command: \cmddef{TrackLangRedefHook} which will redefined the hook to do \meta{code}. Note that no expansion is performed on \meta{code} when appending or redefining a hook. \section{Examples} \label{sec:examples} The examples in this section illustrate the above commands. \subsection{\filefmt{animals.sty}} \label{sec:animals} This example is for a trivial package called \file{animals.sty} that defines three textual commands: \cmd{catname}, \cmd{dogname} and \cmd{ladybirdname}. The default values are: \qt{cat}, \qt{dog} and \qt{bishy-barney-bee}.\footnote{Thass Broad Norfolk, my bewties \code{:-P}} The supported languages are defined in files \localefile{animals}. Here's the code for \file{animals.sty}: \begin{codebox} \comment{Example package animals.sty} \cmd{NeedsTeXFormat}\marg{LaTeX2e} \cmd{ProvidesPackage}\marg{animals} \codepar \cmd{RequirePackage}\marg{tracklang}[2019/11/30]\comment{v1.4} \codepar \comment{Any undeclared options are language settings:} \codepar \cmd{DeclareOption}*\marg{\comment{} \gls{TrackIfKnownLanguage}\marg{\cmd{CurrentOption}}\comment{} \marg{\comment{successful} \cmd{PackageInfo}\marg{animals}\marg{Tracking language `\cmd{CurrentOption}'}\comment{} }\comment{} \marg{\comment{failed} \cmd{PackageError}\marg{animals}\comment{} \marg{Unknown language specification `\cmd{CurrentOption}'}\comment{} \marg{You need to supply either a known dialect label or a valid language tag}\comment{} }\comment{} } \codepar \cmd{ProcessOptions} \codepar \comment{Default definitions} \cmd{newcommand}\cmd{catname}\marg{cat} \cmd{newcommand}\cmd{dogname}\marg{dog} \cmd{newcommand}\cmd{ladybirdname}\marg{bishy-barney-bee} \codepar \gls{AnyTrackedLanguages} \marg{\comment{} \gls{ForEachTrackedDialect}\marg{\cmd{this@dialect}}\marg{\comment{} \gls{TrackLangRequireDialect}\marg{animals}\marg{\cmd{this@dialect}}\comment{} }\comment{} } \marg{\comment{no tracked languages, default already set up} } \codepar \cmd{endinput} \end{codebox} Here's a Plain \TeX\ version that picks up the language from the locale environment variable: \begin{codebox} \gls{input} tracklang \codepar \gls{TrackLangFromEnv} \codepar \comment{Default definitions} \cmd{def}\cmd{catname}\marg{cat} \cmd{def}\cmd{dogname}\marg{dog} \cmd{def}\cmd{ladybirdname}\marg{bishy-barney-bee} \codepar \gls{AnyTrackedLanguages} \marg{\comment{} \gls{ForEachTrackedDialect}\marg{\cmd{thisdialect}}\marg{\comment{} \gls{TrackLangRequireDialect}\marg{animals}\marg{\cmd{thisdialect}}\comment{} }\comment{} } \marg{\comment{no tracked languages, default already set up} } \end{codebox} In the event that a user or supplementary package for some reason wants to load a resource file for a language that hasn't been tracked, it might be worth providing a command for this purpose: \begin{codebox} \cmd{newcommand}*\marg{\cmd{RequireAnimalsDialect}}[1]\marg{\comment{} \gls{TrackLangRequireDialect}\marg{animals}\marg{\#1}\comment{} } \end{codebox} The loop can then be changed to: \begin{codebox} \gls{ForEachTrackedDialect}\marg{\cmd{this@dialect}}\marg{\comment{} \cmd{RequireAnimalsDialect}\cmd{this@dialect} }\comment{} \end{codebox} The \ldf{animals}{english} file valid for both the Plain \TeX\ and \LaTeX\ formats contains: \begin{codebox} \gls{TrackLangProvidesResource}\marg{english} \codepar \cmd{def}\cmd{englishanimals}\marg{\comment{} \cmd{def}\cmd{catname}\marg{cat}\comment{} \cmd{def}\cmd{dogname}\marg{dog}\comment{} \cmd{def}\cmd{ladybirdname}\marg{bishy-barney-bee}\comment{} } \codepar \gls{TrackLangAddToCaptions}\marg{\cmd{englishanimals}} \end{codebox} The \ldf{animals}{en-GB} file contains: \begin{codebox} \gls{TrackLangProvidesResource}\marg{en-GB} \gls{TrackLangRequireResource}\marg{english} \codepar \cmd{def}\cmd{enGBanimals}\marg{\comment{} \cmd{englishanimals} \cmd{def}\cmd{ladybirdname}\marg{ladybird}\comment{} } \gls{TrackLangAddToCaptions}\marg{\cmd{enGBanimals}} \end{codebox} The \ldf{animals}{en-US} file contains: \begin{codebox} \gls{TrackLangProvidesResource}\marg{en-US} \gls{TrackLangRequireResource}\marg{english} \codepar \cmd{def}\cmd{enUSanimals}\marg{\comment{} \cmd{englishanimals} \cmd{def}\cmd{ladybirdname}\marg{ladybug}\comment{} } \gls{TrackLangAddToCaptions}\marg{\cmd{enUSanimals}} \end{codebox} Here's a German version in the file \ldf{animals}{german}: \begin{codebox} \gls{TrackLangProvidesResource}\marg{german} \codepar \cmd{def}\cmd{germananimals}\marg{\comment{} \cmd{def}\cmd{catname}\marg{Katze}\comment{} \cmd{def}\cmd{dogname}\marg{Hund}\comment{} \cmd{def}\cmd{ladybirdname}\marg{Marienk\cmd{"}afer}\comment{} } \codepar \gls{TrackLangAddToCaptions}\marg{\cmd{germananimals}} \end{codebox} This means that if \sty{babel} or \sty{polyglossia} are loaded, the redefinitions are automatically performed whenever the language is changed, but if there's no caption mechanism the user can switch the fixed names using the \cmd{\ldots animals} commands. Here's an example \LaTeX\ document that doesn't have any caption hooks: \begin{codebox} \cmd{documentclass}[\opt{english},\opt{german}]\marg{article} \codepar \cmd{usepackage}\marg{animals} \codepar \cbeg{document} \cmd{englishanimals} \codepar \cmd{catname}. \cmd{dogname}. \cmd{ladybirdname}. \codepar \cmd{germananimals} \codepar \cmd{catname}. \cmd{dogname}. \cmd{ladybirdname}. \cend{document} \end{codebox} Here's a \sty{babel} example document: \begin{codebox} \cmd{documentclass}[\opt{american},\opt{german},\opt{british}]\marg{article} \codepar \cmd{usepackage}\marg{babel} \cmd{usepackage}\marg{animals} \codepar \cbeg{document} \cmd{selectlanguage}\marg{american} \codepar \cmd{catname}. \cmd{dogname}. \cmd{ladybirdname}. \codepar \cmd{selectlanguage}\marg{german} \codepar \cmd{catname}. \cmd{dogname}. \cmd{ladybirdname}. \codepar \cmd{selectlanguage}\marg{british} \codepar \cmd{catname}. \cmd{dogname}. \cmd{ladybirdname}. \cend{document} \end{codebox} There is some redundancy with the above resource files. Consider the \sty{babel} example above. The \opt{american} dialect is the first option, so in that case \ldf{animals}{en-US} is loaded followed by \ldf{animals}{english}. This means that the \tklcaptions{american} hook now includes \begin{codebox} \cmd{englishanimals} \cmd{enUSanimals} \end{codebox} Since \cmd{enUSanimals} includes \cmd{englishanimals}, there is redundant code. However, when the \opt{british} dialect is processed, this loads the file \ldf{animals}{en-GB} but not the file \ldf{animals}{english} (since it's already been loaded). This means that \tklcaptions{british} contains \cmd{enGBanimals} but not \cmd{englishanimals}. If this redundancy is an issue (for example, there are so many redefinitions needed that it significantly slows the document build process), then it can be addressed with the following modifications. The \ldf{animals}{en-GB} file is now: \begin{codebox} \gls{TrackLangProvidesResource}\marg{en-GB} \codepar \cmd{def}\cmd{enGBanimals}\marg{\comment{} \cmd{englishanimals} \cmd{def}\cmd{ladybirdname}\marg{ladybird}\comment{} } \codepar \gls{TrackLangRequireResourceOrDo}\marg{english}\comment{} \marg{ \gls{TrackLangAddToCaptions}\marg{\comment{} \cmd{def}\cmd{ladybirdname}\marg{ladybird}\comment{} }\comment{} } \marg{ \gls{TrackLangAddToCaptions}\marg{\cmd{enGBanimals}} } \end{codebox} The \ldf{animals}{en-US} file is now: \begin{codebox} \gls{TrackLangProvidesResource}\marg{en-US} \codepar \cmd{providecommand}*\marg{\cmd{enUSanimals}}\marg{\comment{} \cmd{englishanimals} \cmd{renewcommand}*\marg{\cmd{ladybirdname}}\marg{ladybug}\comment{} } \codepar \gls{TrackLangRequireResourceOrDo}\marg{english} \marg{ \gls{TrackLangAddToCaptions}\marg{\comment{} \cmd{renewcommand}*\marg{\cmd{ladybirdname}}\marg{ladybird}\comment{} }\comment{} } \marg{ \gls{TrackLangAddToCaptions}\marg{\cmd{enUSanimals}} } \end{codebox} This means that the document that has the dialects listed in the order \opt{american}, \opt{british} now has \begin{codebox} \cmd{englishanimals} \cmd{def}\cmd{ladybirdname}\marg{ladybird} \end{codebox} in the \tklcaptions{british} hook and just \cmd{enUSanimals} in the \tklcaptions{american} hook, which has removed most of the redundancy. Note that \sty{polyglossia} has a \tklcaptions{english} hook but not \tklcaptions{american} or \tklcaptions{british}, so this code doesn't allow for switching between variants of the same language with \sty{polyglossia}. \subsection{\filefmt{regions.sty}} \label{sec:regions} \glsadd{file.regions.sty}% \phyperref{Earlier}{pg.britishfilesearch}, I~mentioned the search order for \gls{IfTrackedLanguageFileExists} where if, for example, the dialect is \opt{british}, the file search (v1.4+) will be: \begin{enumerate} \item \ldf{mypackage}{en-GB} (language tag) \item \ldf{mypackage}{british} (dialect label) \item \ldf{mypackage}{en-Latn-GB} (\idx{639-1} language code, \idx{script}, \idx{region}) \item \ldf{mypackage}{en-GB} (\idx{639-1} language code, \idx{region}) \item \ldf{mypackage}{en-Latn} (\idx{639-1} language code, \idx{script}) \item \ldf{mypackage}{en} (\idx{639-1} language code) \item \ldf{mypackage}{eng-Latn-GB} (\idx{639-2} language code, \idx{script}, \idx{region}) \item \ldf{mypackage}{eng-GB} (\idx{639-2} language code, \idx{region}) \item \ldf{mypackage}{eng-Latn} (\idx{639-2} language code, \idx{script}) \item \ldf{mypackage}{eng} (\idx{639-2} language code) \item \ldf{mypackage}{GB} (\idx{region}) \item \ldf{mypackage}{english} (language label) \end{enumerate} You may have wondered why \ldf{mypackage}{GB} is included in the search given that some countries have multiple official languages, which means that the country code on its own may not indicate the language. The reason for including just the country code as the \meta{localeid} in the file search is to allow for region rather than language dependent settings. For example, suppose I~want to write a package that needs to know whether to use imperial or metric measurements in the document, but I also want to provide multilingual support. The language alone won't tell me whether to use imperial or metric (for example, the US uses imperial and the UK uses metric for most product attributes). I could provide \ext+{ldf} files for every language and region combination, but this would result in a lot redundancy. \gls{TrackLangRequireDialect} has an optional argument for adjusting the way the resource files are loaded. Suppose I have \localefile{regions} resource files, then \begin{codebox} \gls{TrackLangRequireDialect}\marg{regions}\marg{\cmd{this@dialect}} \end{codebox} loads the resource file for the dialect given by \cmd{this@dialect} using: \begin{compactcodebox} \gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedTag}} \end{compactcodebox} I can use the optional argument to also load the resource file for the root language as well: \begin{codebox}% \comment{custom file loader for regions.sty} \cmd{newcommand}*\marg{\cmd{RequireRegionsDialect}}[1]\marg{\comment{} \gls{TrackLangRequireDialect} \oarg{\gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedTag}}\comment{} \gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedLanguage}}\comment{} }\comment{} \marg{regions}\marg{\#1}\comment{} } \end{codebox} Now the dialect \opt{british} can load both \ldf{regions}{GB} and \ldf{regions}{english}. The example package (\file{regions.sty}) below illustrates this. \begin{codebox} \comment{Example package regions.sty} \cmd{NeedsTeXFormat}\marg{LaTeX2e} \cmd{ProvidesPackage}\marg{regions} \codepar \gls{RequirePackage}\marg{tracklang}[2016/10/07]\comment{v1.3+} \codepar \cmd{DeclareOption}*\marg{\gls{TrackLanguageTag}\marg{\cmd{CurrentOption}}} \cmd{ProcessOptions} \codepar \cmd{newcommand}*\marg{\cmd{weightunit}}\marg{kg} \cmd{newcommand}*\marg{\cmd{lengthunit}}\marg{mm} \cmd{newcommand}*\marg{\cmd{currencyunit}}\marg{EUR} \codepar \cmd{newcommand}*\marg{\cmd{unitname}}\marg{units} \codepar \cmd{newcommand}*\marg{\cmd{RequireRegionsDialect}}[1]\marg{\comment{} \gls{TrackLangRequireDialect} \oarg{\gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedTag}}\comment{} \gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedLanguage}}\comment{} }\comment{} \marg{regions}\marg{\#1}\comment{} } \codepar \gls{AnyTrackedLanguages} \marg{\comment{} \gls{ForEachTrackedDialect}\marg{\cmd{this@dialect}}\marg{\comment{} \cmd{RequireRegionsDialect}\cmd{this@dialect} }\comment{} } \marg{\comment{no tracked languages, default already set up} } \codepar \cmd{endinput} \end{codebox} There are separate \ext{ldf} files for region and language. First are the regions. \begin{itemize} \item \ldf{regions}{BE} (Belgium): \begin{codebox} \gls{TrackLangProvidesResource}\marg{BE} \codepar \cmd{providecommand}*\marg{\cmd{BEunits}}\marg{\comment{} \cmd{renewcommand}*\marg{\cmd{weightunit}}\marg{kg}\comment{} \cmd{renewcommand}*\marg{\cmd{lengthunit}}\marg{mm}\comment{} \cmd{renewcommand}*\marg{\cmd{currencyunit}}\marg{EUR}\comment{} } \codepar \gls{TrackLangAddToCaptions}\marg{\cmd{BEunits}} \end{codebox} \item \ldf{regions}{CA} (Canada): \begin{codebox} \gls{TrackLangProvidesResource}\marg{CA} \codepar \cmd{providecommand}*\marg{\cmd{CAunits}}\marg{\comment{} \cmd{renewcommand}*\marg{\cmd{weightunit}}\marg{kg}\comment{} \cmd{renewcommand}*\marg{\cmd{lengthunit}}\marg{mm}\comment{} \cmd{renewcommand}*\marg{\cmd{currencyunit}}\marg{CAD}\comment{} } \codepar \gls{TrackLangAddToCaptions}\marg{\cmd{CAunits}} \end{codebox} \item \ldf{regions}{GB} (Great Britain): \begin{codebox} \gls{TrackLangProvidesResource}\marg{GB} \codepar \cmd{providecommand}*\marg{\cmd{GBunits}}\marg{\comment{} \cmd{renewcommand}*\marg{\cmd{weightunit}}\marg{kg}\comment{} \cmd{renewcommand}*\marg{\cmd{lengthunit}}\marg{mm}\comment{} \cmd{renewcommand}*\marg{\cmd{currencyunit}}\marg{GBP}\comment{} } \codepar \gls{TrackLangAddToCaptions}\marg{\cmd{GBunits}} \end{codebox} \item \ldf{regions}{US} (USA): \begin{codebox} \gls{TrackLangProvidesResource}\marg{US} \codepar \cmd{providecommand}*\marg{\cmd{USunits}}\marg{\comment{} \cmd{renewcommand}*\marg{\cmd{weightunit}}\marg{lb}\comment{} \cmd{renewcommand}*\marg{\cmd{lengthunit}}\marg{in}\comment{} \cmd{renewcommand}*\marg{\cmd{currencyunit}}\marg{USD}\comment{} } \codepar \gls{TrackLangAddToCaptions}\marg{\cmd{USunits}} \end{codebox} \end{itemize} Now the language files: \begin{itemize} \item \ldf{regions}{dutch}: \begin{codebox} \gls{TrackLangProvidesResource}\marg{dutch} \codepar \cmd{providecommand}*\marg{\cmd{dutchnames}}\marg{\comment{} \cmd{renewcommand}*\marg{\cmd{unitname}}\marg{meeteenheden}\comment{} } \codepar \gls{TrackLangAddToCaptions}\marg{\cmd{dutchnames}} \end{codebox} \item \ldf{regions}{english}: \begin{codebox} \gls{TrackLangProvidesResource}\marg{english} \codepar \cmd{providecommand}*\marg{\cmd{englishnames}}\marg{\comment{} \cmd{renewcommand}*\marg{\cmd{unitname}}\marg{units}\comment{} } \codepar \gls{TrackLangAddToCaptions}\marg{\cmd{englishnames}} \end{codebox} \item \ldf{regions}{french}: \begin{codebox} \cmd{TrackLangProvidesResource}\marg{french} \codepar \cmd{providecommand}*\marg{\cmd{frenchnames}}\marg{\comment{} \cmd{renewcommand}*\marg{\cmd{unitname}}\marg{unit\cmd{'}es}\comment{} } \codepar \gls{TrackLangAddToCaptions}\marg{\cmd{frenchnames}} \end{codebox} \item \ldf{regions}{german}: \begin{codebox} \gls{TrackLangProvidesResource}\marg{french} \codepar \cmd{providecommand}*\marg{\cmd{germannames}}\marg{\comment{} \cmd{renewcommand}*\marg{\cmd{unitname}}\marg{Ma\cmd{ss} einheiten}\comment{} } \codepar \gls{TrackLangAddToCaptions}\marg{\cmd{germannames}} \end{codebox} \end{itemize} Here's an example document that uses this package: \begin{codebox} \cmd{documentclass}[\opt{canadien}]\marg{article} \codepar \cmd{usepackage}\marg{regions} \codepar \cbeg{document} \codepar \cmd{unitname}: \cmd{weightunit}, \cmd{lengthunit}, \cmd{currencyunit}. \codepar \cend{document} \end{codebox} This works because the \meta{localeid} search looks for the country code before the root language label. However, this will fail if the dialect label is the same as a root language label that has an associated territory, marked with \fnregion\ in \tableref{tab:rootlangopts}, as then it will be picked up before the country code. In the above example, \ldf{regions}{CA} is matched rather than \ldf{regions}{french}, so \ldf{regions}{CA} is loaded by \begin{compactcodebox} \gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedTag}} \end{compactcodebox} After this, the language file \ldf{regions}{french} is then loaded: \begin{compactcodebox} \gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedLanguage}} \end{compactcodebox} This assumes that there's a country code \ext{ldf} file available. This example needs a little modification to use default units in case the region is missing: \begin{codebox} \comment{Modified example package regions.sty} \cmd{NeedsTeXFormat}\marg{LaTeX2e} \cmd{ProvidesPackage}\marg{regions} \codepar \comment{Pass all options to \file{tracklang.sty}:} \cmd{DeclareOption}*\marg{\cmd{PassOptionsToPackage}\marg{\cmd{CurrentOption}}\marg{tracklang}} \cmd{ProcessOptions} \codepar \gls{RequirePackage}\marg{tracklang} \codepar \cmd{newcommand}*\marg{\cmd{weightunit}}\marg{kg} \cmd{newcommand}*\marg{\cmd{lengthunit}}\marg{mm} \cmd{newcommand}*\marg{\cmd{currencyunit}}\marg{EUR} \codepar \cmd{newcommand}*\marg{\cmd{unitname}}\marg{units} \codepar \cmd{newcommand}*\marg{\cmd{defaultunits}}\marg{\comment{} \cmd{renewcommand}*\marg{\cmd{weightunit}}\marg{kg}\comment{} \cmd{renewcommand}*\marg{\cmd{lengthunit}}\marg{mm}\comment{} \cmd{renewcommand}*\marg{\cmd{currencyunit}}\marg{EUR}\comment{} } \codepar \cmd{newcommand}*\marg{\cmd{RequireRegionsDialect}}[1]\marg{\comment{} \gls{TrackLangRequireDialect} \oarg{\gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedTag}}\comment{} \cmd{ifx}\gls{CurrentTrackedTag}\gls{CurrentTrackedLanguage} \gls{TrackLangAddToCaptions}\marg{\cmd{defaultunits}}\comment{} \cmd{else} \gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedLanguage}}\comment{} \cmd{fi} }\comment{} \marg{regions}\marg{\#1}\comment{} } \codepar \gls{AnyTrackedLanguages} \marg{\comment{} \gls{ForEachTrackedDialect}\marg{\cmd{this@dialect}}{\comment{} \cmd{RequireRegionsDialect}\cmd{this@dialect} }\comment{} } \marg{\comment{no tracked languages, default already set up} } \codepar \cmd{endinput} \end{codebox} Note that we still have a problem for dialect labels that are identical to root language labels with an associated territory (such as \opt{manx}). This case can be checked with the following adjustment: \begin{codebox} \cmd{newcommand}*\marg{\cmd{RequireRegionsDialect}}[1]\marg{\comment{} \gls{TrackLangRequireDialect} \oarg{\gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedTag}}\comment{} \cmd{ifx}\gls{CurrentTrackedTag}\gls{CurrentTrackedLanguage} \cmd{ifx}\gls{CurrentTrackedRegion}\cmd{empty} \gls{TrackLangAddToCaptions}\marg{\cmd{defaultunits}}\comment{} \cmd{else} \gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedRegion}}\comment{} \cmd{fi} \cmd{else} \gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedLanguage}}\comment{} \cmd{fi} }\comment{} \marg{regions}\marg{\#1}\comment{} } \end{codebox} In the case where both the dialect and root language label are \opt{manx} with the resource files \ldf{regions}{manx} and \ldf{regions}{IM}, then \gls{CurrentTrackedTag} will be \opt{manx} (the dialect label) so \ldf{regions}{manx} will be loaded with: \begin{compactcodebox} \gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedTag}} \end{compactcodebox} In this case \gls{CurrentTrackedRegion} is \code{IM} (that is, it's not empty) so then \ldf{regions}{IM} will be loaded with: \begin{compactcodebox} \gls{TrackLangRequireResource}\marg{\gls{CurrentTrackedRegion}} \end{compactcodebox} Here's another document that sets up dialects with \sty{tracklang} labels that aren't recognised by \sty{babel}. This means that there's no corresponding \gls{captionsdialect} hook for either the dialect label or the root language label, so mappings need to be defined from the \sty{tracklang} dialect label to the matching \sty{babel} dialect label. \begin{codebox} \cmd{documentclass}\marg{article} \codepar \cmd{usepackage}\marg{tracklang} \codepar \gls{TrackLanguageTag}\marg{de-US-1996} \gls{SetTrackedDialectLabelMap}\marg{\gls{TrackLangLastTrackedDialect}}\marg{ngerman} \codepar \gls{TrackLanguageTag}\marg{en-MT} \gls{SetTrackedDialectLabelMap}\marg{\gls{TrackLangLastTrackedDialect}}\marg{UKenglish} \codepar \cmd{usepackage}[main=ngerman,UKenglish]\marg{babel} \cmd{usepackage}\marg{regions} \codepar \cbeg{document} \gls{selectlanguage}\marg{ngerman} \codepar \cmd{unitname}: \cmd{weightunit}, \cmd{lengthunit}, \cmd{currencyunit}. \codepar \gls{selectlanguage}\marg{UKenglish} \codepar \cmd{unitname}: \cmd{weightunit}, \cmd{lengthunit}, \cmd{currencyunit}. \codepar \cend{document} \end{codebox} This produces: \begin{resultbox} Ma\ss einheiten: lb, in, USD. units: kg, mm, EUR. \end{resultbox} Compare this with: \begin{codebox} \cmd{documentclass}\marg{article} \codepar \cmd{usepackage}[main=ngerman,UKenglish]\marg{babel} \cmd{usepackage}\marg{regions} \codepar \cbeg{document} \gls{selectlanguage}\marg{ngerman} \codepar \cmd{unitname}: \cmd{weightunit}, \cmd{lengthunit}, \cmd{currencyunit}. \codepar \gls{selectlanguage}\marg{UKenglish} \codepar \cmd{unitname}: \cmd{weightunit}, \cmd{lengthunit}, \cmd{currencyunit}. \codepar \cend{document} \end{codebox} which produces: \begin{resultbox} Ma\ss einheiten: kg, mm, EUR. units: kg, mm, GBP. \end{resultbox} Note that these mappings aren't needed if \sty{babel} is loaded with the root language labels instead. For example: \begin{codebox} \cmd{documentclass}\marg{article} \codepar \cmd{usepackage}\marg{tracklang} \codepar \gls{TrackLanguageTag}\marg{de-US-1996} \gls{SetTrackedDialectLabelMap}\marg{\gls{TrackLangLastTrackedDialect}}\marg{ngerman} \codepar \gls{TrackLanguageTag}\marg{en-MT} \codepar \cmd{usepackage}[main=ngerman,english]\marg{babel} \cmd{usepackage}\marg{regions} \codepar \cbeg{document} \gls{selectlanguage}\marg{ngerman} \codepar \cmd{unitname}: \cmd{weightunit}, \cmd{lengthunit}, \cmd{currencyunit}. \codepar \gls{selectlanguage}\marg{english} \codepar \cmd{unitname}: \cmd{weightunit}, \cmd{lengthunit}, \cmd{currencyunit}. \codepar \cend{document} \end{codebox} No mapping is required for the \opt{en-MT} locale as it can pick up \tklcaptions{english} when \gls{TrackLangAddToHook} (used by \gls{TrackLangAddToCaptions}) queries the root language label after failing to find the language hook from the dialect label. Some of the predefined \sty{tracklang} dialects come with a mapping to the closest matching \sty{babel} dialect label. For example, the option \opt{ngermanDE} listed in \tableref{tab:nonisoopts} automatically provides a mapping to \opt{ngerman}. Since a \sty{tracklang} dialect label can only map to one \sty{babel} label, this can be problematic for synonymous labels such as \opt{british}\slash\opt{UKenglish} or \opt{american}\slash\opt{USenglish}. The default mappings used by \sty{tracklang} are shown in \tableref{tab:nonisoopts}. \chapter{Adding Support for Language Tracking} \label{sec:langsty} If you are writing a package that \emph{sets up} the document languages (rather than a package that provides multilingual support if the user has already loaded a language package) then you can load \sty{tracklang} and use the commands below to help other packages track your provided languages. (See also: \dickimawhref{latex/tracklang/langpkg.shtml}{Integrating \filefmt{tracklang.tex} into Language Packages}.) The \sty{tracklang} package can be loaded using \begin{codebox} \gls{input} tracklang \end{codebox} or (\LaTeX\ only) \begin{codebox} \gls{RequirePackage}\marg{tracklang} \end{codebox} When using \LaTeX, there's a difference between the two. The first case prevents \sty{tracklang} from picking up the document class options but skips the check for known language packages. This check is redundant since your package is the language package, so you need to decide whether or not to allow the user to set up the localisation information through the document class options. There's a hook that, if defined, is performed by \file{tracklang.sty} after the package options have been loaded but before known language packages are checked: \cmddef{@tracklang@prelangpkgcheck@hook} If you prefer \gls{RequirePackage} over \gls{input} but you want to make \file{tracklang.sty} skip the check for known language packages then (as from v1.3.8) define the pre-language package check hook as follows: \begin{codebox} \cmd{providecommand}\gls{@tracklang@prelangpkgcheck@hook}\marg{\cmd{endinput}} \gls{RequirePackage}\marg{tracklang}[2019/10/06]\comment{v1.3.8+} \end{codebox} This will still pick up languages supplied through the document class options. If you just use \gls{input}, there's a test at the start of \file{tracklang.tex} to determine if it's already been loaded, so you don't need to worry if the document has already input it. To integrate \sty{tracklang} into your language package, you need to consider the following steps: \begin{enumerate} \item Does \sty{tracklang} define your supported \idxn{15924} language scripts in the \file{tracklang-scripts.tex} file? If yes, then skip this step. Otherwise create a file with the relevant \gls{TrackLangScriptMap} command for each unknown script and identify this new file with \gls{TrackLangAddExtraScriptFile} (see \sectionref{sec:newscripts}). This usually won't be necessary unless you have a custom script or a child script (a script that's a sub-category of another script). \item Does \sty{tracklang} recognise the root language? If yes, then skip this step. If your package is setting up a language that \sty{tracklang} doesn't recognise then you will need to define the root language using \gls{TrackLangNewLanguage} (see \sectionref{sec:newlanguages}). This usually won't be the case as \sty{tracklang} should support all languages that have an official \idxn{639-1} alpha-2 code. If you simply have a different label from \sty{tracklang} identifying the root language, then you can just set up your label as a dialect using \gls{TrackLangProvidePredefinedDialect}. \item Does \sty{tracklang} define the relevant \idxn{3166-1} region codes in the \file{tracklang-region-codes.tex} file? If yes, then skip this step. Otherwise create a file with the relevant \gls{TrackLangRegionMap} command for each new region and identify this new file with \gls{TrackLangAddExtraRegionFile} (see \sectionref{sec:newregions}). This usually won't be necessary as \sty{tracklang} should recognise all countries that have an alpha-2 region code, but you may require it if you need a broader region, such as EU. \item Do you want to define some convenient dialect labels that can be used with \gls{TrackPredefinedDialect}? If no, then skip this step. Otherwise you can use \gls{TrackLangProvidePredefinedLanguage} for root languages and \gls{TrackLangProvidePredefinedDialect} for dialects with additional information, such as a region, sub-language or script (see \sectionref{sec:definelabels}). \item In your language initialisation code, add the \sty{tracklang} code to track the particular dialect (for example, use \gls{TrackPredefinedDialect} for recognised dialect labels or use the \csmetafmt{AddTracked}{Xxx}{} set of commands). See \sectionref{sec:initnewlang}. \item In your language selection code (such as \gls{selectlanguage}), add \gls{SetCurrentTrackedDialect}\margm{label} to allow the document author to easily query the current localisation settings (such as the region). See \sectionref{sec:selectlanguage}. \end{enumerate} \section{Initialising a New Language or Dialect} \label{sec:initnewlang} When the user requests a particular dialect through your language package, you can notify \sty{tracklang} of this choice using \begin{compactcodebox*} \gls{TrackPredefinedDialect}\margm{dialect label} \end{compactcodebox*} provided the dialect label is recognised by \sty{tracklang} (all those listed in \refoptstables). If there's no matching dialect predefined by \sty{tracklang}, you can just use \gls{TrackLocale} or \gls{TrackLanguageTag} (described in \sectionref{sec:generic}) with the appropriate \idx{ISO} codes \emph{if you're not providing caption hooks}. If you are providing a captions hook mechanism in the form \gls{captionsdialect}, then if \meta{dialect} doesn't match the corresponding \sty{tracklang} dialect label, you can provide a mapping using \gls{SetTrackedDialectLabelMap}, described below. \section{Switching Language or Dialect} \label{sec:selectlanguage} When the document author switches to a different language or dialect, the current localisation information can be set with: \cmddef{SetCurrentTrackedDialect} where \meta{dialect} may the \sty{tracklang} dialect label, or the mapped label previously set through \gls{SetTrackedDialectLabelMap}, described below, or the language label (in which case the last dialect to be tracked with that root language will be assumed). This will make the following commands available which may be of use to other packages: \begin{itemize} \item\gls{CurrentTrackedDialect} The dialect label recognised by \sty{tracklang} (which may not be the same as \meta{dialect}). \item\gls{CurrentTrackedLanguage} The root language label used by \sty{tracklang}. \item\gls{CurrentTrackedDialectModifier} The dialect modifier. \item\gls{CurrentTrackedDialectVariant} The dialect variant. \item\gls{CurrentTrackedDialectScript} The dialect script. Note that if \sty{tracklang-scripts} is also loaded, this allows the script direction to be accessed using \begin{codebox} \gls{TrackLangScriptAlphaToDir}\marg{\gls{CurrentTrackedDialectScript}} \end{codebox} See \sectionref{sec:supplpkgs} for further details. \item\gls{CurrentTrackedDialectSubLang} The dialect sub-language code. \item\gls{GetTrackedDialectAdditional} The dialect's additional information. \item\gls{CurrentTrackedIsoCode} The dialect's root language \idx{ISO} code. (The first found in the sequence \idx{639-1}, \idx{639-2}, \idx{639-3}.) \item\gls{CurrentTrackedRegion} The dialect's \idxn{3166-1} region code. \item\gls{CurrentTrackedLanguageTag} The dialect's language tag. \end{itemize} (Without this automated use of \gls{SetCurrentTrackedDialect}, the same information can be picked up using commands like \gls{GetTrackedDialectScript}, but that's less convenient, especially if \gls{languagename} needs to be converted to \meta{dialect}. See the accompanying sample file \filefmt{sample-setlang.tex} for an example.) \section{Defining New Scripts} \label{sec:newscripts} The \file{tracklang-scripts.tex} file isn't automatically loaded, but if it is then, as from v1.4, it contains a hook at the end of the file that can be used to load additional files that define supplementary scripts. This entails creating a file called, say, \filefmt{mypackage-scripts.tex} that contains: \begin{compactcodebox*} \gls{TrackLangScriptMap}\margm{alpha code}\margm{numeric code}\margm{name}\margm{direction}\margm{parent script} \end{compactcodebox*} The first argument \meta{alpha code} is the four-letter ISO~15924 code (such as \opt{Latn}), the second argument is the numeric code (such as 215), the third argument \meta{name} is the name of the script (such as \optfmt{Latin}), the fourth argument is the direction (such as \optfmt{LR} for left-to-right) and the final argument is the parent script (leave blank if there's no parent). Note that this command will override any previous mapping for those codes. No check is performed to determine if they have already been defined. The supplementary file should be identified with: \begin{compactcodebox*} \gls{TrackLangAddExtraScriptFile}\margm{filename} \end{compactcodebox*} Additional information can be found in \sectionref{sec:supplpkgs}. \section{Defining New Regions} \label{sec:newregions} The \file{tracklang-region-codes.tex} file isn't automatically loaded, but if it is then, as from v1.4, it contains a hook at the end of the file that can be used to load additional files that define supplementary regions. This entails creating a file called, say, \filefmt{mypackage-regions.tex} that contains: \begin{compactcodebox*} \gls{TrackLangRegionMap}\margm{numeric code}\margm{alpha-2 code}\margm{alpha-3 code} \end{compactcodebox*} where the first argument is the numeric region code (such as 826), the second argument is the alpha-2 region code (such as \code{GB}) and the third argument is the alpha-3 region code (such as \code{GBR}). Note that this command will override any previous mapping for those codes. No check is performed to determine if they have already been defined. The supplementary file should be identified with: \begin{compactcodebox*} \gls{TrackLangAddExtraRegionFile}\margm{filename} \end{compactcodebox*} Additional information can be found in \sectionref{sec:supplpkgs}. \section{Defining a New Language} \label{sec:newlanguages} (New to version 1.3.) If the root language isn't recognised by \sty{tracklang} (not listed in \tableref{tab:rootlangopts}), then it can be defined (but not tracked at this point) using: \cmddef{TrackLangNewLanguage} where \meta{language label} is the root language label, \meta{639-1 code} is the \idxn{639-1} code for that language (may be empty if there isn't one), \meta{639-2 (T)} is the \idxn{639-2T} code for that language (may be empty if there isn't one), \meta{639-2 (B)} is the \idxn{639-2B} code for that language (may be empty if it's the same as \meta{639-2 (T)}), \meta{639-3} is the \idxn{639-3} code for that language (empty if the same as the \idx{639-2} code), \meta{3166-1} is the territory \idxn{3166-1} code for languages that are only spoken in one territory (should be empty if the language is spoken in multiple territories), and \meta{default script} is the default script (empty if disputed or varies according to region). You can then track this language using: \cmddef{AddTrackedDialect} for dialects (where \meta{dialect label} is the dialect label and \meta{root language label} is the root language label) or, if no regional variant is needed, you can instead use: \cmddef{AddTrackedLanguage} This is equivalent to \begin{compactcodebox} \gls{AddTrackedDialect}\margm{root language label}\margm{root language label} \end{compactcodebox} Note that \gls{AddTrackedDialect} defines: \cmddef{TrackLangLastTrackedDialect} to the dialect label, which makes it easier to reference the last dialect to be tracked. \section{Defining New \styfmt{tracklang} Labels} \label{sec:definelabels} A dialect label may be predefined with associated information that allows that particular combination to be easily tracked with \gls{TrackPredefinedDialect}. In the case of a dialect label that only requires the information provided in \gls{TrackLangNewLanguage} you can use: \cmddef{TrackLangProvidePredefinedLanguage} where \meta{language label} corresponds to the language label used in \gls{TrackLangNewLanguage}. This allows \begin{compactcodebox*} \gls{TrackPredefinedDialect}\margm{label} \end{compactcodebox*} to not only track the root language but also the associated ISO codes. If the dialect label doesn't match the root language label then use: \cmddef{TrackLangProvidePredefinedDialect} where \meta{dialect label} is the new \sty{tracklang} dialect label, \marg{root language label} is the \sty{tracklang} root language label, \meta{region} is the \idxn{3166-1} region code (may be empty), \meta{modifier} is the \idx{modifier} (may be empty), \meta{variant} is the \idx{variant} information (may be empty), \meta{map} is your package's language label that corresponds to the \sty{tracklang} dialect label supplied in the first argument (may be empty if identical), and \meta{script} is the \idxn{15924} alpha-4 script code (may be empty if it's the same as the default script for the root language). For compatibility with pre version 1.3, if the dialect isn't predefined by \sty{tracklang}, then you can use: \begin{compactcodebox*} \gls{AddTrackedDialect}\marg{dialect}\marg{root language label} \end{compactcodebox*} where \meta{root language label} is the label for the dialect's root language (\tableref{tab:rootlangopts}) and \meta{dialect} matches the captions hook. If the dialect is already in the tracked dialect list, it won't be added again. If the root language is already in the tracked language list, it won't be added again. As from version 1.3 this additionally defines \gls{TrackLangLastTrackedDialect} to \meta{dialect} for convenient reference if required. Note that \gls{AddTrackedDialect} is internally used by commands like \gls{TrackPredefinedDialect}, \gls{TrackLocale} and \gls{TrackLanguageTag}. (New to version 1.3.) Many of the \sty{tracklang} dialect labels don't have a corresponding match in various language packages. For example, \sty{tracklang} provides \opt{ngermanDE} but the closest match in \sty{babel} is \opt{ngerman}. This means that the caption hook \tklcaptions{ngerman} can't be accessed through: \begin{compactcodebox} \cmd{csname} captions\gls{CurrentTrackedDialect}\cmd{endcsname} \end{compactcodebox} in the resource files. In this case, a mapping may be defined between the \sty{tracklang} dialect label and the closest matching label used by the language hooks. This is done through \cmddef{SetTrackedDialectLabelMap} where \meta{tracklang-label} is the \sty{tracklang} label and \meta{hook-label} is the language hook label. For example: \begin{compactcodebox*} \gls{TrackLanguageTag}\marg{de-AR-1996} \gls{SetTrackedDialectLabelMap}\marg{\gls{TrackLangLastTrackedDialect}}\marg{ngerman} \end{compactcodebox*} Since \gls{TrackLanguageTag} internally uses \gls{AddTrackedDialect} the dialect label created by \sty{tracklang} can be accessed using \gls{TrackLangLastTrackedDialect}. This means that \gls{TrackLangAddToCaptions} can now find the \tklcaptions{ngerman} hook even though the \sty{tracklang} dialect label isn't \opt{ngerman}. (New to version 1.3.) If the root language label is recognised by \sty{tracklang}, you can add the \idx{ISO} codes using: \cmddef{AddTrackedLanguageIsoCodes} As from v1.3, you can also provide a modifier for a given dialect using: \cmddef{SetTrackedDialectModifier} where \meta{dialect} is the dialect label and \meta{value} is the modifier value. For example: \begin{compactcodebox*} \gls{AddTrackedDialect}\marg{oldgerman}\marg{\opt{german}} \gls{AddTrackedLanguageIsoCodes}\marg{german} \gls{SetTrackedDialectModifier}\marg{oldgerman}\marg{old} \end{compactcodebox*} Note that no sanitization is performed on \meta{value} when the modifier is set explicitly through \gls{SetTrackedDialectModifier}, since it's assumed that any package that specifically sets the modifier in this way is using a sensible labelling system. If the modifier is obtained through commands like \gls{TrackLocale}, then the modifier is sanitized as the value may have been obtained from the operating system and there's no guarantee that it won't contain problematic characters. The \idx{modifier} is typically obtained by parsing locale information in \idx{POSIX} format. \begin{compactcodebox*} \meta{language}[\idx{underscoresep}\meta{territory}][\idx{dotsep}\meta{codeset}][\idx{atmod}\meta{modifier}] \end{compactcodebox*} whereas the \idx{variant} is typically obtained by parsing the language tag. The information provided in the commands below (such as the script) are typically obtained by parsing the language tag. For example, with Serbian in the Latin alphabet the modifier would be \optfmt{latin} whereas the script would be \opt{Latn}: \begin{codebox*} \gls{AddTrackedDialect}\marg{serbianlatin}\marg{\opt{serbian}} \gls{AddTrackedLanguageIsoCodes}\marg{\opt{serbian}} \gls{SetTrackedDialectModifier}\marg{serbianlatin}\marg{latin} \gls{SetTrackedDialectScript}\marg{serbianlatin}\marg{\opt{Latn}} \end{codebox*} As from v1.3, you can provide a script (for example, \opt{Latn} or \opt{Cyrl}) using: \cmddef{SetTrackedDialectScript} where \meta{dialect} is the dialect label and \meta{value} is the \idxn{15924} alpha-4 script identifier. For example: \begin{codebox*} \gls{AddTrackedDialect}\marg{serbiancyrl}\marg{\opt{serbian}} \gls{AddTrackedLanguageIsoCodes}\marg{serbian} \gls{SetTrackedDialectScript}\marg{serbiancyrl}\marg{\opt{Cyrl}} \end{codebox*} As from v1.3, you can provide a variant for a given dialect using: \cmddef{SetTrackedDialectVariant} For example: \begin{codebox*} \gls{AddTrackedDialect}\marg{german1901}\marg{german} \gls{SetTrackedDialectVariant}\marg{german1901}\marg{1901} \end{codebox*} As from v1.3, you can also provide a sub-language using: \cmddef{SetTrackedDialectSubLang} where \meta{dialect} is the dialect label and \meta{value} is the code. For example: \begin{codebox*} \gls{AddTrackedDialect}\marg{mandarin}\marg{\opt{chinese}} \gls{AddTrackedLanguageIsoCodes}\marg{\opt{chinese}} \gls{SetTrackedDialectSubLang}\marg{mandarin}\marg{cmn} \gls{AddTrackedIsoLanguage}\marg{639-3}\marg{cmn}\marg{mandarin} \end{codebox*} As from v1.3, you can also provide additional information using: \cmddef{SetTrackedDialectAdditional} where \meta{dialect} is the dialect label and \meta{value} is the additional information. \section{Example (\filefmt{alien.sty})} \label{sec:examplenewlang} Suppose I want to create a language package \file{alien.sty} that defines the \optfmt{martian} language with regional dialects \optfmt{lowermartian} and \optfmt{uppermartian}. First, let's suppose that \sty{tracklang} recognises the root language \optfmt{martian}: \begin{codebox} \cmd{ProvidesPackage}\marg{alien} \codepar \gls{input}{tracklang}\comment{v1.3} \codepar \cmd{DeclareOption}\marg{martian}\marg{\comment{} \gls{TrackPredefinedDialect}\marg{martian} } \cmd{DeclareOption}\marg{lowermartian}\marg{\comment{} \gls{AddTrackedDialect}\marg{lowermartian}\marg{martian} \gls{AddTrackedLanguageIsoCodes}\marg{martian} \gls{AddTrackedIsoLanguage}\marg{3166-1}\marg{YY}\marg{lowermartian} \comment{other attributes such as} \comment{\gls{SetTrackedDialectVariant}\marg{lowermartian}\marg{...}} } \cmd{DeclareOption}\marg{uppermartian}\marg{\comment{} \gls{AddTrackedDialect}\marg{uppermartian}\marg{martian} \gls{AddTrackedLanguageIsoCodes}\marg{martian} \gls{AddTrackedIsoLanguage}\marg{3166-1}\marg{XX}\marg{uppermartian} \comment{other attributes such as} \comment{\gls{SetTrackedDialectVariant}\marg{uppermartian}\marg{...}} } \codepar \cmd{ProcessOptions} \codepar \cmd{newcommand}*\marg{\gls{selectlanguage}}[1]\marg{\comment{} \cmd{def}\gls{languagename}\marg{\#1}\comment{} \comment{other stuff} \gls{SetCurrentTrackedDialect}\marg{\#1}\comment{} } \codepar \gls{AnyTrackedLanguages} \marg{ \gls{ForEachTrackedDialect}\marg{\cmd{thisdialect}} \marg{\comment{} \gls{TrackLangRequireDialect}\marg{alien}\marg{\cmd{thisdialect}} } } \end{codebox} The caption commands and language set up are in the files \localefile{alien} as in the examples from \sectionref{sec:examples}. This allows for the user having already loaded \sty{tracklang} before \sty{alien} and used \gls{TrackLangFromEnv} to pick up the locale from the operating system's environment variables. (For example, they may have \envvar{LANG} set to \code{xx\idx{underscoresep}YY}.) The resource files may need to set the mapping between the \sty{tracklang} dialect label and the \sty{alien} dialect label. For example, in \ldf{alien}{xx-YY}: \begin{codebox*} \gls{TrackLangProvidesResource}\marg{xx-YY} \codepar \gls{TrackLangRequireResource}\marg{martian}\comment{load common elements} \codepar \cmd{newcommand}\marg{\tklcaptions{lowermartian}}\marg{\comment{} \tklcaptions{martian} \cmd{def}\cmd{contentsname}\marg{X'flurp}\comment{regional variation} } \codepar \gls{SetTrackedDialectLabelMap}\marg{\gls{CurrentTrackedDialect}}\marg{lowermartian} \end{codebox*} Now let's consider the case where \sty{tracklang} doesn't know about the \optfmt{martian} language. In this case the user can't track the dialect until the root language has been defined, so the user can't use \gls{TrackLangFromEnv} before using the \sty{alien} package. With \sty{tracklang} v1.3. The new root language can be defined with a minor adjustment to the above code: \begin{codebox*} \cmd{ProvidesPackage}\marg{alien} \codepar \gls{input}\marg{tracklang}\comment{needs v1.3} \codepar \gls{TrackLangIfKnownLang}\marg{martian} \marg{}\comment{tracklang already knows about the martian language} \marg{ \comment{tracklang doesn't known about the martian language, so define it} \comment{with \idxn{639-1} (xx) and \idxn{639-2} (xxx) codes:} \gls{TrackLangNewLanguage}\marg{martian}\marg{xx}\marg{xxx}\marg{}\marg{}\marg{}\marg{\opt{Latn}} } \end{codebox*} The rest is as before. Now other package writers who want to provide support for the Martian dialects can easily detect which language options the user requested through my package, \emph{without needing to know anything about my \sty{alien} package}. \part{Summaries} \appendix \chapter{Region and Script Mappings} \label{sec:regscriptmappings} Region mappings are listed in \tableref{tab:regionmappings}, and script mappings are listed in \tableref{tab:scriptmappings}. \printunsrttable[type=index, title={Region Mappings},other={alpha3},blocks=2, block-style={name-other-desc},label={tab:regionmappings}, init={% \renewcommand{\glstableNameTarget}[1]{\inlineglsdef[optdef]{##1}}% \renewcommand{\glstableiffilter}[3]{\glsifcategory{##1}{region}{##3}{##2}}% \renewcommand{\glstablenameheader}{Alpha-2}% \renewcommand{\glstableotherheader}{Alpha-3}% \renewcommand{\glstabledescheader}{Numeric}% \renewcommand{\glstableDesc}{\numerictag}% } ] \printunsrttable[type=index,clearpage,par=ragged, title={Script Mappings},other=userii,blocks=1, block-style={name-symbol-other-desc},label={tab:scriptmappings}, init={% \renewcommand{\glstableNameTarget}[1]{\inlineglsdef[optdef]{##1}}% \renewcommand{\glstableiffilter}[3]{\glsifcategory{##1}{script}{##3}{##2}}% \renewcommand{\glstablenameheader}{Alpha-2}% \renewcommand{\glstablesymbolheader}{Numeric}% \renewcommand{\glstableSymbol}{\numerictag}% \renewcommand{\glstableotherheader}{Direction}% } ] \backmatter \printterms \printsummary \renewcommand{\fnregion}{}% \glsdefpostname{isolangregion}{ (option)}% \glsdefpostname{rootlang}{ (root language)}% \glsdefpostname{isocode}{ (\idx{ISO} code)}% \glsdefpostname{noniso}{ (option)}% \glsdefpostname{region}{ (region)}% \glsdefpostname{script}{ (script)}% \glsdefpostname{application}{ (application)}% \printuserguideindex \end{document}