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 | 703 |
1 files changed, 541 insertions, 162 deletions
diff --git a/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex b/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex index 4a4039b46f2..ca79ac9bd84 100644 --- a/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex +++ b/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex @@ -1,9 +1,13 @@ -\documentclass{nlctdoc} +\documentclass[report]{nlctdoc} +\usepackage[inner=0.5in,includemp]{geometry} + +\usepackage{array} \usepackage{alltt} \usepackage{pifont} \usepackage[utf8]{inputenc} \usepackage[T1]{fontenc} +\usepackage{lmodern} \ifpdf \usepackage{mathpazo} \usepackage[scaled=.88]{helvet} @@ -17,6 +21,9 @@ pdfkeywords={LaTeX,package,glossary,acronyms}]{hyperref} \usepackage{xr-hyper} \usepackage[xindy,nonumberlist,seeautonumberlist,toc,style=altlist]{glossaries} +\usepackage{glossary-inline} + +\pagestyle{headings} \renewcommand*{\glsgroupskip}{} @@ -35,8 +42,8 @@ style=altlist]\{glossaries\} \end{tabbing} \cs{renewcommand*}\{\ics{glsgroupskip}\}\{\}\newline -\cs{renewcommand*}\{\ics{glsseeformat}\}[3][\ics{seename}]\{(\ics{xmakefirstuc}\{\#1\} \newline -\ics{glsseelist}\{\#2\}.)\} +\cs{renewcommand*}\{\ics{glsseeformat}\}[3][\ics{seename}]\{\% \newline +(\ics{xmakefirstuc}\{\#1\} \ics{glsseelist}\{\#2\}.)\} \end{ttfamily} } @@ -55,7 +62,8 @@ \newcommand*{\htextbf}[1]{\textbf{\hyperpage{#1}}} \newcommand*{\itermdef}[1]{\index{#1|htextbf}} -\IndexPrologue{} +\IndexPrologue{\chapter*{\indexname} + \markboth{\indexname}{\indexname}} \newglossaryentry{xindy}{ name={\appfmt{xindy}\index{xindy|htextbf}}, @@ -76,10 +84,20 @@ description={An indexing application}, name={\appfmt{makeglossaries}\index{makeglossaries|htextbf}},% sort={makeglossaries},% text={\protect\app{makeglossaries}},% -description={A \sty{glossaries} custom designed Perl script interface +description={A \styfmt{glossaries} custom designed Perl script interface to \gls{xindy} and \gls{makeindex}} } +\newglossaryentry{makeglossariesgui}{% +name={\appfmt{makeglossariesgui}\index{makeglossariesgui|htextbf}},% +sort={makeglossariesgui},% +text={\protect\app{makeglossariesgui}},% +description={A Java GUI alternative to \gls{makeglossaries} that +also provides diagnostic tools. Home page: +\url{http://www.dickimaw-books.com/apps/makeglossariesgui/}. Also +available on CTAN} +} + \newglossaryentry{numberlist}{% name={Number list\itermdef{number list}},% sort={number list},% @@ -100,6 +118,7 @@ have multiple locations} \newglossaryentry{locationlist}{% name={Location list},% +text={location list}, sort={location list},% description={A list of \glslink{entrylocation}{entry locations}},% see={numberlist} @@ -214,7 +233,7 @@ package option \pkgopt{sanitize} described in \sectionref{sec:pkgopts-general}} \MakeShortVerb{"} \DeleteShortVerb{\|} - \title{User Manual for glossaries.sty v3.01} + \title{User Manual for glossaries.sty v3.02} \author{Nicola L.C. Talbot\\[10pt] School of Computing Sciences\\ University of East Anglia\\ @@ -222,7 +241,7 @@ Norwich. Norfolk\\ NR4 7TJ. United Kingdom.\\ \url{http://theoval.cmp.uea.ac.uk/~nlct/}} - \date{2011-04-12} + \date{2012-05-21} \maketitle \noindent @@ -250,10 +269,8 @@ letter}{mfirstuc-manual}. \item[\url{glossaries.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 v3.01}. -This includes how to iterate over all entry labels defined in a -given glossary or how to iterate over all glossary types, as well as -the documented code for the \sty{mfirstuc} package. +\qt{Documented Code for glossaries v3.02}. +This includes the documented code for the \sty{mfirstuc} package. \item[INSTALL] Installation instructions. @@ -274,7 +291,8 @@ If you use \sty{hyperref} and \styfmt{glossaries}, you must load \clearpage \printglossaries - \section{Introduction} + \chapter{Introduction} +\label{sec:intro} The \styfmt{glossaries} package is provided to assist generating glossaries. It has a certain amount of flexibility, allowing the @@ -325,7 +343,7 @@ post-processor to create the sorted glossaries for your document. \end{itemize} -\subsection{Sample Documents} +\section{Sample Documents} \label{sec:samples} The \styfmt{glossaries} package is provided with some sample @@ -574,6 +592,10 @@ that this will only have an effect if you use you will need to use the \texttt{-l} switch to indicate letter ordering.) +\item[sample-inline.tex]\label{ex:sample-inline} This document is +like \texttt{sample.tex}, above, but uses the \glostyle{inline} +glossary style to put the glossary in a footnote. + \item[sampletree.tex]\label{ex:sampletree} This document illustrates a hierarchical glossary structure where child entries have different names to their corresponding parent entry. To create the document @@ -593,6 +615,16 @@ makeglossaries sample-dual latex sample-dual \end{prompt} +\item[sample-langdict]\label{ex:sample-langdict} This document +illustrates how to use the glossaries package to create English +to French and French to English dictionaries. To create the document +do: +\begin{prompt} +latex sample-langdict +makeglossaries sample-langdict +latex sample-langdict +\end{prompt} + \item[samplexdy.tex]\label{ex:samplexdy} This document illustrates how to use the \styfmt{glossaries} package with \gls{xindy} instead of \gls{makeindex}. The document uses UTF8 encoding (with the @@ -692,7 +724,7 @@ about the \styfmt{glossaries-accsupp} package can be found in \end{description} -\subsection{Multi-Lingual Support} +\section{Multi-Lingual Support} \label{sec:languages} As from version 1.17, the \styfmt{glossaries} package can now be @@ -743,7 +775,7 @@ will pick up the encoding from the auxiliary file. If you use you may need to specify the encoding using the \texttt{-C} option. Read the \gls*{xindy} manual for further details. -\subsubsection{Changing the Fixed Names} +\subsection{Changing the Fixed Names} \label{sec:fixednames} As from version 1.08, the \styfmt{glossaries} package now has @@ -815,32 +847,32 @@ glossaries package are listed in \tableref{tab:predefinednames}. \begin{table}[htbp] \caption{Customised Text} \label{tab:predefinednames} -\begin{center} -\begin{tabular}{@{}llp{0.4\linewidth}@{}} +\centering +\setlength{\tabcolsep}{3pt} +\begin{tabular}{@{}l>{\raggedright}p{0.3\linewidth}>{\raggedright}p{0.4\linewidth}@{}} \bfseries Command Name & \bfseries Translator Key Word & -\bfseries Purpose\\ -\ics{glossaryname} & \texttt{Glossary} & Title of the main glossary.\\ +\bfseries Purpose\cr +\ics{glossaryname} & \texttt{Glossary} & Title of the main glossary.\cr \ics{acronymname} & \texttt{Acronyms} & Title of the list of acronyms -(when used with package option \pkgopt{acronym}).\\ +(when used with package option \pkgopt{acronym}).\cr \ics{entryname} & \texttt{Notation (glossaries)} & Header for first column in the glossary (for 2, 3 or 4 column glossaries -that support headers).\\ +that support headers).\cr \ics{descriptionname} & \texttt{Description (glossaries)} & Header for second column in the glossary (for 2, 3 or 4 column glossaries -that support headers).\\ +that support headers).\cr \ics{symbolname} & \texttt{Symbol (glossaries)} & Header for symbol -column in the glossary for glossary styles that support this option.\\ +column in the glossary for glossary styles that support this option.\cr \ics{pagelistname} & \texttt{Page List (glossaries)} & Header for page list column in the glossary for glossaries that support -this option.\\ +this option.\cr \ics{glssymbolsgroupname} & \texttt{Symbols (glossaries)} & Header for symbols section of the glossary for glossary styles that -support this option.\\ +support this option.\cr \ics{glsnumbersgroupname} & \texttt{Numbers (glossaries)} & Header for numbers section of the glossary for glossary styles that support this option. \end{tabular} -\end{center} \end{table} Due to the varied nature of glossaries, it's likely that the @@ -926,10 +958,10 @@ if you have glossary entries that contain diacritics or non-Roman letters. See \sectionref{sec:xindy} for further details. -\subsection{Generating the Associated Glossary Files} +\section{Generating the Associated Glossary Files} \label{sec:makeglossaries} -In order to generate a sorted glossary with compact location lists, +In order to generate a sorted glossary with compact \glspl{locationlist}, it is necessary to use an external indexing application as an intermediate step. It is this application that creates the file containing the code that typesets the glossary. If this step is @@ -970,14 +1002,23 @@ file and see if you can work it out from the \gls*{makeindex} or \end{itemize} +There is also a Java GUI alternative called \gls{makeglossariesgui}, +distributed separately, that has diagnostic tools. + Whilst it is strongly recommended that you use the -\gls{makeglossaries} script, it is possible to use the -\styfmt{glossaries} package without having Perl installed. However, -you will only be able to use \gls{makeindex} as \gls{xindy} also -requires Perl. Note that some commands and package options have no -effect if you don't use \gls*{makeglossaries}. These are listed in +\gls{makeglossaries} script or \gls{makeglossariesgui}, it is +possible to use the \styfmt{glossaries} package without using either +application. However, note that some commands and package options +have no effect if you don't use \gls*{makeglossaries} or +\gls*{makeglossariesgui}. These are listed in \tableref{tab:makeglossariesCmds}. +\begin{important} +If you are choosing not to use \gls*{makeglossaries} because you +don't want to install Perl, you will only be able to use +\gls*{makeindex} as \gls*{xindy} also requires Perl. +\end{important} + Note that if any of your entries use an entry that is not referenced outside the glossary, you will need to do an additional \gls{makeglossaries}, \gls{makeindex} @@ -1058,7 +1099,7 @@ use \texttt{-C} \meta{code} \end{table} -\subsubsection{Using the makeglossaries Perl Script} +\subsection{Using the makeglossaries Perl Script} \label{sec:makeglossariesapp} The \gls{makeglossaries} script picks up the relevant information @@ -1091,10 +1132,10 @@ 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.03. +2.04. \end{important} -\subsubsection{Using xindy explicitly} +\subsection{Using xindy explicitly} \label{sec:xindyapp} \Gls{xindy} comes with TeXLive, but not with MiKTeX. However MikTeX @@ -1112,7 +1153,7 @@ files, you must make sure you have used the \end{verbatim} This is required regardless of whether you use \gls{xindy} explicitly or whether it's called implicitly via -\gls{makeglossaries}. This causes the glossary +\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}. @@ -1163,7 +1204,7 @@ you use \gls{xindy} explicitly instead of using \tableref{tab:makeglossariesCmds}. -\subsubsection{Using makeindex explicitly} +\subsection{Using makeindex explicitly} \label{sec:makeindexapp} If you want to use \gls{makeindex} explicitly, you must @@ -1213,7 +1254,8 @@ you use \gls*{makeindex} explicitly instead of using \tableref{tab:makeglossariesCmds}. -\subsubsection{Note to Front-End and Script Developers} +\subsection{Note to Front-End and Script Developers} +\label{sec:notedev} The information needed to determine whether to use \gls{xindy} or \gls{makeindex} and the information needed to call those @@ -1267,12 +1309,12 @@ is the encoding (e.g.\ \texttt{utf8}). These commands are omitted if \gls{makeindex} should be used. -\section{Package Options} +\chapter{Package Options} \label{sec:pkgopts} This section describes the available \styfmt{glossaries} package options. -\subsection{General Options} +\section{General Options} \label{sec:pkgopts-general} \begin{description} @@ -1336,8 +1378,8 @@ If you want to use \TeX's \ics{write18} mechanism to call document to avoid rewriting the files. For example: \begin{verbatim} \glswritefiles -\write18{makeindex -s \istfilename\space -t \jobname.glg --o \jobname.gls \jobname} +\write18{makeindex -s \istfilename\space +-t \jobname.glg -o \jobname.gls \jobname} \let\glswritefiles\relax \end{verbatim} \end{important} @@ -1374,9 +1416,15 @@ whether each term has a hyperlink on \firstuse. The default is unless explicitly suppressed using starred versions of commands such as \ics{gls*}). +\item[\pkgopt{savenumberlist}] This is a boolean option that +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}.) + \end{description} -\subsection{Sectioning and TOC Options} +\section{Sectioning, Headings and TOC Options} \label{sec:pkgopts-sec} \begin{description} @@ -1436,15 +1484,20 @@ or to prevent it from changing the headers: \begin{verbatim} \renewcommand{\glossarymark}[1]{} \end{verbatim} +If you want \cs{glossarymark} to use \cs{MakeUppercase} in the header, use the +\pkgopt{ucmark} option described below. Occasionally you may find that another package defines -\cs{cleardoublepage} when it is not required. This may cause an +\linebreak\cs{cleardoublepage} when it is not required. This may cause an unwanted blank page to appear before each glossary. This can be fixed by redefining \ics{glsclearpage}: \begin{verbatim} \renewcommand*{\glsclearpage}{\clearpage} \end{verbatim} +\item[\pkgopt{ucmark}] This is a boolean option (default: \pkgopt[false]{ucmark}). If +set, \ics{glossarymark} is defined to use \ics{MakeUppercase}. + \item[\pkgopt{numberedsection}] The glossaries are placed in unnumbered sectional units by default, but this can be changed using \pkgopt{numberedsection}. This option can take @@ -1491,16 +1544,18 @@ For example: will add \texttt{glo:} to the automatically generated label, so you can then, for example, refer to the list of acronyms as follows: \begin{verbatim} -The list of acronyms is in section~\ref{glo:\acronymtype}. +The list of acronyms is in +section~\ref{glo:\acronymtype}. \end{verbatim} Or, if you are undecided on a prefix: \begin{verbatim} -The list of acronyms is in section~\ref{\glsautoprefix\acronymtype}. +The list of acronyms is in +section~\ref{\glsautoprefix\acronymtype}. \end{verbatim} \end{description} -\subsection{Glossary Appearance Options} +\section{Glossary Appearance Options} \label{sec:pkgopts-printglos} \begin{description} @@ -1530,16 +1585,18 @@ option will automatically set \pkgopt[true]{entrycounter} and the \ctr{glossaryentry} counter will be reset every time \meta{value} is incremented. +\DescribeMacro{\glsresetentrycounter} \begin{important} The \ctr{glossaryentry} counter isn't automatically reset at the start of each glossary, except when glossary section numbering is on and the counter used by \pkgopt{counterwithin} is the same as the -counter used in the glossary's sectioning command. If you want -the counter reset at the start of each glossary, you can redefine -\ics{glossarypreamble} so that it sets \ctr{glossaryentry} to zero: +counter used in the glossary's sectioning command. If you want the +counter reset at the start of each glossary, you can redefine +\ics{glossarypreamble} to use \cs{glsresetentrycounter}, which sets +\ctr{glossaryentry} to zero: \begin{verbatim} \renewcommand{\glossarypreamble}{% - \setcounter{glossaryentry}{0}% + \glsresetentrycounter } \end{verbatim} \end{important} @@ -1553,7 +1610,7 @@ The counter is reset with each main (level~0) entry. Note that this package option is independent of \pkgopt{entrycounter}. You can reference the number within the document using \ics{glsrefentry}\marg{label} where \meta{label} is the label -associated with the sub-entry. (See above.) +associated with the sub-entry. \item[\pkgopt{style}] This is a \meta{key}=\meta{value} option. (Default is \pkgopt[list]{style}.) Its value should be the name of @@ -1592,13 +1649,17 @@ you use this option, you won't be able to use any of the glossary styles defined in the \styfmt{glossary-tree} package. \item[\pkgopt{nostyles}] This prevents all the predefined styles -from being loaded. This option is provided in the event that the -user has custom styles that are not dependent on the styles -provided by the \styfmt{glossaries} package. Note that if you use -this option, you can't use the \pkgopt{style} package option. Instead -you must either use \ics{glossarystyle}\marg{style} or -the \gloskey[printglossary]{style} key in the -optional argument to \ics{printglossary}. +from being loaded. If you use this option, you need to load a +glossary style package (such as \sty{glossary-mcols}). Also if you +use this option, you can't use the \pkgopt{style} package option. +Instead you must either use \ics{glossarystyle}\marg{style} or the +\gloskey[printglossary]{style} key in the optional argument to +\ics{printglossary}. Example: +\begin{verbatim} +\usepackage[nostyles]{glossaries} +\usepackage{glossary-mcols} +\glossarystyle{mcoltree} +\end{verbatim} \item[\pkgopt{nonumberlist}] This option will suppress the associated \glspl{numberlist} in the glossaries (see also @@ -1620,7 +1681,7 @@ the default counter to use in the \glspl{numberlist} \end{description} -\subsection{Sorting Options} +\section{Sorting Options} \label{sec:pkgopts-sort} \begin{description} @@ -1684,7 +1745,7 @@ with the \styfmt{glossaries} package. \end{description} -\subsection{Acronym Options} +\section{Acronym Options} \label{sec:pkgopts-acronym} \begin{description} @@ -1751,7 +1812,7 @@ for acronyms. See \sectionref{sec:acronyms} for further details. \end{description} -\section{Setting Up} +\chapter{Setting Up} \label{sec:setup} The command @@ -1826,7 +1887,7 @@ formats, then do: See \sectionref{sec:numberlists} for further information about \glspl{numberlist}. -\section{Defining Glossary Entries} +\chapter{Defining Glossary Entries} \label{sec:newglosentry} All glossary entries must be defined before they are used, so it is @@ -2009,7 +2070,9 @@ supply the \gloskey{sort} key if you are using \gls{makeindex} whereas \gls{xindy} is usually able to sort accented letters correctly. -\subsection{Plurals} +\section{Plurals} +\label{sec:plurals} + You may have noticed from above that you can specify the plural form when you define a term. If you omit this, the plural will be obtained by appending @@ -2057,7 +2120,43 @@ form plurals by simply appending a suffix, all the plural forms must be specified using the \gloskey{plural} key (and the \gloskey{firstplural} key where necessary). -\subsection{Sub-Entries} +\section{Other Grammatical Constructs} +\label{sec:grammar} + +You can use the six user keys to provide alternatives, such as +participles. For example: +\begin{verbatim} +\let\glsing\glsuseri +\let\glsd\glsuserii + +\newcommand*{\ingkey}{user1} +\newcommand*{\edkey}{user2} + +\newcommand*{\newterm}[3][]{% + \newglossaryentry{#2}{% + name={#2},% + description={#3},% + \edkey={#2ed},% + \ingkey={#2ing},#1% + }% +} +\end{verbatim} +With the above definitions, I can now define terms like this: +\begin{verbatim} +\newterm{play}{to take part in activities for enjoyment} +\newterm[\edkey={ran},\ingkey={running}]{run}{to move fast using +the legs} +\end{verbatim} +and use them in the text: +\begin{verbatim} +Peter is \glsing{play} in the park today. + +Jane \glsd{play} in the park yesterday. + +Peter and Jane \glsd{run} in the park last week. +\end{verbatim} + +\section{Sub-Entries} \label{sec:subentries} As from version 1.17, it is possible to specify sub-entries. These @@ -2081,7 +2180,8 @@ If the parent entry is not referenced in the document, it will not have a \gls{numberlist}. Note also that \gls{makeindex} has a restriction on the maximum sub-entry depth. -\subsubsection{Hierarchical Categories} +\subsection{Hierarchical Categories} +\label{sec:hierarchical} To arrange a glossary with hierarchical categories, you need to first define the category and then define the sub-entries using the @@ -2105,7 +2205,8 @@ description terminator. I can now define my sub-entries as follows: \begin{verbatim} \newglossaryentry{pi}{name={\ensuremath{\pi}},sort={pi}, -description={ratio of the circumference of a circle to the diameter}, +description={ratio of the circumference of a circle to +the diameter}, parent=greekletter} \newglossaryentry{C}{name={\ensuremath{C}},sort={C}, @@ -2114,7 +2215,8 @@ parent=romanletter} \end{verbatim} -\subsubsection{Homographs} +\subsection{Homographs} +\label{sec:homographs} Sub-entries that have the same name as the parent entry, don't need to have the \gloskey{name} key. For example, the word \qt{glossary} @@ -2159,20 +2261,21 @@ have different plurals, they will need to be specified. For example: \newglossaryentry{bravo}{name={bravo}, description={\nopostdesc}} -\newglossaryentry{bravocry}{description={cry of approval (pl.\ bravos)}, +\newglossaryentry{bravocry}{description={cry of approval +(pl.\ bravos)}, sort={1}, plural={bravos}, parent=bravo} -\newglossaryentry{bravoruffian}{description={hired ruffian or -killer (pl.\ bravoes)}, +\newglossaryentry{bravoruffian}{description={hired +ruffian or killer (pl.\ bravoes)}, sort={2}, plural={bravoes}, parent=bravo} \end{verbatim} -\subsection{Loading Entries From a File} +\section{Loading Entries From a File} \label{sec:loadglsentries} You can store all your glossary entry definitions in another @@ -2234,7 +2337,8 @@ there are two possible solutions to this problem: \item Change \texttt{myacronyms.tex} so that entries are defined in the form: \begin{verbatim} -\newacronym[type=\glsdefaulttype]{aca}{aca}{a contrived acronym} +\newacronym[type=\glsdefaulttype]{aca}{aca}{a +contrived acronym} \end{verbatim} and do: \begin{verbatim} @@ -2255,7 +2359,34 @@ in the text will appear in the relevant glossaries. Note also that \cs{loadglsentries} may only be used in the preamble. -\section{Number lists} +\section{Moving Entries to Another Glossary} +\label{sec:moveentry} + +As from version~3.02, you can move an entry from one glossary to +another using: +\begin{definition}[\DescribeMacro{\glsmoveentry}] +\cs{glsmoveentry}\marg{label}\marg{target glossary label} +\end{definition} +where \meta{label} is the unique label identifying the required +entry and \meta{target glossary label} is the unique label +identifying the glossary in which to put the entry. + +Note that no check is performed to determine the existence of +the target glossary. This means that you can, for example, move an +entry to an undefined glossary so you can use the entry in the +document text but not have it listed in any of the glossaries. +(Maybe you have an acronym so common it doesn't need listing.) + +\begin{important} +If you move an entry to an undefined glossary and you have +hyperlinked entries, the link will point to an undefined target. +Also, you will get warnings about no file defined for that glossary +(unless you use the \pkgopt{nowarn} package option). Unpredictable +results may occur if you move an entry to a different glossary from +its parent or children. +\end{important} + +\chapter{Number lists} \label{sec:numberlists} Each entry in the glossary has an associated \gls{numberlist}. @@ -2316,7 +2447,7 @@ used. \end{important} -\section{Links to Glossary Entries} +\chapter{Links to Glossary Entries} \label{sec:glslink} Once you have defined a glossary entry using \ics{newglossaryentry}, @@ -2344,8 +2475,8 @@ package. Instead, use one of the commands listed in alternative via the optional argument to the sectioning/caption command. Examples: \begin{verbatim} -\section{An overview of \glsentrytext{perl}} -\section[An overview of Perl]{An overview of \gls{perl}} +\chapter{An overview of \glsentrytext{perl}} +\chapter[An overview of Perl]{An overview of \gls{perl}} \end{verbatim} The way the \gls{linktext} is displayed depends on @@ -2552,7 +2683,8 @@ are using \sty{hyperref} as it can affect the spacing of subscripts and superscripts. For example, suppose you have defined the following entry: \begin{verbatim} -\newglossaryentry{Falpha}{name={F_\alpha},description=sample} +\newglossaryentry{Falpha}{name={F_\alpha}, +description=sample} \end{verbatim} and later you use it in math mode: \begin{verbatim} @@ -2787,7 +2919,7 @@ the hyperlink. Similarly for the other user keys: \cs{GLSuservi}\oarg{options}\marg{text}\oarg{insert} \end{definition} -\subsection{Changing the format of the link text} +\section{Changing the format of the link text} \label{sec:glsdisplay} The format of the \gls{linktext} for \ics{gls}, \ics{glspl} @@ -2823,7 +2955,8 @@ formatting commands, it's best to define a robust version that deals with all the formatting. For example, suppose you want the text to appear in bold italic, it's best to do something like: \begin{verbatim} -\DeclareRobustCommand{\textbfit}[1]{\emph{\bfseries #1}} +\DeclareRobustCommand{\textbfit}[1]{\emph{\bfseries +#1}} \renewcommand{\glsdisplay}[4]{\textbfit{#1#4}} \end{verbatim} See the \sty{mfirstuc} documentation for further details on the @@ -2919,7 +3052,8 @@ to appear in the \gls{linktext}, you will have to disable the \glsation{sanitize} of these keys and protect fragile commands. -\subsection{Enabling and disabling hyperlinks to glossary entries} +\section{Enabling and disabling hyperlinks to glossary entries} +\label{sec:disablehyperlinks} If you load the \sty{hyperref} or \sty{html} packages prior to loading the \styfmt{glossaries} package, commands such as \ics{glslink} @@ -2944,7 +3078,7 @@ affects commands that recognise the \firstuseflag, for example \ics{gls}, \ics{glspl} and \ics{glsdisp} but not \ics{glslink}. -\section{Adding an Entry to the Glossary Without Generating Text} +\chapter{Adding an Entry to the Glossary Without Generating Text} \label{sec:glsadd} It is possible to add a line in the glossary file without @@ -3022,7 +3156,7 @@ You can then define a new dual entry: Now you can reference the acronym with \verb|\gls{svm}| or you can reference the entry in the main glossary with \verb|\gls{main-svm}|. -\section{Cross-Referencing Entries} +\chapter{Cross-Referencing Entries} \label{sec:crossref} There are several ways of cross-referencing entries in the @@ -3060,7 +3194,8 @@ description={firm, round fruit. See also \item As described in \sectionref{sec:newglosentry}, you can use the \gloskey{see} key when you define the entry. For example: \begin{verbatim} -\newglossaryentry{MaclaurinSeries}{name={Maclaurin series}, +\newglossaryentry{MaclaurinSeries}{name={Maclaurin +series}, description={Series expansion}, see={TaylorsTheorem}} \end{verbatim} @@ -3074,7 +3209,8 @@ The \qt{see} tag is produce using \ics{seename}, but can be overridden in specific instances using square brackets at the start of the \gloskey{see} value. For example: \begin{verbatim} -\newglossaryentry{MaclaurinSeries}{name={Maclaurin series}, +\newglossaryentry{MaclaurinSeries}{name={Maclaurin +series}, description={Series expansion}, see=[see also]{TaylorsTheorem}} \end{verbatim} @@ -3108,7 +3244,8 @@ just use the \gloskey{see} key instead of \ics{glssee}, you can automatically activate the \gls*{numberlist} using the \pkgopt{seeautonumberlist} package option. -\subsection{Customising Cross-reference Text} +\section{Customising Cross-reference Text} +\label{sec:customxr} When you use either the \gloskey{see} key or the command \cs{glssee}, the cross-referencing information will be typeset in the @@ -3129,7 +3266,8 @@ both \gloskey{see} and \cs{glssee} explicitly write \texttt[\cs{seename}\texttt] in the output file if no optional argument is given.} \begin{verbatim} -\renewcommand*{\glsseeformat}[3][\seename]{\textbf{#1} \glsseelist{#2}} +\renewcommand*{\glsseeformat}[3][\seename]{\textbf{#1} + \glsseelist{#2}} \end{verbatim} @@ -3143,8 +3281,8 @@ or (for the last pair) \begin{definition}[\DescribeMacro{\glsseelastsep}] \cs{glsseelastsep} \end{definition} -These default to ",\space" and -\cs{space}\ics{andname}\cs{space} respectively. The list entry text +These default to ``",\space"'' and +``\cs{space}\ics{andname}\cs{space}'' respectively. The list entry text is displayed using: \begin{definition}[\DescribeMacro{\glsseeitemformat}] \cs{glsseeitemformat}\marg{label} @@ -3154,7 +3292,8 @@ versions before 3.0, \cs{glsentryname} was used, but this can cause problems when the \gloskey{name} key is \glsd{sanitize}.} For example, to make the cross-referenced list use small caps: \begin{verbatim} -\renewcommand{\glsseeitemformat}[1]{\textsc{\glsentrytext{#1}}} +\renewcommand{\glsseeitemformat}[1]{% + \textsc{\glsentrytext{#1}}} \end{verbatim} \begin{important} @@ -3169,7 +3308,7 @@ Some information (see also \end{verbatim} \end{important} -\section{Using Glossary Terms Without Links} +\chapter{Using Glossary Terms Without Links} \label{sec:glsnolink} The commands described in this section display entry details without @@ -3313,11 +3452,43 @@ 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 +\pkgopt{savenumberlist} package option: +\begin{definition}[\DescribeMacro{\glsentrynumberlist}] +\cs{glsentrynumberlist}\marg{label} +\end{definition} +\begin{definition}[\DescribeMacro{\glsdisplaynumberlist}] +\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 +the number list as is. The second command, +\linebreak\cs{glsdisplaynumberlist}, formats the list using: +\begin{definition}[\DescribeMacro{\glsnumlistsep}] +\cs{glsnumlistsep} +\end{definition} +as the separator between all but the last two elements and +\begin{definition}[\DescribeMacro{\glsnumlistlastsep}] +\cs{glsnumlistlastsep} +\end{definition} +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. +\end{important} + For further information see \ifpdf section~\ref*{sec:code:glsnolink} \fi \qt{Displaying entry details without adding information to the glossary} in the documented code (\texttt{glossaries.pdf}). -\section{Displaying a glossary} +\chapter{Displaying a glossary} \label{sec:printglossary} The command @@ -3370,7 +3541,7 @@ option, described in \sectionref{sec:pkgopts-sec}. \item[{\gloskey[printglossary]{nonumberlist}}] This is a boolean key. If true (\verb|nonumberlist=true|) the numberlist is suppressed -for this glossary. If false (\verb|nonumberlist=false|) the +for this glossary. If false \linebreak(\verb|nonumberlist=false|) the numberlist is displayed for this glossary. If no value is supplied, true is assumed. @@ -3379,7 +3550,7 @@ true is assumed. By default, the glossary is started either by \ics{chapter*} or by \ics{section*}, depending on whether or not \ics{chapter} is defined. This can be overridden by the \pkgopt{section} package option or the -\ics{setglossarysection} command. Numbered sectional units can be +\linebreak\ics{setglossarysection} command. Numbered sectional units can be obtained using the \pkgopt{numberedsection} package option. Each glossary sets the page header via the command \ics{glossarymark}. If this mechanism is unsuitable for your chosen class file or page @@ -3394,26 +3565,26 @@ title and before the main body of the glossary) by redefining \end{definition} For example: \begin{verbatim} -\renewcommand{\glossarypreamble}{Numbers in italic indicate -primary definitions.} +\renewcommand{\glossarypreamble}{Numbers in italic +indicate primary definitions.} \end{verbatim} This needs to be done before the glossary is displayed using -\cs{printglossaries} or \cs{printglossary}. Note that if you +\linebreak\cs{printglossaries} or \cs{printglossary}. Note that if you want a different preamble for each glossary, you will need to use a separate \cs{printglossary} for each glossary and change the definition of \cs{glossarypreamble} between each glossary. For example: \begin{verbatim} -\renewcommand{\glossarypreamble}{Numbers in italic indicate -primary definitions.} +\renewcommand{\glossarypreamble}{Numbers in italic +indicate primary definitions.} \printglossary \renewcommand{\glossarypreamble}{} \printglossary[type=acronym] \end{verbatim} Alternatively, you can do something like: \begin{verbatim} -\renewcommand{\glossarypreamble}{Numbers in italic indicate -primary definitions.\gdef\glossarypreamble{}} +\renewcommand{\glossarypreamble}{Numbers in italic +indicate primary definitions.\gdef\glossarypreamble{}} \printglossaries \end{verbatim} which will print the preamble text for the first glossary and @@ -3435,7 +3606,7 @@ but after the glossary you want to switch back to one column mode, you could do: \begin{verbatim} \renewcommand*{\glossarysection}[2][]{% - \twocolumn[{\section*{#2}}]% + \twocolumn[{\chapter*{#2}}]% \setlength\glsdescwidth{0.6\linewidth}% \glossarymark{\glossarytoctitle}% } @@ -3466,7 +3637,7 @@ medium weight small caps, then you can do: \end{verbatim} -\section{Xindy} +\chapter{Xindy} \label{sec:xindy} If you want to use \gls{xindy} to sort the glossary, you @@ -3513,7 +3684,9 @@ style file from being overwritten by the \styfmt{glossaries} package. For additional information about \gls*{xindy}, read the \gls*{xindy} documentation. -\subsection{Language and Encodings} +\section{Language and Encodings} +\label{sec:langenc} + When you use \gls{xindy}, you need to specify the language and encoding used (unless you have written your own custom \gls*{xindy} style file that defines the relevant alphabet @@ -3570,7 +3743,7 @@ need to remember to set the language and encoding using the \end{important} -\subsection{Locations and Number lists} +\section{Locations and Number lists} \label{sec:xindyloc} If you use \pkgopt{xindy}, the \styfmt{glossaries} package needs to @@ -3622,7 +3795,7 @@ you need to add a location style in the appropriate format using \end{definition} where \meta{name} is the name of the format and \meta{definition} is the \gls{xindy} definition. The optional argument \meta{prefix-location} -is needed if \cs{theH}\meta{counter} either isn't defined or is +is needed if \linebreak\cs{theH}\meta{counter} either isn't defined or is different from \cs{the}\meta{counter}. \begin{important} @@ -3787,7 +3960,8 @@ is used or if \ics{makeglossaries} is omitted. See \sectionref{sec:numberlists} for further details. -\subsection{Glossary Groups} +\section{Glossary Groups} +\label{sec:groups} The glossary is divided into groups according to the first letter of the sort key. The \styfmt{glossaries} package also adds @@ -3816,12 +3990,12 @@ Note that \cs{GlsSetXdyFirstLetterAfterDigits} has no effect if \end{important} -\section{Defining New Glossaries} +\chapter{Defining New Glossaries} \label{sec:newglossary} A new glossary can be defined using: \begin{definition}[\DescribeMacro{\newglossary}] -\cs{newglossary}\oarg{log-ext}\marg{name}\marg{in-ext}\marg{out-ext}\marg{title}\oarg{counter} +\cs{newglossary}\oarg{log-ext}\marg{name}\marg{in-ext}\marg{out-ext}\marg{title}\linebreak\oarg{counter} \end{definition} where \meta{name} is the label to assign to this glossary. The arguments \meta{in-ext} and \meta{out-ext} specify the extensions to @@ -3860,7 +4034,7 @@ ensure that the relevant output files are opened. \end{important} -\section{Acronyms} +\chapter{Acronyms} \label{sec:acronyms} You may have noticed in \sectionref{sec:newglosentry} that when you @@ -4043,7 +4217,7 @@ variants: \begin{definition}[\DescribeMacro{\Acrlong}] \cs{Acrlong}\oarg{options}\marg{label}\oarg{insert} \end{definition} -\begin{definition}[\DescribeMacro{\ACRshort}] +\begin{definition}[\DescribeMacro{\ACRlong}] \cs{ACRlong}\oarg{options}\marg{label}\oarg{insert} \end{definition} @@ -4143,7 +4317,8 @@ using: \cs{Glsentryfullpl}\marg{label} \end{definition} -\subsection{Predefined Acronym Styles} +\section{Predefined Acronym Styles} +\label{sec:predefinedacrstyles} Some of the acronym-related package options may be combined. Listed below are the effects of different combinations. If you use an @@ -4263,7 +4438,8 @@ while subsequent use displays the entry as: Entries will be sorted according to the short form. \end{description} -\subsection{Displaying the List of Acronyms} +\section{Displaying the List of Acronyms} +\label{sec:disploa} The list of acronyms is just like any other type of glossary and can be displayed on its own using @@ -4340,7 +4516,7 @@ None of the above& \end{center} \end{table} -\subsection{Defining A Custom Acronym Style} +\section{Defining A Custom Acronym Style} \label{sec:customacronym} You may find that the predefined acronyms styles that come with the @@ -4368,7 +4544,7 @@ This is used to set up the display style for the glossary given by and \ics{defglsdisplay}. Once you have redefined \cs{CustomAcronymFields} and -\cs{SetCustomDisplayStyle}, you must then switch to this style using +\linebreak\cs{SetCustomDisplayStyle}, you must then switch to this style using \begin{definition}[\DescribeMacro{\SetCustomStyle}] \cs{SetCustomStyle} \end{definition} @@ -4452,18 +4628,19 @@ the argument of \ics{SetCustomDisplayStyle}, and \verb|##1|, \ldots, \ics{glsdisplay}. Now that I've redefined \ics{CustomAcronymFields} and -\ics{SetCustomDisplayStyle}, I can set this style using +\linebreak\ics{SetCustomDisplayStyle}, I can set this style using \begin{verbatim} \SetCustomStyle \end{verbatim} and now I can define my acronyms: \begin{verbatim} -\newacronym[description={set of tags for use in developing hypertext -documents}]{html}{html}{Hyper Text Markup Language} +\newacronym[description={set of tags for use in +developing hypertext documents}]{html}{html}{Hyper +Text Markup Language} -\newacronym[description={language used to describe the layout of a -document written in a markup language}]{css}{css}{Cascading Style -Sheet} +\newacronym[description={language used to describe the +layout of a document written in a markup language}]{css} +{css}{Cascading Style Sheet} \end{verbatim} Note that since I've used the description in the main body of the @@ -4476,20 +4653,22 @@ that displays the symbol. Therefore, in my preamble I have: \begin{verbatim} \usepackage[colorlinks]{hyperref} -\usepackage[acronym, % create list of acronyms - nomain, % don't need main glossary for this example - style=tree, % need a style that displays the symbol - hyperfirst=false,% don't hyperlink first use - sanitize=none % switch off sanitization as description - % will be used in the main text - ]{glossaries} +\usepackage + [acronym, % create list of acronyms + nomain, % don't need main glossary for this example + style=tree, % need a style that displays the symbol + hyperfirst=false,% don't hyperlink first use + sanitize=none % switch off sanitization as description + % will be used in the main text + ]{glossaries} \end{verbatim} Note that I haven't used the \pkgopt{description} or \pkgopt{footnote} package options. -\subsection{Upgrading From the glossary Package} +\section{Upgrading From the glossary Package} \label{sec:oldacronym} + Users of the obsolete \sty{glossary} package may recall that the syntax used to define new acronyms has changed with the replacement \styfmt{glossaries} package. In addition, the old @@ -4566,7 +4745,7 @@ optional argument from being recognised. -\section{Unsetting and Resetting Entry Flags} +\chapter{Unsetting and Resetting Entry Flags} \label{sec:glsunset} When using \ics{gls}, \ics{glspl} and their uppercase variants it is @@ -4619,7 +4798,7 @@ entry has been used, \meta{true part} will be done, otherwise \meta{false part} will be done. -\section{Glossary Styles} +\chapter{Glossary Styles} \label{sec:styles} The \styfmt{glossaries} package comes with some pre-defined glossary styles. Note that the styles are suited to different @@ -4666,10 +4845,11 @@ be displayed.} \ttfamily super4col* & 1 & \tick & \tick \\ \ttfamily altsuper*4col* & 1 & \tick & \tick \\ \ttfamily super* & 1 & \tick & \\ -\ttfamily index* & 2 & & \tick\\ +\ttfamily *index* & 2 & & \tick\\ \ttfamily treenoname* & --- & \tick & \tick\\ -\ttfamily tree* & --- & & \tick\\ -\ttfamily alttree* & --- & & \tick +\ttfamily *tree* & --- & & \tick\\ +\ttfamily *alttree* & --- & & \tick\\ +\ttfamily inline & 1 & \tick & \end{tabular} \par \end{table} @@ -4738,7 +4918,7 @@ a comma) you will need to redefine \cs{glspostdescription} before the glossary is displayed. Alternatively, you can suppress it for a given entry by placing \ics{nopostdesc} in the entry's description. -\subsection{List Styles} +\section{List Styles} \label{sec:liststyles} The styles described in this section are all defined in the package @@ -4813,7 +4993,7 @@ the same manner as \glostyle{listdotted}. \end{description} -\subsection{Longtable Styles} +\section{Longtable Styles} \label{sec:longstyles} The styles described in this section are all defined in the package @@ -4891,7 +5071,7 @@ around it. \glostyle{long4col} but allows multi-line descriptions and page lists. The width of the description column is governed by the length \ics{glsdescwidth} and the width of the page list column is -governed by the length \ics{glspagelistwidth}. The widths of the +governed by the length \linebreak\ics{glspagelistwidth}. The widths of the name and symbol columns are governed by the widest entry in the given column. @@ -4904,12 +5084,12 @@ page lists. page lists. \item[altlong4colheaderborder] The \glostyle{altlong4colheaderborder} -style is like \glostyle{long4colheaderborder} but allows multi-line +style is like \linebreak\glostyle{long4colheaderborder} but allows multi-line descriptions and page lists. \end{description} -\subsection{Longtable Styles (Ragged Right)} +\section{Longtable Styles (Ragged Right)} \label{sec:longraggedstyles} The styles described in this section are all defined in the package @@ -4996,7 +5176,7 @@ lines around it. \end{description} -\subsection{Supertabular Styles} +\section{Supertabular Styles} \label{sec:superstyles} The styles described in this section are all defined in the package @@ -5051,7 +5231,7 @@ lines around it. \glostyle{super3col} but has a header row. \item[super3colheaderborder] The \glostyle{super3colheaderborder} style -is like \glostyle{super3colheader} but has horizontal and vertical +is like the \linebreak\glostyle{super3colheader} style but has horizontal and vertical lines around it. \item[super4col] The \glostyle{super4col} style is like @@ -5069,7 +5249,7 @@ lines around it. \glostyle{super4col} but has a header row. \item[super4colheaderborder] The \glostyle{super4colheaderborder} style -is like \glostyle{super4colheader} but has horizontal and vertical +is like the \linebreak\glostyle{super4colheader} style but has horizontal and vertical lines around it. \item[altsuper4col] The \glostyle{altsuper4col} style is like @@ -5095,7 +5275,7 @@ descriptions and page lists. \end{description} -\subsection{Supertabular Styles (Ragged Right)} +\section{Supertabular Styles (Ragged Right)} \label{sec:superraggedstyles} The styles described in this section are all defined in the package @@ -5183,7 +5363,7 @@ lines around it. \end{description} -\subsection{Tree-Like Styles} +\section{Tree-Like Styles} \label{sec:treestyles} The styles described in this section are all defined in the package @@ -5270,7 +5450,112 @@ groups. The navigation line is the same as that for \end{description} -\section{Defining your own glossary style} +\section{Multicols Style} +\label{sec:mcolstyles} + +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''. +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}. + +\begin{important} +Note that \sty{glossary-mcols} is not loaded by \styfmt{glossaries}. If +you want to use any of the multicol styles in that package you need +to load it explicitly with \cs{usepackage} and set the required glossary +style using \ics{glossarystyle}. +\end{important} + +The default number of columns is 2, but can be changed by redefining +\begin{definition}[\DescribeMacro{\glsmcols}] +\cs{glsmcols} +\end{definition} +to the required number. For example, for a three column glossary: +\begin{verbatim} +\usepackage{glossary-mcols} +\renewcommand*{\glsmcols}{3} +\glossarystyle{mcolindex} +\end{verbatim} + +\begin{table}[htbp] +\caption{Multicolumn Styles} +\label{tab:mcols} +\centering +\begin{tabular}{ll} +\bfseries +\sty{glossary-mcols} Style & +\bfseries +Analogous Tree Style\\ +\glostyle{mcolindex} & \glostyle{index}\\ +\glostyle{mcolindexgroup} & \glostyle{indexgroup}\\ +\glostyle{mcolindexhypergroup} & \glostyle{indexhypergroup}\\ +\glostyle{mcoltree} & \glostyle{tree}\\ +\glostyle{mcoltreegroup} & \glostyle{treegroup}\\ +\glostyle{mcoltreehypergroup} & \glostyle{treehypergroup}\\ +\glostyle{mcoltreenoname} & \glostyle{treenoname}\\ +\glostyle{mcoltreenonamegroup} & \glostyle{treenonamegroup}\\ +\glostyle{mcoltreenonamehypergroup} & \glostyle{treenonamehypergroup}\\ +\glostyle{mcolalttree} & \glostyle{alttree}\\ +\glostyle{mcolalttreegroup} & \glostyle{alttreegroup}\\ +\glostyle{mcolalttreehypergroup} & \glostyle{alttreehypergroup} +\end{tabular} +\end{table} + +\section{In-Line Style} +\label{sec:inline} + +This section covers the \sty{glossary-inline} package that supplies +the \glostyle{inline} style. This is a style that is designed for +in-line use (as opposed to block styles, such as lists or tables). +This style doesn't display the \gls{numberlist}. + +You will most likely need to redefine \ics{glossarysection} with +this style. For example, suppose you are required to have your +glossaries and list of acronyms in a footnote, you can do: +\begin{verbatim} + \usepackage{glossary-inline} + + \renewcommand*{\glossarysection}[2][]{\textbf{#1}: } + \glossarystyle{inline} +\end{verbatim} + +\begin{important} +Note that you need to include \sty{glossary-inline} with +\cs{usepackage} as it's not automatically included by the +\styfmt{glossaries} package and then set the style using +\ics{glossarystyle}. +\end{important} + +Where you need to include your glossaries as a footnote you can do: +\begin{verbatim} +\footnote{\printglossaries} +\end{verbatim} + +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 +main (i.e.\ level~0) entries. +\begin{definition}[\DescribeMacro{\glsinlinesubseparator}] +\ics{glsinlinesubseparator} +\end{definition} +This defaults to ``\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 +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 +of the glossary. + +\chapter{Defining your own glossary style} \label{sec:newglossarystyle} If the predefined styles don't fit your requirements, you can @@ -5452,7 +5737,8 @@ For further details of these commands, see \ifpdf section~\ref*{sec:code:printglos} \fi \qt{Displaying the glossary} in the documented code (\texttt{glossaries.pdf}). -\subsection{Example: creating a completely new style} +\section{Example: creating a completely new style} +\label{sec:exnewstyle} If you want a completely new style, you will need to redefine all of the commands and the environment listed above. @@ -5472,7 +5758,8 @@ at the end. Then you can create this new glossary style, called, say, \begin{verbatim} \newglossarystyle{mylist}{% % put the glossary in the itemize environment: - \renewenvironment{theglossary}{\begin{itemize}}{\end{itemize}}% + \renewenvironment{theglossary}% + {\begin{itemize}}{\end{itemize}}% % have nothing after \begin{theglossary}: \renewcommand*{\glossaryheader}{}% % have nothing between glossary groups: @@ -5497,8 +5784,9 @@ It also hasn't used \ics{glsentryitem} or \ics{glssubentryitem} so it won't be affected by the \pkgopt{entrycounter}, \pkgopt{counterwithin} or \pkgopt{subentrycounter} package options. -\subsection{Example: creating a new glossary style based on an +\section{Example: creating a new glossary style based on an existing style} +\label{sec:exadaptstyle} If you want to define a new style that is a slightly modified version of an existing style, you can use \ics{glossarystyle} @@ -5511,13 +5799,15 @@ follows: \begin{verbatim} \newglossarystyle{mylist}{% \glossarystyle{list}% base this style on the list style -\renewcommand{\glsgroupskip}{}% make nothing happen between groups +\renewcommand{\glsgroupskip}{}% make nothing happen + % between groups } \end{verbatim} -\subsection{Example: creating a glossary style that uses the +\section{Example: creating a glossary style that uses the \texorpdfstring{\gloskey{user1}}{user1}, \ldots, \texorpdfstring{\gloskey{user6}}{user6} keys} +\label{sec:exuserstyle} Since \ics{glossaryentryfield} and \ics{glossarysubentryfield} provide the label for the entry, it's also possible to access @@ -5566,8 +5856,78 @@ that displays each entry in a \env{longtable} as follows: } \end{verbatim} +\chapter{Utilities} +\label{sec:utilities} + +This section describes some utility commands. Additional commands +can be found in the documented code (glossaries.pdf). + +\begin{definition}[\DescribeMacro{\forallglossaries}] +\cs{forallglossaries}\oarg{glossary list}\marg{cs}\marg{body} +\end{definition} +This iterates through \meta{glossary list}, a comma-separated list +of glossary labels (as supplied when the glossary was defined). +At each iteration \meta{cs} (which must be a control sequence) is +set to the glossary label for the current iteration and \meta{body} +is performed. If \meta{glossary list} is omitted, the default is to +iterate over all glossaries. + +\begin{definition}[\DescribeMacro{\forglsentries}] +\cs{forglsentries}\oarg{glossary label}\marg{cs}\marg{body} +\end{definition} +This iterates through all entries in the glossary given by +\meta{glossary label}. At each iteration \meta{cs} (which must be a +control sequence) is set to the entry label for the current +iteration and \meta{body} is performed. If \meta{glossary label} is +omitted, \ics{glsdefaulttype} (usually the main glossary) is used. + +\begin{definition}[\DescribeMacro{\forallglsentries}] +\cs{forallglsentries}\oarg{glossary list}\marg{cs}\marg{body} +\end{definition} +This is like \cs{forglsentries} but for each glossary in +\meta{glossary list} (a comma-separated list of glossary labels). If +\meta{glossary list} is omitted, the default is the list of all +defined glossaries. At each iteration \meta{cs} is set to the entry +label and \meta{body} is performed. (The current glossary label can +be obtained using \cs{glsentrytype}\marg{cs} within \meta{body}.) + +\begin{definition}[\DescribeMacro{\ifglossaryexists}] +\cs{ifglossaryexists}{\meta{label}}{\meta{true part}}{\meta{false +part}} +\end{definition} +This checks if the glossary given by \meta{label} exists. If it +does \meta{true part} is performed, otherwise \meta{false part}. -\section{Accessibility Support}\label{sec:accsupp} +\begin{definition}[\DescribeMacro{\ifglsentryexists}] +\cs{ifglsentryexists}{\meta{label}}{\meta{true part}}{\meta{false +part}} +\end{definition} +This checks if the glossary entry given by \meta{label} exists. If it +does \meta{true part} is performed, otherwise \meta{false part}. + +\begin{definition}[\DescribeMacro{\ifglsused}] +\cs{ifglsentryexists}{\meta{label}}{\meta{true part}}{\meta{false +part}} +\end{definition} +See \sectionref{sec:glsunset}. + +\begin{definition}[\DescribeMacro{\ifglshaschildren}] +\cs{ifglshaschildren}{\meta{label}}{\meta{true part}}{\meta{false +part}} +\end{definition} +This checks if the glossary entry given by \meta{label} has any +sub-entries. If it does, \meta{true part} is performed, otherwise +\meta{false part}. + +\begin{definition}[\DescribeMacro{\ifglshasparent}] +\cs{ifglshasparent}{\meta{label}}{\meta{true part}}{\meta{false +part}} +\end{definition} +This checks if the glossary entry given by \meta{label} has a parent +entry. If it does, \meta{true part} is performed, otherwise +\meta{false part}. + +\chapter{Accessibility Support}\label{sec:accsupp} Limited accessibility support is provided by the accompanying \sty{glossaries-accsupp} package, but note that this package is experimental and it requires the \sty{accsupp} package @@ -5617,8 +5977,8 @@ the \gloskey{shortplural} key (used by \ics{newacronym}). \end{description} For example: \begin{verbatim} -\newglossaryentry{tex}{name={\TeX},description={Document preparation -language},access={TeX}} +\newglossaryentry{tex}{name={\TeX},description={Document +preparation language},access={TeX}} \end{verbatim} Now \verb|\gls{tex}| will be equivalent to \begin{verbatim} @@ -5631,7 +5991,7 @@ See \ifpdf section~\ref*{sec:code:accsupp} in \fi the documented code (\texttt{glossaries.pdf}) for further details. It is recommended that you also read the \sty{accsupp} documentation. -\section{Troubleshooting} +\chapter{Troubleshooting} \label{sec:trouble} The \styfmt{glossaries} package comes with a minimal file called @@ -5640,7 +6000,7 @@ should be located in the \texttt{samples} subdirectory (folder) of the \styfmt{glossaries} documentation directory. The location varies according to your operating system and \TeX\ installation. For example, on my Linux partition it can be found in -\texttt{/usr/local/texlive/2008/texmf-dist/doc/latex/glossaries/}. +\texttt{/usr/local/texlive/2008/texmf-dist\linebreak/doc/latex/glossaries/}. Further information on debugging \LaTeX\ code is available at \url{http://theoval.cmp.uea.ac.uk/~nlct/latex/minexample/}. @@ -5660,7 +6020,8 @@ package. \item \textbf{Q.} When I use \gls{xindy}, I get the following error message: \begin{verbatim} -ERROR: CHAR: index 0 should be less than the length of the string +ERROR: CHAR: index 0 should be less than the length of +the string \end{verbatim} \textbf{A.} \gls{xindy} discards all commands and braces from the @@ -5728,10 +6089,12 @@ as above. For example to make the acronym emphasized on \item \textbf{Q.} I don't have Perl installed, do I have to use \gls{makeglossaries}? -\textbf{A.} Although it is strongly recommended that you use -\gls{makeglossaries}, you don't have to use it. For further details, -read \sectionref{sec:xindyapp} or \sectionref{sec:makeindexapp}, -depending on whether you want to use \gls{xindy} or \gls{makeindex}. +\textbf{A.} No. Although it is strongly recommended, you don't have to +use \gls{makeglossaries}. If you prefer a GUI application and have +Java installed, you can use \gls{makeglossariesgui} instead. +Otherwise you can just call \gls{makeindex} explicitly (see +\sectionref{sec:makeindexapp}). Note that you can't use \gls{xindy} +if you don't have Perl installed. \item \textbf{Q.} I'm used to using the \styfmt{glossary} package: are there any instructions on migrating from the \sty{glossary} package to the @@ -5835,10 +6198,26 @@ If you want to sort according to order of definition or order of use, use the \pkgopt{sort} package option described in \sectionref{sec:pkgopts-sort}. +\item \textbf{Q.} I get an error when using TeX4HT\index{TeX4HT|hyperpage} with +\styfmt{glossaries}. + +\textbf{A.} TeX4HT seems to have a problem with the glossary styles +that use \ics{indexspace}. I don't know enough about TeX4HT to find +out why. Either use a different glossary style or redefine the +style command that uses \cs{indexspace}. For example, if you are +using the \glostyle{list} style, try: +\begin{verbatim} +\renewcommand*{\glsgroupskip}{} +\end{verbatim} +or +\begin{verbatim} +\renewcommand*{\glsgroupskip}{\item[]} +\end{verbatim} + \end{enumerate} \clearpage\phantomsection -\addcontentsline{toc}{section}{Index}\PrintIndex +\addcontentsline{toc}{chapter}{Index}\PrintIndex \end{document} |