Skip to content

Commit

Permalink
Update style guide on the use of \firstuse
Browse files Browse the repository at this point in the history
  • Loading branch information
henrikt-ma committed Nov 22, 2021
1 parent 0032014 commit 1b6848e
Showing 1 changed file with 6 additions and 3 deletions.
9 changes: 6 additions & 3 deletions styleguide.md
Expand Up @@ -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.

Expand Down

0 comments on commit 1b6848e

Please sign in to comment.