add CONTRIBUTING.md file for github PRs
[ach-master.git] / 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