diff --git a/styleguide.md b/styleguide.md index ed722f87b..9df5145d7 100644 --- a/styleguide.md +++ b/styleguide.md @@ -155,9 +155,12 @@ base-clock | `base-clock` | Similarly: sub-cock New terminology is either introduced with a `definition` environment, or as part of the running text. When part of the running text, the introduced terminology should be marked with `\firstuse` at the point of the definition. -As a general rule, `\firstuse` should appear in combination with `\index` for adding the term to the document index. -(The use of `\firstuse` instead of just `\emph` helps us both produce consistent formatting and makes it easier to spot cases where the additional use of `\index` has been forgotten. -The reason that `\firstuse` doesn't also do the job calling `\index` is that the form of the term presented to `\firstuse` isn't always in the base form expected in the document index, that there can be a need for special styling tricks in the `\index` argument, etc.) +As a general rule, terminology introduced with `\firstuse` should appear in the document index, and by default the mandatory argument to `\firstuse` is automatically passed to `\index`. +To change the appearance of the index entry, the default may be overridden using an optional argument to `\firstuse`, for example, `\firstuse[array!variable]{array variable}`. +This is also useful when capitalization or plural/singular differs; excapt for things like names, lower case should be used in the index, and terms should typically appear in the singular, for example, `\firstuse[vector]{Vectors}`. +On rare occasions, one just wants the standardized typesetting of `\firstuse` but no entry in the index, which can be achieved by passing an em-dash for the optional argument, for example, \firstuse[---]{constant}. +When suppressing the appearnce in the index, it is recommended to add a comment in the source explaining why. +It is common that the use of `\firstuse` is directly followed by additional calls to `\index` for adding the terminology in more variants to the document index. If the new terminology is used before being introduced, it should be marked with `\willintroduce` (instead of `\firstuse`) to alert the reader that this is not a term that is expected to be known yet by a first-time reader.