A short helper on how to use acronyms, glossary entries, and the index.
To common/names.tex
add
\newacronym{ABC}{abc}{%
a Better Crypto}
In text use \ac{ABC}
. The first time, this expands to “a Better Crypto (ᴀʙᴄ)”, subsequently, to “ᴀʙᴄ”.
See below for more commands.
Do use for
- typically abbreviated phrases
- that occur frequently
- and do not need further explanation (eg, HTTP)
- or are explained in text (eg, ECDH).
Do not use for
- phrases / words that are no acronyms
- or acronyms that need further explanation (which is not given in text).
To common/names.tex
add
\newglossaryentry{firewall}{%
name=firewall,
description={technological barrier designed to prevent unauthorized or
unwanted communications between computer networks or hosts}
}
In text use \gls{firewall}
. This produces a link with the text “firewall” to the glossary and the description there.
See below for more commands.
Do use for
- phrases / words that are no acronyms and need explanation (which is not given in text)
- or acronyms that need further explanation (which is not given in text).
Do not for
- typically abbreviated phrases
- that occur frequently
- and do not need further explanation (eg, HTTP)
- or are explained in text (eg, ECDH).
Every good book needs an index
— anonymous
To common/names.tex
add
\doindex{Diffie--Hellman}
If you want to index acronyms or glossary entries, do so in their definition:
\newacronym{DH}{dh\alsoidx{Diffie--Hellman}}{%
Diffie--Hellman key exchange}
In text use |Diffie--Hellman|
or \idx{Diffie--Hellman}
. To get a literal “|“, use \textbar
or ||
.
See below for more commands.
Do use for
- important terms, definitions, concepts etc.,
- proper names,
- or product names.
Do not for
- everyday words like “computer”
- or colloquial words like “crypto”.
Refer to “Acronyms” in the glossaries documentation.
If possible, use
\ac
— on first usage, same as\acf
, else, same as\acs
\Ac
— on first usage, same as\Acf
, else, same as\Acs
\acp
— on first usage, same as\acfp
, else, same as\acsp
\Acp
— on first usage, same as\Acfp
, else, same as\Acsp
and only seldomly
\acs
— acronym short form “ᴀʙᴄ”\Acs
— capitalized acronym short form “Aʙᴄ”\acsp
— plural acronym short form “ᴀʙᴄs”\Acsp
— capitalized plural acronym short form “Aʙᴄs”\acl
— acronym long form “a Better Crypto”\Acl
— capitalized acronym long form “A Better Crypto”\aclp
— plural acronym long form “a Better Crypto” (does not fit example)\Aclp
— capitalized plural acronym long form “A Better Crypto” (does not fit example)\acf
— acronym full form “a Better Crypto (ᴀʙᴄ)”\Acf
— capitalized acronym full form “A Better Crypto (ᴀʙᴄ)”\acfp
— plural acronym full form “a Better Cryptos (ᴀʙᴄs)” (does not fit example)\Acfp
— capitalized plural acronym full form “A Better Crypto (ᴀʙᴄs)” (does not fit example)
Refer to “Links to glossary entries” in the glossaries documentation.
A selection:
\gls
— glossary entry as defined “firewall”\Gls
— capitalized glossary entry “Firewall”\GLS
— all-caps glossary entry “FIREWALL”\glspl
— plural glossary entry as defined “firewalls”\Glspl
— plural capitalized glossary entry “Firewalls”\GLSpl
— plural all-caps glossary entry “FIREWALLS”
Internally, \idx
uses \gls
(see above) with special treating, so we provide the following mapping:
\idx
→\gls
\Idx
→\Gls
\IDX
→\GLS
\idxpl
→\glspl
\Idxpl
→\Glspl
\IDXpl
→\GLSpl
The form |indexword|
is a shortcut for \idx{indexword}
and behaves the same.
To pass optional arguments to idx
(and hence \gls
), use the form
|[format=emph]Diffie--Hellman| is the same as \idx[format=emph]{Diffie--Helmann}