diff --git a/source/clear-linux/reference/collaboration/documentation/code.rst b/source/clear-linux/reference/collaboration/documentation/code.rst index 53585557..9490e75b 100644 --- a/source/clear-linux/reference/collaboration/documentation/code.rst +++ b/source/clear-linux/reference/collaboration/documentation/code.rst @@ -4,15 +4,15 @@ Code blocks ########### Collaborating to the |CLOSIA| is all about code. Therefore, your -documentation must include code examples. The code examples can be written -directly in the documentation or included from a source file. Use these -guidelines to insert code blocks to your documentation: +documentation must include as many code examples as possible. You can write +code examples directly in the documentation or include them from a source +file. Use these guidelines to insert code blocks to your documentation: * Include code examples from a source file. Only write the code example directly into the documentation if the example is less than 10 lines long. -* Use the ``:lineos:`` option of the directives to add line numbers to - your example if it is larger than 12 lines. +* Use the ``:linenos:`` option of the `literalinclude` directive to add line + numbers to your example. * Specify the programing language of your example. Not only will it add syntax highlighting but it also allows the reader to identify code @@ -27,14 +27,7 @@ Examples This is a code example included from a file. Note how only certain lines of the source file are included and how the lines are renumbered. -Renders as: - -.. literalinclude:: ./hello.c - :language: c - :lines: 97-110 - :linenos: - -From the source: +This source: .. code-block:: rst @@ -43,22 +36,19 @@ From the source: :lines: 97-110 :linenos: +Renders as: + +.. literalinclude:: ./hello.c + :language: c + :lines: 97-110 + :linenos: + This example shows a series of console commands. Line numbering is not required. Specify that these are commands using `bash` as the programing language. -Renders as: - -.. code-block:: bash - - $ mkdir ${HOME}/x86-build - - $ mkdir ${HOME}/arm-build - - $ mkdir ${HOME}/cross-src - -From the source: +This source: .. code-block:: rst @@ -70,6 +60,16 @@ From the source: $ mkdir ${HOME}/cross-src +Renders as: + +.. code-block:: bash + + $ mkdir ${HOME}/x86-build + + $ mkdir ${HOME}/arm-build + + $ mkdir ${HOME}/cross-src + .. note:: You will find instances which use `console` instead of `bash`. We are currently in the process of implementing a distinction between the two. @@ -79,30 +79,7 @@ From the source: Finally, this is a code example that is not part of the |CL| code base. It is not even valid code but it can illustrate the concept. -Renders as: - -.. code-block:: c - - static NANO_CPU_INT_STUB_DECL (deviceStub); - - void deviceDriver (void) - - { - - . - . - . - - nanoCpuIntConnect (deviceIRQ, devicePrio, deviceIntHandler, - deviceStub); - - . - . - . - - } - -From the source: +This source: .. code-block:: rest @@ -127,6 +104,29 @@ From the source: } +Renders as: + +.. code-block:: c + + static NANO_CPU_INT_STUB_DECL (deviceStub); + + void deviceDriver (void) + + { + + . + . + . + + nanoCpuIntConnect (deviceIRQ, devicePrio, deviceIntHandler, + deviceStub); + + . + . + . + + } + Templates ********* @@ -156,6 +156,6 @@ specific lines. .. caution:: The ``:emphasize-lines:`` option uses the line numbering provided - by ``:lineos:``. The emphasized line in the template will be the + by ``:linenos:``. The emphasized line in the template will be the third one of the example but the eighth one of the source file. diff --git a/source/clear-linux/reference/collaboration/documentation/documentation.rst b/source/clear-linux/reference/collaboration/documentation/documentation.rst index df83ef8a..eb469526 100644 --- a/source/clear-linux/reference/collaboration/documentation/documentation.rst +++ b/source/clear-linux/reference/collaboration/documentation/documentation.rst @@ -41,7 +41,7 @@ This guide includes the following sections: Scope ***** -The |CL| documentation is dived in five sections: +The |CL| documentation is divided in five sections: * **Get started:** Information about installing Clear Linux. * **Concepts:** Detailed technical information about our features. diff --git a/source/clear-linux/reference/collaboration/documentation/grammar.rst b/source/clear-linux/reference/collaboration/documentation/grammar.rst index 832fe5e7..4e2ac8d1 100644 --- a/source/clear-linux/reference/collaboration/documentation/grammar.rst +++ b/source/clear-linux/reference/collaboration/documentation/grammar.rst @@ -9,6 +9,7 @@ hyphenation, possessives, and contractions. Capitalization ************** + The preferred capitalization style for all documentation is sentence case. @@ -16,52 +17,13 @@ Words should only be capitalized when: * They are proper nouns or adjectives. * They refer to trademarked product names. -* When they are part of a heading using title case. .. important:: - Do not capitalize a word to indicate it has a greater status than - other words. Never change the case of variable, function or file - names; always keep the original case. + Do not capitalize a word to indicate it has a greater status than other + words. Never change the case of variable, function or file names; always + keep the original case. -Capitalization styles -===================== - -We refer to several capitalization styles in this document: uppercase, -title case, sentence case, and lowercase. - -Do not use uppercase capitalization for any passages, not even extreme -warnings. Some legal disclaimers are written in all caps for emphasis; -this is the only exception. - -The only paragraphs that shall use title case are the headings of the -document. - -All items associated with tables and figures shall use sentence -case capitalization: Only the first word and proper names are -capitalized. - -The following list provides sample paragraph types with the correct -capitalization style: - - -* Headings: Title case - - Widget Pro User Manual - - Installing Widget Pro in a Distributed Environment - -* Table titles: Sentence case - - MPEG profile/level matrix -* Table column headings: Sentence case - - First level of values; Second level of values, etc. - -* Figure titles, callouts and legends: Sentence case - - Widget backplane connections - - Edit icon - - Date/time spinbox - - Rate of acceleration - - Color code explanation - - Legend - -Menu Capitalization +Menu capitalization =================== When referring to software menu items by name, replicate the @@ -72,7 +34,8 @@ not a specific name of a window or field on a menu, for example: Click :guilabel:`Edit` to display the :guilabel:`Widget Configuration` window. -The widget configuration window has several advanced widget configuration options. +The widget configuration window has several advanced widget configuration +options. The second sentence could have capitalized the term "Widget Configuration window"; but there are times when you might want to @@ -87,13 +50,14 @@ A few other menu capitalization rules to keep in mind: :menuselection:`View --> Side Bar --> Hide Side Bar`" * Do not include more than 3 navigation steps in a menu selection. If - more than three steps are needed devide the steps using + more than three steps are needed divide the steps using ``:guilabel:`` or ``:menuselection:``. For example: "Go to :guilabel:`File` and select :menuselection:`Print --> Print Preview --> Set Up`." -Software Version Capitalization +Software version capitalization =============================== + Do not capitalize the word version or letter v when listing software or hardware version numbers. The v is lowercase and closed with the number (no period). For example: @@ -101,21 +65,22 @@ number (no period). For example: * Widget Pro v5.0 * Widget Master v2.1.12 -Hyphenated or Slashed-concatenated Terms +Hyphenated or slashed-concatenated terms ======================================== + For hyphenated or slash-concatenated terms, capitalize only the first letter, even if they are headings. For example: * Day/night Menu * Follow-up Action Items -Plurals and Possessives +Plurals and possessives *********************** Because English plurals and possessives use the same /s/ and /z/ phonemes, they can create problems for even experienced writers. This section deals with these issues. -Singular vs. Plural Possessives +Singular vs. plural possessives =============================== Here are some guidelines for singular and plural possessives: @@ -167,7 +132,7 @@ incorrect cases and the notes that accompanies them. | | | the apostrophe-s. | +-------------------+------------------+---------------------------+ -Apostrophe-s Anomalies +Apostrophe-s anomalies ====================== If a company name ends in s, x, c, or a sibilant sound, use the @@ -198,8 +163,8 @@ Plural modifiers Avoid plural modifiers. For example, it should be a system administrator, not a systems administrator. It doesn't matter how many -systems this person manage, we don't typically use the plural of a word -to modify a noun. Here a list of exceptions: +systems this person manages, we don't typically use the plural of a word +to modify a noun. Here is a list of exceptions: * operations manager * sales department @@ -232,7 +197,7 @@ A m(e)n, wom(a)n, a child(ren), college alumn(i), (moose), and even a desert plant(s) such as a cact(i) should not use a parenthes(e)s around a plural(s). -Internal Plural Acronyms +Internal plural acronyms ======================== Some abbreviated terms can cause trouble, particularly when the @@ -244,7 +209,7 @@ rules when abbreviated: The plural goes at the end of the term. * Attorneys-general: AG, AGs. * Regions of interest: ROI, ROIs. -Plurals of Acronyms and Capitalized Product Names +Plurals of acronyms and capitalized product names ================================================= Pluralize acronyms, initialisms, and capitalized product names by @@ -279,8 +244,8 @@ Pluralize Latin terms in body text as shown: Contractions ************ -Avoid the use contractions since some of them might be ambiguous and confusing -to non-native English-speaking audiences. +Avoid the use of contractions since some of them might be ambiguous and +confusing to non-native English-speaking audiences. Some contractions can cause confusion for nonnative English-speakers because these contractions stand for more than one construction. For @@ -304,7 +269,7 @@ Compound nouns often go through this progressions: The English language is trending away from hyphenated compounds to closed compounds. -Prefix Hyphenation +Prefix hyphenation ================== Do not hyphenate the prefixes listed below. Join the prefix to the @@ -347,7 +312,7 @@ Some prefixes, such as self-, half-, quasi-, and ex-, when meaning * Self-control, half-truth, quasi-corporation, ex-governor -Suffix Hyphenation +Suffix hyphenation ================== In general, do not hyphenate suffixes. Here are some examples. diff --git a/source/clear-linux/reference/collaboration/documentation/inline.rst b/source/clear-linux/reference/collaboration/documentation/inline.rst index ed858a55..2fb08380 100644 --- a/source/clear-linux/reference/collaboration/documentation/inline.rst +++ b/source/clear-linux/reference/collaboration/documentation/inline.rst @@ -49,9 +49,10 @@ the roles. ``:option:`Option``` -* Use the `:file:` role to emphasize a filename or directory. Do not - use the role inside a code-block but use it inside all notices that - contain files or directories. Place variable parts of the path or filename in brackets `{}`. +* Use the `:file:` role to emphasize a filename or directory. Do not use the + role inside a code-block but use it inside all notices that contain files + or directories. Place variable parts of the path or filename in brackets + `{}`. :file:`collaboration.rst` :file:`doc/{user}/collaboration/figures` @@ -102,7 +103,7 @@ the roles. ``:makevar:`VARIABLE``` * Use the `:envvar:` role to emphasize the name of environment - variables. Just as with `:makevar:`, the markup can include only for the + variables. Just as with `:makevar:`, the markup can include only the name of the variable or the variable plus its value. :envvar:`ZEPHYR_BASE` diff --git a/source/clear-linux/reference/collaboration/documentation/punctuation.rst b/source/clear-linux/reference/collaboration/documentation/punctuation.rst index bdaab2f3..88b04d38 100644 --- a/source/clear-linux/reference/collaboration/documentation/punctuation.rst +++ b/source/clear-linux/reference/collaboration/documentation/punctuation.rst @@ -15,7 +15,7 @@ when in doubt. Serial Commas ============= -When writing a series or items, use the serial comma before the +When writing a series of items, use the serial comma before the coordinating conjunctions *and* and *or* to avoid confusion and ambiguity. For example: diff --git a/source/clear-linux/reference/collaboration/documentation/simple.rst b/source/clear-linux/reference/collaboration/documentation/simple.rst index 53696fc7..7815e6b1 100644 --- a/source/clear-linux/reference/collaboration/documentation/simple.rst +++ b/source/clear-linux/reference/collaboration/documentation/simple.rst @@ -74,10 +74,13 @@ Keep these basic guidelines in mind as you check your verbs: * Avoid linking verbs; is, seems, becomes. * Convert weak verbs and nominalizations to strong verbs. * Be concise. -* Avoid "there are" and "it is" constructions. .. note:: The following - examples offer two versions of the same information. The incorrect - version always comes first and is formatted *in italics*. The correct - version is comes always second and is formatted **in bold**. +* Avoid "there are" and "it is" constructions. + +.. note:: + The examples in the following sections offer two versions of the same + information. The incorrect version always comes first and is formatted *in + italics*. The correct version always comes second and is formatted **in + bold**. Imperatives ===========