This subsection covers the capitalization of words and terms for certain elements, like headings.
Titles of chapters and sections should
use initial capitals following these rules: Cap the first
letter of each word, with the exception of articles,
conjunctions, prepositions of four letters or less, and
program names or technical words that are always lowercase.
Hyphenated words in titles or captions should both be capped
if the second word is a main word, but only the first should
be capped if the second word isn't too important (it is a bit
of a judgment call). Example: Big-Endian,
Built-in
Prepositions with four
letters or fewer should be lowercase:
from, with, Within, Between
.
Also, the word to
should be lowercase.
Figures get title capping, just like
headings. There is no period after figure captions. Example:
Switching to Configure-Service Mode
Figure captions may end with a period. This makes sense if most figure captions are full sentences. Currently, we don't use periods, but should we start using them we should use periods even for captions that are not full sentences (consistency overrules grammatical correctness).
Tables get title capping, just like figures and headings.
List items begin with capitalized words.
Inline titles, for example titles of <formalpara> elements, get sentence capping. That is, capitalization is like in regular sentences.
SQL function names should use all
capitals, followed by ()
; for
example, DATABASE()
, and the
<literal>
element. The
<literal>
element must not be used when
an SQL function is inside a
<programlisting>
element.
SQL keywords and statements should use
all capitals. In paragraph text, enclose the terms within
<literal>
. In program listings
(<programlisting>...</programlisting>
),
do not use <literal>
.
<replaceable>
is allowable within
<literal>
and
<programlisting>
.
<userinput>
and
<replaceable>
are allowable within
<programlisting>
.
Product names should be capitalized. Sometimes it's not easy to determine whether a term is a product name or not. Here's an example:
“MySQL Server” is a product name, while “MySQL server” is for phrases like “the MySQL server”. Use of the product name is a concept that gets a lot of love from marketing or something. However, use of it everywhere makes text sound still and stilted. We should use “MySQL Server” when talking about the product in general (for example, discussing features) but “MySQL server” (or just “the server”) when talking about specific uses (for example, “the MySQL server performs character set conversion when necessary”).