[ << Documentation work ] | [Top][Contents] | [ Website work >> ] |
[ < Miscellany ] | [ Up : Texinfo introduction and usage policy ] | [ Documentation policy > ] |
5.4.7 Other text concerns
- References should occur at the end of a sentence; for more
information see the
Texinfo
manual. Ideally this should also be the final sentence of a
paragraph, but this is not required. Any link in a doc section
must be duplicated in the
@morerefs
section at the bottom. - Introducing examples should be done with
. (i.e., finish the previous sentence/paragraph) : (i.e., 'in this example:') , (i.e., 'may add foo with the blah construct,')
The method “sentence runs directly into the example” is discouraged.
- Write abbreviation and acronyms in uppercase letters, e.g., HTML, DVI, MIDI.
- Colon usage
- To introduce lists.
- When beginning a quote: “So, he said,...”.
This usage is rarer. Americans often just use a comma.
- When adding a defining example at the end of a sentence.
- Non-ASCII characters should be directly used; this is, don’t say ‘Ba@ss{}tuba’ but ‘Baßtuba’. This ensures that all such characters appear in all output formats. There are limitations for PDF output, though, because the used fonts only support a relatively small number of Unicode characters.6
Footnotes
(6)
This might change in the future since recent versions of Texinfo support output to LaTeX, which doesn’t have this limitation.