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