clearlinux/clear-linux-documentation
2
0
Fork 0
mirror of https://github.com/clearlinux/clear-linux-documentation.git synced 2026-07-10 22:55:54 +00:00
Code Issues Packages Projects Releases Wiki Activity

Fixed typos and removed unneeded content.

Browse Source 
Signed-off-by: Rodrigo Caballero <rodrigo.caballero.abraham@intel.com>
This commit is contained in:
Rodrigo Caballero
2017-11-30 15:56:57 -06:00
parent 76109e7d1a
commit b874bafdbb
6 changed files with 86 additions and 117 deletions
Download Patch File Download Diff File Expand all files Collapse all files
source/clear-linux/reference/collaboration/documentation/code.rst
+49 -49
View File
@@ -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.
source/clear-linux/reference/collaboration/documentation/documentation.rst
+1 -1
View File
@@ -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.
source/clear-linux/reference/collaboration/documentation/grammar.rst
+23 -58
View File
@@ -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.
source/clear-linux/reference/collaboration/documentation/inline.rst
+5 -4
View File
@@ -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`
source/clear-linux/reference/collaboration/documentation/punctuation.rst
+1 -1
View File
@@ -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:
source/clear-linux/reference/collaboration/documentation/simple.rst
+7 -4
View File
@@ -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
===========