1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
|
Stylistic considerations
------------------------
Many of the suggestions in this file are meant for non-native English
speakers (the authors are French). Don't be surprised if some of them
seem obvious to you.
* In titles, capitalize words that:
* are the first or the last word in the title
* are not conjunctions (“and”, “but”, “or”, “nor”), adpositions (“to”,
“over”), articles (“an”, “a”, “the”), or the “to” in infinitives.
More conjunctions: for, and, nor, but, or, yet, and so, both … and,
either … or, neither … nor, and not (only) … but (… also), “because“,
“if“, “so that“, “after“, “when“, “although“, “while“, and “even
though“.
More adpositions: of, to, in, for, on, with, as, by, at, from
* Use the American spelling wherever applicable ("color" and not "colour",
etc.).
* Use contractions only for negative forms:
* "don't", "won't", "isn't" are OK
* "it's", "there's" are not OK, use "it is", "there is"
* Always write down the conjunction words (like "that") that you might
skip when you speak.
* About punctuation:
* Use "semi-colon" for enumerations if "commas" are used in the list
items.
* The "semi-colon" can be used to link two sentences which are logically
related.
* Don't hesite to use "—" to separate subordinates clauses
(instead of parenthesis or commas).
* Avoid too long sentences. Don't hesitate to cut them in two separate
sentences.
* Remember to use "they" (and not "he") when you refer to some singular
"generic person". Example: “The administrator was busy, they could not
respond immediately.”
* Use imperative forms when you list instructions:
“Run foo, then remove bar.”
* When you explain what's coming up next in the book, you can use the
first person of the plural form ("we will now..." or "let us now
study...")
* Use passive forms when the subject is not clearly identified (or doesn't
need to be clearly identified): “This key can be added by..." instead of
"The administrator can add this key by..."
* Sidebars are categorized with an <emphasis>CATEGORY</emphasis> at
the start of their title. Here are the common categories:
- BACK TO BASICS
- TIP
- CULTURE
- GOING FURTHER
- CAUTION
- VOCABULARY
- TOOL/TOOLS
- ALTERNATIVE
- NOTE
- SECURITY
- IN PRACTICE
- QUICK LOOK
- COMMUNITY
- EXTRA
- DOCUMENTATION
- DEBIAN POLICY
- THE BROADER VIEW
- SPECIFIC CASE
- HARDWARE
- WORTH FOLLOWING
- DEBIAN SPECIFICITY
- GET INVOLVED
- BACKSTAGE
|
