diff options
author | Karl Berry <karl@freefriends.org> | 2009-09-25 00:48:57 +0000 |
---|---|---|
committer | Karl Berry <karl@freefriends.org> | 2009-09-25 00:48:57 +0000 |
commit | 1b5baf0f475cbfdc378718a46057c5c481b59065 (patch) | |
tree | 6ee2f82a5e33642af5af9bfffe47cbc0c48ecbfa /Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex | |
parent | f453f119c796c9607b391bbf26971fda1826c51c (diff) |
glossaries update (24sep09)
git-svn-id: svn://tug.org/texlive/trunk@15452 c570f23f-e606-0410-a88d-b1316a301751
Diffstat (limited to 'Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex')
-rw-r--r-- | Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex | 167 |
1 files changed, 127 insertions, 40 deletions
diff --git a/Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex b/Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex index d17471374bd..8356d8f8b09 100644 --- a/Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex +++ b/Master/texmf-dist/doc/latex/glossaries/glossaries-manual.tex @@ -19,6 +19,11 @@ \usepackage{creatdtx} \ifmakedtx{ +\usepackage{dox} +\doxitem{Option}{option}{package options} +\doxitem{GlsKey}{key}{glossary keys} +\doxitem{Style}{style}{glossary styles} + \renewcommand{\usage}[1]{\textit{\hyperpage{#1}}} \renewcommand{\main}[1]{\hyperpage{#1}} \newcommand{\see}[2]{\emph{see} #1} @@ -27,7 +32,7 @@ \makeatother \RecordChanges \PageIndex -\CheckSum{8711} +\CheckSum{8767} \CodelineNumbered \newcommand*{\termdef}[1]{\emph{#1}\iterm{#1}} \newcommand*{\term}[1]{#1\iterm{#1}} @@ -62,8 +67,18 @@ \newcommand*{\Tableref}[1]{\htmlref{Table~}{#1}\ref{#1}} \newenvironment{important}{}{} \newcommand*{\tick}{X} + +\newcommand{\DescribeOption}[1]{} +\newcommand{\DescribeGlsKey}[1]{} +\newcommand{\DescribeStyle}[1]{} } +\makeatletter +\renewenvironment{theindex}{\twocolumn[\index@prologue] +\let\item\@idxitem +\ignorespaces +}{} +\makeatother \newcommand*{\ifirstuse}{\iterm{first use}} \newcommand*{\firstuse}{first use\ifirstuse} @@ -82,14 +97,14 @@ \newcommand*{\pkgoptni}[1]{\textsf{#1}} \newcommand*{\ipkgopt}[2][]{% \ifthenelse{\equal{#1}{}}{% -\index{package options>#2=\pkgoptni{#2}|hyperpage}}{% -\index{package options>#2=\pkgoptni{#2}>#1=\pkgoptni{#1}|hyperpage}}} +\index{package options:>#2={\protect\ttfamily #2}|main}}{% +\index{package options:>#2={\protect\ttfamily #2}>#1={\protect\ttfamily #1}|main}}} \newcommand*{\pkgopt}[2][]{% \ifthenelse{\equal{#1}{}}{% -\pkgoptni{#2}\index{package options>#2=\pkgoptni{#2}|hyperpage}}{% -\pkgoptni{#2=#1}\index{package options>#2=\pkgoptni{#2}>#1=\pkgoptni{#1}|hyperpage}}} -\newcommand*{\pkgoptval}[2]{\pkgoptni{#1}\index{package options>#2=\pkgoptni{#2}>#1=\pkgoptni{#1}|hyperpage}} -\newcommand*{\glostyle}[1]{\textsf{#1}\index{glossary styles>#1|hyperpage}} +\pkgoptni{#2}\index{package options:>#2={\protect\ttfamily #2}|main}}{% +\pkgoptni{#2=#1}\index{package options:>#2={\protect\ttfamily #2}>#1={\protect\ttfamily #1}|main}}} +\newcommand*{\pkgoptval}[2]{\pkgoptni{#1}\index{package options:>#2={\protect\ttfamily #2}>#1={\protect\ttfamily#1}|main}} +\newcommand*{\glostyle}[1]{\textsf{#1}\index{glossary styles:>#1={\protect\ttfamily#1}|main}} \newcommand*{\filetype}[1]{\texttt{#1}\index{file types>#1|hyperpage}} \newcommand*{\sty}[1]{\textsf{#1}} \newcommand*{\isty}[1]{\sty{#1}\index{#1 package=\sty{#1} package|hyperpage}} @@ -131,7 +146,7 @@ \MakeShortVerb{"} \DeleteShortVerb{\|} - \title{glossaries.sty v 2.02: \LaTeXe\ Package to Assist Generating Glossaries} + \title{glossaries.sty v 2.03: \LaTeXe\ Package to Assist Generating Glossaries} \author{Nicola L.C. Talbot\\[10pt] School of Computing Sciences\\ University of East Anglia\\ @@ -139,7 +154,7 @@ Norwich. Norfolk\\ NR4 7TJ. United Kingdom.\\ \url{http://theoval.cmp.uea.ac.uk/~nlct/}} - \date{13th July 2009} + \date{23rd September 2009} \maketitle \tableofcontents @@ -260,7 +275,7 @@ The sample documents are as follows: You can test your installation using this file. To create the complete document you will need to do the following steps: \begin{enumerate} - \item Run \texttt{minimalgls.tex} through \LaTeX\ by either + \item Run \texttt{minimalgls.tex} through \LaTeX\ either by typing \begin{verbatim} latex minimalgls @@ -278,7 +293,7 @@ latex minimalgls package. \item Run \appname{makeglossaries} on the document. This can - be done on a terminal by either typing + be done on a terminal either by typing \begin{verbatim} makeglossaries minimalgls \end{verbatim} @@ -489,7 +504,7 @@ you don't need to supply any additional information. If you don't use \appname{makeglossaries}, you will need to specify the required information. Note that if you set the style file to \texttt{samplexdy-mc.xdy} you must also specify \ics{noist}, -otherwise the \isty{glossaries} package will overwrite +otherwise the \sty{glossaries} package will overwrite \texttt{samplexdy-mc.xdy} and you will lose the \dq{Mc} letter group. To create the document do: @@ -604,8 +619,8 @@ me the relevant translations either via email or via However you must load \isty{babel} \emph{before} \sty{glossaries} to enable this. Note that if \isty{babel} is loaded and the \isty{translator} package is detected on \TeX's path, then the -\isty{translator} package will be loaded automatically, however, -it may not pick up on the required languages, so if the predefined +\isty{translator} package will be loaded automatically. However, +it may not pick up on the required languages so, if the predefined text is not translated, you may need to explicitly load the \isty{translator} package with the required languages. For example: \begin{verbatim} @@ -633,7 +648,7 @@ to provide the translations. For example: \end{verbatim} The following languages are currently supported by the -\isty{glossaries} package: +\sty{glossaries} package: \begin{center} \begin{tabular}{lc} \bfseries Language & \bfseries As from version\\ @@ -690,14 +705,38 @@ the \isty{babel} package and do not have the \isty{translator} package installed, you need to be familiar with the \ifmakedtx{ advice given in \url{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=latexwords}}{advice on \htmladdnormallink{changing the words babel uses}{http://www.tex.ac.uk/cgi-bin/texfaq2html?label=latexwords}}. +If you have the \isty{translator} package installed, then you +can change the translations using \cs{deftranslation}. See the +\isty{translator} documentation for further details. -If you have the \isty{translator} package installed, then it becomes -much easier to change the default translations. For example, if you -are writing in Irish and you want \cs{symbolname} to produce -\dq{Siombail} instead of \dq{Comhartha}, then you can put the following -in your document preamble: +If you don't want to use the \isty{translator} interface, you +can suppress it using the package option \pkgopt[false]{translate}, +and either load \isty{glossaries-babel} after \sty{glossaries} +or specify you're own translations. For example: \begin{verbatim} -\deftranslation[to=Irish]{Symbol (glossaries)}{Siombail} +\documentclass[british]{article} + +\usepackage{babel} +\usepackage[translate=false]{glossaries} +\usepackage{glossaries-babel} +\end{verbatim} +or: +\begin{verbatim} +\documentclass[british]{article} + +\usepackage{babel} +\usepackage[translate=false]{glossaries} + +\addto\captionsbritish{% + \renewcommand*{\glossaryname}{List of Terms}% + \renewcommand*{\acronymname}{List of Acronyms}% + \renewcommand*{\entryname}{Notation}% + \renewcommand*{\descriptionname}{Description}% + \renewcommand*{\symbolname}{Symbol}% + \renewcommand*{\pagelistname}{Page List}% + \renewcommand*{\glssymbolsgroupname}{Symbols}% + \renewcommand*{\glsnumbersgroupname}{Numbers}% +} \end{verbatim} Note that \appname{xindy} provides much better multi-lingual @@ -848,6 +887,11 @@ perl makeglossaries myDoc 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. + +The \appname{makeglossaries} script contains POD (Plain Old +Documentation). If you want, you can create a man page for +\appname{makeglossaries} using \appname{pod2man} and move the +resulting file onto the man path. \ifmakedtx{}{\toTop} \subsubsection{Using xindy explicitly} @@ -1046,6 +1090,13 @@ the acronyms. This command converts lower case letters to small capitals, while upper case letters remain their usual size. Therefore you need to specify the acronym in lower case letters. +\item \textbf{Q.} My acronyms won't break across a line when they're +expanded. + +\textbf{A.} PDF\LaTeX\ can break hyperlinks across a line, but +\LaTeX\ can't. If you can't use PDF\LaTeX\ then disable the first use +links using the package option \pkgopt[false]{hyperfirst}. + \item \textbf{Q.} How do I change the font that the acronyms are displayed in? \textbf{A.} The easiest way to do this is to specify the \pkgopt{smaller} package @@ -1181,6 +1232,17 @@ site. The \sty{glossaries} package options are as follows: \begin{description} +\item[\pkgopt{nowarn}] This suppresses all warnings generated by +the \sty{glossaries} package. + +\item[\pkgopt{nomain}] This suppresses the creation of the main +glossary. Note that if you use this option, you must create another +glossary in which to put all your entries (either via the +\pkgopt{acronym} package option described below or via +\ics{newglossary} described in +\ifmakedtx{\autoref{sec:newglossary}}{\htmlref{Defining New +Glossaries}{sec:newglossary}}). + \item[\pkgopt{toc}] Add the glossaries to the table of contents. Note that an extra \LaTeX\ run is required with this option. @@ -1207,15 +1269,6 @@ Entries that are defined using \ics{newacronym} are placed in the glossary whose label is given by \ics{acronymtype}, unless another glossary is explicitly specified. -\item[\pkgopt{nomain}] This suppresses the creation of the main -glossary. Note that if you use this option, you must create another -glossary in which to put all your entries (either via the -\pkgopt{acronym} package option described above or via -\ics{newglossary} described in -\ifmakedtx{\autoref{sec:newglossary}}{\htmlref{Defining New -Glossaries}{sec:newglossary}}). - - \item[\pkgopt{section}] This is a \meta{key}=\meta{value} option. Its value should be the name of a sectional unit (e.g.\ chapter). This will make the glossaries appear in the named sectional unit, @@ -1235,9 +1288,10 @@ is equivalent to \end{verbatim} You can change this value later in the document using\\[10pt] \DescribeMacro{\setglossarysection}\cs{setglossarysection}\marg{name}\\[10pt] -where \meta{name} is the sectional unit. The start of each glossary -adds information to the page header via -\DescribeMacro{glossarymark}\cs{glossarymark}\marg{glossary title}. +where \meta{name} is the sectional unit. + +The start of each glossary adds information to the page header via +\DescribeMacro{\glossarymark}\cs{glossarymark}\marg{glossary title}. This defaults to \cs{@mkboth}, but you may need to redefine it. For example, to only change the right header: \begin{verbatim} @@ -1402,7 +1456,11 @@ for further details. for further details. \item[\pkgopt{smaller}] This option changes the definition of -\ics{newacronym} and the way that acronyms are displayed. See \ifmakedtx{\autoref{sec:acronyms}}{\htmlref{later}{sec:acronyms}} +\ics{newacronym} and the way that acronyms are displayed. +If you use this option, you will need to include the \isty{relsize} +package or otherwise define \ics{textsmaller} or redefine +\ics{acronymfont}. See +\ifmakedtx{\autoref{sec:acronyms}}{\htmlref{later}{sec:acronyms}} for further details. \item[\pkgopt{dua}] This option changes the definition of @@ -1451,8 +1509,30 @@ for further details on using \appname{xindy} with the is word ordering. Note that this option has no effect if you don't use \appname{makeglossaries}. -\item[\pkgopt{nowarn}] This suppresses all warnings generated by -the \sty{glossaries} package. +\item[\pkgopt{translate}] This is a boolean option. The default is +\pkgoptval{true}{translate} if \isty{babel} or \isty{translator} +have been loaded, otherwise the default value is +\pkgoptval{false}{translate}. + + \begin{description} + \item[{\pkgopt[true]{translate}}] If the \isty{translator} package + is installed, it will be loaded and the translations will be + provided by the \isty{translator} package interface. If the + \isty{translator} package isn't installed, the + \isty{glossaries-babel} package will be loaded and the translations + will be provided using \sty{babel}'s + \cs{addto}\cs{caption}\meta{language} mechanism. + + \item[{\pkgopt[false]{translate}}] Don't provide translations, even + if \isty{babel} has been loaded. You can then provide you're + own translations or explicitly load \isty{glossaries-babel}. + \end{description} + +\item[\pkgopt{hyperfirst}] This is a boolean option that specifies +whether each term has a hyperlink on \firstuse. The default is +\pkgopt[true]{hyperfirst} (terms on first use have a hyperlink, +unless explicitly suppressed using starred versions of commands +such as \cs{gls*}). \end{description}\ifmakedtx{}{\toTop} @@ -2414,7 +2494,13 @@ and\\[10pt] respectively. The effect can be localised by placing the commands within a group. Note that you should only use \cs{glsenablehyper} if the commands \ics{hyperlink} and \ics{hypertarget} have been -defined (for example, by the \isty{hyperref} package).\ifmakedtx{}{\toTop} +defined (for example, by the \isty{hyperref} package). + +You can disable just the first use links using the package +option \pkgopt[false]{hyperfirst}. Note that this option only +affects commands that recognise the \firstuse\ flag, for example +\ics{gls}, \ics{glspl} and \ics{glsdisp} but not \ics{glslink}. +\ifmakedtx{}{\toTop} \subsection{Adding an Entry to the Glossary Without Generating Text} \label{sec:glsadd} @@ -2638,7 +2724,8 @@ defined). \item[{\gloskey[printglossary]{toctitle}}] This is the title to use for the table of contents (if the \pkgopt{toc} package -option has been used). If omitted, the glossary title is used. +option has been used). It may also be used for the page header, +depending on the page style. If omitted, the glossary title is used. \item[{\gloskey[printglossary]{style}}] This specifies which glossary style to use for this glossary, overriding the effect @@ -3473,7 +3560,7 @@ replacement \sty{glossaries} package. In addition, the old \cs{}\meta{acr-name} when defining the acronym \meta{acr-name}. In order to facilitate migrating from the old package to the new -one, the \isty{glossaries} package\footnote{as from version 1.18} +one, the \sty{glossaries} package\footnote{as from version 1.18} provides the command:\\[10pt] \DescribeMacro{\oldacronym}\cs{oldacronym}\oarg{label}\marg{abbrv}\marg{long}\marg{key-val list}\\[10pt] This uses the same syntax as the \isty{glossary} package's @@ -3497,7 +3584,7 @@ names consisting of alphabetical characters. This is also true for \isty{xspace} package. \end{important} -The \isty{glossaries} package doesn't load the \isty{xspace} package +The \sty{glossaries} package doesn't load the \isty{xspace} package since there are both advantages and disadvantages to using \ics{xspace} in \cs{}\meta{label}. If you don't use the \isty{xspace} package you need to explicitly force a space using |