diff --git a/source/clear-linux/reference/collaboration/collaboration.rst b/source/clear-linux/reference/collaboration/collaboration.rst new file mode 100644 index 00000000..09852e15 --- /dev/null +++ b/source/clear-linux/reference/collaboration/collaboration.rst @@ -0,0 +1,18 @@ +.. _collaboration: + +Collaboration guidelines +######################## + +Thank you for your interest in collaborating with the |CLOSIA|. This guide +details the best ways to communicate and 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. + +.. toctree:: + :maxdepth: 1 + + + documentation/documentation diff --git a/source/clear-linux/reference/collaboration/documentation/basic.rst b/source/clear-linux/reference/collaboration/documentation/basic.rst new file mode 100644 index 00000000..021c345b --- /dev/null +++ b/source/clear-linux/reference/collaboration/documentation/basic.rst @@ -0,0 +1,130 @@ +.. _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 new file mode 100644 index 00000000..9490e75b --- /dev/null +++ b/source/clear-linux/reference/collaboration/documentation/code.rst @@ -0,0 +1,161 @@ +.. _code: + +Code blocks +########### + +Collaborating to the |CLOSIA| 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/cross.rst b/source/clear-linux/reference/collaboration/documentation/cross.rst new file mode 100644 index 00000000..8b4d726d --- /dev/null +++ b/source/clear-linux/reference/collaboration/documentation/cross.rst @@ -0,0 +1,124 @@ +.. _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 |CLOSIA| +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 identical to the file's name in order +to be able to add cross-references without having to open the file. + +The labels' naming conventions are: + +* Use only full words. + +* Use \- to link multiple words. + +* Use only as many words as necessary to ensure the label is unique. + +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. + +.. 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. + + .. _Oregon: http://traveloregon.com/ diff --git a/source/clear-linux/reference/collaboration/documentation/documentation.rst b/source/clear-linux/reference/collaboration/documentation/documentation.rst new file mode 100644 index 00000000..b16ce41b --- /dev/null +++ b/source/clear-linux/reference/collaboration/documentation/documentation.rst @@ -0,0 +1,138 @@ +.. _documentation: + +Documentation contribution guidelines +##################################### + +The |CLOSIA| 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: 2 + + 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. Use our +:ref:`bug-report` to submit the bug. + +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 :ref:`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 :ref:`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 diff --git a/source/clear-linux/reference/collaboration/documentation/figures/fibers-1.svg b/source/clear-linux/reference/collaboration/documentation/figures/fibers-1.svg new file mode 100644 index 00000000..288b2ca9 --- /dev/null +++ b/source/clear-linux/reference/collaboration/documentation/figures/fibers-1.svg @@ -0,0 +1,165 @@ + + + + + + + + + + image/svg+xml + + + + + + + + + + + + + + + + + + + + + + + + + + + Fibers + + + + diff --git a/source/clear-linux/reference/collaboration/documentation/grammar.rst b/source/clear-linux/reference/collaboration/documentation/grammar.rst new file mode 100644 index 00000000..938f0eb2 --- /dev/null +++ b/source/clear-linux/reference/collaboration/documentation/grammar.rst @@ -0,0 +1,342 @@ +.. _grammar: + +Grammar guide +############# + +This guide provides valuable insight into the correct grammar for the +|CLOSIA| 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 new file mode 100644 index 00000000..916299a3 --- /dev/null +++ b/source/clear-linux/reference/collaboration/documentation/headings.rst @@ -0,0 +1,30 @@ +.. _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 |CLOSIA| 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 new file mode 100644 index 00000000..079db353 --- /dev/null +++ b/source/clear-linux/reference/collaboration/documentation/hello.c @@ -0,0 +1,188 @@ +/** @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 new file mode 100644 index 00000000..ee46e817 --- /dev/null +++ b/source/clear-linux/reference/collaboration/documentation/images.rst @@ -0,0 +1,88 @@ +.. _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 |CLOSIA|: + +* 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, please provide figure as a vector graphic to + ensure it can be changed later on. + + +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 new file mode 100644 index 00000000..2fb08380 --- /dev/null +++ b/source/clear-linux/reference/collaboration/documentation/inline.rst @@ -0,0 +1,117 @@ +.. _inline: + +Inline Markup +************* + +Sphinx supports a large number of inline markup elements called roles. The +|CLOSIA| documentation encourages the use of as many roles as +possible. Thus, you can use any additional roles supported by Sphinx +even if not listed here. Please refer to the `Sphinx Inline Markup`_ +documentation for the full list of supported roles. + +The following markup is required in every instance unless otherwise +specified. Each item provides examples and a template for the correct use of +the roles. + +* 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)` + + Template: + + ``:abbr:`TIA (This Is an Abbreviation)``` + +* 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` + + Template: + + ``:command:`command``` + +* Use the `:option:` role to emphasize the name of a command option + with or without its value. This markup is usually employed in + combination with the `:command:` role. For example: + + :option:`-f` + :option:`--all` + :option:`-o output.xsl` + The :command:`pandoc` command can be used without the :option:`-o` + option, creating an output file with the same name as the source + but a different extension. + + Template: + + ``:option:`Option``` + +* Use the `:file:` role to emphasize a filename or directory. Do not use the + role inside a code-block but use it inside all notices that contain files + or directories. Place variable parts of the path or filename in brackets + `{}`. + + :file:`collaboration.rst` :file:`doc/{user}/collaboration/figures` + + Template: + + ``:file:`filename.ext` :file:`path/or/directory``` + +* 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. + Press the :guilabel:`OK` button. + In the :guilabel:`Settings` window you find the :guilabel:`Hide + Content` option. + + Template: + + ``:guilabel:`UI-Label``` + +* 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: + + :menuselection:`File --> Save As --> PDF` + Go to :guilabel:`File` and select :menuselection:`Import --> Data + Base --> MySQL`. + Go to :menuselection:`Window --> View` and select :menuselection:` + Perspective --> Other --> C++` + + Template: + + ``:menuselection:`1stMenu --> 2ndMenu --> Selection``` + +* 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` + + Template: + + ``:makevar:`VARIABLE``` + +* 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` + + Template: + + ``:envvar:`ENVIRONMENT_VARIABLE``` + +.. _Sphinx Inline Markup: + http://sphinx-doc.org/markup/inline.html#inline-markup diff --git a/source/clear-linux/reference/collaboration/documentation/language.rst b/source/clear-linux/reference/collaboration/documentation/language.rst new file mode 100644 index 00000000..f086ce07 --- /dev/null +++ b/source/clear-linux/reference/collaboration/documentation/language.rst @@ -0,0 +1,25 @@ +.. _language: + +Language reference guide +######################## + +This section provides you with the accepted use of the English language. 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, |CLOSIA| 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 new file mode 100644 index 00000000..6f43ec77 --- /dev/null +++ b/source/clear-linux/reference/collaboration/documentation/lists.rst @@ -0,0 +1,112 @@ +.. _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 new file mode 100644 index 00000000..e58cbb83 --- /dev/null +++ b/source/clear-linux/reference/collaboration/documentation/notices.rst @@ -0,0 +1,73 @@ +.. _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 new file mode 100644 index 00000000..611cd5e4 --- /dev/null +++ b/source/clear-linux/reference/collaboration/documentation/parallelism.rst @@ -0,0 +1,32 @@ +.. _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 new file mode 100644 index 00000000..88b04d38 --- /dev/null +++ b/source/clear-linux/reference/collaboration/documentation/punctuation.rst @@ -0,0 +1,86 @@ +.. _punctuation: + +Punctuation guide +################# + +This section contains all the information regarding the correct use of +punctuation for the |CLOSIA| documentation. + +Commas, Semicolons, and Colons +****************************** +Here are the most common problems encountered with commas, semicolons, +and colons. Please refer to Merriam-Webster's Collegiate Dictionary +when in doubt. + +Serial Commas +============= + +When writing a series of items, use the serial comma before the +coordinating conjunctions *and* and *or* to avoid confusion and ambiguity. +For example: + +* Mom, Dad, and I are going to the game. +* Mom, Dad and I are going to the game. + +The first example uses the serial comma. It is clear in this sentence +that three people are going to the game. The second example does NOT +have a comma preceding the and. The reader may interpret this as +meaning the same thing as the first sentence, namely that three people +are going to the game, or that the speaker is addressing "Mom" and +telling her that only two people are going to the game. + +Commas in Numbers +================= + +Use commas to divide large numbers into sets of three digits. Use +periods for decimal points. Do not divide decimal digits into sets of +three. + +Do not use a comma to separate four-digit bit/byte numbers. + +Do not use a comma to separate four-digit page numbers. + +Do not use a comma or other punctuation to separate decimals. + + +Semicolons ";" +============== + +Here are some rules governing the use of semicolons: + +* Use semicolons in long, sentence-style bulleted phrase lists. + +* Use semicolons when two equal clauses are joined because of + similarity of construction or meaning. + +* Use semicolons in a series of items when at least one of the items + itself includes a comma. + +Examples of semicolon usage: + +Similar construction: The prewidget comes before the widget; the +postwidget comes after it. + +Comma-inclusive series: We traveled through Casper, Wyoming; Boise, +Idaho; and Eugene, Oregon. + +Colons ":" +========== + +If the text following a colon is a sentence, capitalize the +first word after the colon. If the subsequent text is not a sentence, +do not capitalize the first term unless it is a title. For example: + +* This is a capitalization example: Donuts do not cause holes. + +* These is a noncapitalization example: colons, semicolons, and commas. + +* In a title, use title case following the colon. Example: Tires: How + to Fix a Flat. + +* Use a colon at the end of a sentence or phrase that introduces + examples, a list, a path, user input, or code. + +* Don't use a colon to introduce graphics, tables, or sections. + +* Don't use a colon at the end of a task title or any heading. diff --git a/source/clear-linux/reference/collaboration/documentation/rest.rst b/source/clear-linux/reference/collaboration/documentation/rest.rst new file mode 100644 index 00000000..a11522bc --- /dev/null +++ b/source/clear-linux/reference/collaboration/documentation/rest.rst @@ -0,0 +1,42 @@ +.. _rest: + +RestructuredText guide +###################### + +The |CLOSIA| 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. + +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. + +.. toctree:: + :maxdepth: 3 + + headings + inline + tables + cross + images + code + + +.. _Sphinx documentation: + http://sphinx-doc.org/contents.html diff --git a/source/clear-linux/reference/collaboration/documentation/simple.rst b/source/clear-linux/reference/collaboration/documentation/simple.rst new file mode 100644 index 00000000..7815e6b1 --- /dev/null +++ b/source/clear-linux/reference/collaboration/documentation/simple.rst @@ -0,0 +1,305 @@ +.. _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. + +|CLOSIA| does not use controlled language, which restricts the writer's +vocabulary to a list of approved words. Some preferences are evidently in +place. + +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 new file mode 100644 index 00000000..9301e570 --- /dev/null +++ b/source/clear-linux/reference/collaboration/documentation/steps.rst @@ -0,0 +1,29 @@ +.. _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 new file mode 100644 index 00000000..38dee121 --- /dev/null +++ b/source/clear-linux/reference/collaboration/documentation/structures.rst @@ -0,0 +1,17 @@ +.. _structures: + +Consistent content structures guide +################################### + +This section guides you through the different content structures used in the +|CLOSIA| 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 new file mode 100644 index 00000000..fe82c527 --- /dev/null +++ b/source/clear-linux/reference/collaboration/documentation/tables.rst @@ -0,0 +1,106 @@ +.. _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 |CLOSIA| 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 is larger than 6, that means + 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!" + +CSV-tables can have a title, the header row is optional and separate from the +rest of the table, each column's width is customizable among others. 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/tutorials/azure.rst b/source/clear-linux/tutorials/azure.rst index d562f1d4..f2c5224e 100644 --- a/source/clear-linux/tutorials/azure.rst +++ b/source/clear-linux/tutorials/azure.rst @@ -5,6 +5,8 @@ Clear Linux\* OS on Microsoft\* Azure\* Clear Linux OS is now an offering in the Azure Marketplace. +:ref:`fig-wp-install-1` + Clear Linux OS is designed with cloud and data center environments in mind and is tuned to maximize the performance and value of Intel® architecture. In Azure our boot times are lightning-quick, with all on-boot services diff --git a/source/clear-linux/tutorials/wp-install/wp-install.rst b/source/clear-linux/tutorials/wp-install/wp-install.rst index 7112c3aa..853f9fcc 100644 --- a/source/clear-linux/tutorials/wp-install/wp-install.rst +++ b/source/clear-linux/tutorials/wp-install/wp-install.rst @@ -105,6 +105,8 @@ go to: http:///blog/wp-admin/install.php. Your screen should look like figure 1: +.. _fig-wp-install-1: + .. figure:: figures/wp-install-1.png :alt: WordPress language selection :width: 600 @@ -112,7 +114,9 @@ Your screen should look like figure 1: WordPress language selection screen. Select :guilabel:`English` for the language and click the -:guilabel:`Continue` button. +:guilabel:`Continue` button. :ref:`As shown on figure 1` + + The WordPress installation continues until the welcome screen shown in figure 2 appears: