clearlinux/clear-linux-documentation
2
0
Fork 0
mirror of https://github.com/clearlinux/clear-linux-documentation.git synced 2026-08-24 08:48:15 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #368 from krisdale/kd-collab-reorg

Browse Source 
Collaboration guidelines - reorg and simplification
This commit is contained in:
michael vincerra
2019-01-24 11:50:42 -08:00
committed by GitHub
parent b307b0f74e 1aa805dddc
commit ded3aa7350
25 changed files with 1007 additions and 2491 deletions
Download Patch File Download Diff File Expand all files Collapse all files
README.rst
+40 -49
View File
@@ -1,83 +1,74 @@
Documentation Build Instructions
Documentation build instructions
################################
The `website documentation`_ for Clear Linux\* OS for Intel Architecture
should be written in :abbr:`ReStructuredText (ReST)` AKA ``.rst``, which
makes it easy to build parsable, command-line readable, indexed, and
search-friendly documentation and APIs with `Sphinx`_.
.. todo add comment re not using standards here.
.. _requirements:
`Clear Linux\* OS documentation`_ is written using `reStructuredText`_ and
built using `Sphinx`_. Follow the instructions in this README to build the
documentation locally for development and testing.
Please make yourself familiar with our `contribution guidelines`_ before
submitting a contribution.
Requirements
============
************
To build documentation with Sphinx, ensure your system has these
prerequisites:
Make sure you have Python and Sphinx installed. We use Python 3 and
Sphinx 1.7.5
* `GNU make`_
* `Python`_
* `PIP`_
* `Sphinx`_
The Sphinx documentation provides `instructions for installing Sphinx`_ on various
platforms.
The instructions for installing these varies according to OS. On a basic out-
of-the-box Ubuntu-like OS (which usually has Python installed by default),
check your python version you might need something like:
.. code-block:: console
$ sudo apt-get install python-pip
$ sudo pip install -U sphinx sphinx-autobuild
.. code-block:: console
$ python -c 'print __import__("sphinx").__version__'
1.3.1
Cloning the documentation repository
====================================
We have confirmed Sphinx installed. The next step is to clone Gitlab
repository to our local machine.
Clone the documentation repository
**********************************
Once Sphinx is installed, clone the documentation repository to your
local machine.
.. code-block:: console
$ git clone https://github.com/clearlinux/clear-linux-documentation
Run make
========
Run the build
*************
Finally are we ready to run :command:`make`. Be sure to :command:`cd` to the
:file:`source/` directory where your ``.rst`` files are, before
running :command:`make html`, or the doc format of your choice.
We build our documentation using Sphinx. In the source directory of your
local clear-linux-documentation repository, build the documentation by running
**make html**:
.. code-block:: console
$ make html
>
sphinx-build -b html -d _build/doctrees . _build/html
Running Sphinx v1.3.1
Running Sphinx v1.7.5
making output directory...
.
.
.
build succeeded, 0 warnings.
The HTML pages are in _build/html.
Build finished. The HTML pages are in _build/html.
Open one of the .html pages in a web browser to view the rendered
Open one of the HTML pages in a web browser to view the rendered
documentation.
For tips on how to contribute documentation formatted in the .rst style
needed to integrate beautifully on the clearlinux.org website, please see
`Theming Sphinx`_.
When testing changes in the documentation, make sure to remove the previous
build before building again by running **make clean**:
.. code-block:: console
.. _website documentation: https://clearlinux.org/documentation
$ make clean
>
rm -rf _build/*
This will completely remove the previous build output.
.. _Clear Linux\* OS documentation: https://clearlinux.org/documentation
.. _Sphinx: http://sphinx-doc.org/
.. _GNU make: https://www.gnu.org/software/make/
.. _Python: https://www.python.org/
.. _PIP: https://pypi.python.org/pypi/pip/
.. _Theming Sphinx: https://github.com/otcshare/tcs-hub/blob/master/theming-sphinx.rst
.. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
.. _contribution guidelines: https://clearlinux.org/documentation/clear-linux/reference/collaboration
.. _instructions for installing Sphinx: https://www.sphinx-doc.org/en/master/usage/installation.html
source/clear-linux/reference/collaboration/collaboration.rst
+75 -9
View File
@@ -1,17 +1,83 @@
.. _collaboration:
Collaboration guidelines
Documentation guidelines
########################
Thank you for your interest in collaborating with the |CL-ATTR|. This guide
details the best ways to collaborate with the |CL| team.
Additionally, this guide provides the guidelines our documentation follows.
Thus, you can help improve our documents with your use case tutorials,
examples, or task focused guides. Read the information carefully before
submitting any work for review to ensure your contribution can be added as
quickly as possible.
See a missing topic in the documentation? Find an existing document that could
be improved? Help us out by contributing! If you haven't contributed before,
take a moment to review our `Contribution guidelines`_.
Do you have questions about the documentation that were not answered by these
guidelines? Send your question to the `mailing list`_.
Contribution guidelines
***********************
The |CL| documentation is hosted in GitHub and is written using
reStructuredText. Use our guidelines and best practices to write consistent,
readable documentation.
.. toctree::
:maxdepth: 1
documentation/documentation
Writing guide: Describes the style we use to keep our documents clear and concise. <writing-guide>
Structure and formatting guide: Explains how we organize and format content, using reStructuredText and Sphinx. <structure-formatting>
How to contribute
*****************
There are multiple ways to contribute and help improve our documentation:
* **Make a suggestion**: Have a documentation suggestion but no time to write it
yourself? Send your suggestion to the `mailing list`_.
* **Log an issue**: If you find a problem in our documentation (such as typos or
out-of-date information), log an issue in the `documentation repository`_.
* **Contribute directly via GitHub**: Whether you've found a typo, have better
instructions or examples, or have a new page to add, submit your improvement
or addition as a pull request on the `documentation repository`_.
* **Test documentation**: Step through our instructional guides and tutorials to
verify the instructions. Log or correct any out-of-date information.
All contributions must follow our `code of conduct`_.
Contribute via GitHub
*********************
Our documentation is hosted in GitHub and we follow the standard `GitHub flow`_:
#. Clone the `documentation repository`_.
#. Create your own fork of the repository.
#. Create a branch for your contribution.
#. Add your commits.
#. Open a pull request.
#. Discuss, review, and update your contributions.
#. Once the maintainer approves, your contribution is merged and published as
part of the documentation.
.. _references:
References
**********
We use the following references to guide the grammar, style, and formatting of
our documentation:
* `Microsoft Writing Style Guide`_
* `Merriam-Webster Dictionary`_
* The Chicago Manual of Style (15th edition), The University of Chicago Press
* Microsoft Press Computer Dictionary, Microsoft Press
* Read Me First!, Oracle Technical Publications
.. _`code of conduct`: https://clearlinux.org/community/code-of-conduct
.. _mailing list: https://lists.clearlinux.org/mailman/listinfo/dev
.. _GitHub flow: https://guides.github.com/introduction/flow/
.. _documentation repository: https://github.com/clearlinux/clear-linux-documentation
.. _Microsoft Writing Style Guide: https://docs.microsoft.com/en-us/style-guide/welcome/
.. _Merriam-Webster Dictionary: https://www.merriam-webster.com/
source/clear-linux/reference/collaboration/documentation/basic.rst
-130
View File
@@ -1,130 +0,0 @@
.. _basic:
Basic contribution guide
########################
This list compiles the most common format, markup, structure, and grammar
rules for your convenience. You can find more detailed information in the
referenced sections.
.. contents::
:local:
:backlinks: entry
Format
******
* Limit line length to 78 characters. The GitHub web interface forces this
limitation for readability.
* Remove trailing white space from your documents.
* Use short sentences and paragraphs. Keep sentence length under 20 words.
* Use only lower case letters for filenames.
* Separate multiple words in filenames using dashes.
Markup
******
* Use the appropriate :abbr:`ReST (ReStructuredText)` roles for your content.
See the `ReST primer`_ for the complete list of roles.
* Use the :abbr: role to define the first instance of an abbreviation, for
example: :abbr:\`CL (Clear Linux)\`.
* Use hash-tags to underline the file's main title.
* Use asterisks to underline the file's first level headings.
* Use equal signs to underline the file's second level of headings.
* Use dashes to underline the file's third level of headings.
* Use labels to reference documentation sections. Do not reference
sections with URLs. See :ref:`cross` for details.
* Don't use explicit URLs as links, for example https://clearlinux.org/.
* Always include descriptive link text. For example:
Visit the `Clear Linux website`_. Do not use "here", "this", or similar
references for link text.
Structure
*********
* All files must have a main title and up to three levels of headings.
Restructure the content in multiple files as needed to comply.
* Use descriptive headings.
* Follow all headings with at least one paragraph of content. There should
never be two consecutive headings.
* Separate the link and the target definition. All target definitions must be
included at the end of the file. See :ref:`cross` for details.
* Use parallelism in headings, sentences, and lists. See our
:ref:`parallelism` for details.
* Put conditional phrases first in cautions and warnings. For example:
"If you do X, then Y will occur." See our :ref:`notices` guide.
* Place figures and tables immediately after related text.
* Place code or commands immediately after the leading text in a new line,
see our :ref:`code`.
* Reference figures, code examples, and tables by number.
For example, use "Figure 1," instead of "The figure above or below". See
:ref:`cross` and :ref:`images`.
* Include at least one direct reference to any table or figure you add. See
:ref:`tables`.
Grammar
*******
* Include only one main idea in a sentence. See :ref:`simple`.
* Limit the number of clauses you use to no more than two. See :ref:`simple`.
* Limit the number of sentences per paragraph to about six. See :ref:`simple`.
* Use strong verbs. See :ref:`simple`.
* Use action verbs. See :ref:`simple`.
* Avoid weak verbs like be, have, make, and do. See :ref:`simple`.
* Use short direct commands and avoid niceties such as the word
"please".
* Use the present tense wherever possible and avoid past and future
tense verbs. See :ref:`simple`.
* Use Active voice. Write, "Someone does something"; don't write,
"Something is done by someone" or "Something is done." See :ref:`simple`.
* Use "we" for recommendations. Write "We recommend..." as opposed to
"It is recommended...." See :ref:`simple`.
* Use "you" rather than "the user" in your instructions.
* Use short common English words whenever possible, see our :ref:`simple`
guide.
* Avoid contractions. See :ref:`grammar`.
* Use articles such as 'a', 'an', and 'the' to reduce ambiguity.
Additional information
**********************
Learn more about the accepted rules of grammar, punctuation, and word use in
our :ref:`language`. If you are looking for tips on how to write shorter,
clearer, and more concise content, visit our :ref:`simple` guide.
.. _Clear Linux website: https://clearlinux.org/
.. _ReST primer: http://docutils.sourceforge.net/docs/user/rst/quickstart.html
source/clear-linux/reference/collaboration/documentation/code.rst
-161
View File
@@ -1,161 +0,0 @@
.. _code:
Code blocks
###########
Contributing to the |CL-ATTR| is all about code. Therefore, your
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 ``: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
efficiently. Use `bash` for console commands, `asm` for assembly code and
`c` for C code.
* Treat all console commands entered by users as code examples.
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.
This source:
.. code-block:: rst
.. literalinclude:: ./hello.c
:language: c
: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.
This source:
.. code-block:: rst
.. code-block:: bash
$ mkdir ${HOME}/x86-build
$ mkdir ${HOME}/arm-build
$ 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.
Moving forward, `bash` will be used for commands entered by readers, and
`console` will be used for the output users obtain in the command prompt.
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.
This source:
.. code-block:: rest
.. code-block:: c
static NANO_CPU_INT_STUB_DECL (deviceStub);
void deviceDriver (void)
{
.
.
.
nanoCpuIntConnect (deviceIRQ, devicePrio, deviceIntHandler,
deviceStub);
.
.
.
}
Renders as:
.. code-block:: c
static NANO_CPU_INT_STUB_DECL (deviceStub);
void deviceDriver (void)
{
.
.
.
nanoCpuIntConnect (deviceIRQ, devicePrio, deviceIntHandler,
deviceStub);
.
.
.
}
Templates
*********
We included templates for a basic ``.. code-block::`` directive
and for a ``.. literalinclude::`` directive.
Use ``code-block`` for console commands, brief examples, and examples
outside the |CL| code base.
.. code-block:: rst
.. code-block:: language
source
Use ``litteralinclude`` to insert code from a source file. Keep in
mind that you can include the entire contents of the file or just
specific lines.
.. code-block:: rst
.. literalinclude:: ../path/to/file/file_name.c
:language: c
:lines: 5-30, 32, 70-100
:emphasize-lines: 3
:linenos:
.. caution::
The ``:emphasize-lines:`` option uses the line numbering provided
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/contents.rst
-40
View File
@@ -1,40 +0,0 @@
.. _contents:
Contents directive
##################
For |CL-ATTR| documentation that has three or more sections, use the `contents::`
directive as shown in the example below. This directive automatically captures the headings (and
subheadings if used) as specified in the value given after `:depth:`. Adding this directive to
longer documents allows users to quickly navigate to the desired section.
.. contents:: :local:
:depth: 2
.. code-block:: bash
.. contents:: :local:
:depth: 2
.. note::
Assure that you add `:local:` as the value. For more resources on this directive,
visit the `reStruturedText Directives`_
EXAMPLE:
Guide Example
*************
Introduction
============
Step-by-Step
============
Launch
======
.. _reStruturedText Directives: http://docutils.sourceforge.net/0.4/docs/ref/rst/directives.html#table-of-contents
source/clear-linux/reference/collaboration/documentation/cross.rst
-153
View File
@@ -1,153 +0,0 @@
.. _cross:
Cross-references
################
Sphinx provides different methods to create both internal and
external cross-references. Use only the following methods to increase the
consistency of the documents.
.. _internal-cross:
Internal cross-references
*************************
An internal cross-reference is a reference to a location within the |CL-ATTR|
documentation. Use explicit markup labels and the ``:ref:`` role to create
cross references to headings, figures, and code examples as needed. Every
file must have a label before the title, which is identical to the file's
name, in order to be be cross-referenced within the entire documentation.
Labels' naming conventions:
* Ensure the label is unique throughout the documentation
* Use only full words.
* Use \- to link multiple words.
* Use only as many words as necessary.
These are some examples of proper labels:
.. code-block:: rst
.. _quick-start:
.. _gerrit-access:
.. _building-clear-linux:
Do not use labels like these:
.. code-block:: rst
.. _QuickStart:
.. _How to Gain Access to Gerrit:
.. _building:
As an example, this is an internal reference to the beginning of the :ref:`rest`.
Observe that the ``:ref:`` role is replaced with the title's text.
Similarly, it will be replaced with the figure's caption. If a different
text is needed the ``:ref:`` role can still be used, for example:
This is an internal reference to the beginning of
:ref:`this section <rest>`.
Use the following templates to insert internal cross references properly.
.. code-block:: rst
.. _label-of-target:
This is a heading
-----------------
This creates a link to the :ref:`label-of-target` using the text of the
heading.
This creates a link to the :ref:`target <label-of-target>` using the word
'target' instead of the heading.
The template renders as:
.. _label-of-target:
This is a heading
-----------------
This creates a link to the :ref:`label-of-target` using the text of the
heading.
This creates a link to the :ref:`target <label-of-target>` using the word
'target' instead of the heading. We use the term 'target' here similar to
the way'anchor' is used in HTML.
.. note::
This type of internal cross reference works across multiple files, is
independent of changes in the text of the headings, and works on all
Sphinx builders.
External References
*******************
External references or hyperlinks can be added easily with reST. Only
hyperlinks with a separated target definition are allowed.
Do not use explicit hyperlinks consisting entire URLs. For example, links
like this one, https://clearlinux.org/ must be avoided.
Hyperlinks with a separated target definition allow us to place the URL after
label. They are easier to update and independent of the text, for example:
`Gitg`_ is a great tool to visualize a GIT tree.
.. _Gitg: https://wiki.gnome.org/Apps/Gitg/
Follow these guidelines when inserting hyperlinks:
* The labels for hyperlinks must be grammatically correct and unique within
the file.
* Do not create labels for hyperlinks using: link, here, this, there, etc.
* Add all target definitions at the end of the file containing the
hyperlinks.
Use this template to add a hyperlink with a separated definition:
.. code-block:: rst
The state of `Oregon`_ offers a wide range of recreational activities.
The include directive
*********************
|CL| documentation also uses the ``.. include::``
directive to include a portion of another reST file.
Use the ``.. include::`` directive to show a select portion of a file.
.. code-block:: console
.. include:: rest.rst
:start-after: incl-restructured-text-overview:
:end-before: incl-restructured-text-overview-end:
In this example, note that you must:
* Create a `target` that appears directly above a header (ease of inclusion)
* Ensure that the target is unique, as explained in :ref:`target <internal-cross>`
* Use a `:` at the end of the value of `start-after` and `end-before`.
Use of the ``.. inclusion::`` for :ref:`rest` is shown below.
.. include:: rest.rst
:start-after: incl-restructured-text-overview:
:end-before: incl-restructured-text-overview-end:
.. _Oregon: http://traveloregon.com/
source/clear-linux/reference/collaboration/documentation/documentation.rst
-139
View File
@@ -1,139 +0,0 @@
.. _documentation:
Documentation contribution guidelines
#####################################
The |CL-ATTR| documentation contribution guidelines provide detailed information
about the scope and purpose of the documentation, the accepted writing style,
and the markup used.
The |CL| documentation is hosted in GitHub and welcomes community
contributions. This guide provides rules to write
:ref:`clear, concise<basic>`, and :ref:`consistent content<structures>`. Our
documentation is written using ReStructuredText and we provide
:ref:`examples, templates, and best practices<rest>` for that markup.
To contribute, follow the standard `GitHub flow`_:
#. Clone the `Clear Linux documentation repository`_.
#. Create your own fork of the repository.
#. Create a branch for your contribution.
#. Add your commits.
#. Open a pull request.
#. Discuss, review, and update your contributions.
#. Once the maintainer approves, your contribution is merged and published as
part of the `documentation section`_.
The |CL| technical content is written in simple American English and our
:ref:`language` contains detailed information on that standard.
This guide includes the following sections:
.. toctree::
:maxdepth: 3
basic
structures
rest
language
Scope
*****
The |CL| documentation is divided in five sections:
* **Get started:** Information about installing Clear Linux.
* **Concepts:** Detailed technical information about our features.
* **Guides:** Step-by-step instructions to complete common tasks and
configuration.
* **Tutorials:** Step-by-step instructions to complete the installation and
configuration of the tools needed for a specific use case.
* **Reference:** Information providing additional context or details.
If you are unsure on which section to use for your contribution, send an
email to our `mailing list`_ at: dev@lists.clearlinux.org Include the outline
of the contribution you are planning and a brief description of its intended
purpose and scope.
This style guide applies to the following technical content:
* Commit messages
* Technical presentations
* All documents in ReStructuredText within and without the documentation
repository
* In-code comments
* Release notes
We are always grateful to receive content contributions and are happy to help
via our mailing list or our IRC channel, #clearlinux. If you have found a
problem with one of our documents, please file a `bug report`_.
Tone and audience
*****************
The tone of the |CL| documentation should be clear, concise, confident, and
courteous. We write for our peers and want to be familiar. Use the second
person, you or we, and active voice, we configure or you run, for example.
Remain professional in your writing and carry an undertone of cordiality,
respect, and cooperation.
Assume your audience has about the same level of technical understanding and
expertise as you did when you first started collaborating. Do not talk down
to our readers but do not assume they know everything about the subject.
Offer brief explanations or summaries of "common knowledge" if a
significant portion of readers might benefit.
All contributions must follow our `code of conduct`_.
Methodology
***********
This guide differs from other style guides and contains additional material
not found in those sources.
To research a style question, look for the answer in this guide
first. If the question is not answered here, send your question to the
`mailing list`_ at: dev@lists.clearlinux.org.
If the question is answered in the existing style guide or dictionary,
the solution is implemented and enforced as described.
References
**********
In creating and refining the policies in this document, we consulted the
following sources for guidance:
* The Chicago Manual of Style (15th edition), The University of
Chicago Press;
* Merriam-Webster Dictionary;
* Microsoft Manual of Style for Technical Publications, Microsoft
Press;
* Microsoft Press Computer Dictionary, Microsoft Press; and
* Read Me First!, Oracle Technical Publications.
These sources do not always concur on questions of style and usage; nor do we
always agree with these sources. In areas where there is disagreement, the
decisions are explained in the respective section.
This guide takes precedence over all other style guides in all cases. In
cases where the guide does not address the issue at hand, please report the
issue to the `mailing list`_ using our `bug report`_.
Use the Merriam-Webster's Collegiate Dictionary to determine correct
spelling, hyphenation, and usage.
.. _mailing list: https://lists.clearlinux.org/mailman/listinfo/dev
.. _GitHub flow: https://guides.github.com/introduction/flow/
.. _documentation section: https://clearlinux.org/documentation
.. _Clear Linux documentation repository:
https://github.com/clearlinux/clear-linux-documentation
.. _bug report: https://github.com/clearlinux/distribution/issues
.. _code of conduct: https://clearlinux.org/community/code-of-conduct
source/clear-linux/reference/collaboration/documentation/figures/fibers-1.svg
-165
View File
@@ -1,165 +0,0 @@
<?xml version="1.0" encoding="UTF-8" standalone="no"?>
<!-- Created with Inkscape (http://www.inkscape.org/) -->
<svg
xmlns:dc="http://purl.org/dc/elements/1.1/"
xmlns:cc="http://creativecommons.org/ns#"
xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
xmlns:svg="http://www.w3.org/2000/svg"
xmlns="http://www.w3.org/2000/svg"
xmlns:sodipodi="http://sodipodi.sourceforge.net/DTD/sodipodi-0.dtd"
xmlns:inkscape="http://www.inkscape.org/namespaces/inkscape"
width="106.55701"
height="106.49829"
id="svg5827"
version="1.1"
inkscape:version="0.48.5 r10040"
sodipodi:docname="Fibers.svg">
<defs
id="defs3" />
<sodipodi:namedview
inkscape:document-units="mm"
id="base"
pagecolor="#ffffff"
bordercolor="#666666"
borderopacity="1.0"
inkscape:pageopacity="0.0"
inkscape:pageshadow="2"
inkscape:zoom="3.959798"
inkscape:cx="138.72634"
inkscape:cy="23.280168"
inkscape:current-layer="layer1"
showgrid="false"
units="mm"
fit-margin-top="0"
fit-margin-left="0"
fit-margin-right="0"
fit-margin-bottom="0"
inkscape:window-width="1920"
inkscape:window-height="1017"
inkscape:window-x="-8"
inkscape:window-y="-8"
inkscape:window-maximized="1" />
<metadata
id="metadata4">
<rdf:RDF>
<cc:Work
rdf:about="">
<dc:format>image/svg+xml</dc:format>
<dc:type
rdf:resource="http://purl.org/dc/dcmitype/StillImage" />
<dc:title></dc:title>
</cc:Work>
</rdf:RDF>
</metadata>
<g
inkscape:label="Layer 1"
inkscape:groupmode="layer"
id="layer1"
transform="translate(-320.92486,-84.790913)">
<g
transform="translate(111.50953,81.385786)"
style="font-size:12px;fill:none;stroke-linecap:square;stroke-miterlimit:3;overflow:visible"
id="g5872">
<path
inkscape:connector-curvature="0"
style="fill:#686868;fill-opacity:1;fill-rule:evenodd;stroke:none"
d="m 315.97234,56.654274 c 0,0.176127 0,0.293546 0,0.410964 -0.0587,6.751545 -1.40902,13.209546 -3.69868,19.080455 -0.11742,0.293545 -0.23483,0.587091 -0.35225,0.880636 -1.99611,4.872855 -4.75544,9.452164 -8.10186,13.503092 -0.29354,0.352254 -0.52838,0.6458 -0.82192,0.998054 -1.40902,1.585146 -2.87675,3.111582 -4.46189,4.5206 -0.29355,0.293546 -0.6458,0.587091 -0.93935,0.821928 -4.16835,3.639967 -8.92378,6.692837 -14.09018,8.865077 -0.29355,0.11741 -0.58709,0.23483 -0.82193,0.35225 -6.04704,2.40707 -12.68116,3.81609 -19.55013,3.81609 -0.17612,0 -0.29354,0 -0.46967,0 -0.11742,0 -0.23484,0 -0.41096,0 -6.86897,0 -13.5031,-1.40902 -19.55013,-3.81609 -0.23484,-0.11742 -0.52838,-0.23484 -0.82193,-0.35225 -5.1664,-2.17224 -9.92184,-5.22511 -14.09018,-8.865077 -0.29355,-0.234837 -0.58709,-0.528382 -0.93935,-0.821928 -1.58514,-1.409018 -3.05287,-2.935454 -4.46189,-4.5206 -0.29354,-0.352254 -0.52838,-0.6458 -0.82193,-0.998054 -3.34641,-4.050928 -6.10574,-8.630237 -8.10185,-13.503092 -0.11742,-0.293545 -0.23484,-0.587091 -0.35225,-0.880636 -2.28966,-5.870909 -3.63997,-12.32891 -3.69868,-19.080455 0,-0.117418 0,-0.234837 0,-0.410964 0,-0.117418 0,-0.234836 0,-0.410963 0.0587,-6.751546 1.40902,-13.150837 3.69868,-19.080455 0.11741,-0.293546 0.23483,-0.528382 0.35225,-0.821928 1.99611,-4.931564 4.75544,-9.452164 8.10185,-13.5618 0.29355,-0.293546 0.52839,-0.587091 0.82193,-0.939346 1.40902,-1.643854 2.87675,-3.170291 4.46189,-4.579309 0.35226,-0.293545 0.6458,-0.587091 0.93935,-0.821927 4.16834,-3.639964 8.92378,-6.6341276 14.09018,-8.806364 0.29355,-0.1761273 0.58709,-0.2348364 0.82193,-0.3522545 6.04703,-2.4657819 12.68116,-3.816091 19.55013,-3.8748001 0.17612,0 0.29354,0 0.41096,0 0.17613,0 0.29355,0 0.46967,0 6.86897,0.058709 13.50309,1.4090182 19.55013,3.8748001 0.23484,0.1174181 0.52838,0.1761272 0.82193,0.3522545 5.1664,2.1722364 9.92183,5.1664 14.09018,8.806364 0.29355,0.234836 0.6458,0.528382 0.93935,0.821927 1.58514,1.409018 3.05287,2.935455 4.46189,4.579309 0.29354,0.352255 0.52838,0.6458 0.82192,0.939346 3.34642,4.109636 6.10575,8.630236 8.10186,13.5618 0.11742,0.293546 0.23483,0.528382 0.35225,0.821928 2.28966,5.929618 3.63997,12.387618 3.69868,19.080455 0,0.176127 0,0.293545 0,0.410963"
id="path5409" />
<path
inkscape:connector-curvature="0"
style="fill:#828282;fill-opacity:1;fill-rule:evenodd;stroke:none"
d="m 315.97234,56.654274 c 0,0.176127 0,0.293546 0,0.410964 l -106.55701,0 c 0,-0.117418 0,-0.234837 0,-0.410964 0,-0.117418 0,-0.234836 0,-0.410963 l 106.55701,0 c 0,0.176127 0,0.293545 0,0.410963 z"
id="path5415" />
<g
id="g5808">
<path
id="path5411"
d="m 298.53574,96.048075 c -0.29355,0.293546 -0.6458,0.587091 -0.93935,0.821928 l -69.80511,0 c -0.29355,-0.234837 -0.58709,-0.528382 -0.93935,-0.821928 l 71.68381,0 z"
style="fill:#828282;fill-opacity:1;fill-rule:evenodd;stroke:none"
inkscape:connector-curvature="0" />
<path
id="path5413"
d="m 312.27366,76.145693 c -0.11742,0.293545 -0.23483,0.587091 -0.35225,0.880636 l -98.45515,0 c -0.11742,-0.293545 -0.23484,-0.587091 -0.35225,-0.880636 l 99.15965,0 z"
style="fill:#828282;fill-opacity:1;fill-rule:evenodd;stroke:none"
inkscape:connector-curvature="0" />
<path
id="path5417"
d="m 312.27366,37.162856 -99.15965,0 c 0.11741,-0.293546 0.23483,-0.528382 0.35225,-0.821928 l 98.45515,0 c 0.11742,0.293546 0.23483,0.528382 0.35225,0.821928 z"
style="fill:#828282;fill-opacity:1;fill-rule:evenodd;stroke:none"
inkscape:connector-curvature="0" />
<path
id="path5419"
d="m 298.53574,17.260473 -71.68381,0 c 0.35226,-0.293545 0.6458,-0.587091 0.93935,-0.821927 l 69.80511,0 c 0.29355,0.234836 0.6458,0.528382 0.93935,0.821927 z"
style="fill:#828282;fill-opacity:1;fill-rule:evenodd;stroke:none"
inkscape:connector-curvature="0" />
<path
id="path5421"
d="m 303.81955,22.779128 0,67.750293 c -0.29354,0.352254 -0.52838,0.6458 -0.82192,0.998054 l 0,-69.687693 c 0.29354,0.352255 0.52838,0.6458 0.82192,0.939346 z"
style="fill:#828282;fill-opacity:1;fill-rule:evenodd;stroke:none"
inkscape:connector-curvature="0" />
<path
id="path5423"
d="m 283.50621,7.632182 0,98.102898 c -0.29355,0.11741 -0.58709,0.23483 -0.82193,0.35225 l 0,-98.8074025 c 0.23484,0.1174181 0.52838,0.1761272 0.82193,0.3522545 z"
style="fill:#828282;fill-opacity:1;fill-rule:evenodd;stroke:none"
inkscape:connector-curvature="0" />
<path
id="path5425"
d="m 263.13415,3.4051274 0,106.4982926 c -0.17612,0 -0.29354,0 -0.46967,0 -0.11742,0 -0.23484,0 -0.41096,0 l 0,-106.4982926 c 0.17612,0 0.29354,0 0.41096,0 0.17613,0 0.29355,0 0.46967,0 z"
style="fill:#828282;fill-opacity:1;fill-rule:evenodd;stroke:none"
inkscape:connector-curvature="0" />
<path
id="path5427"
d="m 242.70339,7.2799275 0,98.8074025 c -0.23484,-0.11742 -0.52838,-0.23484 -0.82193,-0.35225 l 0,-98.102898 c 0.29355,-0.1761273 0.58709,-0.2348364 0.82193,-0.3522545 z"
style="fill:#828282;fill-opacity:1;fill-rule:evenodd;stroke:none"
inkscape:connector-curvature="0" />
<path
id="path5429"
d="m 222.39004,21.839782 0,69.687693 c -0.29354,-0.352254 -0.52838,-0.6458 -0.82193,-0.998054 l 0,-67.750293 c 0.29355,-0.293546 0.52839,-0.587091 0.82193,-0.939346 z"
style="fill:#828282;fill-opacity:1;fill-rule:evenodd;stroke:none"
inkscape:connector-curvature="0" />
<path
id="path5431"
d="m 231.54866,35.812546 0,55.01042 62.23164,0 0,-55.01042 -62.23164,0 z"
style="fill:#f2f2f2;fill-opacity:1;fill-rule:evenodd;stroke:none"
inkscape:connector-curvature="0" />
<path
id="path5433"
d="m 238.82859,46.732438 0,4.227054 47.73049,0 0,-4.227054 -47.73049,0 z"
style="fill:#ead57d;fill-opacity:1;fill-rule:evenodd;stroke:none"
inkscape:connector-curvature="0" />
<path
id="path5435"
d="m 241.76404,39.511219 c 0.6458,0 0.76322,0.469673 0.46968,0.880637 l -2.5832,3.346418 c -0.29355,0.410964 -0.88064,0.469673 -1.2329,0 l -2.52449,-3.346418 c -0.35225,-0.469673 -0.17612,-0.880637 0.41097,-0.880637 l 5.45994,0 z"
style="fill:#c2c2c2;fill-opacity:1;fill-rule:evenodd;stroke:none"
inkscape:connector-curvature="0" />
<path
id="path5437"
d="m 238.82859,63.347111 0,4.168345 47.73049,0 0,-4.168345 -47.73049,0 z"
style="fill:#19d77a;fill-opacity:1;fill-rule:evenodd;stroke:none"
inkscape:connector-curvature="0" />
<path
id="path5439"
d="m 241.76404,56.125892 c 0.6458,0 0.76322,0.410964 0.46968,0.821928 l -2.5832,3.346418 c -0.29355,0.469673 -0.88064,0.469673 -1.2329,0 l -2.52449,-3.346418 c -0.35225,-0.469673 -0.17612,-0.821928 0.41097,-0.821928 l 5.45994,0 z"
style="fill:#c2c2c2;fill-opacity:1;fill-rule:evenodd;stroke:none"
inkscape:connector-curvature="0" />
<path
id="path5441"
d="m 238.82859,79.961784 0,4.168345 47.73049,0 0,-4.168345 -47.73049,0 z"
style="fill:#f0553a;fill-opacity:1;fill-rule:evenodd;stroke:none"
inkscape:connector-curvature="0" />
<path
id="path5443"
d="m 241.76404,72.740566 c 0.6458,0 0.76322,0.352254 0.46968,0.821927 l -2.5832,3.287709 c -0.29355,0.410964 -0.88064,0.410964 -1.2329,0 l -2.52449,-3.287709 c -0.35225,-0.469673 -0.17612,-0.821927 0.41097,-0.821927 l 5.45994,0 z"
style="fill:#c2c2c2;fill-opacity:1;fill-rule:evenodd;stroke:none"
inkscape:connector-curvature="0" />
<text
id="text5445"
style="font-size:17.8475647px;font-style:normal;font-weight:normal;text-align:start;text-anchor:start;fill:#ffffff;font-family:Intel Clear"
y="30.496477"
x="238.84772"
xml:space="preserve">Fibers</text>
</g>
</g>
</g>
</svg>
Side by Side

Before

Width:  |  Height:  |  Size: 10 KiB

source/clear-linux/reference/collaboration/documentation/grammar.rst
-342
View File
@@ -1,342 +0,0 @@
.. _grammar:
Grammar guide
#############
This guide provides valuable insight into the correct grammar for the
|CL-ATTR| documentation. It covers subjects such as capitalization, verbs,
hyphenation, possessives, and contractions.
Capitalization
**************
The preferred capitalization style for all documentation is sentence
case.
Words should only be capitalized when:
* They are proper nouns or adjectives.
* They refer to trademarked product names.
.. note::
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.
Menu capitalization
===================
When referring to software menu items by name, replicate the
capitalization as it appears in the software menus the user will see.
It is acceptable to refer to these items generically by using
lowercase letters if it is clear that your reference is generic and
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 second sentence could have capitalized the term "Widget
Configuration window"; but there are times when you might want to
refer to something with a generic descriptor and not its name. Observe
the use of the ReST markup ``:guilabel:`` on the first sentence.
A few other menu capitalization rules to keep in mind:
* Use "Select :menuselection:`File --> New`."
* Put the option to be selected last. "Select
: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 divide the steps using
``:guilabel:`` or ``:menuselection:``. For example: "Go to
:guilabel:`File` and select
:menuselection:`Print --> Print Preview --> Set Up`."
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:
* Widget Pro v5.0
* Widget Master v2.1.12
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
***********************
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
===============================
Here are some guidelines for singular and plural possessives:
* Use only the apostrophe to show possession for a plural that ends in
s: The boys' books.
* Use apostrophe + s to show possession for a plural that does not end
in s: The men's books.
* Use apostrophe + s to show possession for a singular that ends in a
silent sibilant: Illinois's capital.
* Use apostrophe + s to show
possession for a singular that ends in a sibilant; s, x, c, z, or
others.
The following table provides some examples with the correct and
incorrect cases and the notes that accompanies them.
+-------------------+------------------+---------------------------+
| Correct | Incorrect | Notes |
+===================+==================+===========================+
| the boys' books | the boy's books | The books that belong to |
| | | several boys. |
+-------------------+------------------+---------------------------+
| the men's books | the mens' books | The books that belong to |
| | | several men. |
| | | |
+-------------------+------------------+---------------------------+
| Arkansas's code | Arkansas' code | The s at the end of |
| | | Arkansas is silent and |
| | | Arkansas is not a plural. |
+-------------------+------------------+---------------------------+
| the boss's office | the boss' office | We say: "the /BOSS-iz/ |
| | | office" not "the/BOSS/ |
| | | office." |
+-------------------+------------------+---------------------------+
| the box's lid | the boxe's lid | One could say "the box |
| | the box' lid | lid," avoiding the |
| | | possessive. |
+-------------------+------------------+---------------------------+
| Lopez's average | Lopez' average | We say "/LO-pez-iz/ |
| | | average," not "/LO-pez/ |
| | | average." |
+-------------------+------------------+---------------------------+
| business's sales | business' sales | If you pronounce another |
| | | syllable to show |
| | | possession, it must have |
| | | the apostrophe-s. |
+-------------------+------------------+---------------------------+
Apostrophe-s anomalies
======================
If a company name ends in s, x, c, or a sibilant sound, use the
apostrophe-s ending for
possessives:
Traktronix's oscilloscopes
Exception: If the company name is intended as a plural, we allow the
apostrophe-only ending:
Tejada Instruments' calculators
In many cases, it is actually best to avoid the possessive form
altogether for s-ending singular possessives, such as for company
names and use the company name as a nonpossessive modifier instead:
Traktronix oscilloscopes
Tejada Instruments calculators
We say "Intel equipment" when discussing Intel-branded products, not
"Intel's equipment", which implies that we own it, not that we produce
it. "Intel's equipment" sounds like the equipment that Intel employees
use.
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 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
* graphics team
There are always exceptions, especially when the plural form is
generally considered to be singular: sales, physics, operations. It is
best to adhere to this rule and ask if you are unsure.
Parenthetical plurals
=====================
Do not parenthesize optional plurals, whether added to the end of a
word, typically with the letter s, or internally. In general, think in
plurals when you write, assume that the user understands that a plural
could mean a singular as well. A typical user who has only one unit
will not be confused if you say "connect the units." On the contrary,
using parenthetical plurals often creates more confusion.
Correct
Men, women, children, college alumni, moose,
and even desert plants such as cacti should not
use parentheses around plurals.
Incorrect
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
========================
Some abbreviated terms can cause trouble, particularly when the
pluralized portion does not fall at the end of the phrase. These
internal-plural words should follow standard English pluralization
rules when abbreviated: The plural goes at the end of the term.
* Alarms acknowledged and logged: AAL, AALs.
* Attorneys-general: AG, AGs.
* Regions of interest: ROI, ROIs.
Plurals of acronyms and capitalized product names
=================================================
Pluralize acronyms, initialisms, and capitalized product names by
adding a lowercase s; do not use an apostrophe. If the term ends in a
sibilant (s, x, z, sometimes c and others), pluralize it by adding a
lowercase es. Examples:
Use TVs, DVDs, CDs, DVMRs not TV's, DVD's, CD's, DVMR's.
Use OSes not OSs, OS's.
Use TRAXes, iBOXes not TRAXs, TRAX's, iBOX's, iBOXs.
Use FAACes not FAAC's, assuming it is pronounced "face".
Use FAACs not FAAC's Assuming it is pronounced "fake".
Whenever you hear the extra syllable in the plural, add the -es suffix
for the plural; if you do not hear the extra syllable, add the -s
suffix for the plural.
Latin plurals
=============
Pluralize Latin terms in body text as shown:
* Use appendixes not appendices.
* Use matrixes not matrices.
* Use indexes not indices.
* Use vertexes not vertices.
.. note::
Some Latin plurals, such as parentheses, phenomena, alumni, and
crises, are widely used and accepted in English.
Contractions
************
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 non-native English-speakers
because these contractions stand for more than one construction. For
example, there's can be a contraction of there is or there has. The
same applies to where's, it's, that's, and others.
Also, avoid contractions of the word is, especially when combined with
company or product names: Say, WidgetPro is an awesome product; not
WidgetPro's an awesome product.
Hyphenation
***********
The hyphen is often used to join words together to form a compound noun.
Compound nouns often go through this progressions:
* open compound: health care
* hyphenated compound: health-care
* closed compound: healthcare
The English language is trending away from hyphenated compounds to
closed compounds.
Prefix hyphenation
==================
Do not hyphenate the prefixes listed below. Join the prefix to the
term being modified, even if this results in a double vowel or double
consonant:
ante, counter, intra, mini, pro, super, anti, extra, meta, non,
pseudo, trans, bi, by, infra, micro, post, re, ultra, bio, inter, mid,
pre, sub, un.
Here are some words that are often inappropriately hyphenated; do not
hyphenate these words either:
antitheft device, multicamera, multiscreen, prepackaged, reuse,
submenu, autofocus, multifamily, multiuser, pseudoscience, semiannual,
subtotal, autoiris, multimedia, nonprofit, reengineered, semicircle,
superuser, microarchitecture, multiposition, predefined, reevaluate,
subfolder, superscript, microorganism, multiprotocol, predrilled,
reinvent, submarine.
.. note::
Question whether the pre- prefix is needed at all and consider
leaving it off the word entirely if the meaning is the same.
Exceptions
----------
One overriding exception to the prefix rule is when the prefix is
prepended to a proper and capitalized noun:
* Non-European
* Mid-April (but: midweek)
Another exception is when the second word of a compound is a numeral:
* Pre-1914
Some prefixes, such as self-, half-, quasi-, and ex-, when meaning
"formerly", usually need a hyphen:
* Self-control, half-truth, quasi-corporation, ex-governor
Suffix hyphenation
==================
In general, do not hyphenate suffixes. Here are some examples.
The suffix -wide is usually not hyphenated:
* Nationwide, worldwide, systemwide, campuswide, statewide,
companywide, etc.
The suffix -wise is usually not hyphenated:
* Otherwise, businesswise, revenuewise, clockwise, counterclockwise
Quotation marks
***************
Follow these guidelines for quotation marks:
* Restrict use of quotation marks to terms as terms.
* Do not use quotation marks for emphasis; use *italics* for emphasis.
* Avoid using single-quote marks.
* In terms of punctuation: commas and periods typically go inside the
end-quote; semicolons, colons, question marks, and exclamation points
typically go outside quotation marks. Unless they are part of the
actual quotation.
source/clear-linux/reference/collaboration/documentation/headings.rst
-30
View File
@@ -1,30 +0,0 @@
.. _headings:
Headings
########
Descriptive and brief headings are crucial to the quality of the
documentation. Sphinx uses the headings within the
:abbr:`ReST (RestructuredText)` files to generate the navigation of the HTML
output and the outlines of the PDF files. The |CL-ATTR| publishes the
documentation as HTML making consistent heading levels extremely important.
In addition to the title of the file, only three levels of headings are
accepted. The following example shows all accepted levels of headings:
.. code-block:: rst
Title
#####
Level 1 sections
****************
Level 2 sections
================
Level 3 sections
----------------
Headings must be written in sentence case. Learn more about the correct
capitalization in our :ref:`grammar guide<grammar>`.
source/clear-linux/reference/collaboration/documentation/hello.c
-188
View File
@@ -1,188 +0,0 @@
/** @file
@brief Hello World Demo
A Hello World demo for the Nanokernel and the Microkernel.
*/
/*
* Copyright (c) 2012-2014 Wind River Systems, Inc.
*
* Licensed under the Apache License, Version 2.0 (the "License");
* you may not use this file except in compliance with the License.
* You may obtain a copy of the License at
*
* http://www.apache.org/licenses/LICENSE-2.0
*
* Unless required by applicable law or agreed to in writing, software
* distributed under the License is distributed on an "AS IS" BASIS,
* WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
* See the License for the specific language governing permissions and
* limitations under the License.
*/
/** CONFIG_MICROKERNEL
The microkernel hello world demo has two tasks that use semaphores
and sleeps to take turns printing a greeting message at a
controlled rate.*/
/** #else || CONFIG_NANOKERNEL
* The nanokernel hello world demo has a task and a fiber that use
* semaphores and timers to take turns printing a greeting message at
* a controlled rate.
*/
/**
* @def SLEEPTICKS (SLEEPTIME * sys_clock_ticks_per_sec / 1000)
* @brief Compute equivalence in ticks.
*/
/**
* @def SLEEPTIME
* @brief Specify delay between greetings (in ms).
*/
#if defined(CONFIG_STDOUT_CONSOLE)
#include <stdio.h>
#define PRINT printf
#else
#include <misc/printk.h>
#define PRINT printk
#endif
#ifdef CONFIG_MICROKERNEL
#include <zephyr.h>
#define SLEEPTIME 500
#define SLEEPTICKS (SLEEPTIME * sys_clock_ticks_per_sec / 1000)
/**
* @brief A loop saying hello.
*
* @details
* Actions:
* -# Ouputs "Hello World!".
* -# Waits, then lets another task run.
@param taskname The task's identification string.
@param mySem The task's semaphore.
@param otherSem The other task's semaphore.
*/
void helloLoop(const char *taskname, ksem_t mySem, ksem_t otherSem)
{
while (1)
{
task_sem_take (mySem, TICKS_UNLIMITED);
PRINT ("%s: Hello World!\n", taskname); /* Action 1 */
task_sleep (SLEEPTICKS); /* Action 2 */
task_sem_give (otherSem);
}
}
/**
* @brief Exchanges Hello messages with taskB.
*
* @details
* Actions:
* -# taskA gives its own semaphore, thus it says hello right away.
* -# Calls function helloLoop, thus taskA exchanges hello messages with taskB.
*/
void taskA(void)
{
task_sem_give (TASKASEM); /* Action 1 */
helloLoop (__FUNCTION__, TASKASEM, TASKBSEM); /* Action 2 */
}
/**
* @brief Exchanges Hello messages with taskA.
*
* Actions:
* -# Calls function helloLoop, thus taskB exchanges hello messages with taskA.
*/
void taskB(void)
{
helloLoop (__FUNCTION__, TASKBSEM, TASKASEM); /* Action 1 */
}
#else
#include <nanokernel.h>
#include <nanokernel/cpu.h>
#define SLEEPTIME 500
#define SLEEPTICKS (SLEEPTIME * sys_clock_ticks_per_sec / 1000)
#define STACKSIZE 2000
/** Declares a stack for a fiber with a size of 2000.*/
char fiberStack[STACKSIZE];
/** Declares a nanokernel semaphore for a task. */
struct nano_sem nanoSemTask;
/** Declares a nanokernel semaphore for a fiber.*/
struct nano_sem nanoSemFiber;
/**
* @brief Defines the turns taken by the tasks in the fiber.
*
* Actions:
* -# Initializes semaphore.
* -# Initializes timer.
* -# Waits for task, then runs.
* -# Outputs "Hello World!".
* -# Waits, then yields to another task.
*/
void fiberEntry(void) {
struct nano_timer timer;
uint32_t data[2] = { 0, 0 };
nano_sem_init(&nanoSemFiber); /* Action 1 */
nano_timer_init(&timer, data); /* Action 2 */
while (1) {
nano_fiber_sem_take(&nanoSemFiber, TICKS_UNLIMITED); /* Action 3 */
PRINT("%s: Hello World!\n", __FUNCTION__); /* Action 4 */
nano_fiber_timer_start(&timer, SLEEPTICKS); /* Action 5 */
nano_fiber_timer_test(&timer, TICKS_UNLIMITED);
nano_fiber_sem_give(&nanoSemTask);
}
}
/**
* @brief Implements the Hello demo.
*
* Actions:
* -# Outputs "hello".
* -# Waits, then signals fiber's semaphore.
* -# Waits on fiber to yield.
*/
void main(void) {
struct nano_timer timer;
uint32_t data[2] = { 0, 0 };
task_fiber_start(&fiberStack[0], STACKSIZE, (nano_fiber_entry_t) fiberEntry,
0, 0, 7, 0);
nano_sem_init(&nanoSemTask);
nano_timer_init(&timer, data);
while (1) {
PRINT("%s: Hello World!\n", __FUNCTION__); /* Action 1 */
nano_task_timer_start(&timer, SLEEPTICKS); /* Action 2 */
nano_task_timer_test(&timer, TICKS_UNLIMITED);
nano_task_sem_give(&nanoSemFiber);
nano_task_sem_take(&nanoSemTask, TICKS_UNLIMITED); /* Action 3 */
}
}
#endif
source/clear-linux/reference/collaboration/documentation/images.rst
-88
View File
@@ -1,88 +0,0 @@
.. _images:
Images
######
Images or figures grab the reader's attention and convey information that
sometimes is difficult to explain using words alone. Well-planned graphics
reduce the amount of text required to explain information. Non-native English
readers rely heavily on graphics because graphics enhance their understanding of the text.
Follow these guidelines when creating graphics for the |CL-ATTR|:
* Save the image files in a :file:`figures` folder. The folder must be found
at the same level as the file containing the text.
* Use only lower case letters for image filenames.
* Separate multiple words in filenames using dashes.
* Name figures with the filename of the file they appear on and add a number
to indicate their place in the file. For example: The third figure added to
the :file:`fibers.rst` file must be named :file:`fibers-3.png`.
* Include a caption describing the figure's content and to use as a reference.
All figures must have a caption.
* Use cross-references. Refer to your graphics in the main text flow.
Create a label using the filename of the image. Use the `:ref:` role to place
the cross reference, see :ref:`cross` for more details.
* Place the figure immediately after its reference in the text flow or as
close as possible.
* Keep figures simple. They should only contain the information the
reader needs.
* Use figures judiciously. Don't use superfluous graphics and don't
use graphics as mere decorations. They must have purpose. You don't
need to show a screenshot of every single step or window in a software
installation procedure, for example.
* Avoid volatility. Don't incorporate information into a graphic that
might change with each release, for example: product versions or
codename abbreviations.
* Use only approved image formats. Use either PNG or JPEG bitmap files for
screenshots and SVG files for vector graphics. If a figure is not a
photograph or screenshot, use the vector graphic file format to ensure
the figure can be changed later.
Examples
********
These examples follow the guidelines and can be used as a reference.
The fiber context is represented in the diagram either as a box
containing different objects or a :ref:`symbol <fibers-1.svg>`.
.. _fibers-1.svg:
.. figure:: figures/fibers-1.svg
:scale: 75 %
:alt: Fibers Execution Context Symbol
The graphic representation of the fibers execution context.
This symbol is used to illustrate the actions performed by the
abstract fibers execution context.
Templates
*********
Use this template to add a figure to your documentation according to
these guidelines.
.. code-block:: rst
.. _file-name-#.ext:
.. figure:: figures/file-name-#.ext
:scale: 75%
:alt: Alternative text.
Figure 1: Brief caption detailing the contents of the image.
Any additional explanation, description or actions depicted in the
image. It can encompass multiple lines.
source/clear-linux/reference/collaboration/documentation/inline.rst
-162
View File
@@ -1,162 +0,0 @@
.. _inline:
Inline Markup
*************
Sphinx supports a large number of inline markup elements called roles. The
|CL-ATTR| documentation encourages the use of as many roles as
possible. Thus, you can use any additional roles supported by Sphinx
not listed here. Please refer to the `Sphinx reStructuredText Markup`_
documentation for the full list of supported roles.
The following markup is required in every instance unless otherwise
specified. Each item provides a syntax example followed by the rendered
result.
Abbreviations
Use the `:abbr:` abbreviation role to define an acronym or an initialism.
Add the abbreviation markup only once per file. After the abbreviation, the
acronym can be used without further definition or markup. Do not use
abbreviation markup on headings.
::
:abbr:`API (Application Program Interface)`
.. parsed-literal::
:abbr:`API (Application Program Interface)`
OS Commands
Use the `:command:` role when the name of a specific command is used in a
paragraph for emphasis. Use the ``.. code-block::`` directive for fully
actionable commands in a series of steps.
::
:command:`make`
.. parsed-literal::
:command:`make`
Commandline Options
In most cases, use asterisks "*" to emphasize the name of a command
option.
::
Use the *-p* option to print the file.
.. parsed-literal::
Use the *-p* option to print the file.
However, if you have defined an ``.. option::`` directive, you may
use the `:option:` role. Note that the result links back to the
option definition.
.. code-block:: rest
.. option: -o <output.xsl>
Description of the -o option
The :command:`pandoc` command can be used without :option:`-o`
.. option:: -o <output.xsl>
Description of the -o option
.. parsed-literal::
The :command:`pandoc` command can be used without :option:`-o`
Files
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
`{}`.
.. code-block:: rest
:file:`collaboration.rst`
:file:`doc/{user}/collaboration/figures`
.. parsed-literal::
:file:`collaboration.rst`
:file:`doc/{user}/collaboration/figures`
GUI Objects
Use the `:guilabel:` role to emphasize elements of a graphic
user interface within a description. It replaces the use of quotes
when referring to windows' names, button labels, options, or single
menu elements. Always follow the marked element with the appropriate
noun. For example:
::
In the :guilabel:`Tools` menu, click :guilabel:`settings`.
.. parsed-literal::
In the :guilabel:`Tools` menu, click :guilabel:`settings`.
Menu Navigation
Use the `:menuselection:` role to indicate the navigation through a menu
ending with a selection. Every `:menuselection:` element can have up to two
menu steps before the selected item. If more than two steps are required,
it can be combined with a `:guilabel:` or with another `:menuselection:`
element. For example:
::
Go to :guilabel:`File` and select :menuselection:`Import --> Data Base --> MySQL`.
Go to :menuselection:`Window --> View` and select :menuselection:`Perspective --> Other --> C++`
.. parsed-literal::
Go to :guilabel:`File` and select :menuselection:`Import --> Data Base --> MySQL`.
Go to :menuselection:`Window --> View` and select :menuselection:`Perspective --> Other --> C++`
Makefile Variables
Use the `:makevar:` role to emphasize the name of a Makefile variable.
The role can include only the name of the variable or the variable
plus its value.
::
:makevar:`PLATFORM_CONFIG`
:makevar:`PLATFORM_CONFIG=basic_atom`
.. parsed-literal::
:makevar:`PLATFORM_CONFIG`
:makevar:`PLATFORM_CONFIG=basic_atom`
Environment Variables
Use the `:envvar:` role to emphasize the name of environment
variables. Just as with `:makevar:`, the markup can include only the
name of the variable or the variable plus its value.
::
:envvar:`ZEPHYR_BASE`
:envvar:`QEMU_BIN_PATH=/usr/local/bin`
.. parsed-literal::
:envvar:`ZEPHYR_BASE`
:envvar:`QEMU_BIN_PATH=/usr/local/bin`
.. _Sphinx reStructuredText Markup:
http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
source/clear-linux/reference/collaboration/documentation/language.rst
-26
View File
@@ -1,26 +0,0 @@
.. _language:
Language reference guide
########################
This section describes acceptable usage of the English language in the
|CL-ATTR| documentation. It includes information about words use,
punctuation, and grammar. This guide does not replace a professional
writer's review but is intended to help collaborators submit consistent
contributions.
To make translations easier and to make the content accessible to non-native
speakers, |CL-ATTR| uses Simple English. However, we have not implemented any
controlled language standards.
.. toctree::
:maxdepth: 2
simple
grammar
punctuation
source/clear-linux/reference/collaboration/documentation/lists.rst
-112
View File
@@ -1,112 +0,0 @@
.. _lists:
Lists
#####
We use two types of lists: numbered lists and bulleted lists. Use a
numbered, or ordered, list when the order or priority of the items is
important. Use a bulleted, or unordered, list when the order of the
items is not important.
For both kinds of list, strive to keep all items in the list parallel.
See :ref:`parallelism`. Use a sentence style, making all the list items
sentences.
Numbered Lists
**************
Numbered (ordered) lists are most frequently used for procedures. Use
numbered lists to show sequence for the items. Here are some guidelines
for numbered lists:
* Make sure the list is sequential in nature and not simply a
collection of items.
* Introduce a numbered list with a sentence setup text. End the setup
fragment or sentence with a colon. Example: To configure the unit, do
the following:
* Each item in the list should be parallel.
* Without exception, treat numbered list items as full sentences and
end each list entry with a period, a colon, or a comma - when the entries
are complete sentences or a mixture of fragments and sentences. In
cases where the entries are short imperative sentences introducing
commands or code, end them with colons.
* You may interrupt numbered lists with other paragraph styles, if the
interruption is some explanatory text, commands, or code.
* Second-level steps are acceptable; avoid third-level steps.
* Avoid single-step procedures; the minimum number of steps in a
procedure is two.
* Do not create numbered lists that emulate flowcharts. The reader
should be able to execute the list of steps from first to last
without branching or looping.
* Avoid over-using numbered lists, except in procedural documents such as
tutorial and step-by-step guides.
* Use the `#` symbol for all list items. Use a three-space indentation for
second-level items and for the explanatory text, commands, or code. Example:
#. Open the door.
#. Enter the room.
The room you enter may be dark. If it is not equipped with a motion
sensor that triggers a light, you might want to turn on a light to
avoid tripping over furniture.
#. Make a call.
#. Pick up the receiver.
#. Dial a number.
#. Talk to the other party or leave a message.
#. Hang up.
#. Turn off the light.
#. Leave the room.
Bulleted Lists
**************
Use bulleted, or unordered, lists to reduce wordiness and paragraph
density, particularly when a sequence is not required. Here are some
guidelines for bulleted lists:
* Introduce a bulleted list with a sentence. End the setup text with a
colon. Example: To repair the unit, you will need the following:
* Each item in the list should complete the setup sentence staying
parallel.
* Avoid interrupting bulleted lists with other paragraph styles.
* Second-level bullets are acceptable; avoid third-level bullets.
Use sentence style bullet lists.
Sentence style bullet lists are punctuated like sentences because all
items in the list are sentences. End all bullets with a period or a
colon if the bullet introduces a second level list. For example:
**Incorrect**
When setting the user code remember:
* make the user code easy to remember. Use a number that has a meaning
for you
* change the code once a month
* do not disclose the user code to anyone else. This includes the
security company
**Correct**
When setting the user code, it is important to remember a few things:
* Use a number that has a meaning for you.
* Change the code once a month.
* Do not disclose the user code to anyone else. This includes the security
company.
Fragment style bullet lists and presentation style bullet lists are not
acceptable for either in-code documentation or stand alone
documentation. They can only be used for presentations.
Presentation style bullets have little or no punctuation. They are
typically short phrases or even single words. They often start with a
capital and end with no punctuation, unless they are full sentences.
Use only for presentations.
source/clear-linux/reference/collaboration/documentation/notices.rst
-73
View File
@@ -1,73 +0,0 @@
.. _notices:
Notices: notes, cautions, warnings, and dangers
###############################################
We use four special types of notices: notes, cautions, warnings, and
dangers. Here are some specific rules and tips with regard to these
notices:
* Do not use a notice directly after a heading. Notices must follow a
variant of body text.
* Avoid back-to-back notices.
* To improve readability, rewrite content to eliminate multiple
notices in a single module.
* If there is no clean way to avoid using back-to-back notices, use a
different style or multiple paragraphs, for example, combine two
notes into one or separate them with body text.
Notes
*****
Use notes sparingly. Avoid having more than one note per subsection. If
you exceed this number consistently, consider rewriting the notes as
main body text. Example:
.. note::
A note is supposed to provide supplemental information, not
emphasized information.
Cautions, Warnings, and Dangers
*******************************
Tell readers what will happen if they do not heed cautions or warnings,
circuits will fry, electrical shock may kill you, etc.
* Use "Caution" to identify hazards resulting in property damage
accidents, including data loss. Also use "Caution" to alert against
unsafe practices.
* Use "Warning" and "Danger" for property damage accidents only if
personal injury risk appropriate to these levels is also involved.
These are examples of typical notices, the correct syntax and the
conditions for their usage:
.. note::
Notes are ancillary bits of information, subordinate to the main
flow. Reserve the note tag for information that does not readily
flow with the main text but which you want to set apart for one
reason or another. Notes should be relatively short. If there is
more than enough information to warrant a short paragraph,
consider rewriting the note as body text.
.. caution::
Cautions are low-level hazard messages that alert the user of
possible equipment, product, and software damage, including loss
of data. Cautions typically appear as a yellow triangle with a
black exclamation point.
.. warning::
Warnings are mid-level hazards (more serious than cautions) that
are likely to cause product damage as well as bodily injury to
humans. Warnings may appear in a black triangle with orange hazard-
specific graphics for warnings (or with the colors reversed). The
most common warning is for electrical hazards, but there are many
other hazard-specific graphics.
.. danger::
Dangers are high-level hazards that are likely to cause product
damage as well as bodily injury and even death to humans. Dangers
use a red triangle with white (and black) hazard-specific
graphics, the same as found on warnings.
source/clear-linux/reference/collaboration/documentation/parallelism.rst
-32
View File
@@ -1,32 +0,0 @@
.. _parallelism:
Parallelism
###########
Parallelism refers to the practice of using similar patterns of grammar, and
sometimes length, to coordinate words, phrases, and clauses.
Parallel construction is especially important in bulleted lists. The table
shows some unparallel structures and how they can be made parallel with a
little rewording.
+----------------------------------+----------------------------------+
| Parallel (do) | Unparallel (don't) |
+==================================+==================================+
| 1. Mount the panel. | 1. Mount the panel. |
| 2. Install the battery. | 2. Battery installation. |
| 3. Wire the keypad. | 3. Wiring the keypad. |
+----------------------------------+----------------------------------+
| The system sends a message to | The system sent a message to the |
| the call center, which calls the | call center, which calls the |
| customer and tells about the | customer and will tell about the |
| burglary. | burglary. |
+----------------------------------+----------------------------------+
| The system tried to send alarm | The system tried to send alarm |
| messages that were precise and | messages that had precision and |
| accurate. | were accurate. |
+----------------------------------+----------------------------------+
| You need to install the panel, | You need to install the panel, |
| wire the sensors, and test the | wire the sensors, and you |
| phone line. | must test the phone line. |
+----------------------------------+----------------------------------+
source/clear-linux/reference/collaboration/documentation/punctuation.rst
-86
View File
@@ -1,86 +0,0 @@
.. _punctuation:
Punctuation guide
#################
This section contains all the information regarding the correct use of
punctuation for the |CL-ATTR| 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.
source/clear-linux/reference/collaboration/documentation/rest.rst
-49
View File
@@ -1,49 +0,0 @@
.. _rest:
RestructuredText guide
######################
.. incl-restructured-text-overview:
Overview
********
The |CL-ATTR| uses Sphinx and RestructuredText as authoring tools for its
documentation. This section contains the preferred methods for using the
:abbr:`ReST (RestructuredText)` markup on your documents. Please refer to the
`Sphinx documentation`_ for the complete list of available markup and use
as much markup as possible.
.. _Sphinx documentation: http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
Remember: **Changing incorrect markup is easier than adding markup from
scratch.**
We provide templates, examples, and use scenarios to help you write and edit
documents easily. Use only the templates provided to ensure your content is
consistent with the rest of the documentation.
Contributions with incorrect use of markup will not be merged until the
markup is fixed. If you have any questions regarding markup, send an email to
our mailing list at dev@lists.clearlinux.org and we will gladly help.
To allow for easy copy and paste of the provided templates,
they are provided using either the "\`\`" parenthesis, for single line
templates, or the code-block directive, for multi-lined templates.
Every use case is explained, examples provided and, lastly,
templates supplied.
.. incl-restructured-text-overview-end:
.. toctree::
:maxdepth: 3
headings
inline
tables
cross
images
code
contents
source/clear-linux/reference/collaboration/documentation/simple.rst
-305
View File
@@ -1,305 +0,0 @@
.. _simple:
Simple English
##############
Simple English is a generic term for communication that emphasizes
clarity, brevity, and avoiding unnecessarily complicated or
technical terms. It encourages writers to create content that is clear
and appropriate to the audience's reading skills and knowledge.
Simple English improves the clarity of procedural technical writing,
makes translation easier, and improves comprehension for people whose
first language is not English.
|CL-ATTR| does not use controlled language, which restricts the writer's
vocabulary to a list of approved words. However, we do strongly recommend
using the language principles described below.
Short sentences and paragraphs
******************************
Clear writing should average 15 to 20 words per sentence. This does not
mean every sentence should be the same length. Vary your writing by
mixing short sentences with longer ones, but stick to the basic
principle of one main idea in a sentence, plus one additional point if
needed.
Similarly, restrict your paragraph length to about six sentences.
Remember the basic structure of a paragraph: Introduction, body, and
conclusion. Both the introduction and the conclusion should be one
sentence long. The body of a paragraph should never exceed four
sentences. Here less is more.
Simple words
************
Choosing simple words increases reader comprehension and reduces
ambiguity. Here are some guidelines on making good simple word choices:
* Avoid jargon. Jargon is a type of language that is only understood
by a particular group of people, such as an industry or a club. You
can use jargon when writing for an audience who will understand, but
avoid over using it, especially on the general public.
* Be consistent. Use one term for each concept or action and use it
consistently. Don't use a different term for the same object or
action when you refer to it subsequently.
* Keep your style plain but avoid dullness. Avoid clichés, idioms, and
metaphors. Many of these devices are not easily understood across
different cultures and can lead to confusion.
* Avoid "fancy" words and phrases. The goal is to get the information
across, not to impress the reader with your vocabulary, so avoid
bureaucratic, flowery or literary style. Here are some examples of
"formal" words to avoid and preferred "informal" alternatives in
parentheses:
* commence (start, begin)
* consequently (so)
* in excess of (more than)
* in the event of (if)
* prior to (before)
* should you wish (if you want)
* utilize (use)
* instance (example)
Strong verbs
************
The stronger and clearer you can make your verbs, the more directly you
communicate information to your audience.
Keep these basic guidelines in mind as you check your verbs:
* Use imperatives.
* Use active voice not passive voice.
* 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 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
===========
Commands, officially called imperatives, are the fastest and most direct
way of giving someone instructions. Imperatives are an extension of the
second-person pronoun you. The word you is implied.
Be concise.
Example:
*I would appreciate it if you would send it to me.*
**Send it to me.**
Present Tense vs. Future Tense
==============================
Use simple present tense instead of future tense for most text. Future
tense is acceptable for conditional statements, for example in a
caution or a warning.
*The system will operate at a nominal temperature of 180 degrees Fahrenheit.*
**The system operates at a nominal temperature of 180 degrees Fahrenheit.**
Action Verbs vs. Nominalizations
================================
Avoid nominalizations, which are nouns formed from verbs. For example:
===================== =====================
Verbs Nominalizations
===================== =====================
complete completion
introduce introduction
provide provision
fail failure
arrange arrangement
install installation
===================== =====================
The problem with nominalizations is that they are often used instead of
the verbs they come from. Because they are merely the names of things,
they sound as if nothing is actually happening in the sentence. Like
passive verbs, too many of them make writing very dull and heavy-going.
Here are some examples.
*We had a discussion about the matter.*
**We discussed the matter.**
*The blizzard will cause a stoppage of the trains.*
**The blizzard will stop the trains.**
*IT has completed the installation of the software.*
**IT has installed the software.**
Infinitives vs. Participles
===========================
* Avoid present participial forms and gerunds, words ending in -ing,
unless they are part of a technical name.
* Use infinitives instead of participials in this type of
construction. For example:
*There is no way of verifying this.*
**There is no way to verify this.**
Active Voice vs. Passive Voice
==============================
Use active voice whenever possible to show clearly who or what is
performing an action.
* Active voice follows standard English word order:
SUBJECT–VERB–OBJECT (optional). Modifiers come before or immediately
following the terms they modify.
* Passive voice reverses the order and weakens the verb: OBJECT–be
VERB–by SUBJECT (optional).
* Writing sentences in the passive voice, we often have to use the
verb to be and sometimes the preposition "by".
Examples:
*A mistake was made.* (By whom?)
**I made a mistake.**
*The sheriff was shot by me.*
**I shot the sheriff.**
*Version 2.0 was released in June.*
**We released version 2.0 in June.**
.. note::
Sometimes it is okay to use passive voice. For example, you may
use passive voice to avoid gender-specific pronouns, to avoid
blaming someone, or to address situations where the subject, who
did the action, is unknown or irrelevant.
Noun phrases
************
Avoid long strings of nouns. Even native English speakers might have
difficulty determining which term modifies one or another in long
strings.
Similarly, avoid long noun phrases with multiple adjectives. Try to
limit the number of modifiers in any noun phrase to two terms maximum.
Often the best way to split up these long noun strings is to separate
them into digestible prepositional phrases. This tends to lengthen them
but makes them much easier to understand.
Examples of some long noun phrases and possible rewording:
*Power management mechanism integration policies*
**Integration policies for power management mechanisms**
*Signal integrity test deck requirements*
**Requirements for test desks that measure signal integrity**
*Building radon source location method*
**Method for locating the source of radon in buildings**
*Employee compensation level evaluation procedures*
**Procedures for evaluating an employee's compensation level**
Pronouns
********
First Person
============
We recommend using we or |CL|, if you want to sound more formal, to provide
an agent, someone who does the action in a sentence, and avoid passive
constructions such as "It is recommended...." For example:
*5 MB is recommended.*
**We recommend 5 MB.**
*It is recommend that you set the value as low as possible.*
**We recommend setting the value as low as possible.**
*This setting has not been validated.*
**Intel has not validated this setting.**
Second Person
=============
Write directly to the reader and use the second-person pronoun "you"
rather than "the user". For example:
*If the widget is to be compressed....*
**If you want to compress the widget...**
*If reduced costs are wanted...*
*If the user wants to reduce costs...*
**If you want to reduce costs...**
Third Person
============
Third person pronouns tend to create subject-verb agreement errors
because writers often introduce a gender-neutral third person plural
they. Rewrite these sentences using a third person plural antecedent.
Avoid third person singular pronouns, especially the gender-specific
pronouns he and she, and, if necessary, rewrite these sentences using
plurals to avoid a gender-specific references in gender-indeterminate
situations.
The preferred hierarchy of third-person pronoun usage is:
*Wrong*
*If a user needs to update their account...*
Do not use the third person plural for a singular subject.
*Avoid*
*If a user forgets her password...*
Do not force the feminine pronoun set (she) unless there is a specific,
approved feminine antecedent or there is some other very strong,
circumstantial reason to do so.
Acceptable
If a user needs to update his account...
In traditional English usage, it is acceptable to use the masculine
pronoun set (he) when the gender is neutral or indeterminate.
This is often the rule in romance languages and other languages.
**Preferred**
**If users need to update their accounts...**
Often the best solution is to use the plural form to avoid pronoun
problems.
source/clear-linux/reference/collaboration/documentation/steps.rst
-29
View File
@@ -1,29 +0,0 @@
.. _steps:
Step-by-step instructions
#########################
* Provide a sequence of numbered steps, see :ref:`lists`. Do not provide a
paragraph of sentences.
* Describe one action per step.
* If the user needs to do the same thing for several procedures, refer to
earlier steps rather than repeating them.
* When steps and diagrams flow down a page side-by-side, put text on the left
and diagrams on the right.
* When steps include commands or code blocks, put the commands or code blocks
after the step that includes them.
* If directions can appear in only one place, either text or figure, put them
in the text; don't hide directions in diagrams.
* When a series of steps is supported by one figure, refer to the figure in
the introductory text: "See Figure 15 and do the following:"
* When a series of steps is supported by two or more figures, avoid referring
to a range of figures. Rather, refer to a specific figure in the relevant
step and show the figure immediately after the reference. **Do not write**:
"See figures 15 through 22 and do the following:"
source/clear-linux/reference/collaboration/documentation/structures.rst
-17
View File
@@ -1,17 +0,0 @@
.. _structures:
Consistent content structures guide
###################################
This section guides you through the different content structures used in the
|CL-ATTR| documentation. This section serves as an example of the correct use
of markup. Refer to our :ref:`rest` to learn more about using
restructuredText to author your content.
.. toctree::
:maxdepth: 2
lists
steps
notices
parallelism
source/clear-linux/reference/collaboration/documentation/tables.rst
-106
View File
@@ -1,106 +0,0 @@
.. _tables:
Tables
######
Tables must only be used for information that is either too numerous or too
related for a list to be appropriate. The smallest acceptable table is 2x2
not counting the table header. The |CL-ATTR| uses special ReStructuredText
markup to make including tables easier. If you plan on adding a table
consider transforming it into a list before you embark on creating a table.
Follow these general guidelines:
* Use tables sparingly.
* Stick to the 72-78 characters line length limit.
* Indent the contents correctly. This allows the content to be read even if
it is not rendered.
* Only create a table if the body of the table contains six or more cells,
which is a minimum table size of at least 2x3 or 3x2.
ReST supports several types of tables. |CL| uses grid and
:abbr:`CSV-tables (Comma Separated Values tables)`. Grid tables are only
suited for very short content since they must be fully drawn. CSV-tables
support multi-lined cells, are easy to update and allow more layout
options.
Use grid tables for small tables where the layout needs to be determined
manually. For example:
+-----------------+------------------------+--------------+------------+
| Name | Purpose | Known | References |
| (or brand name) | | Applications | |
+=================+========================+==============+============+
| Super Glue | Glues things together | Small car | Quick Fix, |
| | with extra strength. | repairs. | 2010. |
+-----------------+------------------------+--------------+------------+
| Masking Tape | Stops paint from | Painting | Master |
| | covering a surface | walls. | Painter, |
| | allowing for sharp | | 2007. |
| | edges. | | |
+-----------------+------------------------+--------------+------------+
Use '=' between the table heading and the rows to define the table header. Do
not add emphasis to the contents of the table header using \*\*.
This template can help you create grid tables:
.. code-block:: rst
+------------------------+------------+----------+----------+
| Header row, column 1 | Header 2 | Header 3 | Header 4 |
| (header rows optional) | | | |
+========================+============+==========+==========+
| body row 1, column 1 | column 2 | column 3 | column 4 |
+------------------------+------------+----------+----------+
| body row 2 | ... | ... | |
+------------------------+------------+----------+----------+
CSV-tables are more flexible than grid tables. They can be updated easily and
support several layout options. For example:
.. csv-table:: Frozen Delights!
:header: "Treat", "Quantity", "Description"
:widths: 15, 10, 30
"Albatross", 2.99, "On a stick!"
"Crunchy Frog", 1.49, "If we took the bones out, it wouldn't be
crunchy, now would it?"
"Gannet Ripple", 1.99, "On a stick!"
Some of the options available with CSV-tables are table titles, an optional
header row separate from the rest of the table, and customizable column width.
See the Sphinx `CSV-tables documentation`_ to learn all the possible options
available.
This template can help you create CSV-tables:
.. code-block:: rst
.. csv-table:: Table title (optional)
:header: The header, values, for each column
:widths: 15, 10, 30
If the values, in the, "table go beyond the line length, use quotes to
keep the content together."
Numbers like, 10, are never surrounded by quotes.
Text can, "be", in quotes but it is only needed for longer lines.
The template renders as:
.. csv-table:: Table title (optional)
:header: The header, values, for each column
:widths: 15, 10, 30
If the values, in the, "table go beyond the line length, use quotes to keep
the content together."
Numbers like, 10, are never surrounded by quotes.
Text can, "be", in quotes but it is only needed for longer lines.
.. _CSV-tables documentation:
http://docutils.sourceforge.net/docs/ref/rst/directives.html#csv-table
source/clear-linux/reference/collaboration/structure-formatting.rst
+482
View File
@@ -0,0 +1,482 @@
.. _structure-formatting:
Structure and formatting
########################
Content should be organized to support scanning. Consistent organization,
formatting, and writing style helps readers quickly find what they need and to
understand the content more effectively. This document describes our
organization and formatting guidelines.
Refer to :ref:`writing-guide` to learn how we keep our documents clear and
concise.
.. contents:: :local:
:depth: 1
Markup
******
Our documentation is written in the reStructuredText markup language, using
Sphinx roles and directives. We use Sphinx to generate the final documentation.
You can read more about reStructuredText and Sphinx on their respective
websites:
* `Sphinx documentation`_
* `reStructuredText Primer`_
You can view the content directly in the .rst markup files, or generate the HTML
content by installing and building the documentation locally. To run the
documentation locally, follow the instructions found in the
`documentation repository`_ README.
New pages
=========
There are a few additional steps to consider when adding a new page to the
documentation. First, identify where your new page should be located within the
existing `Documentation organization`_. Second, make sure the new page is picked
up in the Sphinx build and easily linkable from other content.
Each page must be included in a `Sphinx toctree`_ in order to be included in the
documentation content tree. Typically, pages are added to the section landing
page toctree.
For example, the :ref:`collaboration` page toctree looks like:
.. code-block:: rest
.. toctree::
:maxdepth: 1
writing-guide
structure-formatting
Additionally, each page must include a uniquely named reST label directly before
the page title, to enable the `Sphinx ref role`_ for linking to a page.
For example, this page "Structure and formating" has the label
``.. _structure-formatting``:
.. code-block:: rest
.. _structure-formatting:
Structure and formatting
########################
This page can then be referenced from other pages in the documentation using the
`:ref:` role:
.. code-block:: rest
:ref:`structure-formatting`
Documentation organization
**************************
The documentation is organized into five general sections:
#. **Concepts**: Introduction and overview of |CL| specific concepts or
features.
#. **Get started**: Information about getting started with |CL|.
#. **Guides**: Detailed information and instruction on using |CL| features.
#. **Tutorials**: Step-by-step instruction for using |CL| in specific use cases.
#. **Reference**: Supplementary and reference information for |CL|.
Page structure
==============
Each page in the documentation should follow the basic format of:
* Overview: 1-2 sentences describing what this page shows and why it matters
* Prerequisites: Describe any pre-work necessary to the content (if appropriate)
* Content
* Next steps: List links to next steps (if appropriate)
* Related topics: List links to related content (if appropriate)
Headings
========
Use headings to section and organize your content for better readability and
clarity.
* All files must have a top level heading, which is the title for the page.
* Up to three additional levels of headings are allowed under the title heading.
* Each heading should be followed by at least one paragraph of content. Avoid
two or more consecutive headings.
Refer to the :ref:`writing-guide` for tips on using headings to create
:ref:`scannable content <scannable-content>`.
To mark up headings in the .rst file:
* Use hash-tags to underline the file's main title:
.. code-block:: rest
Main title
##########
* Use asterisks to underline the file's first level headings:
.. code-block:: rest
First level heading
*******************
* Use equal signs to underline the file's second level of headings:
.. code-block:: rest
Second level heading
====================
* Use dashes to underline the file's third level of headings:
.. code-block:: rest
Third level heading
-------------------
In-page navigation
==================
If a page has three or more sections, provide quick links to each section. Place
the quick links after the overview section.
Use the standard `reST contents directive`_ with depth: 1 for quick links.
Inline text formatting
**********************
We use the `Microsoft Writing Style Guide`_ as our starting point for text
formatting. We apply the formatting using reST and Sphinx markup.
Use our quick reference for the most commonly used inline text elements:
+--------------------------------+---------------------------------------+-----------------------------+
| **Element** | **Convention** | **reST/Sphinx** |
+--------------------------------+---------------------------------------+-----------------------------+
| Acronyms | Define acronym when first used. After | Use the ``:abbr:`` role, in |
| | first use and definition, use the | the following format: |
| | acronym only. | |
| | | ``:abbr:`Acronym (Def)``` |
+--------------------------------+---------------------------------------+-----------------------------+
| Bundle names | Bold | Use the ``:command:`` role. |
+--------------------------------+---------------------------------------+-----------------------------+
| Callouts | | Use ``.. note::`` |
+--------------------------------+---------------------------------------+-----------------------------+
| Code/command examples | Monospace, visually distinct | Use ``.. code-block::`` |
| | from rest of text. Use an | with the correct language |
| | indented call-out box. | setting. |
+--------------------------------+---------------------------------------+-----------------------------+
| Commands | Bold | Use the ``:command:`` role. |
+--------------------------------+---------------------------------------+-----------------------------+
| Command flags | Bold | Use the ``:command:`` role. |
+--------------------------------+---------------------------------------+-----------------------------+
| Console output | Monospace, visual distinction | Use ``.. code-block::`` |
| | from rest of text. Use an | with console as the |
| | indented call-out box. | language setting. |
+--------------------------------+---------------------------------------+-----------------------------+
| Emphasis | Italic | ``*strong*`` |
+--------------------------------+---------------------------------------+-----------------------------+
| Environment variables | Use the case format of the | Use ``:envvar:`` |
| | environment variable. | |
+--------------------------------+---------------------------------------+-----------------------------+
| Example commands with | Use angle brackets for swapping | |
| optional or replaceable | in the specific name, | |
| parts | e.g. <package-name>. | |
| | | |
| | Use square brackets for optional | |
| | parts, | |
| | e.g. [--build]. | |
+--------------------------------+---------------------------------------+-----------------------------+
| Example URLs (not linked) | Plain text | |
+--------------------------------+---------------------------------------+-----------------------------+
| File extensions | Lowercase | |
+--------------------------------+---------------------------------------+-----------------------------+
| File names, directories, paths | Title style capitalization | Use the ``:file:`` role. |
+--------------------------------+---------------------------------------+-----------------------------+
| GUI labels | | Use ``:guilabel:`` |
+--------------------------------+---------------------------------------+-----------------------------+
| Inline comments | | Use ``..`` |
+--------------------------------+---------------------------------------+-----------------------------+
| Keystrokes | | Use ``:kbd:`` |
+--------------------------------+---------------------------------------+-----------------------------+
| Local navigation | | ``.. contents:: :local:`` |
| | | with a depth of 1 |
+--------------------------------+---------------------------------------+-----------------------------+
| Menu selection | | Use ``:menuselection:`` |
+--------------------------------+---------------------------------------+-----------------------------+
| New terms | Italic for first use, normal for all | ``*term*`` |
| | subsequent uses. | |
| | | |
| | If it is used outside of the source | |
| | of definition, link the term. | |
+--------------------------------+---------------------------------------+-----------------------------+
| Product name | Follow correct trademark and | |
| | attribution guidelines. | |
+--------------------------------+---------------------------------------+-----------------------------+
| Tool names | Correctly capitalized, no quotes, | |
| | bold, or italics as the basic rule. | |
| | | |
| | If the tool name is the command, like | |
| | most Linux tools, treat it like a | |
| | command. | |
| | | |
| | If the tool name is lowercase and | |
| | used at the start of a sentence, use | |
| | bold. | |
+--------------------------------+---------------------------------------+-----------------------------+
White space and line length
===========================
Limit line length to 78 characters. The GitHub web interface forces this
limitation for readability.
Remove trailing whitespace from your documents.
Code blocks and examples
************************
When providing example code or commands use the `Sphinx code-block directive`_.
Select the appropriate syntax highlighting for the example command or code.
For example, if showing console output, use console highlighting:
.. code-block:: rest
.. code-block:: console
Sphinx provides other ways of `marking up example code`_ if needed.
Lists and instructions
**********************
Use a numbered list when the order or priority of the items is important, such
as step-by-step instructions.
Use a bulleted list when the order of the items is not important.
For both list types, keep all items in the list parallel. See
:ref:`parallelism`.
Use standard `reST list markup`_.
Numbered lists
==============
Numbered lists are most frequently used for procedures. Use numbered lists to
show sequence for the items. Follow our guidelines for numbered lists:
* Make sure the list is sequential and not just a collection of items.
* Introduce a numbered list with a sentence. End the setup text with a
colon. Example: "To configure the unit, perform the following steps:"
* Each item in the list should be parallel.
* Treat numbered list items as full sentences with correct ending
punctuation.
* You may interrupt numbered lists with other content, if relevant,
e.g. explanatory text, commands, or code.
* Second-level steps are acceptable; avoid third-level steps.
* Avoid single-step procedures; the minimum number of steps in a procedure
is two.
* Do not create numbered lists that emulate flowcharts. The reader should be
able to execute the list of steps from first to last without branching or
looping.
* Avoid over-using numbered lists, except in procedural documents such as
tutorials and step-by-step guides.
Bulleted lists
==============
Use bulleted lists to reduce wordiness and paragraph density, especially when
a sequence is not required. Here are some guidelines for bulleted lists:
* Introduce a bulleted list with a sentence. End the setup text with a
colon. Example: "To repair the unit, you will need the following items:"
* Each item in the list should be parallel.
* Avoid interrupting bulleted lists with other paragraph styles.
* Second-level bullets are acceptable; avoid third-level bullets.
Use the correct ending punctuation for sentence style bullet lists. For example:
**Use this:**
::
When setting the user code, remember:
* Use a number that has a meaning for you.
* Change the code once a month.
* Do not disclose the user code to anyone, including the security company.
**Not this:**
::
When setting the user code remember:
* make the user code easy to remember. Use a number that has a meaning for you
* change the code once a month
* do not disclose the user code to anyone else. This includes the security
company
Instructions
============
When presenting instructions, such as in a tutorial, present them in a numbered
list according to these guidelines:
* Each step (list item) should describe one action.
* If the same steps are repeated, refer to the earlier steps rather than
repeating them.
* When a step includes a command or code block as an example, put the command
or code block after the step that includes them.
* Use supporting images where appropriate. If the series of steps is supported
by one figure, refer to the figure in the introductory text.
For example: "See Figure 15 and do the following:"
When a series of steps is supported by two or more figures, refer to the
specific figure in the relevant step and show the figure immediately after
the reference. **Do not write**: "See figures 15 through 22 and do the
following:"
Notices
*******
We use four special types of notices: notes, cautions, warnings, and dangers.
Here are some specific rules and tips regarding use of these notices:
* Do not use a notice directly after a heading. Notices must follow a variant of
body text.
* Do not include more than one notice in a single notice block.
* Avoid back-to-back notices.
* If back-to-back notices are not avoidable, make sure each distinct notice in
the notice block is clearly defined.
Use the standard `reST admonition directive`_.
Notes, cautions, and warnings
=============================
Use notes sparingly. Avoid having more than one note per section. If you exceed
this number consistently, consider rewriting the notes as main body text.
Use cautions and warnings to alert readers of potential problems or pitfalls.
Use conditional phrases in cautions and warnings, such as "If you do X, then Y
will occur."
These are examples of typical notices and the conditions for their usage:
.. note::
Notes are extra bits of information that supplement the main content. Notes
should be relatively short.
.. caution::
Cautions are low-level hazard messages that alert the user of possible
equipment, product, and software damage, including loss of data.
.. warning::
Warnings are mid-level hazards that are likely to cause product damage.
Links
*****
Use the standard `reST markup for links`_.
To add a cross-reference to another documentation page, use the `:ref:` role:
.. code-block:: rest
:ref:`structure-formatting`
To add an external link, we use named references that refer to a defined
link/label at the bottom of the page.
For example, an external link is defined at the bottom of the page like this:
.. code-block:: rest
.. _wiki about dogs: https://en.wikipedia.org/wiki/Dog
The defined link is then used in the content like this:
.. code-block:: rest
Check out the great `wiki about dogs`_.
Images
******
Use images or figures to convey information that may be difficult to explain
using words alone. Well-planned graphics reduce the amount of text required to
explain a topic or example.
Follow these guidelines when using graphics in support of your documentation:
* Keep it simple. Use images that serve a specific purpose in your document,
and contain only the information the reader needs.
* Avoid graphics that will need frequent updating. Don't include information in
a graphic that might change with each release, such as product versions.
* Use either PNG or JPEG bitmap files for screenshots and SVG files for vector
graphics.
* Place the image immediately after the text it helps clarify, or as close as
possible.
* Use the `Sphinx figure directive`_ to insert images and figures into the
document. Include both alt text, a figure name, and caption.
For example:
.. code-block:: rest
.. figure:: figures/topic-1.png
:alt: An image supporting the topic.
Figure 1: This is the figure 1 caption.
* Include at least one direct reference to an image from the main text, using
the figure number. For example:
**Use this:** ::
Figure 1
**Not this:** ::
The figure above or below
Images should follow these naming and location conventions:
* Save the image files in a :file:`figures` folder at the same level as the file
that will reference the image.
* Name image files according to the following rules:
* Use only lower case letters.
* Separate multiple words in filenames using dashes.
* Name images using the filename of the file they appear on and add a number
to indicate their place in the file. For example, the third figure added to
the :file:`welcome.rst` file must be named :file:`welcome-3.png`.
.. _Sphinx documentation: http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
.. _reStructuredText Primer: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
.. _documentation repository: https://github.com/clearlinux/clear-linux-documentation
.. _Sphinx toctree: https://www.sphinx-doc.org/en/master/usage/quickstart.html?highlight=toctree#defining-document-structure
.. _Sphinx ref role: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref
.. _reST contents directive: http://docutils.sourceforge.net/docs/ref/rst/directives.html#table-of-contents
.. _Microsoft Writing Style Guide: https://docs.microsoft.com/en-us/style-guide/welcome/
.. _Sphinx code-block directive: http://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block
.. _marking up example code: http://www.sphinx-doc.org/en/1.6/markup/code.html
.. _reST list markup: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#lists-and-quote-like-blocks
.. _reST admonition directive: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#directives
.. _reST markup for links: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#hyperlinks
.. _Sphinx figure directive: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#directives
source/clear-linux/reference/collaboration/writing-guide.rst
+410
View File
@@ -0,0 +1,410 @@
.. _writing-guide:
Writing guide
#############
We want our documentation to be easy to read and understand. This document
describes guidelines for writing documentation that is clear, concise,
confident, and courteous.
Refer to :ref:`structure-formatting` for details on organizing content and how
we use reStructuredText and Sphinx.
.. contents:: :local:
:depth: 1
Use simple English
******************
Write using simple English: Be brief and communicate only the information that
is needed. Be friendly and informative. Emphasize clarity and avoid
unecessary complicated or technical terms. Make the content accessible to
non-native speakers.
Be brief
========
Use short sentences and paragraphs. Stick to the principle of one main
idea per sentence, plus one additional point if needed. Each paragraph
should address one main idea. Remember the basic structure of a paragraph:
Introduction, body, and conclusion.
Be friendly
===========
We write for our peers and want to be familiar. Take a personal tone as if you
were speaking directly to the reader. Use "you" to address the reader and "we"
to refer to our view. Be professional, respectful, and cooperative.
Assume your audience has the same level of technical understanding and expertise
as you did when you first started collaborating. Do not talk down to our
readers, but also do not assume they know everything about the subject. Offer
brief explanations or summaries of common knowledge if a significant portion of
readers might benefit.
Use simple words
================
Use simple words to increase reader comprehension and reduce ambiguity. Follow
our tips for making good word choices:
* **Avoid jargon**: Write for your audience, using everyday language where
possible, and technical terms where appropriate. Avoid clichés, idioms, and
metaphors.
* **Be consistent**: Use one term for each concept or action and use it
consistently.
* **Avoid "fancy" words and phrases**: If there is a simpler word or phrase,
use it.
For example:
=================== ===================
Use this Not this
=================== ===================
start, begin commence
so consequently
more than in excess of
if in the event of
before prior to
if you want should one wish
use utilize
example instance
=================== ===================
Avoid overuse of product name
=============================
Use product names only when necessary. Typically, you can rewrite sentences to
remove the product name with no change in meaning, which keeps the content
concise and scannable.
Avoid using the product name in page titles and headings.
.. _scannable-content:
Make content scannable
**********************
Organize your content to make it scannable for the reader, which helps them find
what they need quickly, and to understand the information more efficiently.
* **Put the most important content first.** Make sure your introduction clearly
communicates what the reader can find on the page. Present the point of the
document first, and organize supporting information towards the end of the
page.
* **Write scannable headings.** Expect readers of documentation to skim and scan
the content, and to leave if they dont find what they need quickly. Good
headings add organization to your content and help the reader to find and
understand content more effectively. Follow our guidelines for writing
effective `Headings`_.
* **Write great link text.** Great link text tells the reader what they can
expect when they click on a link. It also helps make the page more scannable.
Follow our guidelines for writing `Link text`_.
Headings
========
Use these guidelines to write effective headings:
* **Be concise and descriptive.** Use only the words necessary to describe the
section.
* **Use sentence case.** Capitalize only the first word and proper nouns in a
heading.
* **Avoid punctuation.** Unless your heading is a question, don't use sentence
punctuation in headings.
* **Use parallel structure.** Headings at the same level should use the same
grammatical pattern. This provides structure to the document and helps users
find information more easily. See :ref:`parallelism`.
* **Use strong verbs.** Strong, active verbs get to the point. Avoid -ing verbs,
such as *Running*, *Testing*, etc.
For example, two headings at the same level:
**Use this:** ::
Install software
Configure software
**Not this:** ::
Installing the Software on the Platform
Software Configuration.
Link text
=========
All links in content should follow these guidelines:
* **Write descriptive link text**: Link text should describe where the link
goes, without having to read the surrounding text.
* **Keep link text concise**: Use only the words needed to accurately describe
the destination.
* **Use unique link text**: Each link on a page should be unique. If users see
the same link text twice on a page, they'll assume it goes to the same place.
* **Start link text with keywords**: Frontload the link text with the most
important words to help users scan the text.
* **Avoid generic text**: Don't use generic, uninformative link text such as
"click here" or "read more".
For example:
**Use this:** ::
For more information about dogs, read the `dog wiki article`_.
**Not this:** ::
For more information about dogs, `click here`_.
Use strong verbs
****************
Passive verbs make writing stuffy and formal. Use strong verbs to get to the
point and avoid unnecessary words and phrases.
Use imperatives
===============
Commands, also called imperatives, are the fastest and most direct way of giving
someone instructions. For example:
**Use this:** ::
Send it to me.
**Not this:** ::
I would appreciate it if you would send it to me.
Use present tense
=================
Use simple present tense instead of future tense for most text. Search for the
words "will" or "shall" to find future tense instances. Future tense is
acceptable for conditional statements, such as in a caution or a warning. For
example:
**Use this:** ::
The system operates at a nominal temperature of 180 degrees Fahrenheit.
**Not this:** ::
The system will operate at a nominal temperature of 180 degrees Fahrenheit.
Avoid nominalizations
=====================
Avoid nominalizations, which are nouns formed from verbs.
For example:
===================== =====================
Verb Nominalization
===================== =====================
complete completion
provide provision
fail failure
install installation
===================== =====================
For example:
**Use this:** ::
We discussed the matter.
**Not this:** ::
We had a discussion about the matter.
Or:
**Use this:** ::
IT has installed the software.
**Not this:** ::
IT has completed the installation of the software.
Avoid words ending in -ing
==========================
Avoid using words ending in -ing unless they are part of a technical name. For
example:
**Use this:** ::
There is no way to verify this.
**Not this:** ::
There is no way of verifying this.
Use the active voice
====================
Use active voice whenever possible to show who or what is performing an
action.
* Active voice follows standard English word order: SUBJECT–VERB–OBJECT
(where the OBJECT is optional).
* Passive voice reverses the order and weakens the verb: OBJECT–be VERB–by
SUBJECT (where the OBJECT is optional).
For example:
**Use this:** ::
I made a mistake.
**Not this:** ::
A mistake was made. *(By whom?)*
Or:
**Use this:** ::
We released version 2.0 in June.
**Not this:** ::
Version 2.0 was released in June.
Avoid long noun phrases
***********************
Noun phrases (a noun and other words that describe or modify it) can be
difficult to understand. Try to limit the number of modifiers in a noun phrase
to two. For example:
**Use this:** ::
Integration policies for power management mechanisms.
**Not this:** ::
Power management mechanism integration policies.
.. _parallelism:
Parallelism
***********
Parallelism refers to the practice of using similar patterns of grammar, and
sometimes length, to coordinate words, phrases, and clauses.
Use parallel construction in lists. The table below shows some unparallel
structures and how they can be made parallel with a little rewording.
+----------------------------------+----------------------------------+
| Parallel (do) | Unparallel (don't) |
+==================================+==================================+
| 1. Mount the panel. | 1. Mount the panel. |
| 2. Install the battery. | 2. Battery installation. |
| 3. Wire the keypad. | 3. Wiring the keypad. |
+----------------------------------+----------------------------------+
| I like practicing my accordion, | I like practicing my accordion, |
| reading sci-fi, and eating | reading sci-fi, and to eat |
| peanut butter and pickle | peanut butter and pickle |
| sandwiches. | sandwiches. |
+----------------------------------+----------------------------------+
| For breakfast he likes coffee | For breakfast he likes coffee |
| and bacon. | and to fry bacon. |
+----------------------------------+----------------------------------+
| Apples or bananas are a good | Apples or a banana are a good |
| snack. | snack. |
+----------------------------------+----------------------------------+
Grammar and punctuation
***********************
This section covers common grammatical topics relevant to our
documentation. For detailed explanations of correct grammar and punctuation,
use one of our :ref:`preferred references <references>`.
Capitalization
==============
The capitalization style for all documentation is sentence case. Words should
only be capitalized when they are proper nouns or refer to trademarked product
names.
.. note::
Do not capitalize a word to indicate it is more important than other
words. Never change the case of variable, function or file names - always
keep the original case.
Menu capitalization
-------------------
When referring to software menu items by name, use the same capitalization as
seen in the actual menu.
A few other tips when referring to menu items:
* Reference the specific menu item using "Select :menuselection:`File --> New`."
* Put the option to be selected last. "Select
: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, divide the steps using
``:guilabel:`` or ``:menuselection:``.
For example: "Go to :guilabel:`File` and select
:menuselection:`Print --> Print Preview --> Set Up`."
Software version capitalization
-------------------------------
When listing software or hardware version numbers, the word “version” or letter
"v" are lowercase. The v is closed with the number (no period).
For example:
* Widget Pro version 5.0
* Widget Master v2.1.12
Contractions
============
Avoid using contractions, such as it's, they're, and you're, because they may be
unclear to non-native English-speaking audiences.
Quotation marks
===============
Follow these guidelines for quotation marks:
* Restrict use of quotation marks to terms as terms.
* Do not use quotation marks for emphasis; use *italics* for emphasis.
* Avoid using single-quote marks.
Commas and colons
=================
This section addresses common use of commas, semicolons, and colons in our
documentation. Refer to one of our :ref:`preferred references <references>`
for further details.
Use the serial comma
--------------------
When writing a series of items, use the serial comma before the final *and* and
*or* to avoid confusion and ambiguity. For example:
**Use this:** ::
Mom, Dad, and I are going to the game.
**Not this:** ::
Mom, Dad and I are going to the game.
.. _click here: https://en.wikipedia.org/wiki/Dog
.. _dog wiki article: https://en.wikipedia.org/wiki/Dog