summaryrefslogtreecommitdiff
path: root/macros/latex/contrib/glossaries/glossariesbegin.tex
diff options
context:
space:
mode:
authorNorbert Preining <norbert@preining.info>2020-03-20 03:01:17 +0000
committerNorbert Preining <norbert@preining.info>2020-03-20 03:01:17 +0000
commitc720a4409b388fa706f3eb1ce275f76f7d49d996 (patch)
treed9e0864c856e4b7abba585785d57bbf02aa1f9ad /macros/latex/contrib/glossaries/glossariesbegin.tex
parentc8b8ea37fe9cd71b53223dff23f291b2f158fc0f (diff)
CTAN sync 202003200301
Diffstat (limited to 'macros/latex/contrib/glossaries/glossariesbegin.tex')
-rw-r--r--macros/latex/contrib/glossaries/glossariesbegin.tex122
1 files changed, 80 insertions, 42 deletions
diff --git a/macros/latex/contrib/glossaries/glossariesbegin.tex b/macros/latex/contrib/glossaries/glossariesbegin.tex
index e0793626a8..c84ff3074e 100644
--- a/macros/latex/contrib/glossaries/glossariesbegin.tex
+++ b/macros/latex/contrib/glossaries/glossariesbegin.tex
@@ -2,11 +2,15 @@
\usepackage[utf8]{inputenc}
\ifpdf
-\usepackage[T1]{fontenc}
-\usepackage{mathpazo}
-\usepackage[scaled=.88]{helvet}
-\usepackage{courier}
-\usepackage{xr-hyper}
+ \usepackage[T1]{fontenc}
+ \usepackage{mathpazo}
+ \usepackage[scaled=.88]{helvet}
+ \usepackage{courier}
+ \usepackage{metalogo}
+ \usepackage{xr-hyper}
+\else
+ \providecommand{\XeLaTeX}{XeLaTeX}
+ \providecommand{\LuaLaTeX}{LuaLaTeX}
\fi
\usepackage{alltt}
@@ -31,10 +35,10 @@
\texorpdfstring{{\frenchspacing\obeyspaces\ttfamily#1}}{#1}}
\newcommand*{\file}[1]{\texorpdfstring{\texttt{#1}}{#1}}
-\title{The glossaries package v4.45:
+\title{The glossaries package v4.46:
a guide for beginners}
-\author{Nicola L.C. Talbot}
-\date{2020-02-13}
+\author{Nicola L.C. Talbot\\\href{https://www.dickimaw-books.com/}{\nolinkurl{dickimaw-books.com}}}
+\date{2020-03-19}
\ifpdf
\externaldocument{glossaries-user}
@@ -162,6 +166,10 @@ Abbreviations are slightly different if you use the extension package
First use: \gls{svm}. Second use: \gls{svm}.
\end{document}
\end{verbatim}
+Since \code{long-short} happens to be the default for
+\cs{newabbreviation} (if you haven't set the \code{category} key)
+you may omit the \cs{setabbreviationstyle} line in this example.
+
If you still want to use \cs{newacronym} (rather than
\cs{newabbreviation}) then you need the optional
argument of \cs{setabbreviationstyle}:
@@ -178,6 +186,12 @@ argument of \cs{setabbreviationstyle}:
First use: \gls{svm}. Second use: \gls{svm}.
\end{document}
\end{verbatim}
+In this example, if you omit the \cs{setabbreviationstyle} line you
+will notice a difference because the \code{short-nolong} style (not
+the \code{long-short} style) is the default with \cs{newacronym}.
+With the \code{short-nolong} style the first use simply shows just
+the short form.
+
\begin{important}
You can't use \cs{setacronymstyle} with \sty{glossaries-extra}.
\end{important}
@@ -288,11 +302,13 @@ label is used to uniquely identify the term (like the standard
following alphanumerics in the labels: \code{a}, \ldots,
\code{z}, \code{A}, \ldots, \code{Z}, \code{0}, \ldots,
\code{9}. Sometimes you can also use punctuation characters but
-not if another package (such as \sty{babel}) meddles with them.
+not if another package (such as \sty{babel}) makes them active.
Don't try using any characters outside of the basic Latin set with
\sty{inputenc} (for example, \'e or \ss) or things will go horribly
wrong. This warning only applies to the label. It doesn't apply to
-the text that appears in the document.
+the text that appears in the document. If you really need UTF-8
+characters in your labels then you'll need to use \XeLaTeX\ or
+\LuaLaTeX.
\begin{important}
Don't use \cs{gls} in chapter or section headings as it can have
@@ -300,7 +316,7 @@ some unpleasant side-effects. Instead use \cs{glsentrytext} for
regular entries and one of \cs{glsentryshort}, \cs{glsentrylong}
or \cs{glsentryfull} for acronyms. Alternatively use
\sty{glossaries-extra} which provides special commands for use in
-section headings, such as \cs{glsfmtshort}\marg{label}.
+section headings and captions, such as \cs{glsfmtshort}\marg{label}.
\end{important}
The above examples are reasonably straightforward. The difficulty
@@ -357,7 +373,9 @@ provides a fourth method: use \app{bib2gls} (\opt4).
The first option (using \TeX) is the simplest method, as it doesn't
require an external tool, but it's very inefficient and the sorting
-is done according to the English alphabet. To use this method, add
+is done according to lower case character code (which matches basic Latin
+alphabets, such as English, but not extended Latin alphabets, such
+as Icelandic). To use this method, add
\cs{makenoidxglossaries} to the preamble and put
\cs{printnoidxglossaries} at the place where you want your glossary.
For example:
@@ -390,7 +408,9 @@ For example:
\begin{important}
The \cs{makenoidxglossaries} method is very slow, uses an ASCII
comparator and often breaks if there are commands in the
-\code{name} key.
+\code{name} key. See
+\href{https://www.dickimaw-books.com/gallery/glossaries-performance.shtml}{Glossaries
+Performance} for a comparison.
\end{important}
Try this out and run \LaTeX\ (or pdf\LaTeX) \emph{twice}. The first
@@ -425,8 +445,8 @@ with the \pkgopt{nopostdot} package option:
\usepackage[nopostdot]{glossaries}
\end{verbatim}
-If you tried out the previous example with \sty{glossaries-extra}
-and \cs{printunsrtglossaries} the terminating full stop is missing
+If you try out the earlier example with \sty{glossaries-extra}
+and \cs{printunsrtglossaries} you may notice that the terminating full stop is missing
and there are no number lists. You can add the full stop back with
\begin{verbatim}
\usepackage[nopostdot=false]{glossaries-extra}
@@ -437,8 +457,7 @@ or
\end{verbatim}
If you want the number lists then you need to use an indexing option.
-
-You may have noticed that I've used another command in the above example:
+You may have noticed that I've used another command in the above examples:
\cs{glspl}. This displays the plural form. By default, this is just
the singular form with the letter \qt{s} appended, but in the case of
\qt{potato} I had to specify the correct plural using the
@@ -561,7 +580,8 @@ or
\verb|}|
\end{alltt}
\end{enumerate}
-(For further details, see the section \qt{UTF-8} of the
+(This isn't necessary for UTF-8 characters with \XeLaTeX\ or
+\LuaLaTeX. For further details, see the section \qt{UTF-8} of the
\href{https://ctan.org/pkg/mfirstuc}{\styfmt{mfirstuc}} user manual.)
If you use \app{bib2gls} with \sty{glossaries-extra} then the
@@ -611,7 +631,7 @@ then put the following line in the document preamble:
You can have a comma-separated list. For example, if you also
have entries defined in the file \file{entries2.bib}:
\begin{verbatim}
-\GlsXtrLoadResources[src={entries,entries2.bib}]
+\GlsXtrLoadResources[src={entries,entries2}]
\end{verbatim}
There are other keys you can use when you define an entry. For
@@ -658,7 +678,7 @@ key with an \qt{s} appended, but if this is incorrect, just use the
(Remember from earlier that the initial ligature \cs{oe} needs to
be grouped.)
-Abbreviations can be defined using
+Abbreviations can be defined using:
\begin{definition}
\cs{newacronym}\oarg{options}\marg{label}\marg{short}\marg{long}
\end{definition}
@@ -683,7 +703,7 @@ argument:
\end{verbatim}
Before you define your acronyms (or other types of abbreviations), you
-need to specify which style to use with
+need to specify which style to use with:
\begin{definition}
\cs{setacronymstyle}\marg{style name}
\end{definition}
@@ -846,6 +866,14 @@ unless you want a separate symbols list.) The corresponding document
\end{document}
\end{verbatim}
+Note that while the \code{sort} key is advised for symbols when
+using \cs{makeglossaries} or \cs{makenoidxglossaries} it shouldn't
+be used with \app{bib2gls}. Instead, \app{bib2gls} has its own
+algorithm for determining the sort value based on the entry type
+(\code{@entry}, \code{@symbol} etc). See
+\href{https://www.dickimaw-books.com/gallery/index.php?label=bib2gls-sorting}{bib2gls
+gallery: sorting} for further details.
+
\section{Using Entries}
\label{sec:useterm}
@@ -960,7 +988,7 @@ disadvantages. (There's a more detailed summary in the main
\item[]\optionlabel1:
This is the simplest option but it's slow and if
- you want a sorted list, it doesn't work for non-Latin alphabets.
+ you want a sorted list, it doesn't work for extended or non-Latin alphabets.
The \code{name} mustn't contain commands (or, if it does, the
\code{sort} value must be supplied) unless you
have the package option \pkgopt{sanitizesort} or \pkgopt[def]{sort}
@@ -1105,6 +1133,10 @@ similar looking names.
as a build tool, 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.
+ (There are some guidelines in
+\href{https://www.dickimaw-books.com/latex/buildglossaries/}{Incorporating
+makeglossaries or makeglossaries-lite or bib2gls into the document
+build}.)
If you still have problems, try adding the \pkgopt{automake}
package option:
\begin{verbatim}
@@ -1259,7 +1291,7 @@ pdflatex myDoc
This requires the extension package \sty{glossaries-extra} and
an application called \app{bib2gls}. This application is able
to sort extended Latin or non-Latin alphabets. It comes with both
- \TeX~Live and MiK\TeX\ but requires at least Java~7. This method
+ \TeX~Live and MiK\TeX\ but requires at least Java~8. This method
works differently to \optsand23. Instead of creating a file
containing the code to typeset the glossary it creates a
\file{.glstex} file containing the entry definitions fetched
@@ -1410,11 +1442,9 @@ then to build the document you just need the single system call:
\begin{verbatim}
arara myDoc
\end{verbatim}
-(The currently pending version 4.0 of \app{arara} has
-directives for \app{makeglossaries-lite} and \app{bib2gls}.
-These aren't available in earlier versions, but you could try
-copying and adapting the \file{makeglossaries.yaml} file and
-replace \app{makeglossaries} as appropriate.)
+(As from version 4.0, \app{arara} also has
+directives for \app{makeglossaries-lite} and \app{bib2gls}. See the
+\app{arara} manual for further details.)
When sorting the entries, the string comparisons are made according
to each entry's \code{sort} key. If this is omitted, the
@@ -1473,8 +1503,12 @@ comparator. In this case you will need to ensure the document can
support this character either with \sty{inputenc} or by switching to
a \LaTeX\ engine with native UTF-8 support.
-\end{description}
+There's more information on how \app{bib2gls} obtains the sort value
+in
+\href{https://www.dickimaw-books.com/gallery/index.php?label=bib2gls-sorting}{bib2gls
+gallery: sorting}.
+\end{description}
If the \sty{inputenc} package is used:
\begin{verbatim}
@@ -1513,7 +1547,7 @@ might put it in the \qt{\'E} letter group.)
\item[\opt4:] The \sty{inputenc} package doesn't affect the
encoding used with \file{.bib} entry definitions, since these are dependent
on the encoding used to save the \file{.bib} file (although the
-labels must still be ASCII). You can help \app{bib2gls} (and
+labels must still be ASCII unless you use \XeLaTeX/\LuaLaTeX). You can help \app{bib2gls} (and
JabRef) by putting an encoding comment at the start of the \file{.bib} file:
\begin{alltt}
\% Encoding: UTF-8
@@ -1610,7 +1644,7 @@ without).
Entries are grouped according to the first letter of
each entry's \code{sort} key. By default a~vertical gap is placed
-between letter groups. You can suppress this with the
+between letter groups for most of the predefined styles. You can suppress this with the
\pkgopt{nogroupskip} package option:
\begin{verbatim}
\usepackage[nogroupskip]{glossaries}
@@ -1667,13 +1701,11 @@ or
Use one of the styles that display the symbol (not all of them do).
For example, one of the tabular styles:
\begin{verbatim}
-\usepackage[nopostdot,nonumberlist]{glossaries}
-\setglossarystyle{long4col}
+\usepackage[nopostdot,nonumberlist,style=long4col]{glossaries}
\end{verbatim}
or one of the \qt{tree} styles:
\begin{verbatim}
-\usepackage[nopostdot,nonumberlist]{glossaries}
-\setglossarystyle{tree}
+\usepackage[nopostdot,nonumberlist,style=tree]{glossaries}
\end{verbatim}
\end{enumerate}
@@ -1725,15 +1757,15 @@ indicate the file extensions used by
\app{makeindex}\slash\app{xindy} (described in
\sectionref{sec:printglossaries}). If you use \opt1 described
above (or \app{bib2gls} and \cs{printunsrtglossaries}),
-then the \meta{glg}, \meta{gls} and \meta{glo} arguments are
-ignored, in which case you may prefer to use the starred version
+then the \meta{glg}, \meta{gls} and \meta{glo} arguments aren't
+relevant, in which case you may prefer to use the starred version
where you don't specify the extensions:
\begin{definition}
\cs{newglossary*}\marg{label}\marg{title}
\end{definition}
In the case of \optsor23, all glossary definitions must come before
-\cs{makeglossaries}. (Entries definitions should come after
+\cs{makeglossaries}. (\emph{Entry} definitions should come after
\cs{makeglossaries}.) In the case of \opt4, all glossary definitions
must come before any \cs{GlsXtrLoadResources} that requires them.
@@ -1852,7 +1884,8 @@ If you use \opt1, you don't need to do anything else. If you use
\optsor23 with the \app{makeglossaries} Perl script or the
\app{makeglossaries-lite} Lua script, you
similarly don't need to do anything else. If you use \optsor23
-without the \app{makeglossaries} Perl script then you need to
+without the \app{makeglossaries} Perl script or
+\app{makeglossaries-lite} Lua script then you need to
make sure you run \app{makeindex}\slash\app{xindy} \emph{for
each defined glossary}. The \meta{gls} and \meta{glo} arguments of
\cs{newglossary} specify the file extensions to use instead of
@@ -1936,8 +1969,8 @@ superscripts aren't correctly sized with the DVI format.
By default, if the \sty{hyperref} package has been loaded, commands
like \cs{gls} will form a~hyperlink to the relevant entry in the
-glossary. If you to disable this for \emph{all} your
-glossaries, then use
+glossary. If you want to disable this for \emph{all} your
+glossaries, then use:
\begin{definition}
\cs{glsdisablehyper}
\end{definition}
@@ -1959,6 +1992,9 @@ the \pkgopt[false]{hyperfirst} package option:
\usepackage[colorlinks]{hyperref}
\usepackage[hyperfirst=false]{glossaries}
\end{verbatim}
+The \sty{glossaries-extra} extension package provides another method
+using category attributes. See the \sty{glossaries-extra} user
+manual for further details.
Take care not to use non-expandable commands in PDF bookmarks. This
isn't specific to the \sty{glossaries} package but is a~limitation
@@ -1970,7 +2006,7 @@ bookmarks via \cs{texorpdfstring}. For example:
\section{The \texorpdfstring{\gls{fishage}}{Fish Age}}
\end{verbatim}
However, it's not a~good idea to use commands like \cs{gls} in
-a~section heading as you'll end up with the table of contents in
+a~section heading as you'll end up with the table of contents page in
your location list. Instead you can use
\begin{definition}
\cs{glsentrytext}\marg{label}
@@ -2089,4 +2125,6 @@ build}.
\item The \href{https://ctan.org/pkg/bib2gls}{\appfmt{bib2gls}}
application.
\end{itemize}
+The \href{https://www.dickimaw-books.com/gallery}{Dickimaw Books
+Gallery} provides additional example documents.
\end{document}