clearlinux/clear-linux-documentation
2
0
Fork 0
mirror of https://github.com/clearlinux/clear-linux-documentation.git synced 2026-09-07 06:11:44 +00:00
Code Issues Packages Projects Releases Wiki Activity

Revert "Merge of latest changes into RTD theme to enable multi-language support (#604)"

Browse Source 
This reverts commit 186f1e02b8.
This commit is contained in:
Kevin Putnam
2019-07-10 15:20:53 -07:00
committed by GitHub
parent 186f1e02b8
commit f2a5c5a46b
407 changed files with 2660 additions and 2918 deletions
Download Patch File Download Diff File Expand all files Collapse all files
source/clear-linux/reference/bundle-commands.rst
+47
View File
@@ -0,0 +1,47 @@
.. _bundle-commands:
Useful bundle commands
######################
To see a list of currently installed bundles, enter:
.. code-block:: bash
sudo swupd bundle-list
To see the list of all available bundles, enter:
.. code-block:: bash
sudo swupd bundle-list --all
Alternatively, you can view our :ref:`available bundles <bundles>`
webpage.
To search for bundles and their contents, enter:
.. code-block:: bash
sudo swupd search [bundle name]
To add a bundle, enter:
.. code-block:: bash
sudo swupd bundle-add [bundle name]
Additional information
======================
For additional :command:`swupd` commands, enter:
.. code-block:: bash
swupd --help
To reference the :command:`swupd` man page, enter:
.. code-block:: bash
man swupd
source/clear-linux/reference/bundles/bundles.html.txt
+26219
View File
File diff suppressed because it is too large Load Diff
source/clear-linux/reference/bundles/bundles.rst
+18
View File
@@ -0,0 +1,18 @@
.. _bundles:
Available bundles
#################
This document provides a current list of available bundles. View the `clr-bundles repo`_ on GitHub\*, or select the bundle
:file:`Name` for more details.
To learn more about how |CL-ATTR| uses bundles for software deployment, visit
:ref:`bundles-about`.
Bundle list
===========
.. raw:: html
:file: bundles.html.txt
.. _clr-bundles repo: https://github.com/clearlinux/clr-bundles/tree/master/bundles
source/clear-linux/reference/bundles/openssh-server.rst
+169
View File
@@ -0,0 +1,169 @@
.. _openssh-server:
openssh-server
##############
The **openssh-server** bundle provides the OpenSSH\* package needed to enable
an SSH service in |CL-ATTR|. Remote users require an SSH service to be able
to use an encrypted login shell.
|CL| enables the `sshd.socket` unit, which will listen on port 22 by default
and start the OpenSSH service as required. The first time OpenSSH starts, it
generates the server SSH keys needed for the service.
Prerequisites
*************
Assure the bundle :file:`openssh-server` is installed.
To check it it's on your host, enter:
.. code-block:: bash
sudo swupd bundle-list
To add it, enter:
.. code-block:: bash
sudo swupd bundle-add openssh-server
Change default port
*******************
Perform the following steps to change the default listening port for the
OpenSSH service:
#. Open the sshd.socket file:
.. code-block:: bash
sudo systemctl edit sshd.socket
#. Add the `[Socket]` section and `ListenStream` option to the sshd.socket
file as shown below. The first `ListenStream` entry removes the |CL|
default listen port value. The second `ListenStream` entry sets the new
default listen port value. In this example, we set the new default port
to 4200:
.. code-block:: console
[Socket]
ListenStream=
ListenStream=4200
Make sure to include a new line after the last line of text in the sshd.socket file.
#. Verify your changes:
.. code-block:: bash
cat /etc/systemd/system/sshd.socket.d/override.conf
You should see the following output:
.. code-block:: console
[Socket]
ListenStream=
ListenStream=4200
#. Reload the systemd daemon configurations:
.. code-block:: bash
sudo systemctl daemon-reload
#. Restart the sshd.socket unit:
.. code-block:: bash
sudo systemctl restart sshd.socket
#. Confirm the the sshd.socket unit is listening on your new port:
.. code-block:: bash
sudo systemctl status sshd.socket
.. note::
Output should show :guilabel:`Active:` as `active(listening)`.
Enable SFTP
***********
|CL| *disables* the :abbr:`SFTP (SSH File Transfer Protocol)` subsystem by
default due to security considerations. To enable the SFTP subsystem, perform
the following configuration of the :abbr:`SSHD (SSH Daemon)` service file:
#. Create a systemd drop-in directory for the SSHD service:
.. code-block:: bash
sudo mkdir -p /etc/systemd/system/sshd@.service.d
#. Create the following file:
:file:`/etc/systemd/system/sshd@.service.d/sftp.conf`
#. Add the OPTIONS environment variable to the sftp.conf file.
.. code-block:: console
[Service]
Environment="OPTIONS=-o Subsystem=\"sftp /usr/libexec/sftp-server\""
#. Reload systemd configuration:
.. code-block:: bash
sudo systemctl daemon-reload
Congratulations! The SFTP subsystem is enabled.
Enable root login
*****************
To enable root login via SSH, perform the following steps:
#. Create a *ssh* directory in :file:`/etc`, if it does not already exist.
.. code-block:: bash
mkdir /etc/ssh
#. Create the following file, if it does not already exist:
:file:`/etc/ssh/sshd_config`
#. Set the configuration variable in /etc/ssh/sshd_config
.. code-block:: console
PermitRootLogin yes
Enable X11-forwarding
*********************
X11 forwarding allows you to securely run graphical applications
(i.e., X clients) over the ssh conection. This will alow for remote gui apps
without the need for full VNC/remotedesktop. To enable X11-forwarding via
SSH, perform the following steps:
#. Create a *ssh* directory in :file:`/etc`, if it does not already exist.
.. code-block:: bash
mkdir /etc/ssh
#. Create the following file, if it does not already exist:
:file:`/etc/ssh/sshd_config`
#. Set the configuration variables.
.. code-block:: bash
AllowTcpForwarding yes
X11UseLocalhost yes
X11DisplayOffset 10
X11Forwarding yes
source/clear-linux/reference/collaboration/collaboration.rst
+83
View File
@@ -0,0 +1,83 @@
.. _collaboration:
Documentation guidelines
########################
See a missing topic in the documentation? Find an existing document that could
be improved? Help us out by contributing! If you haven't contributed before,
take a moment to review our `Contribution guidelines`_.
Do you have questions about the documentation that were not answered by these
guidelines? Send your question to the `mailing list`_.
Contribution guidelines
***********************
The |CL| documentation is hosted in GitHub and is written using
reStructuredText. Use our guidelines and best practices to write consistent,
readable documentation.
.. toctree::
:maxdepth: 1
Writing guide: Describes the style we use to keep our documents clear and concise. <writing-guide>
Structure and formatting guide: Explains how we organize and format content, using reStructuredText and Sphinx. <structure-formatting>
How to contribute
*****************
There are multiple ways to contribute and help improve our documentation:
* **Make a suggestion**: Have a documentation suggestion but no time to write it
yourself? Send your suggestion to the `mailing list`_.
* **Log an issue**: If you find a problem in our documentation (such as typos or
out-of-date information), log an issue in the `documentation repository`_.
* **Contribute directly via GitHub**: Whether you've found a typo, have better
instructions or examples, or have a new page to add, submit your improvement
or addition as a pull request on the `documentation repository`_.
* **Test documentation**: Step through our instructional guides and tutorials to
verify the instructions. Log or correct any out-of-date information.
All contributions must follow our `code of conduct`_.
Contribute via GitHub
*********************
Our documentation is hosted in GitHub and we follow the standard `GitHub flow`_:
#. Clone the `documentation repository`_.
#. Create your own fork of the repository.
#. Create a branch for your contribution.
#. Add your commits.
#. Open a pull request.
#. Discuss, review, and update your contributions.
#. Once the maintainer approves, your contribution is merged and published as
part of the documentation.
.. _references:
References
**********
We use the following references to guide the grammar, style, and formatting of
our documentation:
* `Microsoft Writing Style Guide`_
* `Merriam-Webster Dictionary`_
* The Chicago Manual of Style (15th edition), The University of Chicago Press
* Microsoft Press Computer Dictionary, Microsoft Press
* Read Me First!, Oracle Technical Publications
.. _`code of conduct`: https://clearlinux.org/community/code-of-conduct
.. _mailing list: https://lists.clearlinux.org/mailman/listinfo/dev
.. _GitHub flow: https://guides.github.com/introduction/flow/
.. _documentation repository: https://github.com/clearlinux/clear-linux-documentation
.. _Microsoft Writing Style Guide: https://docs.microsoft.com/en-us/style-guide/welcome/
.. _Merriam-Webster Dictionary: https://www.merriam-webster.com/
source/clear-linux/reference/collaboration/structure-formatting.rst
+482
View File
@@ -0,0 +1,482 @@
.. _structure-formatting:
Structure and formatting
########################
Content should be organized to support scanning. Consistent organization,
formatting, and writing style helps readers quickly find what they need and to
understand the content more effectively. This document describes our
organization and formatting guidelines.
Refer to :ref:`writing-guide` to learn how we keep our documents clear and
concise.
.. contents:: :local:
:depth: 1
Markup
******
Our documentation is written in the reStructuredText markup language, using
Sphinx roles and directives. We use Sphinx to generate the final documentation.
You can read more about reStructuredText and Sphinx on their respective
websites:
* `Sphinx documentation`_
* `reStructuredText Primer`_
You can view the content directly in the .rst markup files, or generate the HTML
content by installing and building the documentation locally. To run the
documentation locally, follow the instructions found in the
`documentation repository`_ README.
New pages
=========
There are a few additional steps to consider when adding a new page to the
documentation. First, identify where your new page should be located within the
existing `Documentation organization`_. Second, make sure the new page is picked
up in the Sphinx build and easily linkable from other content.
Each page must be included in a `Sphinx toctree`_ in order to be included in the
documentation content tree. Typically, pages are added to the section landing
page toctree.
For example, the :ref:`collaboration` page toctree looks like:
.. code-block:: rest
.. toctree::
:maxdepth: 1
writing-guide
structure-formatting
Additionally, each page must include a uniquely named reST label directly before
the page title, to enable the `Sphinx ref role`_ for linking to a page.
For example, this page "Structure and formating" has the label
``.. _structure-formatting``:
.. code-block:: rest
.. _structure-formatting:
Structure and formatting
########################
This page can then be referenced from other pages in the documentation using the
`:ref:` role:
.. code-block:: rest
:ref:`structure-formatting`
Documentation organization
**************************
The documentation is organized into five general sections:
#. **Concepts**: Introduction and overview of |CL| specific concepts or
features.
#. **Get started**: Information about getting started with |CL|.
#. **Guides**: Detailed information and instruction on using |CL| features.
#. **Tutorials**: Step-by-step instruction for using |CL| in specific use cases.
#. **Reference**: Supplementary and reference information for |CL|.
Page structure
==============
Each page in the documentation should follow the basic format of:
* Overview: 1-2 sentences describing what this page shows and why it matters
* Prerequisites: Describe any pre-work necessary to the content (if appropriate)
* Content
* Next steps: List links to next steps (if appropriate)
* Related topics: List links to related content (if appropriate)
Headings
========
Use headings to section and organize your content for better readability and
clarity.
* All files must have a top level heading, which is the title for the page.
* Up to three additional levels of headings are allowed under the title heading.
* Each heading should be followed by at least one paragraph of content. Avoid
two or more consecutive headings.
Refer to the :ref:`writing-guide` for tips on using headings to create
:ref:`scannable content <scannable-content>`.
To mark up headings in the .rst file:
* Use hash-tags to underline the file's main title:
.. code-block:: rest
Main title
##########
* Use asterisks to underline the file's first level headings:
.. code-block:: rest
First level heading
*******************
* Use equal signs to underline the file's second level of headings:
.. code-block:: rest
Second level heading
====================
* Use dashes to underline the file's third level of headings:
.. code-block:: rest
Third level heading
-------------------
In-page navigation
==================
If a page has three or more sections, provide quick links to each section. Place
the quick links after the overview section.
Use the standard `reST contents directive`_ with depth: 1 for quick links.
Inline text formatting
**********************
We use the `Microsoft Writing Style Guide`_ as our starting point for text
formatting. We apply the formatting using reST and Sphinx markup.
Use our quick reference for the most commonly used inline text elements:
+--------------------------------+---------------------------------------+-----------------------------+
| **Element** | **Convention** | **reST/Sphinx** |
+--------------------------------+---------------------------------------+-----------------------------+
| Acronyms | Define acronym when first used. After | Use the ``:abbr:`` role, in |
| | first use and definition, use the | the following format: |
| | acronym only. | |
| | | ``:abbr:`Acronym (Def)``` |
+--------------------------------+---------------------------------------+-----------------------------+
| Bundle names | Bold | Use the ``:command:`` role. |
+--------------------------------+---------------------------------------+-----------------------------+
| Callouts | | Use ``.. note::`` |
+--------------------------------+---------------------------------------+-----------------------------+
| Code/command examples | Monospace, visually distinct | Use ``.. code-block::`` |
| | from rest of text. Use an | with the correct language |
| | indented call-out box. | setting. |
+--------------------------------+---------------------------------------+-----------------------------+
| Commands | Bold | Use the ``:command:`` role. |
+--------------------------------+---------------------------------------+-----------------------------+
| Command flags | Bold | Use the ``:command:`` role. |
+--------------------------------+---------------------------------------+-----------------------------+
| Console output | Monospace, visual distinction | Use ``.. code-block::`` |
| | from rest of text. Use an | with console as the |
| | indented call-out box. | language setting. |
+--------------------------------+---------------------------------------+-----------------------------+
| Emphasis | Italic | ``*strong*`` |
+--------------------------------+---------------------------------------+-----------------------------+
| Environment variables | Use the case format of the | Use ``:envvar:`` |
| | environment variable. | |
+--------------------------------+---------------------------------------+-----------------------------+
| Example commands with | Use angle brackets for swapping | |
| optional or replaceable | in the specific name, | |
| parts | e.g. <package-name>. | |
| | | |
| | Use square brackets for optional | |
| | parts, | |
| | e.g. [--build]. | |
+--------------------------------+---------------------------------------+-----------------------------+
| Example URLs (not linked) | Plain text | |
+--------------------------------+---------------------------------------+-----------------------------+
| File extensions | Lowercase | |
+--------------------------------+---------------------------------------+-----------------------------+
| File names, directories, paths | Title style capitalization | Use the ``:file:`` role. |
+--------------------------------+---------------------------------------+-----------------------------+
| GUI labels | | Use ``:guilabel:`` |
+--------------------------------+---------------------------------------+-----------------------------+
| Inline comments | | Use ``..`` |
+--------------------------------+---------------------------------------+-----------------------------+
| Keystrokes | | Use ``:kbd:`` |
+--------------------------------+---------------------------------------+-----------------------------+
| Local navigation | | ``.. contents:: :local:`` |
| | | with a depth of 1 |
+--------------------------------+---------------------------------------+-----------------------------+
| Menu selection | | Use ``:menuselection:`` |
+--------------------------------+---------------------------------------+-----------------------------+
| New terms | Italic for first use, normal for all | ``*term*`` |
| | subsequent uses. | |
| | | |
| | If it is used outside of the source | |
| | of definition, link the term. | |
+--------------------------------+---------------------------------------+-----------------------------+
| Product name | Follow correct trademark and | |
| | attribution guidelines. | |
+--------------------------------+---------------------------------------+-----------------------------+
| Tool names | Correctly capitalized, no quotes, | |
| | bold, or italics as the basic rule. | |
| | | |
| | If the tool name is the command, like | |
| | most Linux tools, treat it like a | |
| | command. | |
| | | |
| | If the tool name is lowercase and | |
| | used at the start of a sentence, use | |
| | bold. | |
+--------------------------------+---------------------------------------+-----------------------------+
White space and line length
===========================
Limit line length to 78 characters. The GitHub web interface forces this
limitation for readability.
Remove trailing whitespace from your documents.
Code blocks and examples
************************
When providing example code or commands use the `Sphinx code-block directive`_.
Select the appropriate syntax highlighting for the example command or code.
For example, if showing console output, use console highlighting:
.. code-block:: rest
.. code-block:: console
Sphinx provides other ways of `marking up example code`_ if needed.
Lists and instructions
**********************
Use a numbered list when the order or priority of the items is important, such
as step-by-step instructions.
Use a bulleted list when the order of the items is not important.
For both list types, keep all items in the list parallel. See
:ref:`parallelism`.
Use standard `reST list markup`_.
Numbered lists
==============
Numbered lists are most frequently used for procedures. Use numbered lists to
show sequence for the items. Follow our guidelines for numbered lists:
* Make sure the list is sequential and not just a collection of items.
* Introduce a numbered list with a sentence. End the setup text with a
colon. Example: "To configure the unit, perform the following steps:"
* Each item in the list should be parallel.
* Treat numbered list items as full sentences with correct ending
punctuation.
* You may interrupt numbered lists with other content, if relevant,
e.g. explanatory text, commands, or code.
* Second-level steps are acceptable; avoid third-level steps.
* Avoid single-step procedures; the minimum number of steps in a procedure
is two.
* Do not create numbered lists that emulate flowcharts. The reader should be
able to execute the list of steps from first to last without branching or
looping.
* Avoid over-using numbered lists, except in procedural documents such as
tutorials and step-by-step guides.
Bulleted lists
==============
Use bulleted lists to reduce wordiness and paragraph density, especially when
a sequence is not required. Here are some guidelines for bulleted lists:
* Introduce a bulleted list with a sentence. End the setup text with a
colon. Example: "To repair the unit, you will need the following items:"
* Each item in the list should be parallel.
* Avoid interrupting bulleted lists with other paragraph styles.
* Second-level bullets are acceptable; avoid third-level bullets.
Use the correct ending punctuation for sentence style bullet lists. For example:
**Use this:**
::
When setting the user code, remember:
* Use a number that has a meaning for you.
* Change the code once a month.
* Do not disclose the user code to anyone, including the security company.
**Not this:**
::
When setting the user code remember:
* make the user code easy to remember. Use a number that has a meaning for you
* change the code once a month
* do not disclose the user code to anyone else. This includes the security
company
Instructions
============
When presenting instructions, such as in a tutorial, present them in a numbered
list according to these guidelines:
* Each step (list item) should describe one action.
* If the same steps are repeated, refer to the earlier steps rather than
repeating them.
* When a step includes a command or code block as an example, put the command
or code block after the step that includes them.
* Use supporting images where appropriate. If the series of steps is supported
by one figure, refer to the figure in the introductory text.
For example: "See Figure 15 and do the following:"
When a series of steps is supported by two or more figures, refer to the
specific figure in the relevant step and show the figure immediately after
the reference. **Do not write**: "See figures 15 through 22 and do the
following:"
Notices
*******
We use four special types of notices: notes, cautions, warnings, and dangers.
Here are some specific rules and tips regarding use of these notices:
* Do not use a notice directly after a heading. Notices must follow a variant of
body text.
* Do not include more than one notice in a single notice block.
* Avoid back-to-back notices.
* If back-to-back notices are not avoidable, make sure each distinct notice in
the notice block is clearly defined.
Use the standard `reST admonition directive`_.
Notes, cautions, and warnings
=============================
Use notes sparingly. Avoid having more than one note per section. If you exceed
this number consistently, consider rewriting the notes as main body text.
Use cautions and warnings to alert readers of potential problems or pitfalls.
Use conditional phrases in cautions and warnings, such as "If you do X, then Y
will occur."
These are examples of typical notices and the conditions for their usage:
.. note::
Notes are extra bits of information that supplement the main content. Notes
should be relatively short.
.. caution::
Cautions are low-level hazard messages that alert the user of possible
equipment, product, and software damage, including loss of data.
.. warning::
Warnings are mid-level hazards that are likely to cause product damage.
Links
*****
Use the standard `reST markup for links`_.
To add a cross-reference to another documentation page, use the `:ref:` role:
.. code-block:: rest
:ref:`structure-formatting`
To add an external link, we use named references that refer to a defined
link/label at the bottom of the page.
For example, an external link is defined at the bottom of the page like this:
.. code-block:: rest
.. _wiki about dogs: https://en.wikipedia.org/wiki/Dog
The defined link is then used in the content like this:
.. code-block:: rest
Check out the great `wiki about dogs`_.
Images
******
Use images or figures to convey information that may be difficult to explain
using words alone. Well-planned graphics reduce the amount of text required to
explain a topic or example.
Follow these guidelines when using graphics in support of your documentation:
* Keep it simple. Use images that serve a specific purpose in your document,
and contain only the information the reader needs.
* Avoid graphics that will need frequent updating. Don't include information in
a graphic that might change with each release, such as product versions.
* Use either PNG or JPEG bitmap files for screenshots and SVG files for vector
graphics.
* Place the image immediately after the text it helps clarify, or as close as
possible.
* Use the `Sphinx figure directive`_ to insert images and figures into the
document. Include both alt text, a figure name, and caption.
For example:
.. code-block:: rest
.. figure:: figures/topic-1.png
:alt: An image supporting the topic.
Figure 1: This is the figure 1 caption.
* Include at least one direct reference to an image from the main text, using
the figure number. For example:
**Use this:** ::
Figure 1
**Not this:** ::
The figure above or below
Images should follow these naming and location conventions:
* Save the image files in a :file:`figures` folder at the same level as the file
that will reference the image.
* Name image files according to the following rules:
* Use only lower case letters.
* Separate multiple words in filenames using dashes.
* Name images using the filename of the file they appear on and add a number
to indicate their place in the file. For example, the third figure added to
the :file:`welcome.rst` file must be named :file:`welcome-3.png`.
.. _Sphinx documentation: http://www.sphinx-doc.org/en/master/usage/restructuredtext/index.html
.. _reStructuredText Primer: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
.. _documentation repository: https://github.com/clearlinux/clear-linux-documentation
.. _Sphinx toctree: https://www.sphinx-doc.org/en/master/usage/quickstart.html?highlight=toctree#defining-document-structure
.. _Sphinx ref role: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#role-ref
.. _reST contents directive: http://docutils.sourceforge.net/docs/ref/rst/directives.html#table-of-contents
.. _Microsoft Writing Style Guide: https://docs.microsoft.com/en-us/style-guide/welcome/
.. _Sphinx code-block directive: http://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html#directive-code-block
.. _marking up example code: http://www.sphinx-doc.org/en/1.6/markup/code.html
.. _reST list markup: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#lists-and-quote-like-blocks
.. _reST admonition directive: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#directives
.. _reST markup for links: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#hyperlinks
.. _Sphinx figure directive: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html#directives
source/clear-linux/reference/collaboration/writing-guide.rst
+410
View File
@@ -0,0 +1,410 @@
.. _writing-guide:
Writing guide
#############
We want our documentation to be easy to read and understand. This document
describes guidelines for writing documentation that is clear, concise,
confident, and courteous.
Refer to :ref:`structure-formatting` for details on organizing content and how
we use reStructuredText and Sphinx.
.. contents:: :local:
:depth: 1
Use simple English
******************
Write using simple English: Be brief and communicate only the information that
is needed. Be friendly and informative. Emphasize clarity and avoid
unecessary complicated or technical terms. Make the content accessible to
non-native speakers.
Be brief
========
Use short sentences and paragraphs. Stick to the principle of one main
idea per sentence, plus one additional point if needed. Each paragraph
should address one main idea. Remember the basic structure of a paragraph:
Introduction, body, and conclusion.
Be friendly
===========
We write for our peers and want to be familiar. Take a personal tone as if you
were speaking directly to the reader. Use "you" to address the reader and "we"
to refer to our view. Be professional, respectful, and cooperative.
Assume your audience has the same level of technical understanding and expertise
as you did when you first started collaborating. Do not talk down to our
readers, but also do not assume they know everything about the subject. Offer
brief explanations or summaries of common knowledge if a significant portion of
readers might benefit.
Use simple words
================
Use simple words to increase reader comprehension and reduce ambiguity. Follow
our tips for making good word choices:
* **Avoid jargon**: Write for your audience, using everyday language where
possible, and technical terms where appropriate. Avoid clichés, idioms, and
metaphors.
* **Be consistent**: Use one term for each concept or action and use it
consistently.
* **Avoid "fancy" words and phrases**: If there is a simpler word or phrase,
use it.
For example:
=================== ===================
Use this Not this
=================== ===================
start, begin commence
so consequently
more than in excess of
if in the event of
before prior to
if you want should one wish
use utilize
example instance
=================== ===================
Avoid overuse of product name
=============================
Use product names only when necessary. Typically, you can rewrite sentences to
remove the product name with no change in meaning, which keeps the content
concise and scannable.
Avoid using the product name in page titles and headings.
.. _scannable-content:
Make content scannable
**********************
Organize your content to make it scannable for the reader, which helps them find
what they need quickly, and to understand the information more efficiently.
* **Put the most important content first.** Make sure your introduction clearly
communicates what the reader can find on the page. Present the point of the
document first, and organize supporting information towards the end of the
page.
* **Write scannable headings.** Expect readers of documentation to skim and scan
the content, and to leave if they dont find what they need quickly. Good
headings add organization to your content and help the reader to find and
understand content more effectively. Follow our guidelines for writing
effective `Headings`_.
* **Write great link text.** Great link text tells the reader what they can
expect when they click on a link. It also helps make the page more scannable.
Follow our guidelines for writing `Link text`_.
Headings
========
Use these guidelines to write effective headings:
* **Be concise and descriptive.** Use only the words necessary to describe the
section.
* **Use sentence case.** Capitalize only the first word and proper nouns in a
heading.
* **Avoid punctuation.** Unless your heading is a question, don't use sentence
punctuation in headings.
* **Use parallel structure.** Headings at the same level should use the same
grammatical pattern. This provides structure to the document and helps users
find information more easily. See :ref:`parallelism`.
* **Use strong verbs.** Strong, active verbs get to the point. Avoid -ing verbs,
such as *Running*, *Testing*, etc.
For example, two headings at the same level:
**Use this:** ::
Install software
Configure software
**Not this:** ::
Installing the Software on the Platform
Software Configuration.
Link text
=========
All links in content should follow these guidelines:
* **Write descriptive link text**: Link text should describe where the link
goes, without having to read the surrounding text.
* **Keep link text concise**: Use only the words needed to accurately describe
the destination.
* **Use unique link text**: Each link on a page should be unique. If users see
the same link text twice on a page, they'll assume it goes to the same place.
* **Start link text with keywords**: Frontload the link text with the most
important words to help users scan the text.
* **Avoid generic text**: Don't use generic, uninformative link text such as
"click here" or "read more".
For example:
**Use this:** ::
For more information about dogs, read the `dog wiki article`_.
**Not this:** ::
For more information about dogs, `click here`_.
Use strong verbs
****************
Passive verbs make writing stuffy and formal. Use strong verbs to get to the
point and avoid unnecessary words and phrases.
Use imperatives
===============
Commands, also called imperatives, are the fastest and most direct way of giving
someone instructions. For example:
**Use this:** ::
Send it to me.
**Not this:** ::
I would appreciate it if you would send it to me.
Use present tense
=================
Use simple present tense instead of future tense for most text. Search for the
words "will" or "shall" to find future tense instances. Future tense is
acceptable for conditional statements, such as in a caution or a warning. For
example:
**Use this:** ::
The system operates at a nominal temperature of 180 degrees Fahrenheit.
**Not this:** ::
The system will operate at a nominal temperature of 180 degrees Fahrenheit.
Avoid nominalizations
=====================
Avoid nominalizations, which are nouns formed from verbs.
For example:
===================== =====================
Verb Nominalization
===================== =====================
complete completion
provide provision
fail failure
install installation
===================== =====================
For example:
**Use this:** ::
We discussed the matter.
**Not this:** ::
We had a discussion about the matter.
Or:
**Use this:** ::
IT has installed the software.
**Not this:** ::
IT has completed the installation of the software.
Avoid words ending in -ing
==========================
Avoid using words ending in -ing unless they are part of a technical name. For
example:
**Use this:** ::
There is no way to verify this.
**Not this:** ::
There is no way of verifying this.
Use the active voice
====================
Use active voice whenever possible to show who or what is performing an
action.
* Active voice follows standard English word order: SUBJECT–VERB–OBJECT
(where the OBJECT is optional).
* Passive voice reverses the order and weakens the verb: OBJECT–be VERB–by
SUBJECT (where the OBJECT is optional).
For example:
**Use this:** ::
I made a mistake.
**Not this:** ::
A mistake was made. *(By whom?)*
Or:
**Use this:** ::
We released version 2.0 in June.
**Not this:** ::
Version 2.0 was released in June.
Avoid long noun phrases
***********************
Noun phrases (a noun and other words that describe or modify it) can be
difficult to understand. Try to limit the number of modifiers in a noun phrase
to two. For example:
**Use this:** ::
Integration policies for power management mechanisms.
**Not this:** ::
Power management mechanism integration policies.
.. _parallelism:
Parallelism
***********
Parallelism refers to the practice of using similar patterns of grammar, and
sometimes length, to coordinate words, phrases, and clauses.
Use parallel construction in lists. The table below shows some unparallel
structures and how they can be made parallel with a little rewording.
+----------------------------------+----------------------------------+
| Parallel (do) | Unparallel (don't) |
+==================================+==================================+
| 1. Mount the panel. | 1. Mount the panel. |
| 2. Install the battery. | 2. Battery installation. |
| 3. Wire the keypad. | 3. Wiring the keypad. |
+----------------------------------+----------------------------------+
| I like practicing my accordion, | I like practicing my accordion, |
| reading sci-fi, and eating | reading sci-fi, and to eat |
| peanut butter and pickle | peanut butter and pickle |
| sandwiches. | sandwiches. |
+----------------------------------+----------------------------------+
| For breakfast he likes coffee | For breakfast he likes coffee |
| and bacon. | and to fry bacon. |
+----------------------------------+----------------------------------+
| Apples or bananas are a good | Apples or a banana are a good |
| snack. | snack. |
+----------------------------------+----------------------------------+
Grammar and punctuation
***********************
This section covers common grammatical topics relevant to our
documentation. For detailed explanations of correct grammar and punctuation,
use one of our :ref:`preferred references <references>`.
Capitalization
==============
The capitalization style for all documentation is sentence case. Words should
only be capitalized when they are proper nouns or refer to trademarked product
names.
.. note::
Do not capitalize a word to indicate it is more important than other
words. Never change the case of variable, function or file names - always
keep the original case.
Menu capitalization
-------------------
When referring to software menu items by name, use the same capitalization as
seen in the actual menu.
A few other tips when referring to menu items:
* Reference the specific menu item using "Select :menuselection:`File --> New`."
* Put the option to be selected last. "Select
:menuselection:`View --> Side Bar --> Hide Side Bar`"
* Do not include more than 3 navigation steps in a menu selection. If
more than three steps are needed, divide the steps using
``:guilabel:`` or ``:menuselection:``.
For example: "Go to :guilabel:`File` and select
:menuselection:`Print --> Print Preview --> Set Up`."
Software version capitalization
-------------------------------
When listing software or hardware version numbers, the word “version” or letter
"v" are lowercase. The v is closed with the number (no period).
For example:
* Widget Pro version 5.0
* Widget Master v2.1.12
Contractions
============
Avoid using contractions, such as it's, they're, and you're, because they may be
unclear to non-native English-speaking audiences.
Quotation marks
===============
Follow these guidelines for quotation marks:
* Restrict use of quotation marks to terms as terms.
* Do not use quotation marks for emphasis; use *italics* for emphasis.
* Avoid using single-quote marks.
Commas and colons
=================
This section addresses common use of commas, semicolons, and colons in our
documentation. Refer to one of our :ref:`preferred references <references>`
for further details.
Use the serial comma
--------------------
When writing a series of items, use the serial comma before the final *and* and
*or* to avoid confusion and ambiguity. For example:
**Use this:** ::
Mom, Dad, and I are going to the game.
**Not this:** ::
Mom, Dad and I are going to the game.
.. _click here: https://en.wikipedia.org/wiki/Dog
.. _dog wiki article: https://en.wikipedia.org/wiki/Dog
source/clear-linux/reference/compatible-hardware.rst
+113
View File
@@ -0,0 +1,113 @@
.. _compatible-hardware:
Compatible Hardware
###################
This document describes hardware that has been tested and confirmed as
compatible with |CL-ATTR|. This list is not comprehensive and will continue to
grow.
.. list-table:: **Table 1. Compatible Hardware**
:widths: 20, 20
:header-rows: 1
* - Processor SKU
- Platform
* - Intel® Core™ i5-6260U
-
* - Intel® Core™ i5-6560U
- Dell XPS\* 13 9350
* - Intel® Celeron® J3455
- NUC6CAYS
* - Intel® Core™ i5-4250U
-
* - Intel® Core™ i7-5557U
-
* - Intel® Core™ i9-7900X
- Gigabyte\* X299
* - Intel® Core™ i3-4130
- Lenovo Thinkserver\* TS140
* - Intel® Core™ i7-7567U
- NUC7i7BNH
* - Intel® Core™ i7-8809G
- NUC8i7HVK
* - Intel® Core™ i5-7260U
- NUC7i5BNH
* - Intel® Core™ i7-8650U
- NUC7i7DNKE
* - Intel® Core™ i5-7300U
- NUC7i5DNHE
* - Intel® Xeon® Gold 6138
-
* - Intel® Xeon® E5-2699A v4
- Dell PowerEdge\* R630
* - Intel® Xeon® E5-2620 v3
-
* - Intel® Core™ i5-6600
- Gigabyte\* Z170X-UD5
* - Intel® Core™ i5-4250U
- D54250WYK
* - Intel® Xeon® E5-2699 v3
- S2600WT2
* - Intel® Atom™ J3455
- NUC6CAYB
* - Intel® Xeon® Bronze 3104
- 0W23H8
* - Intel® Atom™ C2750
- SuperMicro\* A1SAi
* - Intel® Atom™ E3825
- CircuitCo MinnowBoard MAX\*
* - Intel® Core™ i7-8700
- Gigabyte\* H370 WIFI
* - Intel® Core™ i7-3667U
- Lenovo ThinkPad\* X1 Carbon laptop
* - Intel® Core™ i5-4210U
- Dell XPS\* 13 laptop
* - Intel® Celeron® J3455
- NUC6CAYB
* - Intel® Core™ i7-4790
- Gigabyte\* desktop
* - Intel® Core™ i5-6260U
- NUC6I6SYH
* - Intel® Core™ i7-5557U
- NUC5I7RYH
* - Intel® Core™ i7-4700MQ
- Lenovo ThinkPad\* T540p
* - Intel® Core™ i7-5557U
- NUC5I7RYB
* - Intel® Core™ i5-6260U
- NUC6I5SYH
\* Other names and brands may be claimed as the property of others.
source/clear-linux/reference/compatible-kernels.rst
+91
View File
@@ -0,0 +1,91 @@
.. _compatible-kernels:
Compatible kernels
##################
The |CL-ATTR| provides the following Linux kernels with a respective bundle.
This document describes the specific use cases these `bundles`_ serve
and provides links to their source code.
Kernel native
=============
The *kernel-native* bundle focuses on the bare metal platforms. It is
optimized for fast booting and performs best on the Intel® architectures
described on the :ref:`supported hardware list<system-requirements>`. The
optimization patches are found in our `Linux`_ GitHub\* repo.
Kernel Container
================
The *kernel-container* bundle contains the kernel used by the
Intel® Clear Containers project. This kernel is optimized for
fast booting and performs best on |CC| running on the Intel® architectures
described on the :ref:`supported hardware list<system-requirements>`.
The optimization patches are found in our `Linux-Container`_ GitHub repo.
.. _vm-kernels:
Kernel LTS
==========
The *kernel-lts* bundle focuses on the bare metal platforms but uses the
latest :abbr:`LTS (Long Term Support)` Linux kernel. It is optimized for fast
booting and performs best on the Intel® architectures described on the
:ref:`supported hardware list<system-requirements>`. Additionally, this
kernel includes the VirtualBox\* kernel modules, see our
:ref:`instructions on using Virtualbox<virtualbox>` for more information.
The optimization patches are found in our `Linux-LTS`_ GitHub repo.
Kernel KVM
==========
The *kernel-kvm* bundle focuses on the Linux
:abbr:`KVM (Kernel-based Virtual Machine)`. It is optimized for fast booting
and performs best on Virtual Machines running on the Intel® architectures
described on the :ref:`supported hardware list<system-requirements>`.
Use this kernel when running |CL| as the guest OS on top of *qemu/kvm*. Use
this kernel with **cloud orchestrators** using *qemu/kvm* internally as
their **hypervisor**. This kernel can be used as a standalone |CL| VM, see
our :ref:`instructions on using KVM<kvm>` for more information. The
optimization patches are found in our `Linux-KVM`_ GitHub repo.
Kernel Hyper-V\*
================
The *kernel-hyperv* bundle focuses on running Linux on Microsoft\*
Hyper-V. It is optimized for fast booting and performs best on Virtual
Machines running on the Intel® architectures described on the
:ref:`supported hardware list<system-requirements>`.
Use this kernel when running |CL| as the guest OS of **Cloud Instances** in
projects such as Microsoft `Azure`_\*. This kernel can be used in a
standalone |CL| VM, see our :ref:`instructions on using Hyper-V<hyper-v>` for
more information. The optimization patches are found in our `Linux-HyperV`_
GitHub repo.
Kernel Hyper-V LTS
==================
The *kernel-hyperv-lts* bundle focuses on running Linux on Microsoft
Hyper-V but uses the latest :abbr:`LTS (Long Term Support)` Linux kernel. It
is optimized for fast booting and performs best on Virtual
Machines running on the Intel® architectures described on the
:ref:`supported hardware list<system-requirements>`.
Use this kernel when running |CL| as the guest OS of **Cloud Instances** in
projects such as Microsoft `Azure`_. This kernel can be used in a standalone
|CL| VM, see our :ref:`instructions on using Hyper-V<hyper-v>` for
more information. The optimization patches are found in our
`Linux-HyperV-LTS`_ GitHub repo.
.. _Linux: https://github.com/clearlinux-pkgs/linux
.. _Linux-LTS: https://github.com/clearlinux-pkgs/linux-lts
.. _Linux-KVM: https://github.com/clearlinux-pkgs/linux-kvm
.. _Linux-HyperV: https://github.com/clearlinux-pkgs/linux-hyperv
.. _Linux-HyperV-LTS: https://github.com/clearlinux-pkgs/linux-hyperv-lts
.. _Linux-Container: https://github.com/clearlinux-pkgs/linux-container
.. _bundles: https://github.com/clearlinux/clr-bundles
.. _CIAO: https://github.com/01org/ciao
.. _Azure:
https://azuremarketplace.microsoft.com/en-us/marketplace/apps/clear-linux-project.clear-linux-os
source/clear-linux/reference/how-to-clear-overview.rst
+46
View File
@@ -0,0 +1,46 @@
.. _how-to-clear-overview:
How to Clear training overview
##############################
The existing Linux\* ecosystem can be challenging to users because of long
intervals between :abbr:`OS (operating system)` updates, which leads to large
update downloads. Users can also be frustrated when managing complicated
component dependencies. |CL-ATTR| solves these problems by:
* Allowing you to update frequently, even multiple times per day
* Preventing you from combining incompatible components
The |CL| team delivers technology advances with the |CL| OS and its tooling,
concepts, and content. The team has created training materials as a GitHub\*
project to get you up and running quickly.
The training provides complete details on the methods used to create updates
and how to deploy the updates to targets. The following items provide an
overview of these |CL| mechanisms:
* Update server: an https-enabled web server where the content files are served
as static content. |CL| periodically queries the data on the update server and
determines whether updates are available. The update content files provide the
data and metadata to perform the required actions.
* Software delivery mechanism: :abbr:`swupd (software updater)`
queries metadata from the update server and calculates what to do and which
content to use.
* Tools: `mixer-tools` software suite generates the update server content using |CL|
official software update content, local bundle definitions, and local RPM files.
The training helps you create a customized OS that is based on |CL|. The
training content is self-contained and hosted on GitHub. You need a clean
|CL| installation and a functional network connection to complete the
training. For convenience, the project includes the training files you need
for the exercises.
We appreciate your feedback and comments, especially in the form of Pull
Requests. Please visit the `how-to-clear project`_ page to access the training
materials, open a ticket, or clone/branch the training and help us improve
|CL|.
.. _how-to-clear project: https://github.com/clearlinux/how-to-clear
source/clear-linux/reference/image-types.rst
+81
View File
@@ -0,0 +1,81 @@
.. _image-types:
|CL-ATTR| image types
#########################
.. _image-types-content:
|CL-ATTR| offers many types of `images`_ for different platforms and environments.
.. _incl-image-filename:
The naming convention of a |CL| image filename is:
.. code-block:: console
clear-[version number]-[image type].[compression type]
* The *[version number]* field specifies the version number.
* The *[image type]* field specifies the type of image and its corresponding
file format.
* The *[compression type]* field specifies the compression type. Two types of
compressions are used: GNU\* zip (*.gz*) and XZ (*.xz*).
.. _incl-image-filename-end:
Table 1 lists the currently available images that are platform independent.
Table 2 lists the currently available images that are platform specific.
.. list-table:: Table 1: Types of platform-independent |CL| images
:widths: 15, 85
:header-rows: 1
* - Image Type
- Description
* - installer.img
- Preferred image of |CL| with interactive installer.
* - installer.iso
- ISO of |CL| with interactive installer. Only for special cases where ISO image format is required (not for use with a USB key)
* - live.img
- Image for live booting into memory, without requiring installaton.
.. list-table:: Table 2: Types of platform-specific |CL| images
:widths: 15, 85
:header-rows: 1
* - Image Type
- Description
* - azure.vhd
- Virtual Hard Disk for use on Microsoft\* Azure\* cloud platform
* - azure-docker.vhd
- Virtual Hard Disk for use on Microsoft Azure cloud platform with Docker\* pre-installed
* - azure-machine-learning.vhd
- Virtual Hard Disk for use on Microsoft Azure cloud platform with the `machine-learning-basic` bundle installed
* - cloud.img
- Image for use by cloud deployments such as OpenStack\*
* - containers.img
- Image for use by Clear Containers runtime. Includes `optimized kernel`_ for Clear Containers.
* - hyperv.vhdx
- Virtual Hard Disk for use with Microsoft Hyper-V\* hypervisor. Includes `optimized kernel`_ for Hyper-V.
* - kvm.img
- Image for booting in a simple VM with start_qemu.sh. Includes
`optimized kernel`_ for KVM.
* - vmware.vmdk
- Virtual Machine Disk for VMware\* platforms inclduing Player, Workstation, and ESXi.
.. _images: https://cdn.download.clearlinux.org/image
.. _`optimized kernel`: https://clearlinux.org/documentation/clear-linux/reference/compatible-kernels
source/clear-linux/reference/reference.rst
+20
View File
@@ -0,0 +1,20 @@
.. _reference:
Reference
#########
This section provides additional information on the |CL| project and
features.
.. toctree::
:maxdepth: 1
compatible-hardware
bundle-commands
bundles/bundles
bundles/openssh-server
how-to-clear-overview
collaboration/collaboration
compatible-kernels
system-requirements
image-types
source/clear-linux/reference/system-requirements.rst
+45
View File
@@ -0,0 +1,45 @@
.. _system-requirements:
Recommended minimum system requirements
#######################################
|CL-ATTR| can run on very minimal hardware. For example, it can run on a
system with a single core CPU, 128MB of memory, and 600MB of disk space.
Different use cases and applications will require different configurations.
For general |CL| use, in addition to a supported processor, the recommended
minimum requirements include:
* Processors:
|CL-ATTR| can run on any Intel® 64bit processors which support UEFI\*
and SSE\* v4.1 streaming SIMD\* instructions.
The following processor families have been verified to run |CL|:
* 2nd Generation, or later, Intel® Core™ processor family.
* Intel® Xeon® Processor E3
* Intel® Xeon® Processor E5
* Intel® Xeon® Processor E7
* Intel® Atom™ processor C2000 product family for servers -- Q3 2013
version or later.
* Intel® Atom™ processor E3800 series -- Q4 2013 version or later.
To help determine if a processor is supported, you can run a
:ref:`compatibility check<compatibility-check>` or go to
http://ark.intel.com and check for these features:
* Instruction Set = 64-bit
* Instruction Set Extensions = SSSE3
* Instruction Set Extensions = SSE 4.1
* Instruction Set Extensions = SSE 4.2
* Instruction Set Extensions = AES
* Instruction Set Extensions = PCLMUL
* Memory: 4GB RAM
* Hard Disk: 20GB HDD
* Network: Active Internet connection
* Graphics: Intel HD Graphics (required if running a GUI desktop)