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.tex1176
1 files changed, 950 insertions, 226 deletions
diff --git a/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex b/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
index dbc79467c05..8da3d8bcaf0 100644
--- a/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
+++ b/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
@@ -20,7 +20,14 @@
pdftitle={User Manual for glossaries.sty},
pdfkeywords={LaTeX,package,glossary,acronyms}]{hyperref}
\usepackage{xr-hyper}
-\usepackage[xindy,nonumberlist,seeautonumberlist,toc,nogroupskip,style=altlist]{glossaries}
+\usepackage[
+ xindy,
+ nonumberlist,
+ toc,
+ nopostdot,
+ nogroupskip,
+ style=altlist
+]{glossaries}
\usepackage{glossary-inline}
\pagestyle{headings}
@@ -37,8 +44,8 @@
\begin{tabbing}
\cs{usepackage}[\=xindy,\\
\+\>nonumberlist,\\
- seeautonumberlist,\\
toc,\\
+ nopostdot,\\
style=altlist,\\
nogroupskip]\{glossaries\}
\end{tabbing}
@@ -109,7 +116,7 @@
name={\appfmt{makeindex}\index{makeindex=\appfmt{makeindex}|htextbf}},%
sort={makeindex},%
text={\appfmt{makeindex}\iapp{makeindex}},%
-description={An \gls{indexingapp}},
+description={An \gls{indexingapp}.},
}
\newglossaryentry{makeglossaries}{%
@@ -118,7 +125,7 @@ sort={makeglossaries},%
text={\appfmt{makeglossaries}\iapp{makeglossaries}},%
description={A custom designed Perl script interface
to \gls{xindy} and \gls{makeindex} provided with the \styfmt{glossaries}
-package}
+package.}
}
\longnewglossaryentry{makeglossariesgui}{%
@@ -137,7 +144,7 @@ sort={number list},%
text={number list\iterm{number list}},%
description={A list of \glslink{entrylocation}{entry locations} (also
called a location list). The number list can be suppressed using the
-\pkgopt{nonumberlist} package option}
+\pkgopt{nonumberlist} package option.}
}
\newglossaryentry{entrylocation}{%
@@ -146,15 +153,15 @@ sort={entry location},%
text={entry location\iterm{entry location}},%
description={The location of the entry in the document. This
defaults to the page number on which the entry appears. An entry may
-have multiple locations}
+have multiple locations.}
}
\newglossaryentry{locationlist}{%
name={Location list},%
text={location list},
sort={location list},%
-description={A list of \glslink{entrylocation}{entry locations}},%
-see={numberlist}
+description={A list of \glslink{entrylocation}{entry locations}.
+See \gls{numberlist}.}%
}
\newglossaryentry{linktext}{%
@@ -162,7 +169,7 @@ name={Link text\itermdef{link text}},
sort={link text},%
text={link text\iterm{link text}},
description={The text produced by commands such as \ics{gls}. It may
-or may not be a hyperlink to the glossary}
+or may not be a hyperlink to the glossary.}
}
\let\glsd\glsuseri
@@ -200,7 +207,7 @@ text={first use text},%
description={The text that is displayed on \gls{firstuse}, which is
governed by the \gloskey{first} and \gloskey{firstplural} keys of
\ics{newglossaryentry}. (May be overridden by
-\ics{glsdisp}.)\nopostdesc}%
+\ics{glsdisp}.)}%
}
\longnewglossaryentry{sanitize}{%
@@ -223,6 +230,68 @@ user2={sanitization\protect\iterm{sanitize}}%
for the \gloskey{sort} key.
}
+\newglossaryentry{latinchar}{%
+ name={Latin Character\itermdef{Latin character}},
+ text={Latin character\iterm{Latin character}},
+ sort={Latin character},
+ description={One of the letters \texttt{a}, \ldots, \texttt{z},
+ \texttt{A}, \ldots, \texttt{Z}.
+ See also \gls{exlatinchar}.}
+}
+
+\newglossaryentry{exlatinchar}{%
+ name={Extended Latin Character\itermdef{extended Latin character}},
+ text={extended Latin character\iterm{extended Latin character}},
+ sort={extended Latin character},
+ description={A character that's created by combining \glspl{latinchar}
+ to form ligatures (e.g.\ \ae) or by applying diacritical marks
+ to a~\gls*{latinchar} or characters (e.g.\ \'a or \o).
+ See also \gls{nonlatinchar}.}
+}
+
+\newglossaryentry{latexexlatinchar}{%
+ name={Standard \LaTeX\ Extended Latin Character\itermdef{standard
+\LaTeX\ extended Latin character}},
+ text={standard \LaTeX\ extended Latin character\iterm{standard
+\LaTeX\ extended Latin character}},
+ sort={standard LaTeX extended Latin character},
+ description={An \gls{exlatinchar} that can be created by a~core
+\LaTeX\ command, such as \cs{o} (\o) or \cs{'}\texttt{e} (\'e).
+ That is, the character can be produced without the need to load
+ a~particular package.}
+}
+
+\newglossaryentry{nonlatinchar}{%
+ name={Non-Latin Character\itermdef{non-Latin character}},
+ text={non-Latin character\iterm{non-Latin character}},
+ sort={non-Latin character},
+ description={An \gls{exlatinchar} or a~character from
+ a~non-\gls{latinalph}.}
+}
+
+\newglossaryentry{latinalph}{%
+ name={Latin Alphabet\itermdef{Latin alphabet}},
+ text={Latin alphabet\iterm{Latin alphabet}},
+ sort={Latin alphabet},
+ description={The alphabet consisting of \glspl{latinchar}.
+ See also \gls{exlatinalph}.}
+}
+
+\newglossaryentry{exlatinalph}{%
+ name={Extended Latin Alphabet\itermdef{Extended Latin Alphabet}},
+ text={extended Latin alphabet},
+ sort={extended Latin alphabet},
+ description={An alphabet consisting of \glspl{latinchar}
+ and \glspl{exlatinchar}.}
+}
+
+\newglossaryentry{nonlatinalph}{%
+ name={Non-Latin Alphabet\itermdef{Non-Latin Alphabet}},
+ text={non-Latin alphabet},
+ sort={non-Latin alphabet},
+ description={An alphabet consisting of \glspl{nonlatinchar}.}
+}
+
\ifpdf
\externaldocument{glossaries-code}
\fi
@@ -236,6 +305,21 @@ user2={sanitization\protect\iterm{sanitize}}%
\newcommand*{\tick}{\ding{51}}
+\newcommand*{\yes}{\ding{52}}
+\newcommand*{\no}{\ding{56}}
+
+\makeatletter
+\newcommand*{\optionlabel}[1]{%
+ \@glstarget{option#1}{}\textbf{Option~#1}}
+\makeatother
+
+\newcommand*{\opt}[1]{\hyperlink{option#1}{Option~#1}}
+\newcommand*{\optsor}[2]{Options~\hyperlink{option#1}{#1}
+or~\hyperlink{option#2}{#2}}
+\newcommand*{\optsand}[2]{Options~\hyperlink{option#1}{#1}
+and~\hyperlink{option#2}{#2}}
+
+
\newcommand*{\ifirstuse}{\iterm{first use}}
\newcommand*{\ifirstuseflag}{\iterm{first use>flag}}
\newcommand*{\ifirstusetext}{\iterm{first use>text}}
@@ -278,11 +362,11 @@ user2={sanitization\protect\iterm{sanitize}}%
\MakeShortVerb{"}
\DeleteShortVerb{\|}
- \title{User Manual for glossaries.sty v4.03}
+ \title{User Manual for glossaries.sty v4.04}
\author{Nicola L.C. Talbot\\%
\url{http://www.dickimaw-books.com/}}
- \date{2014-01-20}
+ \date{2014-03-06}
\maketitle
\begin{abstract}
@@ -335,7 +419,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.03}.
+\qt{Documented Code for glossaries v4.04}.
This includes the documented code for the \sty{mfirstuc} package.
\item[INSTALL] Installation instructions.
@@ -382,13 +466,15 @@ Nomenclature, Lists of Symbols and Acronyms}.
\clearpage
\printglossaries
+\glsresetall
+
\chapter{Introduction}
\label{sec:intro}
The \styfmt{glossaries} package is provided to assist generating
-glossaries. It has a certain amount of flexibility, allowing the
+lists of terms, symbols or abbreviations (glossaries). It has a certain amount of flexibility, allowing the
user to customize the format of the glossary and define multiple
-glossaries. It also supports acronyms and glossary styles that
+glossaries. It also supports glossary styles that
include symbols (in addition to a name and description) for glossary
entries. There is provision for loading a database of glossary
terms. Only those terms used\footnote{That is, if the term has been
@@ -409,22 +495,254 @@ size of the manual, try starting off with the much shorter
\docref{guide for beginners}{glossariesbegin}.
\begin{important}
-The \styfmt{glossaries} package comes with a
-\href{http://www.perl.org/about.html}{Perl} script called
-\gls{makeglossaries}. This provides a convenient interface to the
-\glspl{indexingapp} \gls{makeindex} or \gls{xindy}. It is strongly
-recommended that you use this script, but \emph{it is not
-essential}. If you are reluctant to install Perl, or for any other
-reason you don't want to use \gls*{makeglossaries}, you can call
-\gls*{makeindex} or \gls*{xindy} explicitly. See
-\sectionref{sec:makeglossaries} for further details.
+There's a~common misconception that you have to have Perl installed
+in order to use the \styfmt{glossaries} package. Perl is \emph{not}
+a~requirement but it does increase the available options,
+particularly if you use an \gls{exlatinalph} or a~\gls{nonlatinalph}.
+\end{important}
+
+The basic idea behind the \styfmt{glossaries} package is that you
+first define your entries (terms, symbols or abbreviations). Then
+you can reference these within your document (like \cs{cite} or
+\cs{ref}). You can also, optionally, display a~list of the entries
+you have referenced in your document (the glossary). This last part,
+displaying the glossary is the part that most new users find
+difficult. There are three options:
+
+\begin{description}
+\item[]\optionlabel1:
+
+ This is the simplest option but it's slow and if
+ you want a sorted list, it doesn't work well for \glspl{exlatinalph} or
+ \glspl{nonlatinalph}. However, if you use the
+ \pkgopt[false]{sanitizesort} package option (the default for
+ Option~1) then the \glslink{latexexlatinchar}{standard \LaTeX\ accent commands} will be
+ ignored, so if an entry's name is set to \verb|{\'e}lite| then the
+ sort will default to \texttt{elite} if
+ \pkgopt[false]{sanitizesort} is used
+ and will default to \verb|\'elite| if \pkgopt[true]{sanitizesort}
+ is used.
+
+ \begin{enumerate}
+ \item Add \cs{makenoidxglossaries} to your preamble (before you
+ start defining your entries, as described in
+ \sectionref{sec:newglosentry}).
+
+ \item Put
+\begin{definition}
+\cs{printnoidxglossary}
+\end{definition}
+ where you want your list of entries to appear (described in
+ \sectionref{sec:printglossary}).
+
+ \item Run \LaTeX\ twice on your document. (As you would do to
+ make a~table of contents appear.) For example, click twice on
+ the \qt{typeset} or \qt{build} or \qt{PDF\LaTeX} button in your editor.
+ \end{enumerate}
+
+\item\optionlabel2:
+
+ This option uses a~\gls{cli} application called \gls{makeindex} to sort
+ the entries. This application comes with all modern \TeX\ distributions,
+ but it's hard-coded for the non-extended \gls{latinalph}, so
+ it doesn't work well for \glspl{exlatinalph} or
+ \glspl{nonlatinalph}. This process involves making \LaTeX\ write the
+ glossary information to a temporary file which \gls{makeindex} reads.
+ Then \gls{makeindex} writes a~new file containing the code to typeset
+ the glossary. \LaTeX\ then reads this file in on the next run.
+
+ \begin{enumerate}
+ \item Add \cs{makeglossaries} to your preamble (before you start
+ defining your entries, as described in
+ \sectionref{sec:newglosentry}).
+
+ \item Put
+\begin{definition}
+\cs{printglossary}
+\end{definition}
+ where you want your list of entries to appear (described in
+ \sectionref{sec:printglossary}).
+
+ \item Run \LaTeX\ on your document. This creates files with the
+ extensions \texttt{.glo} and \texttt{.ist} (for example, if your
+ \LaTeX\ document is called \texttt{myDoc.tex}, then you'll have
+ two extra files called \texttt{myDoc.glo} and \texttt{myDoc.ist}).
+ If you look at your document at this point, you won't see the
+ glossary as it hasn't been created yet.
+
+ \item Run \gls{makeindex} with the \texttt{.glo} file as the
+ input file and the \texttt{.ist} file as the style so that
+ it creates an output file with the extension \texttt{.gls}. If
+ you have access to a terminal or a command prompt (for example, the
+ MSDOS command prompt for Windows users or the bash console for
+ Unix-like users) then you need to run the command:
+\begin{verbatim}
+makeindex -s myDoc.ist -o myDoc.gls myDoc.glo
+\end{verbatim}
+ (Replace \texttt{myDoc} with the base name of your \LaTeX\
+ document file. Avoid spaces in the file name.) If you don't know
+ how to use the command prompt, then you can probably access
+ \gls{makeindex} via your text editor, but each editor has a
+ different method of doing this, so I~can't give a~general
+ description. You will have to check your editor's manual.
+
+ 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}
+ switch:
+\begin{verbatim}
+makeindex -l -s myDoc.ist -o myDoc.gls myDoc.glo
+\end{verbatim}
+ (See \sectionref{sec:makeindexapp} for further details on using
+ \gls*{makeindex} explicitly.)
+
+ \item Once you have successfully completed the previous step,
+ you can now run \LaTeX\ on your document again.
+ \end{enumerate}
+
+ This is the default option (although you still need to use
+ \cs{makeglossaries} to ensure the glossary files are created).
+
+\item\optionlabel3:
+
+ This option uses a~\gls{cli} application called
+ \gls{xindy} to sort the entries. This application is more flexible than
+ \texttt{makeindex} and is able to sort \glspl{exlatinalph} or
+ \glspl{nonlatinalph}. The \gls{xindy} application comes with \TeX~Live
+ but not with MiK\TeX. Since \gls{xindy} is a Perl script, if you are
+ using MiK\TeX\ you will not only need to install \gls{xindy}, you
+ will also need to install Perl. In a~similar way to \opt2, this
+ option involves making \LaTeX\ write the glossary information to
+ a~temporary file which \gls{xindy} reads. Then \gls{xindy}
+ writes a~new file containing the code to typeset the glossary.
+ \LaTeX\ then reads this file in on the next run.
+
+ \begin{enumerate}
+ \item Add the \pkgopt{xindy} option to the \styfmt{glossaries}
+package option list:
+\begin{verbatim}
+\usepackage[xindy]{glossaries}
+\end{verbatim}
+
+ \item Add \cs{makeglossaries} to your preamble (before you start
+ defining your entries, as described in \sectionref{sec:newglosentry}).
+
+ \item Run \LaTeX\ on your document. This creates files with the
+ extensions \texttt{.glo} and \texttt{.xdy} (for example, if your
+ \LaTeX\ document is called \texttt{myDoc.tex}, then you'll have
+ two extra files called \texttt{myDoc.glo} and \texttt{myDoc.xdy}).
+ If you look at your document at this point, you won't see the
+ glossary as it hasn't been created yet.
+
+ \item Run \gls{xindy} with the \texttt{.glo} file as the
+ input file and the \texttt{.xdy} file as a~module so that
+ it creates an output file with the extension \texttt{.gls}. You
+ also need to set the language name and input encoding. If
+ you have access to a terminal or a command prompt (for example, the
+ MSDOS command prompt for Windows users or the bash console for
+ Unix-like users) then you need to run the command (all on one
+ line):
+\begin{verbatim}
+xindy -L english -C utf8 -I xindy -M myDoc
+-t myDoc.glg -o myDoc.gls myDoc.glo
+\end{verbatim}
+ (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.) 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
+ description. You will have to check your editor's manual.
+
+ The default sort is word order (\qt{sea lion} comes before
+\qt{seal}).
+ If you want letter ordering you need to add the
+ \pkgopt[letter]{order} package option:
+\begin{verbatim}
+\usepackage[xindy,order=letter]{glossaries}
+\end{verbatim}
+ (See \sectionref{sec:xindyapp} for further details on using
+ \gls*{xindy} explicitly.)
+
+ \item Once you have successfully completed the previous step,
+ you can now run \LaTeX\ on your document again.
+
+ \end{enumerate}
+
+\end{description}
+
+For \optsand23, it can be difficult to remember all the
+parameters required for \gls{makeindex} or \gls{xindy}, so the
+\styfmt{glossaries} package provides a~script called
+\gls{makeglossaries} that reads the \texttt{.aux} file to
+determine what settings you have used and will then run
+\gls{makeindex} or \gls{xindy}. Again, this is a~command line
+application and can be run in a~terminal or command prompt. For
+example, if your \LaTeX\ document is in the file \texttt{myDoc.tex},
+then run:
+\begin{verbatim}
+makeglossaries myDoc
+\end{verbatim}
+(Replace \texttt{myDoc} with the base name of your \LaTeX\ document
+file. Avoid spaces in the file name.) This is described in more
+detail in \sectionref{sec:makeglossaries}.
+
+\begin{important}
+The \texttt{.gls} and \texttt{.glo} are temporary files
+created to help build your document. You should not edit or explicitly input
+them. However, you may need to delete them if something goes wrong
+and you need to do a fresh build.
\end{important}
+
+An overview of these three options is given in
+\tableref{tab:options}.
+
+\begin{table}[htbp]
+ \caption{Glossary Options: Pros and Cons}
+ \label{tab:options}
+ {%
+ \centering
+ \begin{tabular}{>{\raggedright}p{0.3\textwidth}ccc}
+ & \bfseries \opt1 & \bfseries \opt2 & \bfseries \opt3\\
+ Requires an external application? &
+ \no & \yes & \yes\\
+ Requires Perl? &
+ \no & \no & \yes\\
+ Can sort \glspl{exlatinalph}
+ or \glspl{nonlatinalph}? &
+ \no\textsuperscript{\textdagger} & \no & \yes\\
+ Efficient sort algorithm? &
+ \no & \yes & \yes\\
+ Can use a different sort algorithm for each glossary? &
+ \yes & \no & \no\\
+ Can form ranges in the location lists? &
+ \no & \yes & \yes\\
+ Can have non-standard locations in the location lists? &
+ \yes & \no & \yes\\
+ Maximum hierarchical depth &
+ Unlimited & 3 & Unlimited\\
+ \ics{glsdisplaynumberlist} reliable? &
+ \yes & \no & \no\\
+ \ics{newglossaryentry} restricted to preamble? &
+ \yes & \no & \no\\
+ Requires additional write registers? &
+ \no & \yes & \yes\\
+ Default value of \pkgopt{sanitizesort} package option &
+ \texttt{false} & \texttt{true} & \texttt{true}
+ \end{tabular}
+ \par
+ }\textsuperscript{\textdagger} Strips standard \LaTeX\ accents
+(that is, accents generated by core \LaTeX\ commands) so,
+for example, \ics{AA} is treated the same as A.
+\end{table}
+
This document uses the \styfmt{glossaries} package. For example,
when viewing the PDF version of this document in a
hyperlinked-enabled PDF viewer (such as Adobe Reader or Okular) if
you click on the word \qt{\gls{xindy}} you'll be taken to the entry
in the glossary where there's a brief description of
-what \qt{\gls*{xindy}} is.
+the term \qt{\gls*{xindy}}.
The remainder of this introductory section covers the following:
\begin{itemize}
@@ -434,12 +752,12 @@ with this package.
\item \sectionref{sec:languages} provides information for users who
wish to write in a language other than English.
-\item \sectionref{sec:makeglossaries} describes how to use a
-post-processor to create the sorted glossaries for your document.
+\item \sectionref{sec:makeglossaries} describes how to use an
+\gls{indexingapp} to create the sorted glossaries for your document
+(\optsor23).
\end{itemize}
-
\section{Sample Documents}
\label{sec:samples}
@@ -522,6 +840,22 @@ You should now have a complete document. The number following
each entry in the glossary is the location number. By default, this
is the page number where the entry was referenced.
+\exitem{-noidx} This document illustrates how to use the
+\styfmt{glossaries} package without an external \gls{indexingapp} (\opt1).
+To create the complete document, you need to do:
+\begin{prompt}
+latex sample-noidx
+latex sample-noidx
+\end{prompt}
+
+\exitem{-noidx-utf8} As the previous example, except that it uses
+the \sty{inputenc} package.
+To create the complete document, you need to do:
+\begin{prompt}
+latex sample-noidx-utf8
+latex sample-noidx-utf8
+\end{prompt}
+
\exitem{4col} This document illustrates
a four column glossary where the entries have a symbol in addition
to the name and description. To create the complete document, you
@@ -815,7 +1149,7 @@ See \sectionref{sec:xindyloc} for further details.
\exitem{utf8} This is another example
that uses \gls{xindy}. Unlike \gls{makeindex},
-\gls{xindy} can cope with accented or non-Latin characters. This
+\gls{xindy} can cope with \glspl{nonlatinchar}. This
document uses UTF8 encoding. To create the document do:
\begin{prompt}
latex sampleutf8
@@ -836,7 +1170,7 @@ latex sampleutf8
makeglossaries sampleutf8
latex sampleutf8
\end{prompt}
-you will see that the entries that start with a non-Latin character
+you will see that the entries that start with a \gls{nonlatinchar}
now appear in the symbols group, and the word \qt{man\oe uvre} is now
after \qt{manor} instead of before it. If you are unable to use
\gls{makeglossaries}, the call to \gls{makeindex} is as
@@ -921,9 +1255,10 @@ about the \styfmt{glossaries-accsupp} package can be found in
As from version 1.17, the \styfmt{glossaries} package can now be
used with \gls{xindy} as well as \gls{makeindex}. If you
-are writing in a language that uses accented characters or
-non-Latin characters it is recommended that you use \gls*{xindy}
-as \gls*{makeindex} is hard-coded for Latin languages. This
+are writing in a language that uses an \gls{exlatinalph} or
+\gls{nonlatinalph} it is recommended that you use \gls*{xindy}
+as \gls*{makeindex} is hard-coded for the non-extended
+\gls{latinalph}. This
means that you are not restricted to the A, \ldots, Z letter groups.
If you want to use \gls*{xindy}, remember to use the
\pkgopt{xindy} package option. For example:
@@ -936,19 +1271,19 @@ If you want to use \gls*{xindy}, remember to use the
\end{verbatim}
\begin{important}
-Note that although an accented character, such as é, looks like a plain
-character in your tex file, it's actually a macro and can therefore
+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
cause expansion problems. You may need to switch off the field
expansions with \cs{glsnoexpandfields}.
-If you use an accented (or other expandable) character at the start of
+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
a problem for commands that convert the first letter to upper case
(e.g.\ \ics{Gls}) due to expansion issues. For example:
-\begin{verbatim}
-\newglossaryentry{elite}{name={{é}lite},
-description={select group or class}}
-\end{verbatim}
+\begin{alltt}
+\verb|\newglossaryentry}{elite}{name={{|\'e\verb|}lite},|
+description=\verb|{select group or class}}|
+\end{alltt}
\end{important}
If you use the \sty{inputenc} package, \gls{makeglossaries}
@@ -1003,10 +1338,17 @@ The languages are currently supported by the
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}
-\begin{center}
+\centering
\begin{tabular}{lc}
\bfseries Language & \bfseries As from version\\
Brazilian Portuguese & 1.17\\
@@ -1022,7 +1364,6 @@ Polish & 1.13\\
Serbian & 2.06\\
Spanish & 1.08
\end{tabular}
-\end{center}
\end{table}
The language dependent commands and \sty{translator} keys used by the
@@ -1121,18 +1462,24 @@ 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}
-if you have glossary entries that contain diacritics or
-non-Roman letters. See \sectionref{sec:xindy} for further
+if you have glossary entries that contain
+\glspl{nonlatinchar}. See \sectionref{sec:xindy} for further
details.
\section{Generating the Associated Glossary Files}
\label{sec:makeglossaries}
-In order to generate a sorted glossary with compact \glspl{numberlist},
-it is necessary to use an external \gls{indexingapp} as an
-intermediate step. It is this application that creates the file
-containing the code that typesets the glossary. If this step is
-omitted, the glossaries will not appear in your document. The two
+\begin{important}
+This section is only applicable if you have chosen \optsor23. You can
+ignore this section if you have chosen \opt1.
+\end{important}
+
+In order to generate a sorted glossary with compact
+\glspl{numberlist}, it is necessary to use an external
+\gls{indexingapp} as an intermediate step (unless you have chosen
+\opt1). It is this application that creates the file containing the
+code that typesets the glossary. If this step is omitted, the
+glossaries will not appear in your document. The two
\glspl*{indexingapp} that are most commonly used with \LaTeX\ are
\gls{makeindex} and \gls{xindy}. As from version 1.17, the
\styfmt{glossaries} package can be used with either of these
@@ -1157,15 +1504,22 @@ on all the glossary files using a customized style file (which is
created by \ics{makeglossaries}). See
\sectionref{sec:makeglossariesapp} for further
details. Perl is stable, cross-platform, open source software that
-is used by a number of \TeX-related applications. Further
-information is available at \url{http://www.perl.org/about.html}.
+is used by a number of \TeX-related applications. Most Unix-like
+operating systems come with a~Perl interpreter. \TeX~Live also comes
+with a~Perl interpreter. MiK\TeX\ doesn't come with a~Perl
+interpreter so if you are a~Windows MiK\TeX\ user you will need to
+install Perl if you want to use \gls{makeglossaries}.
+Further information is available at \url{http://www.perl.org/about.html}
+and
+\href{http://tex.stackexchange.com/questions/158796/miktex-and-perl-scripts-and-one-python-script}{MiKTeX and Perl scripts (and one Python script)}.
+
The advantages of using \gls*{makeglossaries}:
\begin{itemize}
\item It automatically detects whether to use \gls*{makeindex} or
\gls*{xindy} and sets the relevant application switches.
\item One call of \gls*{makeglossaries} will run
-\gls*{makeindex}/\gls*{xindy} for each glossary type.
+\gls*{makeindex}\slash\gls*{xindy} for each glossary type.
\item If things go wrong, \gls{makeglossaries} will scan the
messages from \gls{makeindex} or \gls{xindy} and attempt to diagnose
@@ -1257,8 +1611,9 @@ If any problems occur, remember to check the transcript files
(e.g.\ \filetype{.glg} or \filetype{.alg}) for messages.
\begin{table}[htbp]
-\caption{Commands and package options that have no effect when
-using \texttt{xindy} or \texttt{makeindex} explicitly}
+\caption[Commands and package options that have no effect when
+using xindy or makeindex explicitly]{Commands and package options that have no effect when
+using \gls{xindy} or \gls{makeindex} explicitly}
\label{tab:makeglossariesCmds}
\vskip\baselineskip
\begin{tabular}{@{}lll@{}}
@@ -1297,11 +1652,41 @@ You may need to explicitly load \gls{makeglossaries} into Perl:
\begin{prompt}
perl makeglossaries myDoc
\end{prompt}
-There is a batch file called \texttt{makeglossaries.bat} which does
-this for Windows users, but you must have Perl installed to be able
-to use it.\footnote{Apparently MiKTeX has an alternative
-\texttt{makeglossaries.exe} but I don't know how using this differs
-from using \texttt{makeglossaries.bat}.} You can specify in which directory the \filetype{.aux},
+
+Windows users: TeX~Live on Windows has its own internal Perl
+interpreter and provides \texttt{makeglossaries.exe} as a~convenient
+wrapper for the \gls{makeglossaries} Perl script. MiKTeX also
+provides a~wrapper \texttt{makeglossaries.exe} but doesn't provide
+a~Perl interpreter, which is still required even if you run MiKTeX's
+\texttt{makeglossaries.exe}, so with MiKTeX you'll need to install
+Perl. There's more information about this at
+\url{http://tex.stackexchange.com/q/158796/19862} on the TeX.SX
+site. Alternatively, there is a batch file called
+\texttt{makeglossaries.bat} that should be located in the same
+folder as the \gls{makeglossaries} Perl script. This just explicitly
+loads the script into Perl. If you've installed Perl but for some
+reason your operating system can't find \texttt{perl.exe}, you can
+edit the \texttt{makeglossaries.bat} file to include the full path
+to \texttt{perl.exe} (but take care as this file will be overwritten
+next time you update the \styfmt{glossaries} package). If you move
+the \texttt{.bat} file to a new location, you will also need to
+supply the full path to the \gls{makeglossaries} Perl script. (Don't
+also move the Perl script as well or you may miss out on updates to
+\gls{makeglossaries}.)
+
+The \gls{makeglossaries} script attempts to fork the
+\gls{makeindex}\slash\gls{xindy} process using \texttt{open()} on the
+piped redirection \verb"2>&1 |" and parses the processor output to
+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
+the fallback method without attempting the redirection. Without this
+redirection, the \texttt{-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.
For example:
\begin{prompt}
@@ -1324,14 +1709,15 @@ 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.12.
+2.14.
\end{important}
-\subsection{Using xindy explicitly}
+\subsection[Using xindy explicitly (Option~3)]{Using
+\gls{xindy} explicitly (\ifpdf \opt3\else Option 3\fi)}
\label{sec:xindyapp}
-\Gls{xindy} comes with TeXLive, but not with MiKTeX. However MikTeX
-users can install it. See
+\Gls{xindy} comes with \TeX~Live, but not with MiK\TeX. However
+Mik\TeX\ users can install it. See
\href{http://tex.stackexchange.com/questions/71167/how-to-use-xindy-with-miktex}{How
to use Xindy with MikTeX} on
\urlfootref{http://www.stackexchange.com/}{\TeX\ on StackExchange}.
@@ -1395,7 +1781,8 @@ you use \gls{xindy} explicitly instead of using
\tableref{tab:makeglossariesCmds}.
-\subsection{Using makeindex explicitly}
+\subsection[Using makeindex explicitly (Option~2)]{Using
+\gls{makeindex} explicitly (\ifpdf \opt2\else Option 2\fi)}
\label{sec:makeindexapp}
If you want to use \gls{makeindex} explicitly, you must
@@ -1500,6 +1887,11 @@ the root language (e.g.\ \texttt{english}) and \meta{code}
is the encoding (e.g.\ \texttt{utf8}). These commands are omitted
if \gls{makeindex} should be used.
+If \opt1 has been used, the \texttt{.aux} file will contain
+\begin{definition}
+\cs{@gls@reference}\marg{type}\marg{label}\marg{location}
+\end{definition}
+for every time an entry has been referenced.
\chapter{Package Options}
\label{sec:pkgopts}
@@ -1526,6 +1918,15 @@ 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}).
+\item[\pkgopt{noredefwarn}] If you load \styfmt{glossaries} with
+a~class or another package that already defines glossary related
+commands, by default \styfmt{glossaries} will warn you that it's
+redefining those commands. If you are aware of the consequences of
+using \styfmt{glossaries} with that class or package and you don't
+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{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
@@ -1573,8 +1974,10 @@ suppose you do:
\end{verbatim}
and you actually want \cs{mysortvalue} expanded, so that the entry
is sorted according to \texttt{AAA}, then use the package option
-\pkgopt[false]{sanitizesort}. (The default is
-\pkgopt[true]{sanitizesort}.)
+\pkgopt[false]{sanitizesort}.
+
+The default for \optsand23 is \pkgopt[true]{sanitizesort}, and the
+default for \opt1 is \pkgopt[false]{sanitizesort}.
\item[\pkgopt{savewrites}] This is a boolean option to minimise the
number of write registers used by the \styfmt{glossaries} package.
@@ -1593,6 +1996,10 @@ alternative, you can use the \sty{scrwfile} package (part of the
KOMA-Script bundle) and not use this option.
\end{important}
+You can also reduce the number of write registers by using
+\opt1 or by ensuring you define all your glossary entries in the
+preamble.
+
\begin{important}
If you want to use \TeX's \ics{write18} mechanism to call
\gls{makeindex} or \gls{xindy} from your document and use
@@ -1694,7 +2101,8 @@ See \sectionref{sec:glslink} for further details.
specifies whether or not to gather and store the \gls{numberlist}
for each entry. The default is \pkgopt[false]{savenumberlist}. (See
\ics{glsentrynumberlist} and \ics{glsdisplaynumberlist} in
-\sectionref{sec:glsnolink}.)
+\sectionref{sec:glsnolink}.) This is always true if you
+use \opt1.
\end{description}
@@ -2037,9 +2445,17 @@ some of the predefined styles. The default setting is
\label{sec:pkgopts-sort}
\begin{description}
-\item[\pkgopt{sort}] This is a \meta{key}=\meta{value} option where
-the option can only have one of the following values:
-
+\item[\pkgopt{sort}] If you use \optsor23, this package option is
+the only way of specifying how to sort the glossaries. Only \opt1
+allows you to specify sort methods for individual glossaries
+via the \gloskey[printnoidxglossary]{sort} key in the optional
+argument of \ics{printnoidxglossary}. If you have multiple
+glossaries in your document and you are using \opt1, only use
+\pkgopt[def]{sort} or \pkgopt[use]{sort} if you want to set this
+sort method for \emph{all} your glossaries.
+
+This is a \meta{key}=\meta{value} option where
+\meta{value} may be one of the following:
\begin{itemize}
\item \pkgoptval{standard}{sort} : entries are sorted according to
the value of the \gloskey{sort} key used in \ics{newglossaryentry}
@@ -2079,8 +2495,9 @@ By default \cs{glsprestandardsort} just does:
\begin{definition}[\DescribeMacro{\glsdosanitizesort}]
\cs{glsdosanitizesort}
\end{definition}
-which sanitizes \meta{sort cs} if the \pkgopt{sanitizesort} package option
-is set (or does nothing if the package option \pkgopt[false]{sanitizesort} is used).
+which \gls{sanitize}[s] \meta{sort cs} if the \pkgopt{sanitizesort} package
+option is set (or does nothing if the package option
+\pkgopt[false]{sanitizesort} is used).
The other arguments, \meta{type} and \meta{label}, are the
glossary type and the entry label for the current entry. Note that
@@ -2098,7 +2515,17 @@ Suppose I have three glossaries: \texttt{main},
\texttt{acronym} and \texttt{notation}, and let's suppose
I want the \texttt{main} and \texttt{acronym} glossaries to be
sorted alphabetically, but the \texttt{notation} type should be
-sorted in order of definition. I can set the sort to standard
+sorted in order of definition.
+
+For \opt1, I~just need to set the \gloskey[printnoidxglossary]{sort} key in
+the optional argument of \ics{printnoidxglossary}:
+\begin{verbatim}
+\printnoidxglossary[sort=word]
+\printnoidxglossary[type=acronym,sort=word]
+\printnoidxglossary[type=notation,sort=def]
+\end{verbatim}
+
+For \optsor23, I can set the sort to \texttt{standard}
(which is the default, but can be explicitly set via the
package option \pkgopt[standard]{sort}), and I can either define
all my \texttt{main} and \texttt{acronym} entries, then
@@ -2136,7 +2563,7 @@ The second option can be achieved as follows:
For a complete document, see the sample file \samplefile{Sort}.
\end{example}
-\begin{example}{Customizing Standard Sort}{ex:customsort}
+\begin{example}{Customizing Standard Sort (Options 2 or 3)}{ex:customsort}
Suppose you want a glossary of people and you want the names listed
as \meta{first-name} \meta{surname} in the glossary, but you want the names
sorted by \meta{surname}, \meta{first-name}. You can do this by
@@ -2190,15 +2617,31 @@ Note that the \pkgopt{order} option has no effect if you don't use
\gls{makeglossaries}.
\end{important}
-\item[\pkgopt{makeindex}] (Default) The glossary information and
+If you use \opt1, this setting will be used if you use
+\gloskey[printnoidxglossary]{sort}\texttt{=standard} in
+the optional argument of \ics{printnoidxglossary}:
+\begin{verbatim}
+\printnoidxglossary[sort=standard]
+\end{verbatim}
+Alternatively, you can specify the order for individual glossaries:
+\begin{verbatim}
+\printnoidxglossary[sort=word]
+\printnoidxglossary[type=acronym,sort=letter]
+\end{verbatim}
+
+\item[\pkgopt{makeindex}] (\opt2) The glossary information and
indexing style file will be written in \gls{makeindex} format. If
you use \gls{makeglossaries}, it will automatically detect that it
needs to call \gls*{makeindex}. If you don't use
\gls*{makeglossaries}, you need to remember to use \gls*{makeindex}
-not \gls{xindy}. The indexing style file will been given a
-\filetype{.ist} extension.
+not \gls{xindy}. The indexing style file will been given
+a~\filetype{.ist} extension.
-\item[\pkgopt{xindy}] The glossary information and indexing style
+You may omit this package option if you are using \opt2 as this is the
+default. It's available in case you need to override the effect of an earlier
+occurrence of \pkgopt{xindy} in the package option list.
+
+\item[\pkgopt{xindy}] (\opt3) The glossary information and indexing style
file will be written in \gls{xindy} format. If you use
\gls{makeglossaries}, it will automatically detect that it needs to
call \gls*{xindy}. If you don't use \gls*{makeglossaries}, you need to
@@ -2223,13 +2666,13 @@ language, codepage and number group settings are unchanged. See
\sectionref{sec:xindy} for further details on using \gls{xindy} with
the \styfmt{glossaries} package.
-\item[\pkgopt{xindygloss}] This is equivalent to
+\item[\pkgopt{xindygloss}] (\opt3) This is equivalent to
\verb|xindy={}| (that is, the \pkgopt{xindy} option without any value
supplied) and may be used as a document class option. The language
and code page can be set via \ics{GlsSetXdyLanguage} and
\ics{GlsSetXdyCodePage} (see \sectionref{sec:langenc}.)
-\item[\pkgopt{xindynoglsnumbers}] This is equivalent to
+\item[\pkgopt{xindynoglsnumbers}] (\opt3) This is equivalent to
\verb|xindy={glsnumbers=false}| and may be used as a document class
option.
@@ -2255,6 +2698,12 @@ that's equivalent to
(unless that command is already defined before the beginning of the
document or the package option \pkgopt{compatible-3.07} is used).
+If you are using \opt1, you need to use
+\begin{alltt}
+\ics{printnoidxglossary}[type=acronym,\meta{options}]
+\end{alltt}
+to display the list of acronyms.
+
If the \pkgopt{acronym} package option is used, \ics{acronymtype}
is set to \texttt{acronym} otherwise it is set to
\texttt{main}.\footnote{Actually it sets \ics{acronymtype} to
@@ -2448,7 +2897,15 @@ It also defines
\cs{printsymbols}\oarg{options}
\end{definition}
which is a synonym for
-\ics{printglossary}\texttt{[type=symbols,\meta{options}]}.
+\begin{alltt}
+\ics{printglossary}[type=symbols,\meta{options}]
+\end{alltt}
+
+If you use \opt1, you need to use:
+\begin{alltt}
+\ics{printnoidxglossary}[type=symbols,\meta{options}]
+\end{alltt}
+to display the list of symbols.
\begin{important}
Remember to use the \pkgopt{nomain} package option if you're only
@@ -2465,7 +2922,15 @@ It also defines
\cs{printnumbers}\oarg{options}
\end{definition}
which is a synonym for
-\ics{printglossary}\texttt{[type=numbers,\meta{options}]}.
+\begin{alltt}
+\ics{printglossary}[type=numbers,\meta{options}]
+\end{alltt}
+
+If you use \opt1, you need to use:
+\begin{alltt}
+\ics{printnoidxglossary}[type=numbers,\meta{options}]
+\end{alltt}
+to display the list of numbers.
\begin{important}
Remember to use the \pkgopt{nomain} package option if you're only
@@ -2478,11 +2943,6 @@ the label \texttt{index} via
\newglossary[ilg]{index}{ind}{idx}{\indexname}%
\end{verbatim}
It also defines
-\begin{definition}[\DescribeMacro\printindex]
-\cs{printindex}\oarg{options}
-\end{definition}
-which is a synonym for
-\ics{printglossary}\texttt{[type=index,\meta{options}]} and
\begin{definition}[\DescribeMacro\newterm]
\cs{newterm}\oarg{options}\marg{term}
\end{definition}
@@ -2491,6 +2951,20 @@ which is a synonym for
\ics{newglossaryentry}\marg{term}[type=index,name=\marg{term},%
description=\ics{nopostdesc},\meta{options}]
\end{alltt}
+and
+\begin{definition}[\DescribeMacro\printindex]
+\cs{printindex}\oarg{options}
+\end{definition}
+which is a synonym for
+\begin{alltt}
+\ics{printglossary}[type=index,\meta{options}]
+\end{alltt}
+
+If you use \opt1, you need to use:
+\begin{alltt}
+\ics{printnoidxglossary}[type=index,\meta{options}]
+\end{alltt}
+to display this glossary.
\begin{important}
Remember to use the \pkgopt{nomain} package option if you're only
@@ -2540,36 +3014,56 @@ using commands like \ics{GlsSetXdyLanguage} (see
\sectionref{sec:xindy} for further details).
\begin{important}
-I recommend you use this command as soon as possible after loading
-\styfmt{glossaries} otherwise you might end up using it too late for
-the change to take effect. For example, if you try changing the
-acronym styles (such as \pkgopt{smallcaps}) after you have started
-defining your acronyms, you are likely to get unexpected results. If
-you try changing the sort option after you have started to define
-entries, you may get unexpected results.
+If you need to use this command, use it as soon as
+possible after loading \styfmt{glossaries} otherwise you might
+end up using it too late for the change to take effect. For example,
+if you try changing the acronym styles (such as \pkgopt{smallcaps})
+after you have started defining your acronyms, you are likely to get
+unexpected results. If you try changing the sort option after you have
+started to define entries, you may get unexpected results.
\end{important}
\chapter{Setting Up}
\label{sec:setup}
+In the preamble you need to indicate whether you want to use \opt1,
+\opt2 or \opt3. It's not possible to mix these options within
+a~document.
+
+\section[Option 1]{\ifpdf\opt1\else Option 1\fi}
+\label{sec:setupopt1}
+
+The command
+\begin{definition}[\DescribeMacro{\makenoidxglossaries}]
+\cs{makenoidxglossaries}
+\end{definition}
+must be placed in the preamble. This sets up the internal commands
+required to make \opt1 work.
+\textbf{If you omit \cs{makenoidxglossaries} none of
+the glossaries will be displayed.}
+
+\section[Options 2 and 3]{\ifpdf\optsand23\else Options 2 and 3\fi}
+\label{sec:setupopt23}
+
The command
\begin{definition}[\DescribeMacro{\makeglossaries}]
\cs{makeglossaries}
\end{definition}
must be placed in the preamble in order to create the customised
\gls{makeindex} (\filetype{.ist}) or \gls{xindy} (\filetype{.xdy})
-style file and to ensure that glossary entries are written to the
-appropriate output files. \textbf{If you omit \cs{makeglossaries} none of
-the glossaries will be created.}
+style file (for \optsor23, respectively) and to ensure that glossary
+entries are written to the appropriate output files.
+\textbf{If you omit \cs{makeglossaries} none of
+the glossary files will be created.}
\begin{important}
Note that some of the commands provided by the \styfmt{glossaries}
-package must be placed before \cs{makeglossaries} as they are
+package must not be used after \cs{makeglossaries} as they are
required when creating the customised style file. If you attempt
to use those commands after \cs{makeglossaries} you will generate
an error.
-Similarly, there are some commands that must be used after
+Similarly, there are some commands that must not be used before
\cs{makeglossaries}.
\end{important}
@@ -2578,7 +3072,7 @@ or \gls{makeindex} style file using
\begin{definition}[\DescribeMacro{\noist}]
\cs{noist}
\end{definition}
-Note that this command must be used before \cs{makeglossaries}.
+That this command must not be used after \cs{makeglossaries}.
\begin{important}
Note that if you have a custom \filetype{.xdy} file created when using
\styfmt{glossaries} version 2.07 or below, you will need to use the
@@ -2586,14 +3080,14 @@ Note that if you have a custom \filetype{.xdy} file created when using
\end{important}
The default name for the customised style file is given by
-\ics{jobname}\filetype{.ist} (for \gls{makeindex}) or
-\ics{jobname}\filetype{.xdy} (for \gls{xindy}). This name may be
+\ics{jobname}\filetype{.ist} (\opt2) or
+\ics{jobname}\filetype{.xdy} (\opt3). This name may be
changed using:
\begin{definition}[\DescribeMacro{\setStyleFile}]
\cs{setStyleFile}\marg{name}
\end{definition}
where \meta{name} is the name of the style file without the
-extension. Note that this command must be used before
+extension. Note that this command must not be used after
\cs{makeglossaries}.
Each glossary entry is assigned a \gls{numberlist} that lists all
@@ -2610,15 +3104,14 @@ For example:
\begin{verbatim}
\glsSetCompositor{-}
\end{verbatim}
-Note that this command must be used before \cs{makeglossaries}.
+This command must not be used after \cs{makeglossaries}.
-If you use \gls{xindy}, you can have a different compositor for page
+If you use \opt3, you can have a different compositor for page
numbers starting with an upper case alphabetical character using:
\begin{definition}[\DescribeMacro{\glsSetAlphaCompositor}]
\cs{glsSetAlphaCompositor}\marg{symbol}
\end{definition}
-Note that this command has no effect if you haven't used the
-\pkgopt{xindy} package option. For example, if you want
+This command has no effect if you use \opt2. For example, if you want
\glspl{numberlist} containing a mixture of A-1 and 2.3 style
formats, then do:
\begin{verbatim}
@@ -2631,28 +3124,23 @@ See \sectionref{sec:numberlists} for further information about
\label{sec:newglosentry}
All glossary entries must be defined before they are used, so it is
-better to define them in the preamble to ensure this.\footnote{The
-only preamble restriction on \ics{newglossaryentry} and
-\ics{newacronym} was removed in version 1.13, but the restriction
-remains for \ics{loadglsentries}. See \sectionref{sec:docdefs} for
+better to define them in the preamble to ensure this. In fact, some
+commands such as \cs{longnewglossaryentry}
+may only be used in the preamble. See \sectionref{sec:docdefs} for
a discussion of the problems with defining entries within the
-document instead of in the preamble.} However only those entries that
-occur in the document (using any of the commands described in
+document instead of in the preamble.
+\begin{important}
+\opt1 enforces the preamble-only restriction on
+\ics{newglossaryentry}.
+\end{important}
+
+Only those entries that are referenced in the document
+(using any of the commands described in
\sectionref{sec:glslink}, \sectionref{sec:glsadd} or
-\sectionref{sec:crossref}) will appear in the glossary. Each time an
-entry is used in this way, a line is added to an associated glossary
-file (\filetype{.glo}), which then needs to be converted into a
-corresponding \filetype{.gls} file which contains the typeset
-glossary which is input by \ics{printglossary} or
-\ics{printglossaries}. The Perl script \gls{makeglossaries} can be
-used to call \gls{makeindex} or \gls{xindy}, using a customised
-indexing style file, for each of the glossaries that are defined in
-the document. \textbf{Note that there should be no need for you to
-explicitly edit or input any of these external
-files.}\footnote{Except possibly the style file but then you'll need
-to use \ics{noist} to prevent your changes from being
-overwritten.} See
-\sectionref{sec:makeglossaries} for further details.
+\sectionref{sec:crossref}) will appear in the glossary. See
+\sectionref{sec:printglossary} to find out how to display the
+glossary.
+
New glossary entries are defined using the command:
\begin{definition}[\DescribeMacro{\newglossaryentry}]
@@ -2665,8 +3153,7 @@ needs to span multiple paragraphs, use
\cs{longnewglossaryentry}\marg{label}\marg{key=value
list}\marg{long description}
\end{definition}
-instead. Note that, unlike \cs{newglossaryentry}, the command
-\cs{longnewglossaryentry} may only be used in the preamble.
+instead. Note that this command may only be used in the preamble.
Be careful of unwanted spaces. \cs{longnewglossaryentry}
will remove trailing spaces in the description (via \cs{unskip})
but won't remove leading spaces (otherwise it would interfere with
@@ -2690,9 +3177,9 @@ a~unique label with which to identify this entry. This can't contain
any non-expandable commands or active characters.
\begin{important}
-Note that although an accented character or other non-Latin
-character, such as \'e or \ss, looks like a plain character in your
-\texttt{.tex} file, it's actually a macro (an active character) and
+Note that although an \gls{exlatinchar} or other \gls{nonlatinchar},
+such as \'e or \ss, looks like a plain character in your
+\texttt{.tex} file, it's actually a~macro (an active character) and
therefore can't be used in the label. Also be careful of
\sty{babel}'s options that change certain punctuation characters
(such as \texttt{:} or \texttt{-}) to active characters.
@@ -2702,6 +3189,9 @@ The second argument, \meta{key=value list}, is
a \meta{key}=\meta{value} list that supplies the relevant
information about this entry. There are two required fields:
\gloskey{description} and either \gloskey{name} or \gloskey{parent}.
+The description is set in the third argument of
+\cs{longnewglossaryentry} and \cs{longprovideglossaryentry}. With
+the other commands it's set via the \gloskey{description} key.
Available fields are listed below:
\begin{description}
@@ -2778,8 +3268,8 @@ symbol (as passed to \ics{glsdisplay} and \ics{glsdisplayfirst}
by \ics{glspl}, \ics{Glspl} and \ics{GLSpl}). If omitted, the value
is set to the same as the \gloskey{symbol} key.
-\item[{\gloskey{sort}}] This value indicates how \gls{makeindex} or
-\gls{xindy} should sort this entry. If omitted, the value is given
+\item[{\gloskey{sort}}] This value indicates how this entry should
+be sorted. If omitted, the value is given
by the \gloskey{name} field unless one of the package options
\pkgopt[def]{sort} and \pkgopt[use]{sort} have been used. In
general, it's best to use the \gloskey{sort} key if the
@@ -2787,6 +3277,78 @@ general, it's best to use the \gloskey{sort} key if the
You can also override the \gloskey{sort} key by redefining
\ics{glsprestandardsort} (see \sectionref{sec:pkgopts-sort}).
+\opt1 by default strips the \glslink{latexexlatinchar}{standard
+\LaTeX\ accents} (that is, accents generated by core \LaTeX\ commands) from the
+\gloskey{name} key when it sets the \gloskey{sort} key. So with
+\opt1:
+\begin{verbatim}
+\newglossaryentry{elite}{%
+ name={{\'e}lite},
+ description={select group of people}
+}
+\end{verbatim}
+This is equivalent to:
+\begin{verbatim}
+\newglossaryentry{elite}{%
+ name={{\'e}lite},
+ description={select group of people},
+ sort={elite}
+}
+\end{verbatim}
+Unless you use the package option \pkgopt[true]{sanitizesort}, in
+which case it's equivalent to:
+\begin{verbatim}
+\newglossaryentry{elite}{%
+ name={{\'e}lite},
+ description={select group of people},
+ sort={\'elite}
+}
+\end{verbatim}
+This will place the entry before the \qt{A} letter group since the
+sort value starts with a symbol.
+
+Similarly if you use the \sty{inputenc} package:
+\begin{alltt}
+\verb|\newglossaryentry{elite}{%|
+ name=\verb|{{|\'e\verb|}|lite\verb|}|,
+ description=\verb|{select group of people}|
+\verb|}|
+\end{alltt}
+This is equivalent to
+\begin{alltt}
+\verb|\newglossaryentry{elite}{%|
+ name=\verb|{{|\'e\verb|}|lite\verb|}|,
+ description=\verb|{select group of people}|,
+ sort=elite
+\verb|}|
+\end{alltt}
+Unless you use the package option \pkgopt[true]{sanitizesort}, in
+which case it's equivalent to:
+\begin{alltt}
+\verb|\newglossaryentry{elite}{%|
+ name=\verb|{{|\'e\verb|}|lite\verb|}|,
+ description=\verb|{select group of people}|,
+ sort=\'elite
+\verb|}|
+\end{alltt}
+Again, this will place the entry before the \qt{A} group.
+
+With \optsand23, the default value of \gloskey{sort} will either be
+set to the \gloskey{name} key (if \pkgopt[true]{sanitizesort}) or it
+will set it to the expansion of the \gloskey{name} key (if
+\pkgopt[false]{sanitizesort}).
+
+\begin{important}
+Take care with \gls{xindy} (\opt3): if you have entries with the same
+\gloskey{sort} value they will be treated as the
+same entry.
+
+Take care if you use \opt1 and the \gloskey{name} contains fragile
+commands. You will either need to explicitly set the \gloskey{sort}
+key or use the \pkgopt[true]{sanitizesort} package option (unless
+you use the \texttt{def} or \texttt{use} sort methods).
+\end{important}
+
\item[{\gloskey{type}}] This specifies the label of the glossary in
which this entry belongs. If omitted, the default glossary is
assumed unless \ics{newacronym} is used (see
@@ -2824,7 +3386,7 @@ Alternatively, you can use the \pkgopt{seeautonumberlist} package
option. For further details, see \sectionref{sec:crossref}.
\begin{important}
-\ics{makeglossaries} must be used before any occurrence of
+For \optsand23, \ics{makeglossaries} must be used before any occurrence of
\ics{newglossaryentry} that contains the \gloskey{see} key.
\end{important}
@@ -2838,8 +3400,8 @@ and the \sty{glossaries-accsupp} (\sectionref{sec:accsupp}) packages.
You can also define your own custom keys (see
\sectionref{sec:addkey}).
-Note that if the name starts with an accented letter or other non-Latin
-character, you must group the character, otherwise it will
+Note that if the name starts with
+\gls{nonlatinchar}, you must group the character, otherwise it will
cause a problem for commands like \ics{Gls} and \ics{Glspl}.
For example:
\begin{verbatim}
@@ -2848,14 +3410,16 @@ description={select group or class}}
\end{verbatim}
Note that the same applies if you are using the \sty{inputenc}
package:
-\begin{verbatim}
-\newglossaryentry{elite}{name={{é}lite},
-description={select group or class}}
-\end{verbatim}
+\begin{alltt}
+\verb|\newglossaryentry{elite}{name={{|\'e\verb|}lite},|
+description=\verb|{select group or class}}|
+\end{alltt}
Note that in both of the above examples, you will also need to
-supply the \gloskey{sort} key if you are using \gls{makeindex}
-whereas \gls{xindy} is usually able to sort accented letters
-correctly.
+supply the \gloskey{sort} key if you are using \opt2
+whereas \gls{xindy} (\opt3) is usually able to sort
+\glspl{nonlatinchar}
+correctly. \opt1 discards accents from
+\glspl{latexexlatinchar} unless you use the \pkgopt[true]{sanitizesort}.
\section{Plurals}
\label{sec:plurals}
@@ -3240,6 +3804,9 @@ been omitted (or, more specifically, for those entries whose
type has been specified by \ics{glsdefaulttype}, which is what
\ics{newglossaryentry} uses by default).
+This is a~preamble-only command. You may also use \ics{input} to load
+the file but don't use \ics{include}.
+
\begin{example}{Loading Entries from Another File}{ex:loadgls}
Suppose I have a file called \texttt{myentries.tex} which contains:
\begin{verbatim}
@@ -3374,7 +3941,9 @@ its parent or children.
Originally, \ics{newglossaryentry} (and \ics{newacronym}) could only be
used in the preamble. I reluctantly removed this restriction in version 1.13,
but there are issues with defining commands in the \env{document}
-environment instead of the preamble.
+environment instead of the preamble, which is why the restriction is
+maintained for newer commands. This restriction is also reimposed
+for \cs{newglossaryentry} by the new \opt1.
\subsection{Technical Issues}
\label{sec:techissues}
@@ -3384,9 +3953,8 @@ environment instead of the preamble.
subsequently shuffle sections around, you could end up using an
entry before it has been defined.
- \item Entry information is required when the glossary is displayed
-using \ics{printglossary} or \ics{printglossaries}. When either of these
-commands occur at the start of the document, the entry details are
+ \item Entry information is required when displaying the glossary.
+If this occur at the start of the document, the entry details are
being looked up before the entry has been defined.
\end{enumerate}
@@ -3396,15 +3964,18 @@ To overcome these problems, as from version 4.0 the
environment so that the definitions are written to an external file
(\cs{jobname}\filetype{.glsdefs}) which is then read in at the start
of the document on the next run. The entry will then only be defined
-if it doesn't already exist. This means that the entry can now be
-looked up in the glossary, even if the glossary occurs at the
-beginning of the document.
+in the \env{document} environment if it doesn't already exist. This
+means that the entry can now be looked up in the glossary, even if
+the glossary occurs at the beginning of the document.
There are drawbacks to this mechanism: if you modify an entry
definition, you need a second run to see the effect of your
-modification; this method requires an extra \cs{newwrite}, which may exceed
-\TeX's maximum allocation; if you have very long entries, you could
-find unexpected line breaks have been written to the temporary file.
+modification; this method requires an extra \cs{newwrite}, which may
+exceed \TeX's maximum allocation; unexpected expansion issues could
+occur; if you have very long entries, you could find unexpected line
+breaks have been written to the temporary file causing spurious
+spaces (or, even worse, a~command name could get split across a line
+causing an error message).
The last reason is why \ics{longnewglossaryentry} has the
preamble-only restriction, which I don't intend to lift.
@@ -3429,7 +4000,10 @@ so while you are planning, create a new file with all your entry
definitions. If, while you're writing your document, you remember
another term you need, then you can switch over to your definition file and
add it. Most text editors have the ability to have more than one
-file open at a time.
+file open at a time. The other advantage to this approach is that if
+you forget the label, you can look it up in the definition file
+rather than searching through your document text to find the
+definition.
\chapter{Number lists}
\label{sec:numberlists}
@@ -3443,9 +4017,9 @@ option, or an alternative counter can be set as the default using
the \pkgopt{counter} package option. The number list is also
referred to as the location list\index{location list|see{number list}}.
-Both \gls{makeindex} and \gls{xindy} concatenate a
-sequence of 3 or more consecutive pages into a range. With
-\gls*{xindy} you can vary the minimum sequence length using
+Both \gls{makeindex} and \gls{xindy} (\optsand23) concatenate a
+sequence of~3 or more consecutive pages into~a range. With
+\gls*{xindy} (\opt3) you can vary the minimum sequence length using
\ics{GlsSetXdyMinRangeLength}\marg{n} where \meta{n} is either
an integer or the keyword \texttt{none} which indicates that there
should be no range formation.
@@ -3455,7 +4029,7 @@ Note that \cs{GlsSetXdyMinRangeLength} must be used before
\ics{makeglossaries} and has no effect if \ics{noist} is used.
\end{important}
-With both \gls{makeindex} and \gls{xindy}, you can replace
+With both \gls{makeindex} and \gls{xindy} (\optsand23), you can replace
the separator and the closing number in the range using:
\begin{definition}[\DescribeMacro{\glsSetSuffixF}]
\cs{glsSetSuffixF}\marg{suffix}
@@ -3470,7 +4044,7 @@ For example:
\glsSetSuffixF{f.}
\glsSetSuffixFF{ff.}
\end{verbatim}
-Note that if you use \gls{xindy}, you will also need to
+Note that if you use \gls{xindy} (\opt3), you will also need to
set the minimum range length to 1 if you want to change these
suffixes:
\begin{verbatim}
@@ -3490,6 +4064,62 @@ before \ics{makeglossaries} and have no effect if \ics{noist} is
used.
\end{important}
+\opt1 doesn't form ranges. However, with this option you
+can iterate over an entry's \gls{numberlist} using:
+\begin{definition}[\DescribeMacro\glsnumberlistloop]
+\cs{glsnumberlistloop}\marg{label}\marg{handler cs}\marg{xr handler
+cs}
+\end{definition}
+where \meta{label} is the entry's label and \meta{handler cs} is a
+handler control sequence of the form:
+\begin{definition}
+\meta{handler cs}\marg{prefix}\marg{counter}\marg{format}\marg{location}
+\end{definition}
+where \meta{prefix} is the \sty{hyperref} prefix, \meta{counter} is
+the name of the counter used for the location, \meta{format} is the
+format used to display the location (e.g.\ \texttt{textbf})
+and \meta{location} is the location. The third argument is the
+control sequence to use for any cross-references in the list. This
+handler should have the syntax:
+\begin{definition}
+\meta{xr handler cs}\oarg{tag}\marg{xr list}
+\end{definition}
+where \meta{tag} is the cross-referenced text (e.g.\ \qt{see}) and
+\meta{xr list} is a~comma-separated list of labels. (This actually
+has a third argument but it's always empty when used with \opt1.)
+
+For example, if on page~12
+I~have used
+\begin{verbatim}
+\gls[format=textbf]{apple}
+\end{verbatim}
+and on page~18 I~have used
+\begin{verbatim}
+\gls[format=emph]{apple}
+\end{verbatim}
+then
+\begin{verbatim}
+\glsnumberlistloop{apple}{\myhandler}
+\end{verbatim}
+will be equivalent to:
+\begin{verbatim}
+\myhandler{}{page}{textbf}{12}%
+\myhandler{}{page}{emph}{18}%
+\end{verbatim}
+There is a predefined handler that's used to display the
+\gls{numberlist} in the glossary:
+\begin{definition}[\DescribeMacro\glsnoidxdisplayloc]
+\cs{glsnoidxdisplayloc}\marg{prefix}\marg{counter}\marg{format}\marg{location}
+\end{definition}
+The predefined handler used for the cross-references in the glossary is:
+\begin{definition}
+\cs{glsseeformat}\oarg{tag}\marg{xr list}\marg{location}
+\end{definition}
+which is described in \sectionref{sec:customxr}.
+
+\begin{important}
+\cs{glsnumberlistloop} is not available for \optsand23.
+\end{important}
\chapter{Links to Glossary Entries}
\label{sec:glslink}
@@ -3500,11 +4130,11 @@ commands listed in this section. The text which appears at that
point in the document when using one of these commands is referred
to as the \gls{linktext} (even if there are no hyperlinks). The
commands in this section also add a line to an external file that is
-used by \gls{makeindex} or \gls{xindy} to generate the relevant
-entry in the glossary. This information includes an associated
-location that is added to the \gls{numberlist} for that entry. By
-default, the location refers to the page number. For further
-information on number lists, see \sectionref{sec:numberlists}.
+used to generate the relevant entry in the glossary. This
+information includes an associated location that is added to the
+\gls{numberlist} for that entry. By default, the location refers to
+the page number. For further information on number lists, see
+\sectionref{sec:numberlists}.
\begin{important}
It is strongly recommended that you don't use the commands
@@ -3548,8 +4178,8 @@ as a subscript or superscript, if you use the DVI format, it won't
come out the correct size.
\end{important}
-It may be that you only want terms in a certain glossary to have
-links, but not for another glossary. In which case, you can use the
+It may be that you only want terms in certain glossaries to have
+links, but not for other glossaries. In this case, you can use the
package option \pkgopt{nohypertypes} to identify the glossary lists
that shouldn't have hyperlinked \gls{linktext}. For example, suppose
your document contains lots of technical acronyms that the reader
@@ -3834,9 +4464,11 @@ $\gls{Falpha}[^2]$
Note that \ics{glslink} doesn't use or affect the \firstuseflag, nor
does it use \ics{glsentryfmt} or the equivalent definition provided
by \ics{defglsentryfmt} (see \sectionref{sec:glsdisplay}). Instead,
-you can use: \begin{definition}[\DescribeMacro{\glsdisp}]
+you can use:
+\begin{definition}[\DescribeMacro{\glsdisp}]
\cs{glsdisp}\oarg{options}\marg{label}\marg{link text}
-\end{definition} This behaves in the same way as \ics{gls}, except
+\end{definition}
+This behaves in the same way as \ics{gls}, except
that it uses \meta{link text} instead of the value of the
\gloskey{first} or \gloskey{text} key. (Note that this command
always sets \meta{insert} to nothing.) This command affects the
@@ -4452,10 +5084,12 @@ reference the entry in the main glossary with \verb|\gls{main-svm}|.
\label{sec:crossref}
\begin{important}
-You must use \ics{makeglossaries} \emph{before} defining any
-cross-referenced entries. If any of the terms that you have
+You must use \ics{makeglossaries} (\optsor23) or
+\ics{makenoidxglossaries} (\opt1) \emph{before} defining any
+terms that cross-reference entries. If any of the terms that you have
cross-referenced don't appear in the glossary, check that you have
-put \cs{makeglossaries} before all entry definitions.
+put \cs{makeglossaries}\slash\cs{makenoidxglossaries} before all
+entry definitions.
\end{important}
There are several ways of cross-referencing entries in the
@@ -4502,6 +5136,31 @@ series},
description={Series expansion},
see=[see also]{TaylorsTheorem}}
\end{verbatim}
+Take care if you want to use the optional argument of commands such
+as \ics{newacronym} or \ics{newterm} as the value will need to be
+grouped. For example:
+\begin{verbatim}
+\newterm{seal}
+\newterm[see={[see also]seal}]{sea lion}
+\end{verbatim}
+Similarly if the value contains a list. For example:
+\begin{verbatim}
+\glossaryentry{lemon}{
+ name={lemon},
+ description={Yellow citrus fruit}
+}
+\glossaryentry{lime}
+{
+ name={lime},
+ description={Green citrus fruit}
+}
+\glossaryentry{citrus}
+{
+ name={citrus},
+ description={Plant in the Rutaceae family},
+ see={lemon,lime}
+}
+\end{verbatim}
\item After you have defined the entry, use
\begin{definition}[\DescribeMacro{\glssee}]
@@ -4532,13 +5191,6 @@ just use the \gloskey{see} key instead of \ics{glssee}, you can
automatically activate the \gls*{numberlist} using the
\pkgopt{seeautonumberlist} package option.
-\begin{important}
-You must use \ics{makeglossaries} \emph{before} the entry
-definitions containing the \gloskey{see} key and before any
-instances of \ics{glssee} or the entry won't be automatically added
-to the glossary.
-\end{important}
-
\section{Customising Cross-reference Text}
\label{sec:customxr}
@@ -4577,7 +5229,7 @@ or (for the last pair)
\cs{glsseelastsep}
\end{definition}
These default to ``",\space"'' and
-``\cs{space}\ics{andname}\cs{space}'' respectively. The list entry text
+\qt{\cs{space}\ics{andname}\cs{space}} respectively. The list entry text
is displayed using:
\begin{definition}[\DescribeMacro{\glsseeitemformat}]
\cs{glsseeitemformat}\marg{label}
@@ -4619,6 +5271,8 @@ you will need to provide an alternative via \sty{hyperref}'s
(This isn't specific to the \styfmt{glossaries} package.) See the
\sty{hyperref} documentation for further details. All the commands
that convert the first letter to upper case aren't expandable.
+The other commands depend on whether their corresponding keys were
+assigned non-expandable values.
\end{important}
\begin{definition}[\DescribeMacro{\glsentryname}]
@@ -4844,7 +5498,7 @@ described in \sectionref{sec:glslink} or \sectionref{sec:glsadd}
otherwise you will end up with an undefined link.
\end{important}
-The next two commands are only available with the
+The next two commands are only available with \opt1 or with the
\pkgopt{savenumberlist} package option:
\begin{definition}[\DescribeMacro{\glsentrynumberlist}]
\cs{glsentrynumberlist}\marg{label}
@@ -4853,9 +5507,12 @@ The next two commands are only available with the
\cs{glsdisplaynumberlist}\marg{label}
\end{definition}
Both display the \gls{numberlist} for the entry given by
-\meta{label} and require a run of \gls{makeglossaries} (or
-\gls{xindy} or \gls{makeindex}) followed by one or two runs of
-\LaTeX. The first command, \cs{glsentrynumberlist}, simply displays
+\meta{label}. When used with \opt1 a~rerun is required to ensure
+this list is up-to-date, when used with \optsor23
+a run of \gls{makeglossaries} (or \gls{makeindex}\slash\gls{xindy})
+followed by one or two runs of \LaTeX\ is required.
+
+The first command, \cs{glsentrynumberlist}, simply displays
the number list as is. The second command,
\linebreak\cs{glsdisplaynumberlist}, formats the list using:
\begin{definition}[\DescribeMacro{\glsnumlistsep}]
@@ -4869,11 +5526,13 @@ between the final two elements. The defaults are
\verb*|, | and \verb*| \& |, respectively.
\begin{important}
-\cs{glsdisplaynumberlist} is fairly experimental. It only works when
-the default counter format is used (that is, when the
-\gloskey[glslink]{format} key is set to \texttt{glsnumberformat}).
-This command also doesn't work with \sty{hyperref}. If you try using
-it with that package, \cs{glsentrynumberlist} will be used instead.
+\cs{glsdisplaynumberlist} is fairly experimental. It works with
+\opt1, but for \optsor23 it only works when the default counter
+format is used (that is, when the \gloskey[glslink]{format} key is
+set to \texttt{glsnumberformat}). This command will only work with
+\sty{hyperref} if you choose \opt1. If you try using this command
+with \optsor23 and \sty{hyperref}, \cs{glsentrynumberlist} will be
+used instead.
\end{important}
For further information see \ifpdf section~\ref*{sec:code:glsnolink}
@@ -4883,24 +5542,44 @@ glossary} in the documented code (\texttt{glossaries-code.pdf}).
\chapter{Displaying a glossary}
\label{sec:printglossary}
-The command
+\begin{description}
+\item[\opt1:]\null
+\begin{definition}[\DescribeMacro{\printnoidxglossaries}]
+\cs{printnoidxglossaries}
+\end{definition}
+(Must be used with \ics{makenoidxglossaries} in the preamble.)
+
+\item[\optsand23:]\null
\begin{definition}[\DescribeMacro{\printglossaries}]
\cs{printglossaries}
\end{definition}
-will display all the glossaries in the order in which they were
-defined. Note that no glossaries will appear until you have either
+(Must be used with \ics{makeglossaries} in the preamble.)
+\end{description}
+
+These commands will display all the glossaries in the order in which they were
+defined. Note that, in the case of \optsand23, no glossaries will appear until you have either
used the Perl script \gls{makeglossaries} or have directly used
\gls{makeindex} or \gls{xindy} (as described in
\sectionref{sec:makeglossaries}). If the glossary
still does not appear after you re-\LaTeX\ your document, check the
\gls*{makeindex}\slash\gls*{xindy} log files to see if there is a problem.
-Remember that you also need to use the command \ics{makeglossaries}
-in the preamble to enable the glossaries.
+With \opt1, you just need two \LaTeX\ runs to make the glossaries appear,
+but you may need further runs to make the \glspl{numberlist} up-to-date.
An individual glossary can be displayed using:
+\begin{description}
+\item[\opt1:]\null
+\begin{definition}[\DescribeMacro{\printnoidxglossary}]
+\cs{printnoidxglossary}\oarg{options}
+\end{definition}
+(Must be used with \ics{makenoidxglossaries} in the preamble.)
+
+\item[\optsand23:]\null
\begin{definition}[\DescribeMacro{\printglossary}]
\cs{printglossary}\oarg{options}
\end{definition}
+(Must be used with \ics{makeglossaries} in the preamble.)
+\end{description}
where \meta{options} is a \meta{key}=\meta{value} list of options.
The following keys are available:
\begin{description}
@@ -4937,6 +5616,25 @@ for this glossary. If false \linebreak(\verb|nonumberlist=false|) the
numberlist is displayed for this glossary. If no value is supplied,
true is assumed.
+\item[{\gloskey{printnoidxglossary}{sort}}] This key is only
+available for \opt1. Possible values are: \texttt{word} (word
+order), \texttt{letter} (letter order), \texttt{standard} (word or
+letter ordering taken from the \pkgopt{order} package option),
+\texttt{use} (order of use), \texttt{def} (order of definition)
+\texttt{nocase} (case-insensitive) or \texttt{case} (case-sensitive).
+
+The word and letter order sort methods use \sty{datatool}'s
+\ics{dtlwordindexcompare} and \ics{dtlletterindexcompare} handlers.
+The case-insensitive sort method uses \sty{datatool}'s
+\ics{dtlicompare} handler. The case-sensitive sort method uses
+\sty{datatool}'s \ics{dtlcompare} handler. See the \sty{datatool}
+documentation for further details.
+
+If you don't get an error with \texttt{sort=use} and
+\texttt{sort=def} but you do get an error with one of the other sort
+options, then you probably need to use the
+\pkgopt[true]{sanitizesort} package option or make sure none of the
+entries have fragile commands in their \gloskey{sort} field.
\end{description}
By default, the glossary is started either by \ics{chapter*} or by
@@ -4963,8 +5661,7 @@ For example:
\renewcommand{\glossarypreamble}{Numbers in italic
indicate primary definitions.}
\end{verbatim}
-This needs to be done before the glossary is displayed using
-\linebreak\cs{printglossaries} or \cs{printglossary}.
+This needs to be done before the glossary is displayed.
If you want a different preamble per glossary you can use
\begin{definition}[\DescribeMacro{\setglossarypreamble}]
@@ -5030,7 +5727,7 @@ medium weight small caps in your glossaries, then you can do:
\end{verbatim}
\end{example}
-\chapter{Xindy}
+\chapter[Xindy (Option 3)]{Xindy (\ifpdf\opt3\else Option 3\fi)}
\label{sec:xindy}
If you want to use \gls{xindy} to sort the glossary, you
@@ -5138,7 +5835,6 @@ need to remember to set the language and encoding using the
\texttt{-L} and \texttt{-C} switches.
\end{important}
-
\section{Locations and Number lists}
\label{sec:xindyloc}
@@ -5371,7 +6067,6 @@ is used or if \ics{makeglossaries} is omitted.
See \sectionref{sec:numberlists} for further details.
-
\section{Glossary Groups}
\label{sec:groups}
@@ -5415,15 +6110,16 @@ is the default title for this new glossary and the final optional
argument \meta{counter} specifies which counter to use for the
associated \glspl{numberlist} (see also
\sectionref{sec:numberlists}). The first optional argument specifies
-the extension for the \gls{makeindex} or \gls{xindy} transcript file
-(this information is only used by \gls{makeglossaries} which picks
-up the information from the auxiliary file).
+the extension for the \gls{makeindex} (\opt2) or \gls{xindy} (\opt3)
+transcript file (this information is only used by
+\gls{makeglossaries} which picks up the information from the
+auxiliary file). If you use \opt1, the \meta{log-ext},
+\meta{in-ext} and \meta{out-ext} arguments are ignored.
\begin{important}
The glossary label \meta{name} must not contain any active
characters. It's generally best to stick with just characters that
-have category code~11 (typically \texttt{a}, \ldots, \texttt{z}
-and \texttt{A}, \ldots, \texttt{Z}).
+have category code~11 (typically the non-extended \glspl{latinchar}).
\end{important}
You can also use:
@@ -5460,20 +6156,28 @@ label \texttt{symbols} using:
\begin{verbatim}
\newglossary[slg]{symbols}{sls}{slo}{\glssymbolsgroupname}
\end{verbatim}
-and the \pkgopt{numbers} package option creates a new glossary with
+The \pkgopt{numbers} package option creates a new glossary with
the label \texttt{numbers} using:
\begin{verbatim}
\newglossary[nlg]{numbers}{nls}{nlo}{\glsnumbersgroupname}
\end{verbatim}
+The \pkgopt{index} package option creates a new glossary with
+the label \texttt{index} using:
+\begin{verbatim}
+\newglossary[ilg]{index}{ind}{idx}{\indexname}
+\end{verbatim}
\begin{important}
-All glossaries must be defined before \ics{makeglossaries} to
+\optsand23: all glossaries must be defined before \ics{makeglossaries} to
ensure that the relevant output files are opened.
See \sectionref{sec:fixednames} if you want to redefine \cs{glossaryname},
especially if you are using \sty{babel} or \sty{translator}.
(Similarly for \cs{glssymbolsgroupname} and
-\cs{glsnumbersgroupname}.)
+\cs{glsnumbersgroupname}.) If you want to redefine \ics{indexname},
+just follow the advice in
+\href{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=fixnam}{How to
+change LaTeX’s \qt{fixed names}}.
\end{important}
\chapter{Acronyms}
@@ -5671,7 +6375,7 @@ the \pkgopt{shortcuts} package option to activate the shorter
command names listed in \tableref{tab:shortcuts}.
\begin{table}[htbp]
-\caption[Synonyms provided by the package option shortcuts]{Synonyms provided by the package option \pkgopt{shortcuts}}
+\caption{Synonyms provided by the package option \pkgoptfmt{shortcuts}}
\label{tab:shortcuts}
\vskip\baselineskip
\centering
@@ -5779,7 +6483,7 @@ or \gloskey{text} keys, but instead they use \ics{defglsentryfmt} to
set a~custom format that uses the \gloskey{long} and \gloskey{short}
keys (or their plural equivalents). This means that these styles
cope better with plurals that aren't formed by simply appending the
-singular form with the letter ``s''. In fact, most of the predefined
+singular form with the letter \qt{s}. In fact, most of the predefined
styles use \ics{glsgenacfmt} and modify the definitions of commands
like \ics{genacrfullformat}.
@@ -6250,7 +6954,7 @@ change the above to:
\renewcommand*{\acronymsort}[2]{##1}%
\end{verbatim}
The acronym font needs to be set to \ics{textsc} and the plural
-suffix adjusted so that the ``s'' suffix in the plural short form
+suffix adjusted so that the \qt{s} suffix in the plural short form
doesn't get converted to smallcaps:
\begin{verbatim}
\renewcommand*{\acronymfont}[1]{\textsc{##1}}%
@@ -6407,12 +7111,19 @@ example.
\label{sec:disploa}
The list of acronyms is just like any other type of glossary and can
-be displayed on its own using
+be displayed on its own using:
+\begin{description}
+\item[\opt1:]\null
+\begin{alltt}
+\ics{printnoidxglossary}[type=\ics{acronymtype}]
+\end{alltt}
+
+\item[\optsand23:]\null
\begin{alltt}
\ics{printglossary}[type=\ics{acronymtype}]
\end{alltt}
-or with all the other
-glossaries using \ics{printglossaries}. (If you use the
+
+(If you use the
\pkgopt{acronym} package option you can also use
\begin{alltt}
\ics{printacronyms}\oarg{options}
@@ -6423,6 +7134,15 @@ as a synonym for
\end{alltt}
See \sectionref{sec:pkgopts-acronym}.)
+\end{description}
+Alternatively the list of acronyms can be displayed with all the other
+glossaries using:
+\begin{description}
+\item[\opt1:] \ics{printnoidxglossaries}
+
+\item[\optsand23:] \ics{printglossaries}
+\end{description}
+
However, care must be taken to choose a glossary style that's
appropriate to your acronym style.
Alternatively, you can define your own custom style (see
@@ -6596,9 +7316,9 @@ Consider the following example:
\end{document}
\end{verbatim}
-On the first overlay, \verb|\gls{svm}| produces ``support vector
-machine (SVM)'' and then unsets the \firstuseflag. When the second
-overlay is processed, \verb|\gls{svm}| now produces ``SVM'', which
+On the first overlay, \verb|\gls{svm}| produces \qt{support vector
+machine (SVM)} and then unsets the \firstuseflag. When the second
+overlay is processed, \verb|\gls{svm}| now produces \qt{SVM}, which
is unlikely to be the desired effect. I~don't know anyway around
this and the only suggestion I~can give is to explicitly reset each
acronym on first use:
@@ -6634,7 +7354,8 @@ document, you can defined your own style (see
\sectionref{sec:newglossarystyle}).
The glossary style can be set using the \gloskey[printglossary]{style} key in the optional
-argument to \ics{printglossary} or using the command:
+argument to \ics{printnoidxglossary} (\opt1) or \ics{printglossary}
+(\optsand23) or using the command:
\begin{definition}[\DescribeMacro{\setglossarystyle}]
\cs{setglossarystyle}\marg{style-name}
\end{definition}
@@ -6663,7 +7384,7 @@ matches \glostyle{long3col}, \glostyle{long3colheader},
A maximum level of 0 indicates a flat glossary (sub-entries
are displayed in the same way as main entries). Where the maximum
level is given as --- there is no limit, but note that
-\gls{makeindex} imposes a limit of 2 sub-levels. If the
+\gls{makeindex} (\opt2) imposes a limit of 2 sub-levels. If the
homograph column is checked, then the name is not displayed for
sub-entries. If the symbol column is checked, then the symbol will
be displayed.}
@@ -6713,7 +7434,8 @@ a tabular-like style it's better to use \ics{newline} instead of
\verb|\\|.
Note that if you use the \gloskey[printglossary]{style} key in the
-optional argument to \ics{printglossary}, it will override any
+optional argument to \ics{printnoidxglossary} (\opt1) or
+\ics{printglossary} (\optsand23), it will override any
previous style settings for the given glossary, so if, for example,
you do
\begin{verbatim}
@@ -7293,7 +8015,8 @@ groups. The navigation line is the same as that for
The \sty{glossary-mcols} package provides tree-like styles that are
in the \env{multicols} environment (defined by the \sty{multicol}
package). The style names are as their analogous tree styles (as
-defined in \sectionref{sec:treestyles}) but are prefixed with ``mcol''.
+defined in \sectionref{sec:treestyles}) but are prefixed with
+\qt{mcol}.
For example, the \glostyle{mcolindex} style is essentially the
\glostyle{index} style but put in a \env{multicols} environment.
For the complete list, see \tableref{tab:mcols}.
@@ -7374,22 +8097,22 @@ The \glostyle{inline} style is governed by the following:
\begin{definition}[\DescribeMacro{\glsinlineseparator}]
\ics{glsinlineseparator}
\end{definition}
-This defaults to ``\texttt{\glsinlineseparator}'' and is used between
+This defaults to \qt{\texttt{\glsinlineseparator}} and is used between
main (i.e.\ level~0) entries.
\begin{definition}[\DescribeMacro{\glsinlinesubseparator}]
\ics{glsinlinesubseparator}
\end{definition}
-This defaults to ``\texttt{\glsinlinesubseparator}'' and is used between
+This defaults to \qt{\texttt{\glsinlinesubseparator}} and is used between
sub-entries.
\begin{definition}[\DescribeMacro{\glsinlineparentchildseparator}]
\ics{glsinlineparentchildseparator}
\end{definition}
-This defaults to ``\texttt{\glsinlineparentchildseparator}'' and is used between
+This defaults to \qt{\texttt{\glsinlineparentchildseparator}} and is used between
a parent main entry and its first sub-entry.
\begin{definition}[\DescribeMacro{\glspostinline}]
\ics{glspostinline}
\end{definition}
-This defaults to ``\texttt{\glsinlineseparator}'' and is used at the end
+This defaults to \qt{\texttt{\glsinlineseparator}} and is used at the end
of the glossary.
\section{Defining your own glossary style}
@@ -8195,8 +8918,9 @@ texmf-dist\slash doc\slash latex\slash glossaries/}.
Further information on debugging \LaTeX\ code is available at
\url{http://www.dickimaw-books.com/latex/minexample/}.
-Below is a list of the most frequently asked questions. For other
-queries, consult the
+Below is a list of some frequently asked questions about the
+\styfmt{glossaries} package. For a complete
+list, consult the
\urlfootref{http://www.dickimaw-books.com/faqs/glossariesfaq.html}{\styfmt{glossaries} FAQ}. If that
doesn't help, try posting your query to somewhere like the
comp.text.tex newsgroup, the