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/telemetry-backend/figures/telemetry-backend-1.PNG b/source/clear-linux/tutorials/telemetry-backend/figures/telemetry-backend-1.PNG new file mode 100644 index 00000000..9cd8df75 Binary files /dev/null and b/source/clear-linux/tutorials/telemetry-backend/figures/telemetry-backend-1.PNG differ diff --git a/source/clear-linux/tutorials/telemetry-backend/figures/telemetry-backend-2.PNG b/source/clear-linux/tutorials/telemetry-backend/figures/telemetry-backend-2.PNG new file mode 100644 index 00000000..08c0f812 Binary files /dev/null and b/source/clear-linux/tutorials/telemetry-backend/figures/telemetry-backend-2.PNG differ diff --git a/source/clear-linux/tutorials/telemetry-backend/telemetry-backend.rst b/source/clear-linux/tutorials/telemetry-backend/telemetry-backend.rst new file mode 100644 index 00000000..0d89b00b --- /dev/null +++ b/source/clear-linux/tutorials/telemetry-backend/telemetry-backend.rst @@ -0,0 +1,474 @@ +.. _telemtry-backend: + +Create a telemetry backend server in Clear Linux +################################################ + +|CLOSIA| includes a telemetry and analytics solution, also known as +telemetrics, as part of the OS that records events of interest and reports +them back to the development team using the :command:`telemd` telemetrics +daemon. + +End users can enable or disable the telemetry client component of |CL| and +also redirect where records go if they wish to collect records for themselves +by setting up and using their own telemetry backend server. + +A telemetry backend server consists of two Flask applications: +* The :guilabel:`collector` is an ingestion app for records received from the + :guilabel:`telemetrics-client` probes. +* The :guilabel:`telemetryui` web app exposes several visualizations of the + telemetry data. The :guilabel:`telemetryui` app also provides a + REST API to perform queries on the data. + +The applications run within a web stack, using the :guilabel:`nginx` web +server, the :guilabel:`uWSGI` application server, and +:guilabel:`PostgreSQL` as the underlying database server. For a detailed +description, visit the `Clear Linux telemetry backend server overview`_. + +This tutorial walks you through creating a telemetrics backend server on +your local |CL| machine. The tutorial uses the :command:`deploy.sh` bash +shell script that is maintained in a GitHub repository at +https://github.com/clearlinux/telemetrics-backend. Once the backend server is +up and running, we show you how to redirect telemetry records from the system +you set up to this new server location. + +.. note:: + The telemetrics functionality adheres to `Intel’s privacy policies`_ + regarding the collection and use of :abbr:`PII (Personally Identifiable + Information)` and is open Source. Specifically, no intentionally + identifiable information about the user or system owner is collected. + +Prerequisites +************* + +For this tutorial, start with a clean installation of |CL| on a new system +using the :ref:`bare-metal-install` getting started guide: + +#. Choose to install |CL|. +#. Join the :guilabel:`Stability Enhancement Program` to install and + enable the telemetrics components. +#. Select the manual installation method with the following settings: + + * Set the hostname to :guilabel:`clr-telem-server`, + * Create an administrative user named :guilabel:`clear` and add this user + to sudoers, + * Add all additional software bundles. + +Download the clearlinux/telemetrics-backend Git repository +********************************************************** + +With all prerequisite software bundles installed and logged in with your +administrative user, from your :file:`$HOME` directory, run :command:`git` +to clone the :guilabel:`telemetrics-backend` repository into the +:file:`$HOME/telemetrics-backend` directory: + +.. code-block:: console + + git clone https://github.com/clearlinux/telemetrics-backend + +.. note:: + You may need to set up the :envvar:`https_proxy` environment variable + if you have issues reaching github.com. + +Run the deploy.sh script to install the backend server +****************************************************** + +#. Change your current working directory to :file:`telemetrics-backend/scripts`. +#. Run the :command:`./deploy.sh -h` to see the list of options for the + :command:`deploy.sh` script: + +.. code-block:: console + + cd telemetrics-backend/scripts + ./deploy.sh -h + + Deploy snapshot of the telemetrics-backend + + -a Perform specified action (deploy, install, migrate, resetdb, + restart, uninstall; default: deploy) + -d Distro to deploy to (ubuntu, centos or clr; default: ubuntu) + -h Print these options + -H Set domain for deployment (only accepted value is "localhost" for + now) + -r Set repo location to deploy from + (default: https://github.com/clearlinux/telemetrics-backend) + -s Set source location (default: "master" branch from git repo) + -t Set source type (tarball, or git; default: git) + -u Perform complete uninstallation + +The :command:`deploy.sh` is a bash shell script that allows you to perform the +following actions: + +* :option:`deploy` - install a complete instance of the telemetrics backend + server and all required components. This is the default action if no + :option:`-a` argument is given on the command line. +* :option:`install` - installs and enables all required components for the + telemetrics backend server. +* :option:`migrate` - migrate database to new schema. +* :option:`resetdb` - reset the database. +* :option:`restart` - restart the nginx and uWSGI services. +* :option:`uninstall` - uninstall all packages. + + ..note:: + + The :option:`uninstall` option does not perform any actions if the distro is + set to |CL| and will only uninstall packages if the distro is Ubuntu + +Next, we install the telemetrics backend server with the following options: + +* :option:`-a install` to perform an install +* :option:`-d clr` to install to a |CL| distro +* :option:`-H localhost` to set the domain to localhost + +We do not need to set the following options since the values are set to the +correct values we want by default: + +* :option:`-r https://github.com/clearlinux/telemetrics-backend` sets the + repo location for :command:`git` to clone from. +* :option:`-s master` to set the location, or branch. +* :option:`-t git` to set the source type to git. + +.. caution:: + The :file:`deploy.sh` shell script has minimal error checking and makes + several changes to your system. Be sure that the options you define on the + cmdline are correct before proceeding. + +To begin the installation with the options defined: + +#. Run the shell script from the :file:`$HOME/telemetrics-backend/scripts` + directory: + + .. code-block:: console + + ./deploy.sh -H localhost -a install -d clr + + The script will start and list all the defined options and prompt you for the + :guilabel:`PostgreSQL` database password as shown below: + + .. code-block:: console + + Options: + host: localhost + distro: clr + action: install + repo: https://github.com/clearlinux/telemetrics-backend + source: master + type: git + DB password: (default: postgres): + +#. For the :guilabel:`DB password:`, press the :kbd:`Enter` key to accept the + default password `postgres`. + +The :command:`swupd` begins installing the required software bundles to set +up the telemetrics backend server. The output will look similar to what is +shown below: + +.. code-block:: console + + swupd-client bundle adder 3.12.7 + Copyright (C) 2012-2017 Intel Corporation + + Downloading packs... + + Extracting application-server pack for version 18740 + ...5% + Extracting database-basic-dev pack for version 18670 + ...10% + Extracting database-basic pack for version 18670 + ...15% + Extracting os-clr-on-clr pack for version 18740 + ...21% + Extracting sysadmin-basic-dev pack for version 18740 + ...26% + Extracting storage-utils-dev pack for version 18770 + ...31% + Extracting os-core-update-dev pack for version 18760 + ...36% + Extracting network-basic-dev pack for version 18760 + ...42% + Extracting mixer pack for version 18790 + ...47% + Extracting os-installer pack for version 18800 + ...52% + Extracting mail-utils-dev pack for version 18760 + ...57% + Extracting koji pack for version 18800 + ...63% + Extracting go-basic pack for version 18800 + ...68% + Extracting dev-utils-dev pack for version 18820 + ...73% + Extracting python-basic-dev pack for version 18750 + ...78% + Extracting perl-basic-dev pack for version 18610 + ...84% + Extracting c-basic pack for version 18800 + ...89% + Extracting os-core-dev pack for version 18800 + ...94% + Extracting web-server-basic pack for version 18680 + ...100% + Installing bundle(s) files... + ...100% + Calling post-update helper scripts. + Possible filedescriptor leak : 8 (socket:[30833]) + Bundle(s) installation done. + +.. note:: + + This script uses :command:`sudo` to run commands and you may be prompted to + enter your user password at any time while the script is executing. If this + occurs, enter your user password to execute the :command:`sudo` command. + + .. code-block:: console + + Password: + + You may also see an informational message about setting the + :envvar:`https_proxy` environment variable if this variable isn't set. + +Once the :command:`swupd` command is complete, the script begins processing +the requirements to install and implement the telemetrics server. Finally, +the script enables the server and provides output similar to: + +.. code-block:: console + + Collecting uwsgitop + Downloading uwsgitop-0.10.tar.gz + Requirement already satisfied: simplejson in /usr/lib/python3.6/site-packages (from uwsgitop) + Collecting argparse (from uwsgitop) + Downloading argparse-1.4.0-py2.py3-none-any.whl + Building wheels for collected packages: uwsgitop + Running setup.py bdist_wheel for uwsgitop ... done + Stored in directory: /root/.cache/pip/wheels/8a/99/e9/accc80bcaa989218da65daaae4205dc4f6288d3551655aa638 + Successfully built uwsgitop + Installing collected packages: argparse, uwsgitop + Successfully installed argparse-1.4.0 uwsgitop-0.10 + mkdir: created directory '/var/www' + mkdir: created directory '/var/www/telemetry' + Already using interpreter /usr/bin/python3 + Using base prefix '/usr' + New python executable in /var/www/telemetry/venv/bin/python3 + Also creating executable in /var/www/telemetry/venv/bin/python + Installing setuptools, pip, wheel...done. + Collecting alembic==0.9.5 (from -r /tmp/requirements.txt.KDI3uU (line 1)) + Downloading alembic-0.9.5.tar.gz (990kB) + 100% |████████████████████████████████| 993kB 2.1MB/s + Collecting click==6.7 (from -r /tmp/requirements.txt.KDI3uU (line 2)) + Downloading click-6.7-py2.py3-none-any.whl (71kB) + 100% |████████████████████████████████| 71kB 8.3MB/s + Collecting Flask==0.12.2 (from -r /tmp/requirements.txt.KDI3uU (line 3)) + Downloading Flask-0.12.2-py2.py3-none-any.whl (83kB) + 100% |████████████████████████████████| 92kB 10.2MB/s + Collecting Flask-Migrate==2.1.0 (from -r /tmp/requirements.txt.KDI3uU (line 4)) + Downloading Flask-Migrate-2.1.0.tar.gz + Collecting Flask-SQLAlchemy==2.2 (from -r /tmp/requirements.txt.KDI3uU (line 5)) + Downloading Flask_SQLAlchemy-2.2-py2.py3-none-any.whl + Collecting Flask-WTF==0.14.2 (from -r /tmp/requirements.txt.KDI3uU (line 6)) + Downloading Flask_WTF-0.14.2-py2.py3-none-any.whl + Collecting itsdangerous==0.24 (from -r /tmp/requirements.txt.KDI3uU (line 7)) + Downloading itsdangerous-0.24.tar.gz (46kB) + 100% |████████████████████████████████| 51kB 12.4MB/s + Collecting Jinja2==2.9.6 (from -r /tmp/requirements.txt.KDI3uU (line 8)) + Downloading Jinja2-2.9.6-py2.py3-none-any.whl (340kB) + 100% |████████████████████████████████| 348kB 3.5MB/s + Collecting Mako==1.0.7 (from -r /tmp/requirements.txt.KDI3uU (line 9)) + Downloading Mako-1.0.7.tar.gz (564kB) + 100% |████████████████████████████████| 573kB 1.9MB/s + Collecting MarkupSafe==1.0 (from -r /tmp/requirements.txt.KDI3uU (line 10)) + Downloading MarkupSafe-1.0.tar.gz + Collecting psycopg2==2.7.3 (from -r /tmp/requirements.txt.KDI3uU (line 11)) + Downloading psycopg2-2.7.3.tar.gz (425kB) + 100% |████████████████████████████████| 430kB 4.0MB/s + Collecting python-dateutil==2.6.1 (from -r /tmp/requirements.txt.KDI3uU (line 12)) + Downloading python_dateutil-2.6.1-py2.py3-none-any.whl (194kB) + 100% |████████████████████████████████| 194kB 6.8MB/s + Collecting python-editor==1.0.3 (from -r /tmp/requirements.txt.KDI3uU (line 13)) + Downloading python-editor-1.0.3.tar.gz + Collecting six==1.10.0 (from -r /tmp/requirements.txt.KDI3uU (line 14)) + Downloading six-1.10.0-py2.py3-none-any.whl + Collecting SQLAlchemy==1.1.13 (from -r /tmp/requirements.txt.KDI3uU (line 15)) + Downloading SQLAlchemy-1.1.13.tar.gz (5.2MB) + 100% |████████████████████████████████| 5.2MB 394kB/s + Collecting uWSGI==2.0.15 (from -r /tmp/requirements.txt.KDI3uU (line 16)) + Downloading uwsgi-2.0.15.tar.gz (795kB) + 100% |████████████████████████████████| 798kB 1.5MB/s + Collecting Werkzeug==0.12.2 (from -r /tmp/requirements.txt.KDI3uU (line 17)) + Downloading Werkzeug-0.12.2-py2.py3-none-any.whl (312kB) + 100% |████████████████████████████████| 317kB 2.2MB/s + Collecting WTForms==2.1 (from -r /tmp/requirements.txt.KDI3uU (line 18)) + Downloading WTForms-2.1.zip (553kB) + 100% |████████████████████████████████| 563kB 1.7MB/s + Skipping bdist_wheel for psycopg2, due to binaries being disabled for it. + Building wheels for collected packages: alembic, Flask-Migrate, itsdangerous, Mako, MarkupSafe, python-editor, SQLAlchemy, uWSGI, WTForms + Running setup.py bdist_wheel for alembic ... done + Stored in directory: /root/.cache/pip/wheels/d1/0e/b9/fb570150b350298e1d8f1ff38a400ae709580b36e43bc3ac91 + Running setup.py bdist_wheel for Flask-Migrate ... done + Stored in directory: /root/.cache/pip/wheels/3d/29/d4/66747eca8b8a28973aa639f39e96a402b3dcab335e608048dd + Running setup.py bdist_wheel for itsdangerous ... done + Stored in directory: /root/.cache/pip/wheels/fc/a8/66/24d655233c757e178d45dea2de22a04c6d92766abfb741129a + Running setup.py bdist_wheel for Mako ... done + Stored in directory: /root/.cache/pip/wheels/33/bf/8f/036f36c35e0e3c63a4685e306bce6b00b6349fec5b0947586e + Running setup.py bdist_wheel for MarkupSafe ... done + Stored in directory: /root/.cache/pip/wheels/88/a7/30/e39a54a87bcbe25308fa3ca64e8ddc75d9b3e5afa21ee32d57 + Running setup.py bdist_wheel for python-editor ... done + Stored in directory: /root/.cache/pip/wheels/84/d6/b8/082dc3b5cd7763f17f5500a193b6b248102217cbaa3f0a24ca + Running setup.py bdist_wheel for SQLAlchemy ... done + Stored in directory: /root/.cache/pip/wheels/f0/50/ca/3cb6e78527eb05e180d19632343ee14d2e5c164da2e61fbd2d + Running setup.py bdist_wheel for uWSGI ... done + Stored in directory: /root/.cache/pip/wheels/26/d0/48/e7b0eed63b5d191e89d94e72196aafae93b2b6505a9feafdd9 + Running setup.py bdist_wheel for WTForms ... done + Stored in directory: /root/.cache/pip/wheels/36/35/f3/7452cd24daeeaa5ec5b2ea13755316abc94e4e7702de29ba94 + Successfully built alembic Flask-Migrate itsdangerous Mako MarkupSafe python-editor SQLAlchemy uWSGI WTForms + Installing collected packages: SQLAlchemy, MarkupSafe, Mako, python-editor, six, python-dateutil, alembic, click, Werkzeug, Jinja2, itsdangerous, Flask, Flask-SQLAlchemy, Flask-Migrate, WTForms, Flask-WTF, psycopg2, uWSGI + Running setup.py install for psycopg2 ... done + Successfully installed Flask-0.12.2 Flask-Migrate-2.1.0 Flask-SQLAlchemy-2.2 Flask-WTF-0.14.2 Jinja2-2.9.6 Mako-1.0.7 MarkupSafe-1.0 SQLAlchemy-1.1.13 WTForms-2.1 Werkzeug-0.12.2 alembic-0.9.5 click-6.7 itsdangerous-0.24 psycopg2-2.7.3 python-dateutil-2.6.1 python-editor-1.0.3 six-1.10.0 uWSGI-2.0.15 + mkdir: created directory '/var/log/uwsgi' + +Once all the server components have been installed you are prompted to enter +the :guilabel:`PostgreSQL` database password to change it as illustrated below: + +.. code-block:: console + + Enter password for 'postgres' user: + New password: + Retype new password: + passwd: password updated successfully + +Enter `postgres` for the current value of the password and then enter a new +password, retype it to verify the new password and the :guilabel:`PostgreSQL` +database password will be updated. + +The script finalizes installation and finishes. + +.. code-block:: console + + Created symlink /etc/systemd/system/multi-user.target.wants/postgresql.service → /usr/lib/systemd/system/postgresql.service. + Cloning into 'telemetrics-backend'... + remote: Counting objects: 344, done. + remote: Compressing objects: 100% (53/53), done. + remote: Total 344 (delta 30), reused 50 (delta 20), pack-reused 268 + Receiving objects: 100% (344/344), 130.20 KiB | 1.40 MiB/s, done. + Resolving deltas: 100% (177/177), done. + '/tmp/telemetrics-backend/scripts/collector_uwsgi.ini' -> '/tmp/telemetrics-backend/collector/collector_uwsgi.ini' + '/tmp/telemetrics-backend/scripts/telemetryui_uwsgi.ini' -> '/tmp/telemetrics-backend/telemetryui/telemetryui_uwsgi.ini' + mkdir: created directory '/var/www/telemetry/collector/uwsgi-spool' + mkdir: created directory '/var/www/telemetry/telemetryui/uwsgi-spool' + '/tmp/telemetrics-backend/scripts/uwsgi.service' -> '/etc/systemd/system/uwsgi.service' + mkdir: created directory '/etc/nginx' + mkdir: created directory '/etc/nginx/conf.d' + '/usr/share/nginx/conf/nginx.conf.example' -> '/etc/nginx/nginx.conf' + Created symlink /etc/systemd/system/multi-user.target.wants/nginx.service → /usr/lib/systemd/system/nginx.service. + mkdir: created directory '/etc/uwsgi' + mkdir: created directory '/etc/uwsgi/vassals' + Created symlink /etc/systemd/system/multi-user.target.wants/uwsgi.service → /etc/systemd/system/uwsgi.service. + ALTER ROLE + sed: can't read /tmp/telemetrics-backend/collector/config.py: No such file or directory + cp: cannot stat '/tmp/telemetrics-backend/collector/config.py': No such file or directory + sed: can't read /tmp/telemetrics-backend/telemetryui/config.py: No such file or directory + cp: cannot stat '/tmp/telemetrics-backend/telemetryui/config.py': No such file or directory + Already using interpreter /usr/bin/python3 + Using base prefix '/usr' + New python executable in /var/www/telemetry/venv/bin/python3 + Not overwriting existing python script /var/www/telemetry/venv/bin/python (you must use /var/www/telemetry/venv/bin/python3) + Installing setuptools, pip, wheel...done. + INFO [alembic.runtime.migration] Context impl PostgresqlImpl. + INFO [alembic.runtime.migration] Will assume transactional DDL. + INFO [alembic.runtime.migration] Running upgrade -> 3230c615d6e0, empty message + INFO [alembic.runtime.migration] Running upgrade 3230c615d6e0 -> 466cf2f35d67, empty message + + Install complete (installation folder: /var/www/telemetry) + +Once the installation is complete you can use your web browser and view the +new server by opening the web browser on the system you installed the backend +server onto and type in ``localhost`` in the address bar. You should see a +web page similar to the one shown in figure 1: + +.. figure:: figures/telemetry-backend-1.png + :scale: 50 % + :alt: Telemetry UI + + Figure 1: :guilabel:`Telemetry UI` + + +Redirect telemetry records +************************** + +Telemetry records from your system are sent to the server location defined in +the :file:`/usr/share/defaults/telemetrics/telemetrics.conf` configuration +file. You can customize this by copying this file to +:file:`/etc/telemetrics/telemetrics.conf` and changing the ``server=`` +setting to your new server location. + +#. Create the :file:`/etc/telemetrics` directory and make it your current + working directory. + + .. code-block:: console + + sudo mkdir -p /etc/telemetrics + cd /etc/telemetrics + + +#. Copy the default :file:`telemetrics.conf` file to the new + :file:`/etc/telemetrics` directory. + + .. code-block:: console + + sudo cp /usr/share/defaults/telemetrics/telemetrics.conf . + +#. Edit the new :file:`/etc/telemetrics/telemetrics.conf` file with your + editor using the :command:`sudo` directive and change the + :guilabel:`server=` setting to ``http://localhost/v2/collector`` and save + this change in the new file. + + .. code-block:: console + + server=http://localhost/v2/collector + + You can also use the fully qualified domain name for your server instead of + :guilabel:`localhost`. + +#. Restart the :command:`telemd` daemon to reload the configuration file. + + .. code-block:: console + + systemctl restart telemd + +Test the new telemetry backend server +************************************* + +|CL| includes a telemetry test probe called :command:`hprobe` that will send a +``hello`` record to the telemetry backend server. To test that the telemetry +records are now going to your new destination, run the :command:`hprobe` +command to send a ``hello`` record to the server as follows: + +.. code-block:: console + + hprobe + +The record should show up on your new server console as shown in figure 2: + +.. figure:: figures/telemetry-backend-2.png + :scale: 50 % + :alt: Telemetry UI + + Figure 2: :guilabel:`Telemetry UI` + +Congratulations! You've just set up and enabled a new telemetrics backend +server, redirected the records from your local machine to this new server and +tested it using the :command:`hprobe` command to send a ``hello`` record to +it. + +Additional resources +******************** + +https://clearlinux.org/features/telemetry + +https://github.com/clearlinux/telemetrics-client + +https://github.com/clearlinux/telemetrics-backend + +.. _`Clear Linux telemetry backend server overview`: + https://github.com/clearlinux/telemetrics-backend + +.. _`Intel's privacy policies`: + http://www.intel.com/content/www/us/en/privacy/intel-privacy.html diff --git a/source/clear-linux/tutorials/tutorials.rst b/source/clear-linux/tutorials/tutorials.rst index 7c7ea285..ad1b3227 100644 --- a/source/clear-linux/tutorials/tutorials.rst +++ b/source/clear-linux/tutorials/tutorials.rst @@ -16,4 +16,6 @@ specific |CLOSIA| use cases. multi-boot/multi-boot hadoop fmv - aws-web/aws-web \ No newline at end of file + aws-web/aws-web + telemetry-backend/telemetry-backend + 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: