diff options
Diffstat (limited to 'Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex')
| -rw-r--r-- | Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex | 391 |
1 files changed, 309 insertions, 82 deletions
diff --git a/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex b/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex index 8044fbe865b..4855b1d9bd5 100644 --- a/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex +++ b/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex @@ -367,11 +367,11 @@ and~\hyperlink{option#2}{#2}} \MakeShortVerb{"} \DeleteShortVerb{\|} - \title{User Manual for glossaries.sty v4.11} + \title{User Manual for glossaries.sty v4.12} \author{Nicola L.C. Talbot\\% \url{http://www.dickimaw-books.com/}} - \date{2014-09-01} + \date{2014-11-22} \maketitle \begin{abstract} @@ -381,6 +381,15 @@ Sorted lists with collated \glslink{entrylocation}{locations} can be generated either using \TeX\ or using a supplementary \gls{indexingapp}. \end{abstract} +If you require multilingual support you must also install +the relevant language module. Each language module is called +\texttt{glossaries-}\meta{language}, where \meta{language} is the +root language name. For example, \texttt{glossaries-french} +or \texttt{glossaries-german}. If a language module is required, +the \styfmt{glossaries} package will automatically try to load it and +will give a warning if the module isn't found. See +\sectionref{sec:languages} for further details. + \begin{important} Documents have various styles when it comes to presenting glossaries or lists of terms or notation. People have their own preferences and @@ -424,7 +433,7 @@ letter}{mfirstuc-manual}. \item[\url{glossaries-code.pdf}] Advanced users wishing to know more about the inner workings of all the packages provided in the \styfmt{glossaries} bundle should read -\qt{Documented Code for glossaries v4.11}. +\qt{Documented Code for glossaries v4.12}. This includes the documented code for the \sty{mfirstuc} package. \item[INSTALL] Installation instructions. @@ -1335,9 +1344,10 @@ If you want to use \gls*{xindy}, remember to use the \begin{important} Note that although a~\gls{nonlatinchar}, such as \'e, looks like a plain -character in your tex file, it's actually a~macro and can therefore +character in your tex file, with standard \LaTeX\ it's actually a~macro and can therefore cause expansion problems. You may need to switch off the field -expansions with \cs{glsnoexpandfields}. +expansions with \cs{glsnoexpandfields}. This issue doesn't occur +with \XeLaTeX. If you use a~\gls{nonlatinchar} (or other expandable) character at the start of an entry name, you must place it in a group, or it will cause @@ -1361,79 +1371,34 @@ option. Read the \gls*{xindy} manual for further details. \subsection{Changing the Fixed Names} \label{sec:fixednames} -As from version 1.08, the \styfmt{glossaries} package now has -limited multi-lingual support, thanks to all the people who have sent -me the relevant translations either via email or via -\texttt{comp.text.tex}. -However you must load \sty{babel} or \sty{polyglossia} \emph{before} -\styfmt{glossaries} to enable this. Note that if \sty{babel} is loaded -and the \sty{translator} package is detected on \TeX's path, then the -\sty{translator} package will be loaded automatically, unless you -use the \pkgopt[false]{translate} or \pkgopt[babel]{translate} -package options. However, -it may not pick up on the required languages so, if the predefined -text is not translated, you may need to explicitly load the -\sty{translator} package with the required languages. For example: -\begin{verbatim} -\usepackage[spanish]{babel} -\usepackage[spanish]{translator} -\usepackage{glossaries} -\end{verbatim} -Alternatively, specify the language as a class option rather -than a package option. For example: -\begin{verbatim} -\documentclass[spanish]{report} - +The fixed names are produced using the commands listed in +\tableref{tab:predefinednames}. If you aren't using a language +package such as \sty{babel} or \sty{polyglossia} that uses caption +hooks, you can just redefine these commands as appropriate. If you +are using \sty{babel} or \sty{polyglossia}, you need to use their +caption hooks to change the defaults. See \urlref{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=latexwords}{changing +the words babel uses} or read the \sty{babel} or \sty{polyglossia} +documentation. If you have loaded \sty{babel}, then \sty{glossaries} +will attempt to load \sty{translator}, unless you have used the +\pkgopt{notranslate}, \pkgopt[false]{translate} or \pkgopt[babel]{translate} +package options. If the \sty{translator} package is loaded, the +translations are provided by dictionary files (for example, +\texttt{glossaries-dictionary-English.dict}). See the +\sty{translator} package for advice on changing translations provided by +\sty{translator} dictionaries. If you can't work out how to modify +these dictionary definitions, try switching to \sty{babel}'s +interface using \pkgopt[babel]{translate}: +\begin{verbatim} +\documentclass[english,french]{article} \usepackage{babel} -\usepackage{glossaries} -\end{verbatim} - -If you want to use \sty{ngerman} or \sty{german} instead -of \sty{babel}, you will need to include the \sty{translator} package -to provide the translations. For example: -\begin{verbatim} -\documentclass[ngerman]{article} -\usepackage{ngerman} -\usepackage{translator} -\usepackage{glossaries} +\usepackage[translate=babel]{glossaries} \end{verbatim} - -The languages are currently supported by the -\styfmt{glossaries} package are listed in -\tableref{tab:supportedlanguages}. Please note that (apart from -spelling mistakes) I don't intend to change the default translations -as it will cause compatibility problems. - -If you want to add a~language not currently supported, you can post -the contents of your \texttt{.dict} file on my feature request form -at \url{http://www.dickimaw-books.com/feature-request.html}. Please -use \LaTeX\ commands for \glspl{nonlatinchar} as the file must be -independent of the input encoding otherwise it won't be of any use -to people who use a~different encoding to yourself. - -\begin{table}[htbp] -\caption{Supported Languages} -\label{tab:supportedlanguages} -\centering -\begin{tabular}{lc} -\bfseries Language & \bfseries As from version\\ -Brazilian Portuguese & 1.17\\ -Danish & 1.08\\ -Dutch & 1.08\\ -English & 1.08\\ -French & 1.08\\ -German & 1.08\\ -Irish & 1.08\\ -Italian & 1.08\\ -Hungarian & 1.08\\ -Polish & 1.13\\ -Serbian & 2.06\\ -Spanish & 1.08 -\end{tabular} -\end{table} - -The language dependent commands and \sty{translator} keys used by the -glossaries package are listed in \tableref{tab:predefinednames}. +and then use \sty{babel}'s caption hook mechanism. Note that if you +pass the language options directly to \sty{babel} rather that using +the document class options or otherwise passing the same options to +\sty{translator}, then \sty{translator} won't pick up the +language and no dictionaries will be loaded and \sty{babel}'s +caption hooks will be used instead. \begin{table}[htbp] \caption{Customised Text} @@ -1466,6 +1431,272 @@ this option. \end{tabular} \end{table} +As from version 4.12, multilingual support is provided by separate +language modules that need to be installed in addition to installing +the \styfmt{glossaries} package. You only need to install the +modules for the languages that you require. If the language module +has an unmaintained status, you can volunteer to take over the +maintenance by contacting me at +\url{http://www.dickimaw-books.com/contact.html}. The +\sty{translator} dictionary files for \styfmt{glossaries} are now +provided by the appropriate language module. + +Examples of use: +\begin{itemize} +\item Using \sty{babel} and \sty{translator}: +\begin{verbatim} +\documentclass[english,french]{article} +\usepackage{babel} +\usepackage{glossaries} +\end{verbatim} +(\sty{translator} is automatically loaded). + +\item Using \sty{babel}: +\begin{verbatim} +\documentclass[english,french]{article} +\usepackage{babel} +\usepackage[translate=babel]{glossaries} +\end{verbatim} +(\sty{translator} isn't loaded). + +\item Using \sty{polyglossia}: +\begin{verbatim} +\documentclass{article} +\usepackage{polyglossia} +\setmainlanguage{english} +\usepackage{glossaries} +\end{verbatim} + +\item Using \sty{ngerman}: +\begin{verbatim} +\documentclass{article} +\usepackage{ngerman} +\usepackage{glossaries} +\end{verbatim} + +\end{itemize} + +The \styfmt{glossaries} package now uses the \sty{tracklang} package +to determine which language modules need to be loaded. If you want +to create a new language module, you should first read the +\sty{tracklang} documentation. + +To create a new language module, you need to at least create two +files: \texttt{glossaries-}\meta{lang}\texttt{.ldf} and +\texttt{glossaries-dictionary-}\meta{Lang}\texttt{.dict} where +\meta{lang} is the root language name (for example, +\texttt{english}) and \meta{Lang} is the language name used by +\sty{translator} (for example, \texttt{English}). + +Here's an example of \texttt{glossaries-dictionary-English.dict}: +\begin{verbatim} +\ProvidesDictionary{glossaries-dictionary}{English} + +\providetranslation{Glossary}{Glossary} +\providetranslation{Acronyms}{Acronyms} +\providetranslation{Notation (glossaries)}{Notation} +\providetranslation{Description (glossaries)}{Description} +\providetranslation{Symbol (glossaries)}{Symbol} +\providetranslation{Page List (glossaries)}{Page List} +\providetranslation{Symbols (glossaries)}{Symbols} +\providetranslation{Numbers (glossaries)}{Numbers} +\end{verbatim} +You can use this as a template for your dictionary file. Change +\texttt{English} to the \sty{translator} name for your language +(so that it matches the file name +\texttt{glossaries-dictionary-}\meta{Lang}\texttt{.dict}) +and, for each \cs{providetranslation}, change the second argument to +the appropriate translation. + +Here's an example of \texttt{glossaries-english.ldf}: +\begin{verbatim} +\ProvidesGlossariesLang{english} + +\glsifusedtranslatordict{English} +{% + \addglossarytocaptions{\CurrentTrackedLanguage}% + \addglossarytocaptions{\CurrentTrackedDialect}% +} +{% + \@ifpackageloaded{polyglossia}% + {% + \newcommand*{\glossariescaptionsenglish}{% + \renewcommand*{\glossaryname}{\textenglish{Glossary}}% + \renewcommand*{\acronymname}{\textenglish{Acronyms}}% + \renewcommand*{\entryname}{\textenglish{Notation}}% + \renewcommand*{\descriptionname}{\textenglish{Description}}% + \renewcommand*{\symbolname}{\textenglish{Symbol}}% + \renewcommand*{\pagelistname}{\textenglish{Page List}}% + \renewcommand*{\glssymbolsgroupname}{\textenglish{Symbols}}% + \renewcommand*{\glsnumbersgroupname}{\textenglish{Numbers}}% + }% + }% + {% + \newcommand*{\glossariescaptionsenglish}{% + \renewcommand*{\glossaryname}{Glossary}% + \renewcommand*{\acronymname}{Acronyms}% + \renewcommand*{\entryname}{Notation}% + \renewcommand*{\descriptionname}{Description}% + \renewcommand*{\symbolname}{Symbol}% + \renewcommand*{\pagelistname}{Page List}% + \renewcommand*{\glssymbolsgroupname}{Symbols}% + \renewcommand*{\glsnumbersgroupname}{Numbers}% + }% + }% + \ifcsdef{captions\CurrentTrackedDialect} + {% + \csappto{captions\CurrentTrackedDialect}% + {% + \glossariescaptionsenglish + }% + }% + {% + \ifcsdef{captions\CurrentTrackedLanguage} + { + \csappto{captions\CurrentTrackedLanguage}% + {% + \glossariescaptionsenglish + }% + }% + {% + }% + }% + \glossariescaptionsenglish +} +\renewcommand*{\glspluralsuffix}{s} +\renewcommand*{\glsacrpluralsuffix}{\glspluralsuffix} +\renewcommand*{\glsupacrpluralsuffix}{\glstextup{\glspluralsuffix}} +\end{verbatim} +This is a somewhat longer file, but again you can use it as a +template. Replace \texttt{English} with the \sty{translator} +language label \meta{Lang} used for the dictionary file and +replace \texttt{english} with the root language name \meta{lang}. Within the +definition of \cs{glossariescaptions}\meta{lang}, replace the +English text (such as \qt{Glossaries}) with the appropriate +translation. + +\textbf{Note:} the suffixes used to generate the plural forms when +the plural hasn't been specified are given by +\cs{glspluralsuffix} (for general entries) and +\cs{glsupacrpluralsuffix} for acronyms where the suffix needs to be +set using \cs{glstextup} to counteract the effects of \cs{textsc} +and \cs{glsacrpluralsuffix} for other acronym styles. These commands +need to be set before the entry is defined and so the definitions +aren't included in the caption mechanism as that's not switched on +until the start of the document. This means that the suffix in +effect will be for the last loaded language. + +If you want to add a regional variation, create a file called +\texttt{glossaries-}\meta{iso lang}\texttt{-}\meta{iso +country}\texttt{.ldf}, where \meta{iso lang} is the ISO language +code and \meta{iso country} is the ISO country code. For example, +\texttt{glossaries-en-GB.ldf}. This file can load the root +language file and make the appropriate changes, for example: +\begin{verbatim} + \ProvidesGlossariesLang{en-GB} + \RequireGlossariesLang{english} + \glsifusedtranslatordict{British} + {% + \addglossarytocaptions{\CurrentTrackedLanguage}% + \addglossarytocaptions{\CurrentTrackedDialect}% + } + {% + \@ifpackageloaded{polyglossia}% + {% + % Modify \glossariescaptionsenglish as appropriate for + % polyglossia + }% + {% + % Modify \glossariescaptionsenglish as appropriate for + % non-polyglossia + }% + } +\end{verbatim} + +If the translations includes \glspl{nonlatinchar}, it's necessary to +provide code that's independent of the input encoding. Remember that +while some users may use UTF-8, others may use Latin-1 or any other +supported encoding, but while users won't appreciate you enforcing +your preference on them, it's useful to provide a UTF-8 version for +\XeLaTeX\ users. + +The \texttt{glossaries-irish.ldf} file provides this as follows: +\begin{verbatim} +\ProvidesGlossariesLang{irish} + +\glsifusedtranslatordict{Irish} +{% + \addglossarytocaptions{\CurrentTrackedLanguage}% + \addglossarytocaptions{\CurrentTrackedDialect}% +} +{% + \ifdefstring{\inputencodingname}{utf8} + {\input{glossaries-irish-utf8.ldf}}% + {% + \ifdef{\XeTeXinputencoding}% XeTeX defaults to UTF-8 + {\input{glossaries-irish-utf8.ldf}}% + {\input{glossaries-irish-noenc.ldf}} + } + \ifcsdef{captions\CurrentTrackedDialect} + {% + \csappto{captions\CurrentTrackedDialect}% + {% + \glossariescaptionsirish + }% + }% + {% + \ifcsdef{captions\CurrentTrackedLanguage} + { + \csappto{captions\CurrentTrackedLanguage}% + {% + \glossariescaptionsirish + }% + }% + {% + }% + }% + \glossariescaptionsirish +} +\end{verbatim} +(Again you can use this as a template. Replace \texttt{irish} with +your root language label and \texttt{Irish} with the +\sty{translator} dictionary label.) + +There are now two extra files: \texttt{glossaries-irish-noenc.ldf} +and \texttt{glossaries-irish-utf8.ldf}. These both define +\cs{glossariescaptionsirish} but the \texttt{*-noenc.ldf} uses +\LaTeX\ accent commands: +\begin{verbatim} +\@ifpackageloaded{polyglossia}% +{% + \newcommand*{\glossariescaptionsirish}{% + \renewcommand*{\glossaryname}{\textirish{Gluais}}% + \renewcommand*{\acronymname}{\textirish{Acrainmneacha}}% + \renewcommand*{\entryname}{\textirish{Ciall}}% + \renewcommand*{\descriptionname}{\textirish{Tuairisc}}% + \renewcommand*{\symbolname}{\textirish{Comhartha}}% + \renewcommand*{\glssymbolsgroupname}{\textirish{Comhartha\'{\i}}}% + \renewcommand*{\pagelistname}{\textirish{Leathanaigh}}% + \renewcommand*{\glsnumbersgroupname}{\textirish{Uimhreacha}}% + }% +}% +{% + \newcommand*{\glossariescaptionsirish}{% + \renewcommand*{\glossaryname}{Gluais}% + \renewcommand*{\acronymname}{Acrainmneacha}% + \renewcommand*{\entryname}{Ciall}% + \renewcommand*{\descriptionname}{Tuairisc}% + \renewcommand*{\symbolname}{Comhartha}% + \renewcommand*{\glssymbolsgroupname}{Comhartha\'{\i}}% + \renewcommand*{\pagelistname}{Leathanaigh}% + \renewcommand*{\glsnumbersgroupname}{Uimhreacha}% + }% +} +\end{verbatim} +whereas the \texttt{*-utf8.ldf} replaces the accent commands with +the appropriate UTF-8 characters. + + Due to the varied nature of glossaries, it's likely that the predefined translations may not be appropriate. If you are using the \sty{babel} package and the \styfmt{glossaries} package option \pkgopt[babel]{translate}, you need to be familiar with the advice given in @@ -1476,7 +1707,7 @@ modifications (using \cs{deftranslation}) and load it using \cs{usedictionary}. \begin{important} -Note that the dictionaries are loaded at the beginning of the +Note that the \sty{translator} dictionaries are loaded at the beginning of the document, so it won't have any effect if you put \cs{deftranslation} in the preamble. It should be put in your personal dictionary instead (as in the example below). See the \sty{translator} @@ -1522,12 +1753,8 @@ option \pkgopt[babel]{translate}. For example: } \end{verbatim} -If you are using \sty{polyglossia} instead of \sty{babel}, -\sty{glossaries-polyglossia} will automatically be loaded unless -you specify the package option \pkgopt[false]{translate}. - Note that \gls{xindy} provides much better multi-lingual support -than \gls{makeindex}, so it's recommended that you use \gls*{xindy} +than \gls{makeindex}, so I~recommend that you use \gls*{xindy} if you have glossary entries that contain \glspl{nonlatinchar}. See \sectionref{sec:xindy} for further details. |