Skip to content

Latest commit

 

History

History
162 lines (109 loc) · 4.39 KB

WRITING_HELPERS.md

File metadata and controls

162 lines (109 loc) · 4.39 KB

A short helper on how to use acronyms, glossary entries, and the index.

Acronyms

How to Use

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.

When to Use

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).

Glossary

How to Use

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.

When to Use

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).

Index

Every good book needs an index

— anonymous

How to Use

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.

When to Use

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”.

Other Commands

For Acronyms

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)

For Glossary Entries

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”

For Index

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}