summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex')
-rw-r--r--Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex391
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.