clear-linux-documentation/source/clear-linux/reference/collaboration/documentation/punctuation.rst

.. _punctuation:

Punctuation guide
#################

This section contains all the information regarding the correct use of
punctuation for the |CLOSIA| documentation.

Commas, Semicolons, and Colons
******************************
Here are the most common problems encountered with commas, semicolons,
and colons. Please refer to Merriam-Webster's Collegiate Dictionary
when in doubt.

Serial Commas
=============

When writing a series of items, use the serial comma before the
coordinating conjunctions *and* and *or* to avoid confusion and ambiguity.
For example:

* Mom, Dad, and I are going to the game.
* Mom, Dad and I are going to the game.

The first example uses the serial comma. It is clear in this sentence
that three people are going to the game. The second example does NOT
have a comma preceding the and. The reader may interpret this as
meaning the same thing as the first sentence, namely that three people
are going to the game, or that the speaker is addressing "Mom" and
telling her that only two people are going to the game.

Commas in Numbers
=================

Use commas to divide large numbers into sets of three digits. Use
periods for decimal points. Do not divide decimal digits into sets of
three.

Do not use a comma to separate four-digit bit/byte numbers.

Do not use a comma to separate four-digit page numbers.

Do not use a comma or other punctuation to separate decimals.


Semicolons ";"
==============

Here are some rules governing the use of semicolons:

* Use semicolons in long, sentence-style bulleted phrase lists.

* Use semicolons when two equal clauses are joined because of
  similarity of construction or meaning.

* Use semicolons in a series of items when at least one of the items
  itself includes a comma.

Examples of semicolon usage:

Similar construction: The prewidget comes before the widget; the
postwidget comes after it.

Comma-inclusive series: We traveled through Casper, Wyoming; Boise,
Idaho; and Eugene, Oregon.

Colons ":"
==========

If the text following a colon is a sentence, capitalize the
first word after the colon. If the subsequent text is not a sentence,
do not capitalize the first term unless it is a title. For example:

* This is a capitalization example: Donuts do not cause holes.

* These is a noncapitalization example: colons, semicolons, and commas.

* In a title, use title case following the colon. Example: Tires: How
  to Fix a Flat.

* Use a colon at the end of a sentence or phrase that introduces
  examples, a list, a path, user input, or code.

* Don't use a colon to introduce graphics, tables, or sections.

* Don't use a colon at the end of a task title or any heading.