diff options
Diffstat (limited to 'macros/generic/tracklang/tracklang-manual.tex')
-rw-r--r-- | macros/generic/tracklang/tracklang-manual.tex | 5641 |
1 files changed, 5641 insertions, 0 deletions
diff --git a/macros/generic/tracklang/tracklang-manual.tex b/macros/generic/tracklang/tracklang-manual.tex new file mode 100644 index 0000000000..a141ea906b --- /dev/null +++ b/macros/generic/tracklang/tracklang-manual.tex @@ -0,0 +1,5641 @@ +% 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}\margm{version info}} + \desc{analogous to \gls{ProvidesFile}} + } + % \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<Code> + \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}{} % <prefix>-<localeid>.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 + % 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{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<dialect> + \gcmdmeta{date}{dialect}{}{}% \date<dialect> + \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: +tracking language options} +\author{Nicola L.C. Talbot\\[10pt] +Dickimaw Books\\ +\href{https://www.dickimaw-books.com/}{\nolinkurl{dickimaw-books.com}}} +\date{2022-10-29 +} + +\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. + +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} |