summaryrefslogtreecommitdiff
path: root/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
diff options
context:
space:
mode:
Diffstat (limited to 'Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex')
-rw-r--r--Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex185
1 files changed, 146 insertions, 39 deletions
diff --git a/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex b/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
index a1288c3db33..98965518cad 100644
--- a/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
+++ b/Master/texmf-dist/doc/latex/glossaries/glossaries-user.tex
@@ -65,11 +65,36 @@
\IndexPrologue{\chapter*{\indexname}
\markboth{\indexname}{\indexname}}
+\newglossaryentry{indexingapp}%
+{
+ name={Indexing application},
+ text={indexing application},
+ description={an application (piece of software) separate from
+ \TeX/\LaTeX\ that collates and sorts information that has an
+ associated page reference. Generally the information is an index
+ entry but in this case the information is a glossary entry.
+ There are two main indexing applications that are used with \TeX:
+ \protect\gls{makeindex} and \protect\gls{xindy}. These are both
+ \gls{cli} applications}
+}
+
+\newglossaryentry{cli}
+{
+ name={Command Line Interface (CLI)},
+ first={command line interface (CLI)},
+ text={CLI},
+ description={an application that doesn't have a graphical user
+ interface. That is, an application that doesn't have any windows,
+ buttons or menus and can be run in a command
+ prompt or terminal (see
+ \url{http://www.dickimaw-books.com/latex/novices/html/terminal.html})}
+}
+
\newglossaryentry{xindy}{
name={\appfmt{xindy}\index{xindy|htextbf}},
sort={xindy},
text={\protect\app{xindy}},
-description={An flexible indexing application with multilingual
+description={A flexible \protect\gls{indexingapp} with multilingual
support written in Perl}
}
@@ -77,7 +102,7 @@ support written in Perl}
name={\appfmt{makeindex}\index{makeindex|htextbf}},%
sort={makeindex},%
text={\protect\app{makeindex}},%
-description={An indexing application},
+description={An \protect\gls{indexingapp}},
}
\newglossaryentry{makeglossaries}{%
@@ -233,11 +258,11 @@ package option \pkgopt{sanitize} described in \sectionref{sec:pkgopts-general}}
\MakeShortVerb{"}
\DeleteShortVerb{\|}
- \title{User Manual for glossaries.sty v3.03}
+ \title{User Manual for glossaries.sty v3.04}
\author{Nicola L.C. Talbot\\%
\url{http://www.dickimaw-books.com/}}
- \date{2012-09-21}
+ \date{2012-11-18}
\maketitle
\noindent
@@ -265,7 +290,7 @@ 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.03}.
+\qt{Documented Code for glossaries v3.04}.
This includes the documented code for the \sty{mfirstuc} package.
\item[INSTALL] Installation instructions.
@@ -278,7 +303,11 @@ This includes the documented code for the \sty{mfirstuc} package.
\begin{important}
If you use \sty{hyperref} and \styfmt{glossaries}, you must load
-\sty{hyperref} \emph{first}.
+\sty{hyperref} \emph{first}. Similarly the \sty{doc} package must
+also be loaded before \styfmt{glossaries}. (If \sty{doc} is loaded,
+the file extensions for the default main glossary are changed to
+\filetype{gls2}, \filetype{glo2} and \filetype{.glg2} to avoid
+conflict with \sty{doc}'s changes glossary.)
\end{important}
\clearpage
@@ -316,14 +345,20 @@ size of the manual, try starting off with the much shorter
\begin{important}
The \styfmt{glossaries} package comes with a
\href{http://www.perl.org/about.html}{Perl} script called
-\gls{makeglossaries}. This provides a convenient interface to
-\gls{makeindex} or \gls{xindy}. It is strongly recommended
-that you use this script, but \emph{it is not essential}. If you are
-reluctant to install Perl, or for any other reason you don't want to
-use \gls*{makeglossaries}, you can called \gls*{makeindex} or
-\gls*{xindy} explicitly. See \sectionref{sec:makeglossaries} for
-further details.
+\gls{makeglossaries}. This provides a convenient interface to the
+\glspl{indexingapp} \gls{makeindex} or \gls{xindy}. It is strongly
+recommended that you use this script, but \emph{it is not
+essential}. If you are reluctant to install Perl, or for any other
+reason you don't want to use \gls*{makeglossaries}, you can call
+\gls*{makeindex} or \gls*{xindy} explicitly. See
+\sectionref{sec:makeglossaries} for further details.
\end{important}
+This document uses the \styfmt{glossaries} package. For example,
+when viewing the PDF version of this document in a
+hyperlinked-enabled PDF viewer (such as Adobe Reader) if
+you click on the word ``\gls{xindy}'' you'll be taken to the entry
+in the glossary where there's a brief description of
+what ``\gls*{xindy}'' is.
The remainder of this introductory section covers the following:
\begin{itemize}
@@ -348,7 +383,8 @@ be located in the \texttt{samples} subdirectory (folder) of the
\styfmt{glossaries} documentation directory. This location varies
according to your operating system and \TeX\ distribution. You
can use \texttt{texdoc} to locate the main glossaries documentation.
-For example, in a terminal or command prompt, type:
+For example, in a
+\href{http://www.dickimaw-books.com/latex/novices/html/terminal.html}{terminal or command prompt}, type:
\begin{prompt}
texdoc -l glossaries
\end{prompt}
@@ -386,7 +422,7 @@ latex minimalgls
If this is the case, you will need to update the \styfmt{xkeyval}
package.
- \item Run \gls{makeglossaries} on the document. This can
+ \item Run \gls{makeglossaries} on the document (\sectionref{sec:makeglossaries}). This can
be done on a terminal either by typing
\begin{prompt}
makeglossaries minimalgls
@@ -955,11 +991,11 @@ details.
\label{sec:makeglossaries}
In order to generate a sorted glossary with compact \glspl{locationlist},
-it is necessary to use an external indexing application as an
+it is necessary to use an external \gls{indexingapp} as an
intermediate step. It is this application that creates the file
containing the code that typesets the glossary. If this step is
omitted, the glossaries will not appear in your document. The two
-indexing applications that are most commonly used with \LaTeX\ are
+\glspl*{indexingapp} that are most commonly used with \LaTeX\ are
\gls{makeindex} and \gls{xindy}. As from version 1.17, the
\styfmt{glossaries} package can be used with either of these
applications. Previous versions were designed to be used with
@@ -1113,7 +1149,13 @@ perl makeglossaries myDoc
\end{prompt}
There is a batch file called \texttt{makeglossaries.bat} which does
this for Windows users, but you must have Perl installed to be able
-to use it.
+to use it. You can specify in which directory the \filetype{.aux},
+\filetype{.glo} etc files are located using the \texttt{-d} switch.
+For example:
+\begin{prompt}
+pdflatex -output-directory myTmpDir myDoc
+makeglossaries -d myTmpDir myDoc
+\end{prompt}
The \gls{makeglossaries} script contains POD (Plain Old
Documentation). If you want, you can create a man page for
@@ -1261,27 +1303,28 @@ The file extensions used by each defined glossary are given by
\begin{definition}[\DescribeMacro{\@newglossary}]
\cs{@newglossary}\marg{label}\marg{log}\marg{out-ext}\marg{in-ext}
\end{definition}
-where \meta{in-ext} is the extension of the \emph{indexing
-application's} input file (the output file from the \styfmt{glossaries}
-package's point of view), \meta{out-ext} is the extension of the
-\emph{indexing application's} output file (the input file from
-the \styfmt{glossaries} package's point of view) and \meta{log} is the
-extension of the indexing application's transcript file. The label
-for the glossary is also given for information purposes only, but
-is not required by the indexing applications. For example, the
-information for the main glossary is written as:
+where \meta{in-ext} is the extension of the
+\emph{\gls{indexingapp}['s]} input file (the output file from the
+\styfmt{glossaries} package's point of view), \meta{out-ext} is the
+extension of the \emph{\gls*{indexingapp}['s]} output file (the
+input file from the \styfmt{glossaries} package's point of view) and
+\meta{log} is the extension of the \gls*{indexingapp}['s] transcript
+file. The label for the glossary is also given for information
+purposes only, but is not required by the \glspl*{indexingapp}. For
+example, the information for the default main glossary is written
+as:
\begin{verbatim}
\@newglossary{main}{glg}{gls}{glo}
\end{verbatim}
-The indexing application's style file is specified by
+The \gls{indexingapp}['s] style file is specified by
\begin{definition}[\DescribeMacro{\@istfilename}]
\cs{@istfilename}\marg{filename}
\end{definition}
The file extension indicates whether to use \gls{makeindex}
(\filetype{.ist}) or \gls{xindy} (\filetype{.xdy}). Note that
the glossary information is formatted differently depending on
-which indexing application is supposed to be used, so it's
+which \gls*{indexingapp} is supposed to be used, so it's
important to call the correct one.
Word or letter ordering is specified by:
@@ -1413,6 +1456,18 @@ 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{nohypertypes}] Use this option if you have multiple
+glossaries and you want to suppress the entry hyperlinks for a
+particular glossary or glossaries. The value of this option should
+be a comma-separated list of glossary types where \ics{gls} etc
+shouldn't have hyperlinks by default. Make sure you enclose the
+value in braces if it contains any commas. Example:
+\begin{verbatim}
+\usepackage[acronym,nohypertypes={acronym,notation}]{glossaries}
+\newglossary[nlg]{notation}{not}{ntn}{Notation}
+\end{verbatim}
+See \sectionref{sec:glslink} for further details.
+
\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
@@ -2389,6 +2444,8 @@ document text but not have it listed in any of the glossaries.
\begin{important}
If you move an entry to an undefined glossary and you have
hyperlinked entries, the link will point to an undefined target.
+(Unless you identify that glossary using \pkgopt{nohypertypes} or
+\ics{GlsDeclareNoHyperList}, as described in \sectionref{sec:glslink}.)
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
@@ -2488,6 +2545,44 @@ command. Examples:
\chapter[An overview of Perl]{An overview of \gls{perl}}
\end{verbatim}
+If you want the \gls{linktext} to produce a hyperlink to the
+corresponding entry details in the glossary, you should load the
+\sty{hyperref} package \emph{before} the \styfmt{glossaries}
+package. That's what I've done in this document, so if you see a
+hyperlinked term, such as \gls{linktext}, you can click on the word
+or phrase and it will take you to a brief description in this
+document's glossary.
+
+It may be that you only want terms in a certain glossary to have
+links, but not for another glossary. In which case, you can use the
+package option \pkgopt{nohypertypes} to identify the glossary lists
+that shouldn't have hyperlinked \gls{linktext}. For example, suppose
+your document contains lots of technical acronyms that the reader
+might not know, but it also contains some very common acronyms that
+most readers will recognise. So you might want two acronym lists,
+but only the technical list will get displayed in your document. The
+technical acronyms can be hyperlinked to that list, but common
+acronyms shouldn't have hyperlinks as there's no target for them. In
+this case, identify the common acronym list as having
+non-hyperlinked entries using \pkgopt{nohypertypes}. Example:
+\begin{verbatim}
+\usepackage[acronym,nohypertypes={common}]{glossaries}
+\newglossary{common}{cacr}{cacn}{Common Acronyms}
+\end{verbatim}
+Alternatively, you can use
+\begin{definition}[\DescribeMacro{\GlsDeclareNoHyperList}]
+\cs{GlsDeclareNoHyperList}\marg{type}
+\end{definition}
+For example:
+\begin{verbatim}
+\usepackage[acronym]{glossaries}
+\newglossary{common}{cacr}{cacn}{Common Acronyms}
+\GlsDeclareNoHyperList{common}
+\end{verbatim}
+Note that no check is performed to see if the glossary types listed
+in \pkgopt{nohypertypes} or \cs{GlsDeclareNoHyperList} have been
+defined.
+
The way the \gls{linktext} is displayed depends on
\begin{definition}[\DescribeMacro{\glstextformat}]
\cs{glstextformat}\marg{text}
@@ -2616,7 +2711,17 @@ used by this entry. (See also \sectionref{sec:numberlists}.)
be used to enable/disable the hyperlink to the relevant entry
in the glossary. (Note that setting \texttt{hyper=true} will have no
effect if \ics{hyperlink} has not been defined.) The default
-value is \texttt{hyper=true}.
+value is \texttt{hyper=true}, unless the entry belongs to a glossary
+that either has been listed in the package option
+\pkgopt{nohypertypes} or has been identified using
+\ics{GlsDeclareNoHyperList} in which case the default is
+\texttt{hyper=false}.
+
+\item[\gloskey{glslink}{local}] This is a boolean key that only
+makes a different when used with commands that change the
+entry's \gls{firstuseflag} (such as \ics{gls}). If
+\texttt{local=true}, the change to the \gls*{firstuseflag} will be
+localised to the current scope. The default is \texttt{local=false}.
\end{description}
There is also a starred version:
@@ -3658,7 +3763,7 @@ This ensures that the glossary information is written in
\gls*{xindy} syntax.
\sectionref{sec:makeglossaries} covers how to use the external
-indexing application. This section covers the commands provided
+\gls{indexingapp}. This section covers the commands provided
by the \styfmt{glossaries} package that allow you to adjust the
\gls{xindy} style file (\filetype{.xdy}) and parameters.
@@ -6025,15 +6130,17 @@ For example, on my Linux partition it can be found in
Further information on debugging \LaTeX\ code is available at
\url{http://theoval.cmp.uea.ac.uk/~nlct/latex/minexample/}.
-Below is a list of the most frequently asked questions. For
-other queries, consult the \styfmt{glossaries} FAQ at
-\url{http://theoval.cmp.uea.ac.uk/~nlct/latex/packages/faq/glossariesfaq.html}.
+Below is a list of the most frequently asked questions. For other
+queries, consult the \styfmt{glossaries} FAQ at
+\url{http://www.dickimaw-books.com/faqs/glossariesfaq.html}. If that
+doesn't help, try posting your query to somewhere like the
+comp.text.tex newsgroup, the \LaTeX\ Community Forum
+(\url{http://www.latex-community.org/}) or Stack Exchange
+(\url{http://tex.stackexchange.com/}). I read all those three places
+and respond to queries there far quicker than to email messages (my
+inbox is always very cluttered).
Bug reports can be submitted at
-\url{http://www.dickimaw-books.com/bug-report.html}. For general
-queries, you are more likely to get a faster response if you post
-them to somewhere like the comp.text.tex newsgroup, the \LaTeX\
-Community Forum (\url{http://www.latex-community.org/}) or
-Stack Exchange (\url{http://tex.stackexchange.com/}).
+\url{http://www.dickimaw-books.com/bug-report.html}.
\begin{enumerate}
\item \textbf{Q.} I get the error message: