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.tex274
1 files changed, 246 insertions, 28 deletions
diff --git a/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex b/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
index c955082e67c..8ef6883f0ad 100644
--- a/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
+++ b/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
@@ -151,7 +151,8 @@ text={\appfmt{makeglossariesgui}\iapp{makeglossariesgui}}%
}%
{%
A Java GUI alternative to \gls{makeglossaries} that
- also provides diagnostic tools. Available separately on CTAN.
+ also provides diagnostic tools. Available separately on
+ \href{http://ctan.org/pkg/makeglossariesgui}{CTAN}.
}
\newglossaryentry{numberlist}{%
@@ -359,6 +360,12 @@ and~\hyperlink{option#2}{#2}}
\newcommand*{\locfmt}[1]{\texttt{#1}\SpecialMainIndex{#1}}
\newcommand*{\mkidxspch}{\index{makeindex=\appfmt{makeindex}>special characters|hyperpage}}
+\newcommand*{\mkidxopt}[1]{\texttt{-#1}\index{makeindex=\appfmt{makeindex}>#1=\texttt{-#1}|hyperpage}}
+
+\newcommand*{\xdyopt}[1]{\texttt{-#1}\index{xindy=\appfmt{xindy}>#1=\texttt{-#1}|hyperpage}}
+
+\newcommand*{\mkglsopt}[1]{\texttt{-#1}\index{makeglossaries=\appfmt{makeglossaries}>#1=\texttt{-#1}|hyperpage}}
+
\newcommand*{\igloskey}[2][newglossaryentry]{\icsopt{#1}{#2}}
\newcommand*{\gloskey}[2][newglossaryentry]{\csopt{#1}{#2}}
@@ -388,11 +395,11 @@ and~\hyperlink{option#2}{#2}}
\MakeShortVerb{"}
\DeleteShortVerb{\|}
- \title{User Manual for glossaries.sty v4.23}
+ \title{User Manual for glossaries.sty v4.25}
\author{Nicola L.C. Talbot\\%
\url{http://www.dickimaw-books.com/}}
- \date{2016-04-30}
+ \date{2016-06-09}
\maketitle
\begin{abstract}
@@ -404,8 +411,8 @@ generated either using \TeX\ or using a supplementary \gls{indexingapp}.
Additional features not provided here may be available through
the supplemental package \gls{glossaries-extra} which, if required,
needs to be installed separately. New features will be added to
-\gls*{glossaries-extra}. Any new versions of the \styfmt{glossaries}
-package after v4.21 will be just bug fixes.
+\gls*{glossaries-extra}. Versions of the \styfmt{glossaries}
+package after v4.21 will mostly be just bug fixes.
\end{abstract}
If you require multilingual support you must also separately install
@@ -470,7 +477,7 @@ package.
\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.23}.
+\qt{Documented Code for glossaries v4.25}.
\item[INSTALL] Installation instructions.
@@ -622,6 +629,17 @@ option is intended as a last resort for alphabetical sorting.}
English alphabet and you don't want to install Perl.
\begin{enumerate}
+ \item If you want to use \gls{makeindex}['s] \mkidxopt{g} option
+ you must change the quote character using \ics{GlsSetQuote}. For
+example:
+\begin{verbatim}
+\GlsSetQuote{+}
+\end{verbatim}
+ This must be used before \cs{makeglossaries}.
+ Note that if you are using \sty{babel}, the shorthands aren't
+ enabled until the start of the document, so you won't be able to use
+ the shorthands in definitions made in the preamble.
+
\item Add \cs{makeglossaries} to your preamble (before you start
defining your entries, as described in
\sectionref{sec:newglosentry}).
@@ -658,7 +676,7 @@ makeindex -s myDoc.ist -o myDoc.gls myDoc.glo
The default sort is word order (\qt{sea lion} comes before
\qt{seal}).
- If you want letter ordering you need to add the \texttt{-l}
+ If you want letter ordering you need to add the \mkidxopt{l}
switch:
\begin{verbatim}
makeindex -l -s myDoc.ist -o myDoc.gls myDoc.glo
@@ -723,8 +741,8 @@ xindy -L english -C utf8 -I xindy -M myDoc
(Replace \texttt{myDoc} with the base name of your \LaTeX\
document file. Avoid spaces in the file name. If necessary, also replace
\texttt{english} with the name of your language and \texttt{utf8}
- with your input encoding, for example, \texttt{-L german -C
- din5007-utf8}.) If you don't know
+ with your input encoding, for example,
+ \xdyopt{L}\texttt{ german }\xdyopt{C}\texttt{ din5007-utf8}.) If you don't know
how to use the command prompt, then you can probably access
\gls{xindy} via your text editor, but each editor has a
different method of doing this, so I~can't give a~general
@@ -1145,7 +1163,7 @@ You can see the difference between word and letter ordering if you
substitute \pkgopt[word]{order} with \pkgopt[letter]{order}. (Note
that this will only have an effect if you use
\gls{makeglossaries}. If you use \gls{makeindex} explicitly,
-you will need to use the \texttt{-l} switch to indicate letter
+you will need to use the \mkidxopt{l} switch to indicate letter
ordering.)
\exitem{-inline} This document is
@@ -1462,9 +1480,85 @@ description=\verb|{select group or class}}|
If you use the \sty{inputenc} package, \gls{makeglossaries}
will pick up the encoding from the auxiliary file. If you use
\gls{xindy} explicitly instead of via \gls*{makeglossaries},
-you may need to specify the encoding using the \texttt{-C}
+you may need to specify the encoding using the \xdyopt{C}
option. Read the \gls*{xindy} manual for further details.
+As from v4.24, if you are writing in German (for example, using the \sty{ngerman}
+package or \sty{babel} with the \pkgopt{ngerman} package option),
+and you want to use \gls{makeindex}['s] \mkidxopt{g} option, you'll
+need to change \gls{makeindex}['s] quote character using:
+\begin{definition}[\DescribeMacro\GlsSetQuote]
+\cs{GlsSetQuote}\marg{character}
+\end{definition}
+Note that \meta{character} may not be one of \verb"?" (question
+mark), \verb"|" (pipe) or \verb"!" (exclamation mark).
+For example:
+\begin{verbatim}
+\GlsSetQuote{+}
+\end{verbatim}
+This must be done before \ics{makeglossaries} and any entry
+definitions. It's only applicable for \app{makeindex}. This option
+in conjunction with \sty{ngerman} will also cause
+\app{makeglossaries} to use the \mkidxopt{g} switch when invoking
+\app{makeindex}.
+
+\begin{important}
+Be careful of \sty{babel}'s shorthands. These aren't switched
+on until the start of the document, so any entries defined
+in the preamble won't be able to use those shorthands.
+However, if you define the entries in the document and any
+of those shorthands happen to be special characters for
+\gls{makeindex} or \gls{xindy} (such as the double-quote)
+then this will interfere with code that tries to escape
+any of those characters that occur in the \gloskey{sort} key.
+\end{important}
+
+In general, it's best not to use \sty{babel}'s shorthands
+in entry definitions. For example:
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage[ngerman]{babel}
+\usepackage{glossaries}
+
+\GlsSetQuote{+}
+
+\makeglossaries
+
+\newglossaryentry{rna}{name={ribonukleins\"aure},
+ sort={ribonukleins"aure},
+ description={eine Nukleins\"aure}}
+
+\begin{document}
+\gls{rna}
+
+\printglossaries
+\end{document}
+\end{verbatim}
+
+The \sty{ngerman} package has the shorthands on in the preamble, so
+they can be used if \cs{GlsSetQuote} has changed the \gls{makeindex}
+quote character. Example:
+\begin{verbatim}
+\documentclass{article}
+
+\usepackage[ngerman]{babel}
+\usepackage{glossaries}
+
+\GlsSetQuote{+}
+
+\makeglossaries
+
+\newglossaryentry{rna}{name={ribonukleins"aure},
+ description={eine Nukleins"aure}}
+
+\begin{document}
+\gls{rna}
+
+\printglossaries
+\end{document}
+\end{verbatim}
+
\subsection{Changing the Fixed Names}
\label{sec:fixednames}
@@ -1938,6 +2032,9 @@ file and see if you can work it out from the \gls*{makeindex} or
problem.\footnote{Added to version \gls{makeglossaries} 2.18.} Since
\gls{xindy} doesn't warn about this, this correction is only
provided by \gls{makeglossaries} when \gls{makeindex} is used.
+(\gls{xindy} uses the order of the attributes list to determine
+which format should take precedence. See \cs{GlsAddXdyAttribute} in
+\sectionref{sec:xindyloc}.)
\end{itemize}
@@ -1951,6 +2048,12 @@ a~Lua interpreter) you don't need to install anything else in order
to use \gls{makeglossaries-lite.lua} so it's an alternative to
\gls{makeglossaries} if you want to use \opt2 (\gls{makeindex}).
+If things go wrong and you can't work out why your glossaries
+aren't being generated correctly, you can use
+\gls{makeglossariesgui} as a diagnostic tool. Once you've
+fixed the problem, you can then go back to using
+\gls{makeglossaries} or \gls{makeglossaries-lite.lua}.
+
Whilst I strongly recommended that you use the \gls{makeglossaries}
Perl script or the \gls{makeglossaries-lite.lua} Lua script, it is
possible to use the \styfmt{glossaries} package without using those
@@ -2041,15 +2144,15 @@ using \gls{xindy} or \gls{makeindex} explicitly}
\begin{tabular}{@{}lll@{}}
\bfseries Command or Package Option & \gls{makeindex} &
\gls{xindy}\\
-\pkgopt[letter]{order} & use \texttt{-l} &
- use \texttt{-M ord/letorder}\\
+\pkgopt[letter]{order} & use \mkidxopt{l} &
+ use \xdyopt{M}\texttt{ ord/letorder}\\
\pkgopt[word]{order} & default & default\\
\pkgopt{xindy}=\{\pkgoptfmt{language=}\meta{lang}\pkgoptfmt{,codename=}\meta{code}\} &
-N/A & use \texttt{-L} \meta{lang} \texttt{-C} \meta{code}\\
+N/A & use \xdyopt{L} \meta{lang} \xdyopt{C} \meta{code}\\
\ics{GlsSetXdyLanguage}\marg{lang} & N/A &
-use \texttt{-L} \meta{lang}\\
+use \xdyopt{L} \meta{lang}\\
\ics{GlsSetXdyCodePage}\marg{code} & N/A &
-use \texttt{-C} \meta{code}
+use \xdyopt{C} \meta{code}
\end{tabular}
\par
\end{table}
@@ -2103,10 +2206,10 @@ help diagnose problems. If this method fails \gls{makeglossaries}
will print an \qt{Unable to fork} warning and will retry without
redirection. If you run \gls{makeglossaries} on an operating system
that doesn't support this form of redirection, then you can use the
-\texttt{-Q} switch to suppress this warning or you can use the
-\texttt{-k} switch to make \gls{makeglossaries} automatically use
+\mkglsopt{Q} switch to suppress this warning or you can use the
+\mkglsopt{k} switch to make \gls{makeglossaries} automatically use
the fallback method without attempting the redirection. Without this
-redirection, the \texttt{-q} (quiet) switch doesn't work as well.
+redirection, the \mkglsopt{q} (quiet) switch doesn't work as well.
You can specify in which directory the \filetype{.aux},
\filetype{.glo} etc files are located using the \texttt{-d} switch.
@@ -2118,8 +2221,8 @@ makeglossaries -d myTmpDir myDoc
Note that \gls*{makeglossaries} assumes by default that
\gls*{makeindex}\slash\gls*{xindy} is on your operating system's
path. If this isn't the case, you can specify the full pathname
-using \texttt{-m} \meta{path/to/makeindex} for \gls*{makeindex}
-or \texttt{-x} \meta{path/to/xindy} for \gls*{xindy}.
+using \mkglsopt{m} \meta{path/to/makeindex} for \gls*{makeindex}
+or \mkglsopt{x} \meta{path/to/xindy} for \gls*{xindy}.
As from \gls{makeglossaries} v2.18, if you are using
\gls{makeindex}, there's a check for \gls*{makeindex}['s] multiple
@@ -2156,7 +2259,7 @@ resulting file onto the man path. Alternatively do
\begin{important}
When upgrading the \styfmt{glossaries} package, make sure you also
upgrade your version of \gls{makeglossaries}. The current version is
-2.18.
+2.19.
\end{important}
\subsection{Using the makeglossaries-lite.lua Lua Script}
@@ -2170,7 +2273,7 @@ light-weight it doesn't have the full-functionality of heavy-weight
scripting languages, such as Perl. The \gls{makeglossaries-lite.lua}
script is therefore limited by this and some of the options
available to the \gls{makeglossaries} Perl script aren't available
-here. (In particular the \texttt{-d} option.)
+here. (In particular the \mkglsopt{d} option.)
The \gls{makeglossaries-lite.lua} script can be invoked in the same way
as \gls{makeglossaries} but you need to remember the \texttt{.lua}
@@ -2208,7 +2311,7 @@ This is required regardless of whether you use \gls{xindy}
explicitly or whether it's called implicitly via applications such
as \gls{makeglossaries} or \gls{makeglossariesgui}. This causes the glossary
entries to be written in raw \gls*{xindy} format, so you need to
-use \texttt{-I xindy} \emph{not} \texttt{-I tex}.
+use \xdyopt{I}\texttt{ xindy} \emph{not} \xdyopt{I}\texttt{ tex}.
To run \gls{xindy} type the following in your terminal
(all on one line):
@@ -2274,7 +2377,7 @@ where \meta{base} is the name of your document without the
name of the \gls{makeindex} style file. By default, this is
\meta{base}\filetype{.ist}, but may be changed via
\ics{setStyleFile}\marg{style}. Note that there are other options,
-such as \texttt{-l} (letter ordering). See the \gls*{makeindex}
+such as \mkidxopt{l} (letter ordering). See the \gls*{makeindex}
manual for further details.
For example, if your document is called \texttt{myDoc.tex}, then
@@ -2393,6 +2496,7 @@ package. Options that aren't \meta{key}=\meta{value} (such as
the \styfmt{glossaries} package. Don't use this option if you're new to using
\styfmt{glossaries} as the warnings are designed to help detect
common mistakes (such as forgetting to use \ics{makeglossaries}).
+Note that the \pkgopt[true]{debug} will override this option.
\item[\pkgopt{noredefwarn}] If you load \styfmt{glossaries} with
a~class or another package that already defines glossary related
@@ -2403,6 +2507,65 @@ want to be warned about it, use this option to suppress those
warnings. Other warnings will still be issued unless you use the
\pkgopt{nowarn} option described above.
+\item[\pkgopt{debug}] Introduced in version 4.24, this boolean
+option switches on the debug mode. Note that the debug mode will automatically
+cancel the \pkgopt{nowarn} option. Consider the following example
+document:
+\begin{verbatim}
+\documentclass{article}
+\usepackage{glossaries}
+\newglossaryentry{sample1}{name={sample1},description={example}}
+\newglossaryentry{sample2}{name={sample2},description={example}}
+\glsadd{sample2}
+\makeglossaries
+\begin{document}
+\gls{sample1}.
+\printglossaries
+\end{document}
+\end{verbatim}
+Here, only the \texttt{sample1} entry has been indexed, even
+though \verb|\glsadd{sample2}| appears in the source code.
+This is because the associated file is opened by
+\ics{makeglossaries}, but \verb|\glsadd{sample2}| has been used
+before this command. Since the file isn't open yet, the
+information can't be written to it, which is why the
+\texttt{sample2} entry doesn't appear in the glossary.
+
+This situation doesn't cause any errors or warnings as it's
+perfectly legitimate for a user to want to use \styfmt{glossaries}
+to format the entries (e.g.\ abbreviation expansion) but not display
+any lists of terms, abbreviations, symbols etc.
+Without \cs{makeglossaries} (or \cs{makenoidxglossaries})
+the indexing is suppressed but, other than that, commands
+like \cs{gls} behave as usual.
+
+The debug mode, enabled with the \pkgopt{debug} option,
+will write information to the log file when the indexing
+can't occur because the associated file isn't open.
+The message is written in the form
+\begin{quote}
+Package glossaries Info: wrglossary(\meta{type})(\meta{line}) on
+input line \meta{line number}.
+\end{quote}
+where \meta{type} is the glossary label and \meta{line} is the line
+of text that would've been written to the associated file if
+it had been open. So if any entries haven't appeared in the
+glossary but you're sure you used commands like \cs{glsadd}
+or \cs{glsaddall}, try switching on the \pkgopt{debug} option
+and see if any information has been written to the log file.
+
+\item[\pkgopt{seenoindex}] Introduced in version 4.24, this option
+may take one of three values: \pkgoptfmt{error}, \pkgoptfmt{warn} or
+\pkgoptfmt{ignore}. The \gloskey{see} key automatically indexes the
+cross-referenced entry using \cs{glsadd}. This means that it suffers
+from the same problem as the above. If used before the relevant
+glossary file has been opened, the indexing can't be performed.
+Since this is easy to miss, the \styfmt{glossaries} package by
+default issues an error message if the \gloskey{see} key is used
+before \cs{makeglossaries}. This option allows you to change the
+error into just a warning (\pkgopt[warn]{seenoindex}) or
+ignore it (\pkgopt[ignore]{seenoindex}).
+
\item[\pkgopt{nomain}] This suppresses the creation of the main
glossary and associated \texttt{.glo} file, if unrequired. Note that
if you use this option, you must create another glossary in which to
@@ -3768,8 +3931,12 @@ list}\marg{long description}
(These are both preamble-only commands.)
For all the above commands, the first argument, \meta{label}, must be
-a~unique label with which to identify this entry. This can't contain
-any non-expandable commands or active characters.
+a~unique label with which to identify this entry. \textbf{This can't contain
+any non-expandable commands or active characters.} The reason for
+this restriction is that the label is used to construct internal commands
+that store the associated information (similarly to commands
+like \cs{label}) and therefore must be able to expand to a valid
+control sequence name.
\begin{important}
Note that although an \gls{exlatinchar} or other \gls{nonlatinchar},
@@ -5216,6 +5383,31 @@ which is described in \sectionref{sec:customxr}.
\cs{glsnumberlistloop} is not available for \optsand23.
\end{important}
+As from version 4.24, there's a hook that's used near the end of
+\ics{writeist} before the file is closed. You can set the code
+to be performed then using:
+\begin{definition}[\DescribeMacro\GlsSetWriteIstHook]
+\cs{GlsSetWriteIstHook}\marg{code}
+\end{definition}
+If you want the \meta{code} to write any information to the
+file, you need to use
+\begin{definition}[\DescribeMacro\glswrite]
+\cs{write}\cs{glswrite}\marg{style information}
+\end{definition}
+Make sure you use the correct format within \meta{style
+information}. For example, if you are using \app{makeindex}:
+\begin{verbatim}
+\GlsSetWriteIstHook{%
+ \write\glswrite{page_precedence "arnAR"}%
+ \write\glswrite{line_max 80}%
+}
+\end{verbatim}
+This changes the page type precedence\index{page type precedence} and the maximum line length
+used by \app{makeindex}.
+
+Remember that if you switch to \app{xindy}, this will no longer be
+valid code.
+
\chapter{Links to Glossary Entries}
\label{sec:glslink}
@@ -7220,6 +7412,11 @@ will appear in the normal font. The hierarchical glossary styles
(defined in the \sty{glossary-tree} style file) also set the name in
bold.
+If you want to change the font for the description, or if you
+only want to change the name font for some types of entries
+but not others, you might want to consider using the
+\sty{glossaries-extra} package.
+
\begin{example}{Changing the Font Used to Display Entry Names in the
Glossary}{ex:glsnamefont}
Suppose you want all the entry names to appear in
@@ -7349,7 +7546,7 @@ The commands \cs{GlsSetXdyLanguage} and \cs{GlsSetXdyCodePage}
have no effect if you don't use \gls{makeglossaries}. If
you call \gls{xindy} without \gls*{makeglossaries} you
need to remember to set the language and encoding using the
-\texttt{-L} and \texttt{-C} switches.
+\xdyopt{L} and \xdyopt{C} switches.
\end{important}
\section{Locations and Number lists}
@@ -7378,6 +7575,23 @@ attribute, you need to add it using:
where \meta{name} is the name of the attribute, as used in
the \gloskey[glslink]{format} key.
+Take care if you have multiple instances of the same location with
+different formats. The duplicate locations will be discarded
+according to the order in which the attributes are listed. Consider
+defining semantic commands to use for primary references. For
+example:
+\begin{verbatim}
+\newcommand*{\primary}[1]{\textbf{#1}}
+\GlsAddXdyAttribute{primary}
+\end{verbatim}
+Then in the document:
+\begin{verbatim}
+A \gls[format=primary]{duck} is an aquatic bird.
+There are lots of different types of \gls{duck}.
+\end{verbatim}
+This will give the \verb|format=primary| instance preference over
+the next use that doesn't use the \gloskey[glslink]{format} key.
+
\begin{example}{Custom Font for Displaying a Location}{ex:hyperbfit}
Suppose I want a bold, italic, hyperlinked location. I first need to define a
command that will do this:
@@ -7764,6 +7978,10 @@ argument. The \cs{newacronym} command also uses the \gloskey{long},
in \cs{newglossaryentry} to store the long and abbreviated forms and
their plurals.
+Note that the same restrictions on the entry \meta{label}
+in \ics{newglossaryentry} also apply to \cs{newacronym}
+(see \sectionref{sec:newglosentry}).
+
\begin{important}
If you haven't identified the specified glossary type as a list of
acronyms (via the package option