WRITING_HELPERS.md

   1 A short helper on how to use _acronyms_, _glossary entries_, and the _index_.
   2
   3 ## Acronyms ##
   4
   5 ### How to Use ###
   6
   7 To `common/names.tex` add
   8
   9 ```
  10 \newacronym{ABC}{abc}{%
  11   a Better Crypto}
  12 ```
  13
  14 In text use `\ac{ABC}`. The first time, this expands to “a Better Crypto (ᴀʙᴄ)”, subsequently, to “ᴀʙᴄ”.
  15
  16 See below for more commands.
  17
  18 ### When to Use ###
  19
  20 Do use for
  21
  22  * typically abbreviated phrases
  23  * that occur frequently
  24  * and do not need further explanation (eg, HTTP)
  25  * or are explained in text (eg, ECDH).
  26
  27 Do _not_ use for
  28
  29  * phrases / words that are no acronyms
  30  * or acronyms that need further explanation (which is _not_ given in text).
  31
  32 ## Glossary ##
  33 ### How to Use ###
  34
  35 To `common/names.tex` add
  36
  37 ```
  38 \newglossaryentry{firewall}{%
  39   name=firewall,
  40   description={technological barrier designed to prevent unauthorized or
  41     unwanted communications between computer networks or hosts}
  42 }
  43 ```
  44
  45 In text use `\gls{firewall}`. This produces a _link_ with the text “firewall” to the glossary and the description there.
  46
  47 See below for more commands.
  48
  49 ### When to Use ###
  50
  51 Do use for
  52
  53  * phrases / words that are no acronyms and need explanation (which is _not_ given in text)
  54  * or acronyms that need further explanation (which is _not_ given in text).
  55
  56 Do _not_ for
  57
  58  * typically abbreviated phrases
  59  * that occur frequently
  60  * and do not need further explanation (eg, HTTP)
  61  * or are explained in text (eg, ECDH).
  62
  63 ## Index ##
  64 > Every good book needs an index
  65 >
  66 > — anonymous
  67 ### How to Use ###
  68
  69 To `common/names.tex` add
  70
  71 ```
  72 \doindex{Diffie--Hellman}
  73 ```
  74
  75 If you want to index acronyms or glossary entries, do so in their definition:
  76
  77 ```
  78 \newacronym{DH}{dh\alsoidx{Diffie--Hellman}}{%
  79   Diffie--Hellman key exchange}
  80 ```
  81
  82 In text use `|Diffie--Hellman|` or `\idx{Diffie--Hellman}`. To get a literal “|“, use `\textbar` or `||`.
  83
  84 See below for more commands.
  85
  86 ### When to Use ###
  87
  88 Do use for
  89
  90  * important terms, definitions, concepts etc.,
  91  * proper names,
  92  * or product names.
  93
  94 Do _not_ for
  95
  96  * everyday words like “computer”
  97  * or colloquial words like “crypto”.
  98
  99 ---
 100
 101 ## Other Commands ##
 102
 103 ### For Acronyms ###
 104
 105 Refer to “Acronyms” in [the glossaries documentation][glossaries].
 106
 107 If possible, use
 108
 109 * `\ac` — on first usage, same as `\acf`, else, same as `\acs`\r* `\Ac` — on first usage, same as `\Acf`, else, same as `\Acs`\r* `\acp` — on first usage, same as `\acfp`, else, same as `\acsp`\r* `\Acp` — on first usage, same as `\Acfp`, else, same as `\Acsp`
 110
 111 and only seldomly
 112
 113 * `\acs` — acronym short form “ᴀʙᴄ”\r* `\Acs` — capitalized acronym short form “Aʙᴄ”\r* `\acsp` — plural acronym short form “ᴀʙᴄs”\r* `\Acsp` — capitalized plural acronym short form “Aʙᴄs”\r* `\acl` — acronym long form “a Better Crypto”\r* `\Acl` — capitalized acronym long form “A Better Crypto”\r* `\aclp` — plural acronym long form “a Better Crypto” (_does not fit example_)\r* `\Aclp` — capitalized plural acronym long form “A Better Crypto” (_does not fit example_)\r* `\acf` — acronym full form “a Better Crypto (ᴀʙᴄ)”\r* `\Acf` — capitalized acronym full form “A Better Crypto (ᴀʙᴄ)”\r* `\acfp` — plural acronym full form “a Better Cryptos (ᴀʙᴄs)” (_does not fit example_)\r* `\Acfp` — capitalized plural acronym full form “A Better Crypto (ᴀʙᴄs)” (_does not fit example_)\r
 114 ### For Glossary Entries ###
 115
 116 Refer to “Links to glossary entries” in [the glossaries documentation][glossaries].
 117
 118 A selection:
 119
 120 * `\gls` — glossary entry as defined “firewall”
 121 * `\Gls` — capitalized glossary entry “Firewall”
 122 * `\GLS` — all-caps glossary entry “FIREWALL”
 123 * `\glspl` — plural glossary entry as defined “firewalls”
 124 * `\Glspl` — plural capitalized glossary entry “Firewalls”
 125 * `\GLSpl` — plural all-caps glossary entry “FIREWALLS”
 126
 127 ### For Index ###
 128
 129 Internally, `\idx` uses `\gls` (see above) with special treating, so we provide the following mapping:
 130
 131 * `\idx` → `\gls`
 132 * `\Idx` → `\Gls`
 133 * `\IDX` → `\GLS`
 134 * `\idxpl` → `\glspl`
 135 * `\Idxpl` → `\Glspl`
 136 * `\IDXpl` → `\GLSpl`
 137
 138 The form `|indexword|` is a shortcut for `\idx{indexword}` and behaves the same.
 139 To pass optional arguments to `idx` (and hence `\gls`), use the form
 140
 141 ```
 142 |[format=emph]Diffie--Hellman| is the same as \idx[format=emph]{Diffie--Helmann}
 143 ```
 144
 145
 146 [glossaries]: http://mirrors.ctan.org/macros/latex/contrib/glossaries/glossaries-user.pdf
 147
 148