diff --git a/README.rst b/README.rst index 83cf1266..ab37040d 100644 --- a/README.rst +++ b/README.rst @@ -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 + diff --git a/source/clear-linux/reference/collaboration/collaboration.rst b/source/clear-linux/reference/collaboration/collaboration.rst index 341d5c91..fb7b5369 100644 --- a/source/clear-linux/reference/collaboration/collaboration.rst +++ b/source/clear-linux/reference/collaboration/collaboration.rst @@ -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. + Structure and formatting guide: Explains how we organize and format content, using reStructuredText and Sphinx. + +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/ \ No newline at end of file diff --git a/source/clear-linux/reference/collaboration/documentation/basic.rst b/source/clear-linux/reference/collaboration/documentation/basic.rst deleted file mode 100644 index 021c345b..00000000 --- a/source/clear-linux/reference/collaboration/documentation/basic.rst +++ /dev/null @@ -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 diff --git a/source/clear-linux/reference/collaboration/documentation/code.rst b/source/clear-linux/reference/collaboration/documentation/code.rst deleted file mode 100644 index 870faeba..00000000 --- a/source/clear-linux/reference/collaboration/documentation/code.rst +++ /dev/null @@ -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. - diff --git a/source/clear-linux/reference/collaboration/documentation/contents.rst b/source/clear-linux/reference/collaboration/documentation/contents.rst deleted file mode 100644 index 248053b4..00000000 --- a/source/clear-linux/reference/collaboration/documentation/contents.rst +++ /dev/null @@ -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 diff --git a/source/clear-linux/reference/collaboration/documentation/cross.rst b/source/clear-linux/reference/collaboration/documentation/cross.rst deleted file mode 100644 index 6780dde1..00000000 --- a/source/clear-linux/reference/collaboration/documentation/cross.rst +++ /dev/null @@ -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 `. - -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 ` 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 ` 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 ` -* 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/ diff --git a/source/clear-linux/reference/collaboration/documentation/documentation.rst b/source/clear-linux/reference/collaboration/documentation/documentation.rst deleted file mode 100644 index 15056a84..00000000 --- a/source/clear-linux/reference/collaboration/documentation/documentation.rst +++ /dev/null @@ -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`, and :ref:`consistent content`. Our -documentation is written using ReStructuredText and we provide -:ref:`examples, templates, and best practices` 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 diff --git a/source/clear-linux/reference/collaboration/documentation/figures/fibers-1.svg b/source/clear-linux/reference/collaboration/documentation/figures/fibers-1.svg deleted file mode 100644 index 288b2ca9..00000000 --- a/source/clear-linux/reference/collaboration/documentation/figures/fibers-1.svg +++ /dev/null @@ -1,165 +0,0 @@ - - - - - - - - - - image/svg+xml - - - - - - - - - - - - - - - - - - - - - - - - - - - Fibers - - - - diff --git a/source/clear-linux/reference/collaboration/documentation/grammar.rst b/source/clear-linux/reference/collaboration/documentation/grammar.rst deleted file mode 100644 index 037ec965..00000000 --- a/source/clear-linux/reference/collaboration/documentation/grammar.rst +++ /dev/null @@ -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. \ No newline at end of file diff --git a/source/clear-linux/reference/collaboration/documentation/headings.rst b/source/clear-linux/reference/collaboration/documentation/headings.rst deleted file mode 100644 index 6f1d584d..00000000 --- a/source/clear-linux/reference/collaboration/documentation/headings.rst +++ /dev/null @@ -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`. diff --git a/source/clear-linux/reference/collaboration/documentation/hello.c b/source/clear-linux/reference/collaboration/documentation/hello.c deleted file mode 100644 index 079db353..00000000 --- a/source/clear-linux/reference/collaboration/documentation/hello.c +++ /dev/null @@ -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 -#define PRINT printf -#else -#include -#define PRINT printk -#endif - -#ifdef CONFIG_MICROKERNEL - -#include - -#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 -#include - -#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 diff --git a/source/clear-linux/reference/collaboration/documentation/images.rst b/source/clear-linux/reference/collaboration/documentation/images.rst deleted file mode 100644 index c631f15d..00000000 --- a/source/clear-linux/reference/collaboration/documentation/images.rst +++ /dev/null @@ -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: - -.. 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. diff --git a/source/clear-linux/reference/collaboration/documentation/inline.rst b/source/clear-linux/reference/collaboration/documentation/inline.rst deleted file mode 100644 index a4ccfe91..00000000 --- a/source/clear-linux/reference/collaboration/documentation/inline.rst +++ /dev/null @@ -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 - - Description of the -o option - - The :command:`pandoc` command can be used without :option:`-o` - - .. option:: -o - - 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 \ No newline at end of file diff --git a/source/clear-linux/reference/collaboration/documentation/language.rst b/source/clear-linux/reference/collaboration/documentation/language.rst deleted file mode 100644 index ba2abe49..00000000 --- a/source/clear-linux/reference/collaboration/documentation/language.rst +++ /dev/null @@ -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 - - - - - diff --git a/source/clear-linux/reference/collaboration/documentation/lists.rst b/source/clear-linux/reference/collaboration/documentation/lists.rst deleted file mode 100644 index 6f43ec77..00000000 --- a/source/clear-linux/reference/collaboration/documentation/lists.rst +++ /dev/null @@ -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. diff --git a/source/clear-linux/reference/collaboration/documentation/notices.rst b/source/clear-linux/reference/collaboration/documentation/notices.rst deleted file mode 100644 index e58cbb83..00000000 --- a/source/clear-linux/reference/collaboration/documentation/notices.rst +++ /dev/null @@ -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. \ No newline at end of file diff --git a/source/clear-linux/reference/collaboration/documentation/parallelism.rst b/source/clear-linux/reference/collaboration/documentation/parallelism.rst deleted file mode 100644 index 611cd5e4..00000000 --- a/source/clear-linux/reference/collaboration/documentation/parallelism.rst +++ /dev/null @@ -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. | -+----------------------------------+----------------------------------+ diff --git a/source/clear-linux/reference/collaboration/documentation/punctuation.rst b/source/clear-linux/reference/collaboration/documentation/punctuation.rst deleted file mode 100644 index f019b1c3..00000000 --- a/source/clear-linux/reference/collaboration/documentation/punctuation.rst +++ /dev/null @@ -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. diff --git a/source/clear-linux/reference/collaboration/documentation/rest.rst b/source/clear-linux/reference/collaboration/documentation/rest.rst deleted file mode 100644 index a64f6a78..00000000 --- a/source/clear-linux/reference/collaboration/documentation/rest.rst +++ /dev/null @@ -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 - diff --git a/source/clear-linux/reference/collaboration/documentation/simple.rst b/source/clear-linux/reference/collaboration/documentation/simple.rst deleted file mode 100644 index b8ea9773..00000000 --- a/source/clear-linux/reference/collaboration/documentation/simple.rst +++ /dev/null @@ -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. diff --git a/source/clear-linux/reference/collaboration/documentation/steps.rst b/source/clear-linux/reference/collaboration/documentation/steps.rst deleted file mode 100644 index 9301e570..00000000 --- a/source/clear-linux/reference/collaboration/documentation/steps.rst +++ /dev/null @@ -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:" \ No newline at end of file diff --git a/source/clear-linux/reference/collaboration/documentation/structures.rst b/source/clear-linux/reference/collaboration/documentation/structures.rst deleted file mode 100644 index 04cf1bc7..00000000 --- a/source/clear-linux/reference/collaboration/documentation/structures.rst +++ /dev/null @@ -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 diff --git a/source/clear-linux/reference/collaboration/documentation/tables.rst b/source/clear-linux/reference/collaboration/documentation/tables.rst deleted file mode 100644 index 814de470..00000000 --- a/source/clear-linux/reference/collaboration/documentation/tables.rst +++ /dev/null @@ -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 \ No newline at end of file diff --git a/source/clear-linux/reference/collaboration/structure-formatting.rst b/source/clear-linux/reference/collaboration/structure-formatting.rst new file mode 100644 index 00000000..6391dccb --- /dev/null +++ b/source/clear-linux/reference/collaboration/structure-formatting.rst @@ -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 `. + +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. . | | +| | | | +| | 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 diff --git a/source/clear-linux/reference/collaboration/writing-guide.rst b/source/clear-linux/reference/collaboration/writing-guide.rst new file mode 100644 index 00000000..f69a0344 --- /dev/null +++ b/source/clear-linux/reference/collaboration/writing-guide.rst @@ -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 `. + +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 ` +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