diff options
author | Norbert Preining <norbert@preining.info> | 2020-03-20 03:01:17 +0000 |
---|---|---|
committer | Norbert Preining <norbert@preining.info> | 2020-03-20 03:01:17 +0000 |
commit | c720a4409b388fa706f3eb1ce275f76f7d49d996 (patch) | |
tree | d9e0864c856e4b7abba585785d57bbf02aa1f9ad /macros/latex/contrib/glossaries/glossariesbegin.tex | |
parent | c8b8ea37fe9cd71b53223dff23f291b2f158fc0f (diff) |
CTAN sync 202003200301
Diffstat (limited to 'macros/latex/contrib/glossaries/glossariesbegin.tex')
-rw-r--r-- | macros/latex/contrib/glossaries/glossariesbegin.tex | 122 |
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} |