Revert "Add Example 5 for updating an existing package in autospec. (#827 )"

This reverts commit 7861c356db.
2026-09-05 21:31:30 +00:00 · 2019-09-27 14:48:05 -07:00
140 changed files with 977 additions and 4359 deletions
@@ -1,13 +0,0 @@
-name: Greetings
-
-on: [pull_request, issues]
-
-jobs:
-  greeting:
-    runs-on: ubuntu-latest
-    steps:
-    - uses: actions/first-interaction@v1
-      with:
-        repo-token: ${{ secrets.GITHUB_TOKEN }}
-        issue-message: 'Welcome to Clear Linux OS Docs. Thanks for submitting your first issue. :thumbsup:'
-        pr-message: 'Welcome to Clear Linux OS Docs. Thanks for submitting your first PR. :thumbsup:'
@@ -65,7 +65,7 @@ to view the rendered documentation.

 If you want to build the documentation exactly as seen on the website, use
 ``make py`` followed by ``make htmlall``. This builds some
-external dependencies and all supported languages.
+external dependenices and all supported languages.

 Additional help
 ***************
@@ -98,6 +98,6 @@ To stop the web server simply use ``ctrl-c``.
 .. _Clear Linux\* OS documentation:  https://docs.01.org/clearlinux/
 .. _Sphinx: http://sphinx-doc.org/
 .. _reStructuredText: http://www.sphinx-doc.org/en/master/usage/restructuredtext/basics.html
-.. _contribution guidelines: https://docs.01.org/clearlinux/latest/collaboration/collaboration.html
+.. _contribution guidelines: https://clearlinux.org/documentation/clear-linux/reference/collaboration
 .. _instructions for installing Sphinx: https://www.sphinx-doc.org/en/master/usage/installation.html

@@ -16,7 +16,7 @@ Why did you make another distro?
 ================================

 The |CL| team felt that performance was left on the table with Linux software.
-|CL| takes a holistic approach to improve performance across the stack. We
+|CL| takes a holistic approach to improving performance across the stack. We
 also wanted to take more modern approaches with OS updates and tooling.

 |
@@ -31,7 +31,7 @@ Yes, we absolutely love open source reuse and upstreaming improvements.
 How often do you update?
 ========================

-The |CL| team puts out multiple releases a week, often releasing two or more
+The |CL| team puts out multiple releases a week, often releasing 2 or more
 times a day. This rolling release approach allows |CL| to remain agile to
 upstream changes and security patches.

@@ -137,7 +137,7 @@ Is Microsoft\* Visual Studio Code\* available?

 Yes. Find the CLI command for installing `VS Code`_ and other Flatpak apps in
 the `software store`_. Installing Flatpak apps is also covered in our
-:ref:`tutorial <flatpak-tutorial>`.
+:ref:`tutorial <flatpak-tutorial>`. 

 The |CL| team is working on a natively packaged version of Visual Studio Code
 for future release.
@@ -1,79 +0,0 @@
-<!doctype html>
-<html lang="en">
-<head>
-    <meta charset="utf-8">
-    <title>Page Not Found</title>
-    <meta name="viewport" content="width=device-width, initial-scale=1">
-
-<script async="" src="https://www.google-analytics.com/analytics.js"></script><script>(function(i,s,o,g,r,a,m){i["GoogleAnalyticsObject"]=r;i[r]=i[r]||function(){(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)})(window,document,"script","https://www.google-analytics.com/analytics.js","ga");ga("create", "UA-61272224-1", {"cookieDomain":"auto","allowLinker":true});ga("require", "linker");ga("linker:autoLink", [/(community\.|www\.|^)clearlinux\.org/gi], true);ga("set", "anonymizeIp", true);ga("send", "pageview");</script>
-
-    <style>
-
-        * {
-            line-height: 1.2;
-            margin: 0;
-        }
-
-        html {
-            color: #404040;
-            display: table;
-            font-family: "Lato","proxima-nova","Helvetica Neue",Arial,sans-serif;
-            height: 100%;
-            text-align: center;
-            width: 100%;
-            background: #fcfcfc;
-        }
-
-        body {
-            display: table-cell;
-            vertical-align: middle;
-            margin: 2em auto;
-        }
-
-        h1 {
-            color: #555;
-            font-size: 2em;
-            font-weight: 400;
-            margin-bottom: 1em;
-        }
-
-        p {
-            margin: 1em auto;
-        }
-
-        input {
-        	padding: .3em .5em;
-        	font-size: 1em;
-        	background-color: #fff;
-        }
-
-        @media only screen and (max-width: 280px) {
-
-            body, p {
-                width: 95%;
-            }
-
-            h1 {
-                font-size: 1.5em;
-                margin: 0 0 0.3em;
-            }
-
-        }
-
-    </style>
-</head>
-<body>
-    <img src="https://docs.01.org/clearlinux/latest/_static/clearlinux.png" class="logo" alt="Logo">
-    <h1>403 Forbidden</h1>
-    <p>Sorry, looks like you don't have permission to access this page.</p>
-    <p>Please go back to the <a href="https://docs.01.org/clearlinux">documentation home page</a> or try searching:</p>
-
-    <div role="search">
-	  <form id="rtd-search-form" class="wy-form" action="https://docs.01.org/clearlinux/latest/search.html" method="get">
-	    <input type="text" name="q" id="clear-docs-search" placeholder="Search documentation" results="0">
-	    <input type="hidden" name="check_keywords" value="yes">
-	    <input type="hidden" name="area" value="default">
-	  </form>
-	</div>
-</body>
-</html>
@@ -1,79 +0,0 @@
-<!doctype html>
-<html lang="en">
-<head>
-    <meta charset="utf-8">
-    <title>Page Not Found</title>
-    <meta name="viewport" content="width=device-width, initial-scale=1">
-
-<script async="" src="https://www.google-analytics.com/analytics.js"></script><script>(function(i,s,o,g,r,a,m){i["GoogleAnalyticsObject"]=r;i[r]=i[r]||function(){(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)})(window,document,"script","https://www.google-analytics.com/analytics.js","ga");ga("create", "UA-61272224-1", {"cookieDomain":"auto","allowLinker":true});ga("require", "linker");ga("linker:autoLink", [/(community\.|www\.|^)clearlinux\.org/gi], true);ga("set", "anonymizeIp", true);ga("send", "pageview");</script>
-
-    <style>
-
-        * {
-            line-height: 1.2;
-            margin: 0;
-        }
-
-        html {
-            color: #404040;
-            display: table;
-            font-family: "Lato","proxima-nova","Helvetica Neue",Arial,sans-serif;
-            height: 100%;
-            text-align: center;
-            width: 100%;
-            background: #fcfcfc;
-        }
-
-        body {
-            display: table-cell;
-            vertical-align: middle;
-            margin: 2em auto;
-        }
-
-        h1 {
-            color: #555;
-            font-size: 2em;
-            font-weight: 400;
-            margin-bottom: 1em;
-        }
-
-        p {
-            margin: 1em auto;
-        }
-
-        input {
-        	padding: .3em .5em;
-        	font-size: 1em;
-        	background-color: #fff;
-        }
-
-        @media only screen and (max-width: 280px) {
-
-            body, p {
-                width: 95%;
-            }
-
-            h1 {
-                font-size: 1.5em;
-                margin: 0 0 0.3em;
-            }
-
-        }
-
-    </style>
-</head>
-<body>
-    <img src="https://docs.01.org/clearlinux/latest/_static/clearlinux.png" class="logo" alt="Logo">
-    <h1>404 Not Found</h1>
-    <p>Sorry, we didn't find the page you're looking for.</p>
-    <p>Please go back to the <a href="https://docs.01.org/clearlinux">documentation home page</a> or try searching:</p>
-
-    <div role="search">
-	  <form id="rtd-search-form" class="wy-form" action="https://docs.01.org/clearlinux/latest/search.html" method="get">
-	    <input type="text" name="q" id="clear-docs-search" placeholder="Search documentation" results="0">
-	    <input type="hidden" name="check_keywords" value="yes">
-	    <input type="hidden" name="area" value="default">
-	  </form>
-	</div>
-</body>
-</html>
@@ -12,8 +12,4 @@ https://www.intel.com/content/www/us/en/privacy/intel-privacy-notice.html
 http://www.intel.com/content/www/us/en/nuc/nuc-kit-nuc6i5syh.html
 https://software.intel.com/en-us/mkl
 https://www.intel.com/content/www/us/en/architecture-and-technology/turbo-boost/turbo-boost-technology.html
-https://www.nvidia.com/download/index.aspx
-https://www.intel.com/content/www/us/en/architecture-and-technology/optane-technology/optane-for-data-centers.html
-https://downloadcenter.intel.com/download/28695/Intel-Server-Board-S2600WF-Family-BIOS-and-Firmware-Update-Package-for-UEFI
-https://software.intel.com/en-us/articles/quick-start-guide-configure-intel-optane-dc-persistent-memory-on-linux
-https://software.intel.com/en-us/articles/configure-manage-and-profile-intel-optane-dc-persistent-memory-modules
+https://www.nvidia.com/download/index.aspx
@@ -119,8 +119,6 @@ th,td {
  padding-left: 0 !important;
 }

-/*Begin support for collapsbile sections*/
-
 .clps1 {
  font-size: 175%;
 }
@@ -175,29 +173,9 @@ th,td {

 .content-collapse {
  overflow: hidden;
-  /*transition: max-height 0.2s ease-out;*//*removed as it was breaking nested collapsible sections*/
+  transition: max-height 0.2s ease-out;
 }

-/*Fix for permalinks to collapsible sections*/
-
-button a.headerlink {
-  visibility: hidden;
-}
-
-button a.headerlink:after {
-  content: "\f0c1";
-  font-size: 14px;
-  font-family: FontAwesome;
-  font-weight: normal;
-}
-
-button:hover a.headerlink:after {
-  visibility: visible;
-}
-
-/*End support for collapsbile sections*/
-
-/*Begin support for custom Clear Linux header*/
 #header {
    width: 100%;
    display: block;
@@ -300,8 +278,6 @@ button:hover a.headerlink:after {
   line-height: 100px;
 }

-/*End support for custom Clear Linux header*/
-
 /*Adds a bit of spacing after the last paragraph in a bulleted list*/
 .wy-plain-list-disc li p:last-child, .rst-content .section ul li p:last-child, .rst-content .toctree-wrapper ul li p:last-child, article ul li p:last-child {
    margin-bottom: 10px;
@@ -315,7 +291,7 @@ div#trademarks {
    color: gray;
 }

-/*Adds magnifying glass to search box*/
+
 #clear-docs-search {
  background: url(./mag-glass.png) left no-repeat;
  background-size: 15px 15px;
@@ -336,187 +312,3 @@ div#trademarks {
 .pending-delete-status {
  color:#ce2029; 
 }
-
-/*Begin support for code blocks with $ signs that aren't copied with content*/
-
-.bash-dollar:before {
-  content: '$ ';
-}
-
-/*End support for code blocks with $ signs that aren't copied with content*/
-
-/*Begin support for labeled code-blocks - need to add an entry for every type of code-block that needs to be labeled*/
-
-div.highlight-powershell .highlight:before{
-  background: #909090;
-  color: white;
-  content: " PowerShell ";
-  font-family: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;
-  font-size: 14px;
-  white-space: pre;
-}
-
-div.highlight-python .highlight:before{
-  background: #909090;
-  color: white;
-  content: " Python ";
-  font-family: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;
-  font-size: 14px;
-  white-space: pre;
-}
-
-div.highlight-console .highlight:before{
-  background: #909090;
-  color: white;
-  content: " Console ";
-  font-family: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;
-  font-size: 14px;
-  white-space: pre;
-}
-
-div.highlight-rst .highlight:before{
-  background: #909090;
-  color: white;
-  content: " reStructuredText ";
-  font-family: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;
-  font-size: 14px;
-  white-space: pre;
-}
-
-div.highlight-rest .highlight:before{
-  background: #909090;
-  color: white;
-  content: " reStructuredText ";
-  font-family: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;
-  font-size: 14px;
-  white-space: pre;
-}
-
-div.highlight-yaml .highlight:before{
-  background: #909090;
-  color: white;
-  content: " yaml ";
-  font-family: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;
-  font-size: 14px;
-  white-space: pre;
-}
-
-div.highlight-bash .highlight:before{
-  background: #909090;
-  color: white;
-  content: " bash ";
-  font-family: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;
-  font-size: 14px;
-  white-space: pre;
-}
-
-div.highlight-diff .highlight:before{
-  background: #909090;
-  color: white;
-  content: " Diff ";
-  font-family: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;
-  font-size: 14px;
-  white-space: pre;
-}
-
-div.highlight-c .highlight:before{
-  background: #909090;
-  color: white;
-  content: " c ";
-  font-family: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;
-  font-size: 14px;
-  white-space: pre;
-}
-
-div.highlight-json .highlight:before{
-  background: #909090;
-  color: white;
-  content: " json ";
-  font-family: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;
-  font-size: 14px;
-  white-space: pre;
-}
-
-div.highlight-spec .highlight:before{
-  background: #909090;
-  color: white;
-  content: " spec ";
-  font-family: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;
-  font-size: 14px;
-  white-space: pre;
-}
-
-div.highlight-perl .highlight:before{
-  background: #909090;
-  color: white;
-  content: " Perl ";
-  font-family: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;
-  font-size: 14px;
-  white-space: pre;
-}
-
-div.highlight-php .highlight:before{
-  background: #909090;
-  color: white;
-  content: " php ";
-  font-family: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;
-  font-size: 14px;
-  white-space: pre;
-}
-
-div.highlight-xml .highlight:before{
-  background: #909090;
-  color: white;
-  content: " xml ";
-  font-family: SFMono-Regular,Menlo,Monaco,Consolas,"Liberation Mono","Courier New",Courier,monospace;
-  font-size: 14px;
-  white-space: pre;
-}
-
-div.linenodiv:before { /*add extra new line to make sure code and line numbers align*/
-   content: '\00000a';
-   white-space: pre;
-}
-
-/*End support for labeled code-blocks*/
-
-/*Begin support for multi-column sections*/
-
-.column {
-  float: left;
-  width: 350px;
-  padding: 10px;
-  margin: 10px;
-  border: 10px;
-  background: white;
-}
-
-.column.featurecard {
-  background: #CCE9F5;
-}
-
-.column.verticalcard {
-  height: 615px;
-  overflow: auto;
-}
-
-/* Clear floats after the columns */
-.multicolumns:after {
-  content: "";
-  display: table;
-  clear: both;
-}
-
-.colh2 {
-  font-size: 150%;
-  font-weight: 700;
-  font-family: "Roboto Slab","ff-tisa-web-pro","Georgia",Arial,sans-serif;
-}
-
-.video.docutils.container {
-  margin: 10px;
-  width:720px;
-  height:405px;
-}
-
-/*End support for multi-column sections*/
@@ -1,76 +1,50 @@
-var i;
-var contents = document.getElementsByClassName("content-collapse section");
-
-var bashDollarDivs = document.getElementsByClassName("bash-dollars highlight-bash"); 
-
-for (i = 0; i< bashDollarDivs.length; i++) {
-    _pre = bashDollarDivs[i].querySelectorAll("pre");
-    for (j = 0; j < _pre.length; j++) {
-      console.log(_pre[j]);
-      _pre[j].innerHTML="<span class='bash-dollar'>"+(_pre[j].textContent.split("\n").filter(Boolean).join("</span>\n<span class='bash-dollar'>"))+"</span>";
-    }
-}
-
-//needed for nested collapsible sections - otherwise the top container 
-//won't resize after expanding a child.
-function resetActiveCollapsedSections() {
-
-  var sections = document.getElementsByClassName("content-collapse section");
-
-  //for (i = 0; i < sections.length; i++) {
-  for (i = sections.length -1; i >= 0; i-- ){
-
-    if (sections[i].style.maxHeight != "0px"){
-       sections[i].style.maxHeight = sections[i].scrollHeight + "px";
-    }
-  }
-}
-
-for (i = 0; i < contents.length; i++) {
-
-  //Make sure the "content-collapse section" class is occurring in <div>
-  if (contents[i].tagName.toLowerCase() == 'div') {
-    var element = contents[i].children[0];
-    var element_type = element.tagName.toLowerCase();
-    var btn_id;
-    var divElement;
-
-    divElement = contents[i];
-    btn_id = contents[i].id;
-
-    //if the next element is a span skip to the header
-    if (element_type == 'span') {
-      element = contents[i].children[1];
-      element_type = element.tagName.toLowerCase();
-    } else {
-      divElement.id = "";
-    }
-
-    var btn = document.createElement("BUTTON");
-    //If it is a header capture which level and pass on to button
-    if (element_type.length == 2 && element_type[0] == 'h') {
-      var newClass = 'clps' + element_type[1];
-      //collapses the section by default only if javascript is working
-      contents[i].style.maxHeight = 0;
-      //Build the button and define behavior
-      btn.className += " " + newClass;
-      btn.innerHTML = element.innerHTML;
-      btn.className += " collapsible";
-      btn.id = btn_id;
-      btn.addEventListener("click", function() {
-        this.classList.toggle("active");
-        var content = this.nextElementSibling;
-        if (content.style.maxHeight != "0px"){
-          content.style.maxHeight = 0;
-        } else {
-          content.style.maxHeight = content.scrollHeight + "px";
-        } 
-        resetActiveCollapsedSections(); //reset the size of parent containers
-      });
-
-      //Add the button to the page and remove the header
-      contents[i].parentNode.insertBefore(btn, contents[i]);
-      contents[i].removeChild(element);
-    }
-  }
-}
+var i;
+var contents = document.getElementsByClassName("content-collapse section");
+
+for (i = 0; i < contents.length; i++) {
+
+  //Make sure the "content-collapse section" class is occurring in <div>
+  if (contents[i].tagName.toLowerCase() == 'div') {
+    var element = contents[i].children[0];
+    var element_type = element.tagName.toLowerCase();
+    var span_id;
+    var spanElement;
+
+    //if the next element is a span grab the id and skip to the header
+    if (element_type == 'span') {
+      span_id = element.id;
+      element.id = "";
+      element = contents[i].children[1];
+      element_type = element.tagName.toLowerCase();
+    }
+
+    var btn = document.createElement("BUTTON");
+    //If it is a header capture which level and pass on to button
+    if (element_type.length == 2 && element_type[0] == 'h') {
+      var newClass = 'clps' + element_type[1];
+      //collapses the section by default only if javascript is working
+      contents[i].style.maxHeight = 0;
+      //Build the button and define behavior
+      btn.className += " " + newClass;
+      btn.innerHTML = element.innerHTML;
+      btn.className += " collapsible";
+      btn.id = span_id;
+      btn.addEventListener("click", function() {
+        this.classList.toggle("active");
+        var content = this.nextElementSibling;
+        if (content.style.maxHeight != "0px"){
+          content.style.maxHeight = 0;
+        } else {
+          content.style.maxHeight = content.scrollHeight + "px";
+        } 
+      });
+
+      //Add the button to the page and remove the header
+      contents[i].parentNode.insertBefore(btn, contents[i]);
+      contents[i].removeChild(element);
+    }else{
+      //reset span id if it isn't followed by Hx element
+      spanElement.id = span_id;
+    }
+  }
+}
@@ -44,7 +44,7 @@ Ease of Use
  environments without needing to be configured.

 * Being :ref:`stateless` means that configuration settings are easier to manage
-  and remain untouched when system software is updated.
+  and remain untouched when system sofware is updated.

 * :ref:`swupd-guide` simplifies managing software and maintaining compatibility.

@@ -1,74 +0,0 @@
-.. _collaboration:
-
-Contribute
-##########
-
-There are multiple ways to help improve our documentation:
-
-* `Contribute via GitHub`_: Submit pull requests in the GitHub\* documentation
-  repository.
-* `Log an issue`_: Enter an issue in the documentation repository for
-  minor issues such as typos.
-* `Make a suggestion`_: Send your documentation suggestion to the mailing list.
-* Test documentation: Step through our guides and tutorials to verify the
-  instructions. `Log an issue`_ or `submit a pull request`_ with your findings.
-
-All contributions must follow our `code of conduct`_.
-
-Contribute via GitHub
-*********************
-
-Our documentation is hosted in GitHub and we follow the standard `GitHub flow`_.
-Here are the basic steps for contributing:
-
-#. 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.
-
-
-Contribution guidelines
-***********************
-
-The |CL| documentation is written using reStructuredText. Use our guidelines
-and best practices to write consistent, readable documentation.
-
-.. toctree::
-   :maxdepth: 1
-
-   Writing guide <writing-guide>
-   Structure and formatting guide <structure-formatting>
-
-.. _references:
-
-References
-**********
-
-We use the following references for grammar, style, and formatting:
-
-* `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
-.. _Make a suggestion: https://lists.clearlinux.org/postorius/lists/dev.lists.clearlinux.org/
-.. _GitHub flow: https://guides.github.com/introduction/flow/
-.. _Log an issue: https://github.com/clearlinux/clear-linux-documentation/issues
-.. _Contribute via GitHub: https://github.com/clearlinux/clear-linux-documentation
-.. _submit a pull request: https://github.com/clearlinux/clear-linux-documentation
-.. _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/
@@ -132,7 +132,6 @@ html_theme_options = {
  'navigation_depth': 4,
  'display_version': False,
  'collapse_navigation': False,
-  'prev_next_buttons_location': 'None',
  'sticky_navigation': True
 }

@@ -179,7 +178,7 @@ html_favicon = '_images/favicon.ico'
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied
 # directly to the root of the documentation.
-html_extra_path = ['_html_extra']
+#html_extra_path = []

 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
@@ -19,8 +19,6 @@ installation:
 * :ref:`system-requirements`
 * :ref:`compatibility-check`

-.. _preliminary-steps-install-desktop:
-
 Preliminary steps
 *****************

@@ -33,8 +31,13 @@ Preliminary steps

      <release-number> is the latest |CL| auto-numbered release.

-#. Follow your OS instructions to
-   :ref:`create a bootable usb drive <bootable-usb>`.
+#. Verify and decompress the file per your OS.
+
+   * :ref:`download-verify-decompress`
+
+#. Follow your OS instructions to create a bootable USB drive.
+
+   * :ref:`bootable-usb`

 .. _install-on-target-start:

@@ -58,8 +61,6 @@ these steps.

 #. Reboot the target system.

-.. _preliminary-steps-install-desktop-end:
-
 #. Select :guilabel:`Clear Linux OS` in the boot menu, shown in Figure 1.

   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-01.png
@@ -110,6 +111,20 @@ Launch the |CL| installer

 #. Select :guilabel:`Next`.

+Checking prerequisites
+======================
+
+The installer automatically launches :guilabel:`Checking Prerequisites`,
+which checks your target system for compatibility and network connectivity.
+
+After the installer shows `Prerequisites passed`, select :guilabel:`Next` to
+proceed with installation.
+
+.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-04.png
+   :scale: 100%
+   :alt: Checking Prerequisites
+
+   Figure 4: Checking Prerequisites

 Network Proxy (optional)
 ------------------------
@@ -150,16 +165,16 @@ To fulfill minimum installation requirements, complete the
 |CL| Desktop Installer
 **********************

-The |CL| Desktop Installer Main Menu appears as shown in Figure 4. To meet
+The |CL| Desktop Installer Main Menu appears as shown in Figure 5. To meet
 the minimum requirements, enter values in all submenus for the
 :guilabel:`Required options`. After you complete them, your selections appear
 below submenus and a check mark appears at right.

-.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-04.png
+.. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-05.png
   :scale: 100%
   :alt: Clear Linux OS Desktop Installer - Main Menu

-   Figure 4: Clear Linux OS Desktop Installer - Main Menu
+   Figure 5: Clear Linux OS Desktop Installer - Main Menu

 Navigation
 **********
@@ -188,11 +203,11 @@ Select Time Zone

 #. Select :guilabel:`Confirm`.

-   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-05.png
+   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-06.png
      :scale: 100%
      :alt: Select System Timezone

-      Figure 5: Select System Time Zone
+      Figure 6: Select System Time Zone

 Select Keyboard
 ===============
@@ -204,11 +219,11 @@ Select Keyboard

 #. Select :guilabel:`Confirm`.

-   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-06.png
+   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-07.png
      :scale: 100%
      :alt: Select Keyboard menu

-      Figure 6: Select Keyboard menu
+      Figure 7: Select Keyboard menu

 Select Installation Media
 =========================
@@ -218,11 +233,11 @@ Select Installation Media
 #. Choose an installation method: `Safe Installation`_ or
   `Destructive Installation`_.

-   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-07.png
+   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-08.png
      :scale: 100%
      :alt: Select Installation Media

-      Figure 7: Select Installation Media
+      Figure 8: Select Installation Media

 Safe Installation
 -----------------
@@ -253,21 +268,21 @@ For greater security, disk encryption is supported using LUKS. Encryption is
 optional.

 #. To encrypt the root partition, select :guilabel:`Enable Encryption`,
-   as shown in Figure 8.
-
-   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-08.png
-      :scale: 100%
-      :alt: Enable Encryption
-
-      Figure 8: Enable Encryption
-
-#. When :guilabel:`Encryption Passphrase` appears, enter a passphrase.
+   as shown in Figure 9.

   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-09.png
+      :scale: 100%
+      :alt: Enable Encryption
+
+      Figure 9: Enable Encryption
+
+#. When :guilabel:`Encryption Passphrase` appears, enter a passphrase.
+
+   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-10.png
      :scale: 100%
      :alt: Encryption Passphrase

-      Figure 9: Encryption Passphrase
+      Figure 10: Encryption Passphrase

   .. note::

@@ -295,22 +310,22 @@ Our example uses the `Default partition schema`_. The space you allocate for

 #. Select :guilabel:`Partition Media`, shown in Figure 11.

-   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-10.png
+   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-11.png
      :scale: 100%
      :alt: Advanced Installation

-      Figure 10: Advanced Installation
+      Figure 11: Advanced Installation

 boot partition
 --------------

 #. Select the available target media shown as `unallocated`.

-   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-11.png
+   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-12.png
      :scale: 100%
      :alt: Advanced Disk Partitioning

-      Figure 11: Advanced Disk Partitioning
+      Figure 12: Advanced Disk Partitioning

 #. Choose :menuselection:`Device --> Create Partition Table`.

@@ -326,18 +341,18 @@ boot partition
      The `/boot` partition must be `VFAT(FAT32)`.

 #. In :guilabel:`Create new Partition`, complete the following fields to
-   match Figure 12. Don't change other default values.
+   match Figure 13. Don't change other default values.

   * :guilabel:`New size:`                150
   * :guilabel:`Partition name:`          CLR_BOOT
   * :guilabel:`File system:`             fat32
   * :guilabel:`Label:`                   boot

-   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-12.png
+   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-13.png
      :scale: 100%
      :alt: boot partition

-      Figure 12: boot partition
+      Figure 13: boot partition

 #. Select :guilabel:`Add`.

@@ -348,18 +363,18 @@ swap partition
   :menuselection:`Partition --> New`.

 #. In :guilabel:`Create new Partition`, complete the following fields to
-   match Figure 13. Don't change other default values.
+   match Figure 14. Don't change other default values.

   * :guilabel:`New size:`                256
   * :guilabel:`Partition name:`          CLR_SWAP
   * :guilabel:`File system:`             linux-swap
   * :guilabel:`Label:`                   swap

-   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-13.png
+   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-14.png
      :scale: 100%
      :alt: swap partition

-      Figure 13: swap partition
+      Figure 14: swap partition

 #. Select :guilabel:`Add`.

@@ -370,7 +385,7 @@ root partition
   :menuselection:`Partition --> New`.

 #. In :guilabel:`Create new Partition`, complete the following fields to
-   match Figure 14. Don't change other default values.
+   match Figure 15. Don't change other default values.

 #. In :guilabel:`New size`, enter the desired size, or leave as is
   to accept the *default: remaining size*.
@@ -380,20 +395,20 @@ root partition
   * :guilabel:`File system:`             ext[234] or XFS
   * :guilabel:`Label:`                   root

-   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-14.png
+   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-15.png
      :scale: 100%
      :alt: root partition

-      Figure 14: root partition
+      Figure 15: root partition

 #. After all partitions are defined, verify your partition
-   configuration is similar to Figure 15.
+   configuration is similar to Figure 16.

-   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-15.png
+   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-16.png
      :scale: 100%
      :alt: Final partition configuration

-      Figure 15: Final partition configuration
+      Figure 16: Final partition configuration

 #. Select :menuselection:`Edit --> Apply All Operations`.

@@ -416,11 +431,11 @@ Manage User

 #. In :guilabel:`User Name`, enter a user name.

-   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-16.png
+   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-17.png
      :scale: 100%
      :alt: Manage User

-      Figure 16: Manage User
+      Figure 17: Manage User

 #. In :guilabel:`Login`, create a login name. It must start with a letter
   and can use numbers, hyphens, and underscores. Maximum length is 31
@@ -470,11 +485,11 @@ team for improvements.

 #. Select :kbd:`Yes`.

-   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-17.png
+   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-18.png
      :scale: 100%
      :alt: Enable Telemetry

-      Figure 17: Enable Telemetry
+      Figure 18: Enable Telemetry

 #. If you don't wish to participate, select :kbd:`No`.

@@ -490,31 +505,28 @@ after reboot.

   You can always add more bundles later with :ref:`swupd-guide`.

-Select Additional Bundles
-=========================
+Bundle Selection
+================

-This option is only available with a valid network connection.
-Bundle selection is disabled if no network connection exists.
-
-#. On the Advanced menu, select :guilabel:`Select Additional Bundles`.
+#. On the Advanced menu, select :guilabel:`Bundle Selection`

 #. Select your desired bundles.

-   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-18.png
+   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-19.png
      :scale: 100%
      :alt: Bundle Selection

-      Figure 18: Bundle Selection
+      Figure 19: Bundle Selection

 #. Select :kbd:`Confirm`.

 #. View the bundles that you selected.

-   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-19.png
+   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-20.png
      :scale: 100%
-      :alt: Select Additional Bundles
+      :alt: Bundle Selections - Advanced Options

-      Figure 19: Select Additional Bundles
+      Figure 20: Bundle Selections - Advanced Options

 Optional: Skip to `Finish installation`_.

@@ -525,11 +537,11 @@ Assign Hostname

 #. In :guilabel:`Hostname`, enter the hostname only (excluding the domain).

-   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-20.png
+   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-21.png
      :scale: 100%
      :alt: Assign Hostname

-      Figure 20: Assign Hostname
+      Figure 21: Assign Hostname

   .. note::

@@ -547,11 +559,11 @@ Kernel Configuration
 #. In :guilabel:`Kernel Configuration`, navigate to select your desired
   kernel. :guilabel:`Native` is selected by default.

-   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-21.png
+   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-22.png
      :scale: 100%
      :alt: Kernel Configuration

-      Figure 21: Kernel Configuration
+      Figure 22: Kernel Configuration

 #. To add arguments, enter the argument in :guilabel:`Add Extra Arguments`.

@@ -570,11 +582,11 @@ Software Updater Configuration
 #. :guilabel:`Enable Auto Updates` is selected by default. If you **do not**
   wish to enable automatic software updates, uncheck the box.

-   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-22.png
+   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-23.png
      :scale: 100%
      :alt: Software Updater Configuration

-      Figure 22: Software Updater Configuration
+      Figure 23: Software Updater Configuration

 #. Select :kbd:`Confirm`.

@@ -584,11 +596,11 @@ Finish installation
 #. When you are satisfied with your installation configuration, select
   :guilabel:`Install`.

-   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-23.png
+   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-24.png
      :scale: 100%
      :alt: Assign Hostname

-      Figure 23: Finish installation
+      Figure 24: Finish installation

   .. note:

@@ -597,13 +609,13 @@ Finish installation

 #. If you do not enter a selection for all :guilabel:`Required Options`,
   the :guilabel:`Install` button remains disabled, as shown
-   in Figure 24. Return to `Required Options`_ and make selections.
+   in Figure 25. Return to `Required Options`_ and make selections.

-   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-24.png
+   .. figure:: /_figures/bare-metal-install-desktop/bare-metal-install-desktop-25.png
      :scale: 100%
      :alt: Required Options - Incomplete

-      Figure 24: Required Options - Incomplete
+      Figure 25: Required Options - Incomplete

 #. After installation is complete, select :guilabel:`Exit`.

@@ -22,17 +22,16 @@ installation:
 Download the latest |CL| live server image
 ******************************************

-#. Visit our `Downloads`_ page.
+Get the latest |CL| installer image from the `Downloads`_ page. Look for the
+:file:`clear-[version number]-live-server.iso` file.

-#. Download the file :file:`clear-<release number>-live-server.iso`,
-   also called the |CL| Server.
+#. Verify and decompress the file per your OS.

-   .. note::
+   * :ref:`download-verify-decompress`

-      <release-number> is the latest |CL| auto-numbered release.
+#. Follow your OS instructions to create a bootable USB drive.

-#. Follow your OS instructions to
-   :ref:`create a bootable usb drive <bootable-usb>`.
+   * :ref:`bootable-usb`

 Install |CL| on your target system
 **********************************
@@ -468,99 +467,6 @@ be configured post-installation using the ``cryptsetup`` tool.

      :guilabel:`Confirm` is only highlighted if passphrases match.

-Manage User
-===========
-
-Add New User
------------
-
-#. In Required Options, select :guilabel:`Manage User`.
-
-#. Select :guilabel:`Add New User` as shown in Figure 18.
-
-   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-18.png
-      :scale: 100%
-      :alt: Add New User, User Name
-
-      Figure 18: Add New User
-
-#. Optional: Enter a :guilabel:`User Name`.
-
-   .. note:
-
-      The User Name must be alphanumeric and can include spaces, commas, underscores or hyphens. Maximum length is 64 characters.
-
-   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-19.png
-      :scale: 100%
-      :alt: User Name
-
-      Figure 19: User Name
-
-#. Enter a :guilabel:`Login`.
-
-   .. note::
-
-      The User Login must be alphanumeric and can include hyphens and underscores. Maximum length is 31 characters.
-
-#. Enter a :guilabel:`Password`.
-
-   .. note:
-
-      Minimum length is 8 characters. Maximum length is 255 characters.
-
-#. In :guilabel:`Confirm`, enter the same password.
-
-#. The :guilabel:`Administrator` checkbox is selected by default.
-
-   .. note::
-
-      Selecting Administrator enables sudo privileges for the user. For the installation to proceed, at least one user must be assigned as an Administrator.
-
-#. Select :kbd:`Confirm`. To reset the form, select :guilabel:`Reset`.
-
-#. In :guilabel:`Manage User`, navigate to :guilabel:`Confirm`.
-
-#. With :guilabel:`Confirm` highlighted, select :kbd:`Enter`.
-
-Modify / Delete User
--------------------
-
-#. In :guilabel:`Manage User`, navigate to the user you wish
-   to modify until highlighted, as shown in Figure 20.
-
-#. Select :kbd:`Enter` to modify the user.
-
-   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-20.png
-      :scale: 100%
-      :alt: Modify User
-
-      Figure 20: Modify User
-
-#. Modify user details as desired.
-
-#. Navigate to :kbd:`Confirm` until highlighted.
-
-   .. note::
-
-      Optional: Select :guilabel:`Reset` to rest the form.
-
-#. Select :guilabel:`Confirm` to save the changes you made.
-
-#. Optional: In :guilabel:`Modify User`, to delete the user, navigate to
-   the :guilabel:`Delete` button and select :kbd:`Enter`.
-
-   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-21.png
-      :scale: 100%
-      :alt: Delete User
-
-      Figure 21: Delete User
-
-You are returned to :guilabel:`Manage User`.
-
-#. Navigate to :kbd:`Confirm` until highlighted.
-
-#. Select :guilabel:`Enter` to complete :guilabel:`Manage User` options.
-
 Telemetry
 =========

@@ -576,18 +482,19 @@ Select your desired option on whether to participate in telemetry.

 #. Select :kbd:`Enter` to confirm.

-   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-22.png
+   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-18.png
      :scale: 100%
      :alt: Enable Telemetry

-      Figure 22: Enable Telemetry
+      Figure 18: Enable Telemetry

 Recommended options
 *******************

 After you complete the `Required options`_, we highly recommend completing
-some `Advanced options`_:
+these selected `Advanced options`_ at minimum:

+* `Manage User`_ Assign a new user with administrative rights
 * `Assign Hostname`_ Simplify your development environment

 Skip to finish installation
@@ -625,22 +532,22 @@ interface settings are automatically applied.

   .. note:: Multiple network interfaces may appear.

-   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-23.png
+   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-19.png
      :scale: 100%
      :alt: Configure Network Interfaces

-      Figure 23: Configure Network Interfaces
+      Figure 19: Configure Network Interfaces

 #. Notice :guilabel:`Automatic / dhcp` is selected by default (at bottom).

   Optional: Navigate to the checkbox :guilabel:`Automatic / dhcp` and select
   :kbd:`Spacebar` to deselect.

-   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-24.png
+   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-20.png
      :scale: 100%
      :alt: Network interface configuration

-      Figure 24: Network interface configuration
+      Figure 20: Network interface configuration

 #. Navigate to the appropriate fields and assign the desired
   network configuration.
@@ -676,11 +583,11 @@ instruction.

 #. Navigate to the field :guilabel:`HTTPS Proxy`.

-   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-25.png
+   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-21.png
      :scale: 100%
      :alt: Configure the network proxy

-      Figure 25: Configure the network proxy
+      Figure 21: Configure the network proxy

 #. Enter the desired proxy address and port using conventional syntax,
   such as: \http://address:port.
@@ -698,16 +605,13 @@ Test Network Settings
 To manually assure network connectivity before installing |CL|,
 select :guilabel:`Test Network Settings` and select :guilabel:`Enter`.

-.. note::
-   If using the :command:`off-line installer`, this option is not available.
+A progress bar appears as shown in Figure 22.

-A progress bar appears as shown in Figure 26.
-
-.. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-26.png
+.. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-22.png
   :scale: 100%
   :alt: Testing Networking dialog

-   Figure 26: Testing Networking dialog
+   Figure 22: Testing Networking dialog

 .. note::

@@ -716,23 +620,20 @@ A progress bar appears as shown in Figure 26.

 Optional: Skip to `Finish installation`_.

-Select Additional Bundles
-=========================
+Bundle Selection
+================

-This option is only available with a valid network connection.
-Bundle selection is disabled if no network connection exists.
-
-#. On the Advanced menu, select :guilabel:`Select Additional Bundles`.
+#. On the Advanced menu, select :guilabel:`Bundle Selection`

 #. Navigate to the desired bundle using :kbd:`Tab` or :kbd:`Up/Down` arrows.

 #. Select :kbd:`Spacebar` to select the checkbox for each desired bundle.

-   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-27.png
+   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-23.png
      :scale: 100%
      :alt: Bundle Selection

-      Figure 27: Bundle Selection
+      Figure 23: Bundle Selection

 #. Optional: To start developing with |CL|, we recommend
   adding :file:`os-clr-on-clr`.
@@ -743,6 +644,107 @@ Bundle selection is disabled if no network connection exists.

 Optional: Skip to `Finish installation`_.

+Manage User
+===========
+
+Add New User
+------------
+
+#. In Advanced Options, select :guilabel:`Manage User`.
+
+#. Select :guilabel:`Add New User` as shown in Figure 24.
+
+   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-24.png
+      :scale: 100%
+      :alt: Add New User, User Name
+
+      Figure 24: Add New User
+
+#. Optional: Enter a :guilabel:`User Name`.
+
+   .. note:
+
+      The User Name must be alphanumeric and can include spaces, commas, or
+      hyphens. Maximum length is 64 characters.
+
+   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-25.png
+      :scale: 100%
+      :alt: User Name
+
+      Figure 25: User Name
+
+#. Enter a :guilabel:`Login`.
+
+   .. note::
+
+      The User Login must be alphanumeric and can include hyphens and underscores. Maximum length is 31 characters.
+
+#. Enter a :guilabel:`Password`.
+
+   .. note:
+
+      Minimum length is 8 characters. Maximum length is 255 characters.
+
+#. In :guilabel:`Confirm`, enter the same password.
+
+#. Optional: Navigate to the :guilabel:`Administrative` checkbox and select
+   :kbd:`Spacebar` to assign administrative rights to the user.
+
+   .. note::
+
+      Selecting this option enables sudo privileges for the user.
+
+#. Select :kbd:`Confirm`.
+
+   .. note::
+
+      If desired, select :guilabel:`Reset` to reset the form.
+
+#. In :guilabel:`Manage User`, navigate to :guilabel:`Confirm`.
+
+#. With :guilabel:`Confirm` highlighted, select :kbd:`Enter`.
+
+Modify / Delete User
+--------------------
+
+#. In :guilabel:`Manage User`, navigate to the user you wish
+   to modify until highlighted, as shown in Figure 26.
+
+#. Select :kbd:`Enter` to modify the user.
+
+   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-26.png
+      :scale: 100%
+      :alt: Modify User
+
+      Figure 26: Modify User
+
+#. Modify user details as desired.
+
+#. Navigate to :kbd:`Confirm` until highlighted.
+
+   .. note::
+
+      Optional: Select :guilabel:`Reset` to rest the form.
+
+#. Select :guilabel:`Confirm` to save the changes you made.
+
+#. Optional: In :guilabel:`Modify User`, to delete the user, navigate to
+   the :guilabel:`Delete` button and select :kbd:`Enter`.
+
+   .. figure:: /_figures/bare-metal-install-server/bare-metal-install-server-27.png
+      :scale: 100%
+      :alt: Delete User
+
+      Figure 27: Delete User
+
+You are returned to :guilabel:`Manage User`.
+
+#. Navigate to :kbd:`Confirm` until highlighted.
+
+#. Select :guilabel:`Enter` to complete :guilabel:`Manage User` options.
+
+Optional: Skip to `Finish installation`_.
+
 Kernel Command Line
 ===================

@@ -840,7 +842,7 @@ Optional: Skip to `Finish installation`_.
 Automatic OS Updates
 ====================

-Automatic OS updates are enabled by default. In the rare case that you
+Automatical OS updates are enabled by default. In the rare case that you
 need to disable automatic software updates, follow the onscreen instructions,
 shown in Figure 32.

@@ -3,8 +3,8 @@
 Create a bootable USB drive
 ###########################

-Follow the instructions applicable to your system to create a bootable
-|CL-ATTR| USB drive:
+Follow the instructions applicable to your system to create a bootable |CL-ATTR|
+USB drive:

 * :ref:`bootable-usb-linux`
 * :ref:`bootable-usb-mac`
@@ -13,29 +13,34 @@ Follow the instructions applicable to your system to create a bootable
 Prerequisites
 *************

-* Download the |CL| Desktop or Server image from the `Downloads`_ page
-* Recommended minimum **4GB** USB drive or larger
+* Use an **8GB** or larger USB drive.
+* Download the |CL| live boot image or interactive installer image from the
+  `Downloads`_ page.

 .. _bootable-usb-linux:

 Create a bootable USB drive on Linux\*
 **************************************

-* Make sure you completed all `Prerequisites`_.
+Make sure you have completed all `Prerequisites`_.

-* :ref:`verify-linux` on Linux.
+Before burning the image onto your USB drive, :ref:`verify-linux` on Linux.

 Burn the |CL| image onto a USB drive
 ====================================

 .. caution::

-   Burning an image formats the USB drive and destroys all pre-existing
+   Burning an image formats the USB drive, and will destroy all pre-existing
   content.  Back up your data before proceeding.

-#. Open a terminal window.
+#. Open a terminal emulator and get root privilege.

-#. Change directory to where the image resides.
+   .. code-block:: bash
+
+      sudo -s
+
+#. Go to the directory with the decompressed image.

 #. Plug in the USB drive.

@@ -43,7 +48,7 @@ Burn the |CL| image onto a USB drive
   drives attached to the system, including the primary hard disk. In the
   example output below, there are 4 drives
   (`/dev/sda`, `/dev/sdb`, `/dev/sdc`, and `/dev/sdd`) attached, where
-   `/dev/sda` is the primary drive. The remaining are three USB drives. The output
+   `/dev/sda` is primary drive. The remaining are three USB drives. The output
   also shows the mounted partitions (under the `MOUNTPOINT` column) for each
   drive.

@@ -54,7 +59,6 @@ Burn the |CL| image onto a USB drive
   Example output:

   .. code-block:: console
-      :emphasize-lines: 1-5

      NAME   MAJ:MIN RM   SIZE RO TYPE MOUNTPOINT
      sdd      8:48   1    15G  0 disk
@@ -75,24 +79,22 @@ Burn the |CL| image onto a USB drive
      ├─sda8   8:8    0    30G  0 part /
      └─sda6   8:6    0   7.9G  0 part [SWAP]

-   .. note::
-
-      Some Linux distros may automatically mount a USB drive when it is plugged in.
-
-#. If the USB drive you want to use is mounted, it must be umounted before
-   burning an image onto it.  Use the :command:`umount` command followed by
-   the device identifier/partition. For example, to unmount all /dev/sdd
-   partitions:
+#. You must unmount a USB drive before burning an image onto it. Note that
+   some Linux distros automatically mount a USB drive when it is plugged in.
+   Unmount a USB drive with the :command:`umount` command followed by the device
+   identifier/partition. For example:

   .. code-block:: bash

-      sudo umount /dev/sdd*
+      umount /dev/sdd2
+      umount /dev/sdd3

-#. Burn the image onto the USB drive. The example below burns an image onto `<your USB device>`:
+#. Burn the image onto the USB drive. The example below burns an uncompressed
+   image onto `<your USB device>`:

   .. code-block:: bash

-      sudo dd if=./clear-[version number]-live-[desktop | server].iso of=<your USB device> oflag=sync bs=4M status=progress
+      dd if=./clear-[version number]-[image type] of=<your USB device> oflag=sync bs=4M status=progress

 .. caution::

@@ -105,21 +107,21 @@ Burn the |CL| image onto a USB drive
 Create a bootable USB drive on macOS\*
 **************************************

-* Make sure you completed all `Prerequisites`_.
+Make sure you have completed all `Prerequisites`_.

-* :ref:`verify-mac` on macOS.
+Before burning the image onto your USB drive, :ref:`verify-mac` on macOS.

 Burn the |CL| image onto a USB drive
 ====================================

 .. caution::

-   Burning an image formats the USB drive and destroys all pre-existing
+   Burning an image formats the USB drive, and will destroy all pre-existing
   content.  Back up your data before proceeding.

-#. Open a Terminal window.
+#. Launch the Terminal app.

-#. Change directory to where the image resides.
+#. Change directory to where the decompressed image is saved.

 #. Plug in a USB drive and get its identifier:

@@ -127,7 +129,7 @@ Burn the |CL| image onto a USB drive

      diskutil list

-   This lists available disks and their partitions, as shown in Figure 1.
+   This will list available disks and their partitions, as shown in Figure 1.

   .. figure:: /_figures/bootable-usb/bootable-usb-mac-01.png
      :scale: 100 %
@@ -135,22 +137,21 @@ Burn the |CL| image onto a USB drive

      Figure 1: macOS - Get USB drive identifier

-#. Unmount the USB drive identified in the previous step. For example, to unmount /dev/disk2:
+#. Unmount the USB drive identified in the previous step. For example:

   .. code-block:: bash

      diskutil umountDisk /dev/disk2

 #. Burn the image onto the drive using the :command:`dd` command.
-   This example uses `./`, your current directory, and it shows how to burn
-   an image onto `<your USB device>`:
+   This example uses `./`, your current directory, and it shows how to burn an uncompressed image onto `<your USB device>`:

   .. code-block:: bash

-      sudo dd if=./clear-[version number]-live-[desktop | server].iso of=<your USB device> bs=4m
+      sudo dd if=./clear-[version number]-[image type] of=<your USB device> bs=4m

   To accelerate the imaging process, add an ‘r’ before the disk identifier.
-   Example: `sudo dd if=./clear-30800-live-server.iso of=/dev/rdisk2 bs=4m`.
+   Example: `sudo dd if=./clear-30800-live-server of=/dev/rdisk2 bs=4m`.

   Press :kbd:`<CTRL>-T` to check imaging progress.

@@ -162,36 +163,29 @@ Burn the |CL| image onto a USB drive

 .. _bootable-usb-windows:

-Create a bootable USB drive on Windows
-**************************************
+Create a bootable USB drive on Windows\*
+****************************************

-* Make sure you completed all `Prerequisites`_.
+Make sure you have completed all `Prerequisites`_.

-* :ref:`verify-windows` on Windows\* OS.
+Before burning the image onto your USB drive, :ref:`verify-windows` on Windows.

 Burn the |CL| image onto a USB drive
 ====================================

 .. caution::

-   Burning an image formats the USB drive and destroys all pre-existing
+   Burning an image formats the USB drive, and will destroy all pre-existing
   content.  Back up your data before proceeding.

 #. Download the `Rufus`_ utility to burn the image onto a USB drive.
-   We use Rufus 3.5 for this example.
-   **Only use the latest version of Rufus**.
+   We use Rufus 3.5 here. **Only use the latest version of Rufus**.

-#. Plug in the USB drive.
-
-#. Launch Rufus.
-
-#. Under `Device`, select the USB drive.
+#. Plug in the USB drive and open Rufus.

 #. Under `Boot selection`, click the :guilabel:`SELECT` button.

-   .. note::
-
-      For other image tools, verify the `Volume label` is set to :guilabel:`CLR_ISO` **Do not change the label as installer relies on it.**
+#. Find and select the previously extracted |CL| image file.

 #. Click the :guilabel:`START` button. See Figure 2.

@@ -210,13 +204,7 @@ Burn the |CL| image onto a USB drive

      Figure 3: ISOHybrid image detected

-#. Click :guilabel:`OK`.
-
-#. The process make take more than a few minutes. When the process completes,
-   close Rufus.
-
-#. Select the Windows taskbar menu for USB and select
-   :guilabel:`Eject <drive name>`.
+#. Select the Windows taskbar menu for USB and select eject.

 .. _Rufus: https://rufus.ie/
 .. _Downloads: https://clearlinux.org/downloads
@@ -4,7 +4,7 @@ Check processor and EFI firmware compatibility
 ##############################################

 Before installing |CL-ATTR|, check your host system's processor and EFI firmware
-compatibility. To check compatibility, choose one of the following paths:
+compatibility. To check compatibilty, choose one of the following paths:

 * From a system with a Linux\* OS installed, follow the instructions to :ref:`check-compatibility-steps`.

@@ -4,7 +4,7 @@ Get started
 ###########

 The Get Started section guides you through the requirements and installation of
-|CL-ATTR|. Follow these step-by-step instructions to get started with |CL|, fast.
+|CL-ATTR|. Follow these step-by-step intructions to get started with |CL|, fast.

 Pre-install
 ***********
@@ -15,7 +15,7 @@ There are a couple of things to take care of before you install.
 * :ref:`compatibility-check`
 * :ref:`bootable-usb`

-When installing |CL-ATTR| in a VM, consider which kernel to use.
+When installing |CL-ATTR| in a VM, consider which kernel to use. 

 * :ref:`Compatible VM kernels <vm-kernels>`

@@ -55,4 +55,4 @@ Deploy to the cloud
   :maxdepth: 1
   :glob:

-   cloud-install/*
+   cloud-install/*
@@ -4,7 +4,7 @@
 ################################

 This page explains how to run a |CL-ATTR| :abbr:`VM (virtual machine)` on a
-Microsoft\* Hyper-V\* hypervisor.
+a Microsoft Hyper-V\* hypervisor.

 .. contents::
   :local:
@@ -15,41 +15,41 @@ Overview
 ********

 Hyper-V is a type 1 bare-metal hypervisor that runs directly on system
-hardware. It is available for `Windows\* server`_ and client operating systems,
-including `Windows 10`_.
+hardware.

-|CL| provides a virtual disk image for Hyper-V, which also includes
-a :ref:`Hyper-V specific kernel <compatible-kernels>` and drivers.
+Hyper-V is available both on server and client Windows operating systems as
+`Hyper-V on Windows Server`_ and `Hyper-V on Windows 10`_.

 Prerequisites
 *************

-* Enable virtualization on the host system from EFI/BIOS, such as:
+* Enable virtualization, such as `Intel® Virtualization Technology`_
+  (Intel® VT) and `Intel® Virtualization Technology for Directed I/O`_ (Intel®
+  VT-d), on the host system from EFI/BIOS.

-  * `Intel® Virtualization Technology`_ (Intel® VT)
-  * `Intel® Virtualization Technology for Directed I/O`_ (Intel® VT-d)
+* Hyper-V installed on a capable Windows operating system. Refer to the
+  Microsoft documentation on `Install the Hyper-V role on Windows Server`_ or
+  `Install Hyper-V on Windows 10`_.

-* Install Hyper-V on the appropriate Windows operating system:
-
-  * `Install the Hyper-V role on Windows Server`_
-  * `Install Hyper-V on Windows 10`_
-
-* Configure the appropriate virtual networking in Hyper-V:
-
-  * `Create a virtual network on Windows Server`_
-  * `Create a virtual network on Windows 10`_
+* Configure appropriate virtual networking in Hyper-V. Refer to the Microsoft
+  documentation on `Create a virtual network on Window Server`_ or `Create a
+  virtual network on Window 10`_.


 Download the |CL| disk image for Hyper-V
 ****************************************

-#. Download the :file:`clear-[VERSION]-hyperv.vhdx.gz` for Microsoft* Hyper-V
-   from the `downloads`_ website.
+|CL| provide a virtual disk image for Hyper-V with |CL| pre-installed. This
+includes a |CL| :ref:`Hyper-V specific kernel <compatible-kernels>` with
+Hyper-V Linux drivers ready-to-go. Get the latest |CL| image for Microsoft*
+Hyper-V from the `downloads`_ website. The file is named
+:file:`clear-[VERSION]-hyperv.vhdx.gz`.

-#. Verify and extract the image using these instructions:
-   :ref:`download-verify-decompress`.
+We also provide instructions for downloading and verifying a Clear Linux
+images. For more information, refer to :ref:`download-verify-decompress`.

-   After extraction, the file should be named :file:`clear-[VERSION]-hyperv.vhdx`.
+After extraction, the file should be named
+:file:`clear-[VERSION]-hyperv.vhdx`.


 Create and configure new VM
@@ -64,8 +64,9 @@ Create and configure new VM
   Figure 1: Hyper-V Manager from the Start menu


-#. Create a *New Virtual Machine* by clicking the :guilabel:`Action` menu,
-   then selecting :guilabel:`New` and :guilabel:`Virtual Machine...`.
+#. Create a *New Virtual Machine* by clicking the :guilabel:`Action` menu and
+   selecting the :guilabel:`New` submenu, and selecting :guilabel:`Virtual
+   Machine...`.

   .. figure:: figures/hyper-v/hyper-v-02.png
      :scale: 100%
@@ -76,55 +77,54 @@ Create and configure new VM
 #. Follow the *New Virtual Machine Wizard* to create a new virtual machine
   specifying the options below:

-   - **Name**: Choose name (for example, ClearLinuxOS-VM)
+   - **Name**: Choose name (e.g. ClearLinuxOS-VM).
   - **Generation**: Generation 2
   - **Startup memory**: 2048 MB or more
-   - **Connect Virtual Hard Disk**: Select :guilabel:`Use an existing virtual
+   - **Connect Virtual Hard Disk**: select :guilabel:`Use an existing virtual
     hard disk` and browse to find the :file:`clear-[VERSION]-hyperv.vhdx`
     file.

   After finishing the wizard, the VM will be created but not powered on.

-#. Configure the VM by right-clicking it in the Hyper-V Manager and selecting
-   :guilabel:`Settings...`.
-   Figure 3 shows the Settings page after configuration selections.
+#. Go to *Virtual Machine Settings* by right-clicking the newly created |CL|
+   VM in the Hyper-V Manager and selecting :guilabel:`Settings...`

   - Under :guilabel:`Firmware`, select the Virtual disk and click
-     :guilabel:`Move Up...` until it is at the top of the list.
+     :guilabel:`Move Up...` until it is at the top of the list. 

   - Under :guilabel:`Security`, uncheck the :guilabel:`Enable Secure Boot`
     checkbox.

   - Under :guilabel:`Processor`, consider increasing the number of virtual
-     processors assigned to the |CL| VM to improve performance.
+     processors assigned to the |CL| VM for performance.

   .. figure:: figures/hyper-v/hyper-v-03.png
      :scale: 100%
      :alt: |CL| VM Settings in Hyper-V Manager

-   Figure 3: |CL| VM Settings page after configuration
+   Figure 3: |CL| VM Settings page after selections

 #. Click :guilabel:`Apply` at the bottom of the VM Settings screen.

-#. Click :guilabel:`OK` at the bottom of the VM Settings screen.
+#. Click :guilabel:`OK` at the bottom of the VM Setting screen.


 Start the VM
 ************

 #. Start the |CL| VM by right-clicking the VM in Hyper-V Manager and selecting
-   :guilabel:`Start`.
+   :guilabel:`Start`

 #. Connect to the VM console by right-clicking the VM in Hyper-V Manager and
   selecting :guilabel:`Connect...`. A new *Virtual Machine Connection* window
-   is displayed.
+   will appear.

-#. After |CL| is booted, log in to the console with user *root*. You are
-   prompted to set a new password immediately.
+#. After |CL| is booted, login to the console with user *root*. You will be
+   prompted to set a new password immediately. 

   .. code-block:: console

-      > User: root
+      > User: root   

 |CL-ATTR| on Microsoft Hyper-V\* is ready for use.

@@ -135,13 +135,13 @@ Related topics



-.. _`Windows\* Server`: https://docs.microsoft.com/en-us/windows-server/virtualization/hyper-v/hyper-v-on-windows-server
-.. _`Windows 10`: https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/index
+.. _`Hyper-V on Windows Server`: https://docs.microsoft.com/en-us/windows-server/virtualization/hyper-v/hyper-v-on-windows-server
+.. _`Hyper-V on Windows 10`: https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/index
 .. _`Intel® Virtualization Technology`: http://www.intel.com/content/www/us/en/virtualization/virtualization-technology/intel-virtualization-technology.html
 .. _`Intel® Virtualization Technology for Directed I/O`: https://software.intel.com/en-us/articles/intel-virtualization-technology-for-directed-io-vt-d-enhancing-intel-platforms-for-efficient-virtualization-of-io-devices
 .. _`Install the Hyper-V role on Windows Server`: https://docs.microsoft.com/en-us/windows-server/virtualization/hyper-v/get-started/install-the-hyper-v-role-on-windows-server
 .. _Install Hyper-V on Windows 10: https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/enable-hyper-v
-.. _`Create a virtual network on Windows Server`: https://docs.microsoft.com/en-us/windows-server/virtualization/hyper-v/get-started/create-a-virtual-switch-for-hyper-v-virtual-machines
-.. _`Create a virtual network on Windows 10`: https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/connect-to-network
+.. _`Create a virtual network on Window Server`: https://docs.microsoft.com/en-us/windows-server/virtualization/hyper-v/get-started/create-a-virtual-switch-for-hyper-v-virtual-machines
+.. _`Create a virtual network on Window 10`: https://docs.microsoft.com/en-us/virtualization/hyper-v-on-windows/quick-start/connect-to-network
 .. _downloads: https://clearlinux.org/downloads

@@ -1,223 +0,0 @@
-.. _virt-manager:
-
-|CL-ATTR| using virt-manager
-############################
-
-This page explains how to create a |CL-ATTR| virtual machine using the
-`virt-mgr`_ desktop application with |CL| as the guest operating system.
-These instructions support the |CL| live-server installer to create the |CL|
-:abbr:`VM (Virtual Machine)`.
-
-.. contents::
-   :local:
-   :depth: 1
-
-Prerequisites
-*************
-
-#. Enable virtualization, such as `Intel® Virtualization Technology`_
-   (Intel® VT), on the host system from the UEFI firmware setup.
-
-#. Install the software bundles kvm-host and virt-manager-gui using
-   :command:`swupd`:
-
-   .. code-block:: bash
-
-      sudo swupd bundle-add kvm-host virt-manager-gui
-
-#. Add your userid to the `kvm` and `libvirt` groups.
-
-   .. code-block:: bash
-
-      sudo usermod -G kvm -a $USER
-      sudo usermod -G libvirt -a $USER
-
-#. Enable the `libvirtd` daemon and reboot the system to complete the
-   process.
-
-   .. code-block:: bash
-
-      sudo systemctl enable libvirtd
-      sudo reboot
-
-
-Download the |CL| installer ISO
-*******************************
-
-There are several options available to set up and use a |CL| VM with
-:command:`virt-manager`. You can either download the `KVM` image and run it
-as-is or download the installer ISO and run it to create a new installation of
-|CL|.
-
-This example uses the live-server-installer ISO to create a new installation.
-
-#. Download the `Clear Linux* OS Server` from the `Downloads`_ page.
-
-#. (Optional) Validate the integrity of the downloaded image by checking the
-   file hash and signatures. Refer to :ref:`validate-signatures` for detailed
-   steps.
-
-Launch and set up virt-manager
-******************************
-
-Virt-manager is a GUI-based virtual machine manager that runs in your desktop
-environment. This example uses the Gnome\* desktop.
-
-#. Launch the Virtual Machine Manager from the applications window. The
-   application window opens as shown in Figure 1.
-
-   .. figure:: figures/virtmgr/virt-manager-01.png
-      :scale: 100%
-      :alt: Virtual Machine Manager
-
-      Figure 1: Virtual Machine Manager
-
-#. In the `Name` field, select and highlight the `QEMU/KVM` item, then select
-   :menuselection:`Edit > Connection Details`. A dialog box with
-   `QEMU/KVM Connection Details` opens as shown in Figure 2.
-
-   .. figure:: figures/virtmgr/virt-manager-02.png
-      :scale: 100%
-      :alt: QEMU/KVM Connection Details
-
-      Figure 2: QEMU/KVM Connection Details
-
-#. On the `Overview` tab, check the `Autoconnect` field. Select the `Virtual
-   Networks` tab and in the lower left of the dialog window, select the
-   :guilabel:`+` key to add a new network connection. The `Create a new virtual
-   network` dialog window opens as shown in Figure 3. To accept the default
-   values, select the :guilabel:`Finish` button.
-
-   .. figure:: figures/virtmgr/virt-manager-03.png
-      :scale: 100%
-      :alt: Create a new virtual network
-
-      Figure 3: Create a new virtual network
-
-#. Close the `QEMU/KVM Connection details` dialog box and return to the Virtual
-   Machine Manager main console. You are ready to create your VM.
-
-Create a new virt-manager virtual machine
-*****************************************
-
-In the Virtual Machine Manager main console, either select
-:menuselection:`File > New Virtual Machine` or click the `Create a
-new virtual machine` icon. This launches the `New VM` wizard, shown in Figure 4.
-
-.. figure:: figures/virtmgr/virt-manager-04.png
-   :scale: 100%
-   :alt: New VM
-
-   Figure 4: New VM dialog box, step 1
-
-#. Select `Local install media (ISO image or CDROM)` and select the
-   :guilabel:`Forward` button.
-
-#. In step 2 of the `New VM` wizard, you can choose ISO or CDROM install
-   media.
-
-   a. Uncheck `Automatically detect from the installation media / source`
-      field and select the :guilabel:`Browse...` button as shown in Figure 5.
-
-      .. figure:: figures/virtmgr/virt-manager-05.png
-         :scale: 100%
-         :alt: New VM
-
-         Figure 5: New VM dialog box, step 2: Choose media
-
-   #. In the `Choose Storage Volume` dialog, select the
-      :guilabel:`Browse Local` button as shown in Figure 6. Browse to
-      the ISO image that you downloaded earlier and open it.
-
-      .. figure:: figures/virtmgr/virt-manager-06.png
-         :scale: 100%
-         :alt: Choose storage volume
-
-         Figure 6: Choose storage volume dialog box
-
-   #. In the `Choose the operating system you are installing` search field,
-      type `generic` and select the `Generic default` value when it is displayed.
-      Select the :guilabel:`Forward` button as shown in Figure 7.
-
-      .. figure:: figures/virtmgr/virt-manager-07.png
-         :scale: 100%
-         :alt: New VM
-
-         Figure 7: New VM dialog box, step 2: Choose operating system
-
-      .. note::
-
-         A message may be displayed that says the emulator does not have
-         search permissions for the ISO image path. Select :guilabel:`Yes` to
-         proceed to the next step.
-
-#. Step 3 of the `New VM` wizard allocates the memory and CPUs for
-   the new VM. Choose settings that are valid for the resources on your host
-   system. This example sets `Memory` to 2048GB and `CPUs` to 1. Once complete,
-   select the :guilabel:`Forward` button as shown in Figure 8.
-
-   .. figure:: figures/virtmgr/virt-manager-08.png
-      :scale: 100%
-      :alt: New VM Choose Memory and CPU settings dialog box
-
-      Figure 8: New VM dialog box, step 3: Choose Memory and CPU settings
-
-#. Step 4 of the `New VM` wizard sets up the storage media for your VM. You
-   can create a new disk image or use an existing image. This example selects
-   `Enable storage for this virtual machine` and creates a 20GB image for it.
-   Once complete, select the :guilabel:`Forward` button as shown in Figure 9.
-
-   .. figure:: figures/virtmgr/virt-manager-09.png
-      :scale: 100%
-      :alt: New VM Enable storage dialog box
-
-      Figure 9: New VM dialog box, step 4: Enable storage
-
-#. Step 5 of the `New VM` wizard displays the selections you made and allows
-   you to customize the configuration before running the installation. Select the
-   `Customize configuration before install` checkbox and select the
-   :guilabel:`Finish` button as shown in Figure 10.
-
-   .. figure:: figures/virtmgr/virt-manager-10.png
-      :scale: 100%
-      :alt: New VM Ready to begin the installation dialog box
-
-      Figure 10: New VM dialog box, step 5: Ready to begin the installation
-
-#. Customize the installation process by changing the firmware from `BIOS` to
-   `UEFI x86_64`. |CL| requires UEFI firmware. In the `Firmware` field, select
-   the :file:`UEFI x86_64:/usr/share/qemu/OVMF.fd` entry as shown in Figure 11
-   and select the :guilabel:`Apply` button.
-
-   .. figure:: figures/virtmgr/virt-manager-11.png
-      :scale: 100%
-      :alt: vm1 on QEMU/KVM dialog box
-
-      Figure 11: vm1 on QEMU/KVM dialog box
-
-#. Begin the installation by selecting the :guilabel:`Begin Installation` in
-   the upper left corner of the `vm1 on QEMU/KVM` dialog box.
-
-Install |CL| in the virt-manager VM
-***********************************
-
-To install |CL| in your VM, follow the instructions in the getting started
-guide :ref:`bare-metal-install-server`.
-
-.. note::
-
-   You do not need to set up the network as described in the installation
-   guide, because you already downloaded the ISO image and connected to your
-   VM. Your network will show up as a wired connection.
-
-Congratulations! You have successfully installed |CL| in your new VM and can
-begin using it immediately. The `virt-manager` tool is maintained on GitHub\*
-at `virt-manager-github`_.
-
-.. _virt-mgr: https://www.virt-manager.org
-
-.. _Downloads: https://clearlinux.org/downloads
-
-.. _virt-manager-github: https://github.com/virt-manager/virt-manager
-
-.. _Intel® Virtualization Technology: https://www.intel.com/content/www/us/en/virtualization/virtualization-technology/intel-virtualization-technology.html
@@ -44,45 +44,45 @@ For more information, refer to :ref:`download-verify-decompress`.
 Upload the |CL| installer ISO to the VMware server
 **************************************************

-#.  Connect to the VMware server and log into an account with sufficient
-    permission to create and manage VMs.
-#.  Under the :guilabel:`Navigator` window, select :guilabel:`Storage`.
+#.  Connect to the VMware server and log into an account with sufficient 
+    permission to create and manage VMs.  
+#.  Under the :guilabel:`Navigator` window, select :guilabel:`Storage`. 
    See Figure 1.
-#.  Under the :guilabel:`Datastores` tab, click the :guilabel:`Datastore browser`
-    button.
-
+#.  Under the :guilabel:`Datastores` tab, click the :guilabel:`Datastore browser` 
+    button.   
+    
    .. figure:: figures/vmware-esxi/vmware-esxi-install-cl-1.png
      :scale: 100 %
-      :alt: VMware ESXi - Navigator > Storage
+      :alt: VMware ESXi - Navigator > Storage 

-      Figure 1: VMware ESXi - Navigator > Storage
+      Figure 1: VMware ESXi - Navigator > Storage 

 #.  Click the :guilabel:`Create directory` button and name the directory `ISOs`.
    See Figure 2.

    .. figure:: figures/vmware-esxi/vmware-esxi-install-cl-2.png
      :scale: 100 %
-      :alt: VMware ESXi - Datastore > Create directory
-
-      Figure 2: VMware ESXi - Datastore > Create directory
+      :alt: VMware ESXi - Datastore > Create directory 

+      Figure 2: VMware ESXi - Datastore > Create directory 
+   
 #.  Select the newly-created directory and click the :guilabel:`Upload` button.
    See Figure 3.

    .. figure:: figures/vmware-esxi/vmware-esxi-install-cl-3.png
      :scale: 100 %
-      :alt: VMware ESXi - Datastore > Upload ISO
+      :alt: VMware ESXi - Datastore > Upload ISO 

-      Figure 3: VMware ESXi - Datastore > Upload ISO
-
-#.  Select the decompressed |CL| installer ISO file :file:`clear-[version number]-installer.iso`
+      Figure 3: VMware ESXi - Datastore > Upload ISO 
+   
+#.  Select the decompressed |CL| installer ISO file :file:`clear-[version number]-installer.iso` 
    and upload it.

 Create and configure a new VM
 *****************************

-In this section, you will create a new VM, configure its basic parameters such
-as drive size, number of CPUs, memory size, and then attach the |CL| installer ISO.
+In this section, you will create a new VM, configure its basic parameters such 
+as drive size, number of CPUs, memory size, and then attach the |CL| installer ISO. 

 #.  Under the :guilabel:`Navigator` window, select :guilabel:`Virtual Machines`.
    See Figure 4.
@@ -93,9 +93,9 @@ as drive size, number of CPUs, memory size, and then attach the |CL| installer I
      :alt: VMware ESXi - Navigator > Virtual Machines

      Figure 4: VMware ESXi - Navigator > Virtual Machines
-
+   
 #.  On the :guilabel:`Select creation type` step:
-
+    
    #.  Select the :guilabel:`Create a new virtual machine` option.
        See Figure 5.
    #.  Click the :guilabel:`Next` button.
@@ -105,11 +105,11 @@ as drive size, number of CPUs, memory size, and then attach the |CL| installer I
          :alt: VMware ESXi - Create a new virtual machine

          Figure 5: VMware ESXi - Create a new virtual machine
-
+   
 #.  On the :guilabel:`Select a name and guest OS` step:

    #.  Give the new VM a name in the :guilabel:`Name` field. See Figure 6.
-    #.  Set the :guilabel:`Compatibility` option to :guilabel:`ESXi 6.5 virtual machine`.
+    #.  Set the :guilabel:`Compatability` option to :guilabel:`ESXi 6.5 virtual machine`.
    #.  Set the :guilabel:`Guest OS family` option to :guilabel:`Linux`.
    #.  Set the :guilabel:`Guest OS version` option to :guilabel:`Other 3.x or later Linux (64-bit)`.
    #.  Click the :guilabel:`Next` button.
@@ -126,15 +126,15 @@ as drive size, number of CPUs, memory size, and then attach the |CL| installer I
    #.  Click the :guilabel:`Next` button.

 #.  On the :guilabel:`Customize settings` step:
-
+    
    #.  Click the :guilabel:`Virtual Hardware` button. See Figure 7.
-    #.  Expand the :guilabel:`CPU` setting and enable :guilabel:`Hardware virtualization` by
+    #.  Expand the :guilabel:`CPU` setting and enable :guilabel:`Hardware virtualization` by 
        checking :guilabel:`Expose hardware assisted virtualization to the guest OS`.

        .. figure:: figures/vmware-esxi/vmware-esxi-install-cl-7.png
          :scale: 100 %
          :alt: VMware ESXi - Enable hardware virtualization
-
+      
          Figure 7: VMware ESXi - Enable hardware virtualization

    #.  Set :guilabel:`Memory` size to 2048MB (2GB). See Figure 8.
@@ -145,12 +145,12 @@ as drive size, number of CPUs, memory size, and then attach the |CL| installer I

          Figure 8: VMware ESXi - Set memory size

-        .. note::
+        .. note:: 

          The |CL| installer ISO needs a minimum of 2GB of RAM to work properly.
-          You can reduce the memory size after the installation completes if you want,
+          You can reduce the memory size after the installation completes if you want, 
          because a minimum |CL| installation can function on as little as 128MB of RAM.
-          See :ref:`system-requirements` for more details.
+          See :ref:`system-requirements` for more details.  

    #.  Set :guilabel:`Hard disk 1` to the desired capacity. See Figure 9.

@@ -162,12 +162,12 @@ as drive size, number of CPUs, memory size, and then attach the |CL| installer I

        .. note::

-          A minimum |CL| installation can exist on 600MB of drive space.
-          See :ref:`system-requirements` for more details.
+          A minimum |CL| installation can exist on 600MB of drive space.  
+          See :ref:`system-requirements` for more details.       

-    #.  Attach the |CL| installer ISO.  For the :guilabel:`CD/DVD Drive 1` setting,
+    #.  Attach the |CL| installer ISO.  For the :guilabel:`CD/DVD Drive 1` setting, 
        click the drop-down list to the right of it and select the :guilabel:`Datastore ISO file`
-        option.  Then select the |CL| installer ISO :file:`clear-[version number]-installer.iso`
+        option.  Then select the |CL| installer ISO :file:`clear-[version number]-installer.iso` 
        that you previously uploaded to the VMware server. See Figure 10.

        .. figure:: figures/vmware-esxi/vmware-esxi-install-cl-10.png
@@ -183,13 +183,13 @@ Install |CL| into the new VM
 ****************************

 #.  Power on the VM.
-
+    
    #.  Under the :guilabel:`Navigator` window, select :guilabel:`Virtual Machines`.
        See Figure 11.
    #.  In the right window, select the newly-created VM.
-    #.  Click the :guilabel:`Power on` button.
+    #.  Click the :guilabel:`Power on` button.  
    #.  Click on the icon representing the VM to bring it into view and maximize
-        its window.
+        its window.  

        .. figure:: figures/vmware-esxi/vmware-esxi-install-cl-11.png
          :scale: 100 %
@@ -197,23 +197,23 @@ Install |CL| into the new VM

          Figure 11: VMware ESXi - Navigator > Virtual Machines > Power on VM

-#.  Follow the :ref:`install-on-target-start` guide to complete the installation of
+#.  Follow the :ref:`install-on-target-start` guide to complete the installation of 
    |CL|.
-#.  After the installation is complete, follow the |CL| instruction to reboot it.
-    This will restart the installer again.
+#.  After the installation is complete, follow the |CL| instruction to reboot it.  
+    This will restart the installer again. 

 Reconfigure the VM's settings to boot the newly-installed |CL|
 **************************************************************

 After |CL| has been installed using the installer ISO, it must be detached so
 it will not run again.  Also, in order to boot the newly-installed |CL|, you must
-enable UEFI support.
+enable UEFI support. 

 #.  Power off the VM.

-    #.  Click the :guilabel:`Actions` button - located on the top-right corner
-        of the VM's windows - and go to the :guilabel:`Power` setting and
-        select the :guilabel:`Power off` option. See Figure 12.
+    #.  Click the :guilabel:`Actions` button - located on the top-right corner 
+        of the VM's windows - and go to the :guilabel:`Power` setting and  
+        select the :guilabel:`Power off` option. See Figure 12. 

        .. figure:: figures/vmware-esxi/vmware-esxi-install-cl-12.png
          :scale: 100 %
@@ -223,7 +223,7 @@ enable UEFI support.

 #.  Edit the VM settings.

-    #.  Click the :guilabel:`Actions` button again and select :guilabel:`Edit settings`.
+    #.  Click the :guilabel:`Actions` button again and select :guilabel:`Edit settings`.  
        See Figure 13.

        .. figure:: figures/vmware-esxi/vmware-esxi-install-cl-13.png
@@ -233,9 +233,9 @@ enable UEFI support.
          Figure 13: VMware ESXi - Actions > Edit settings

 #.  Disconnect the CD/DVD to stop it from booting the |CL| installer ISO again.
-
+    
    #.  Click the :guilabel:`Virtual Hardware` button.  See Figure 14.
-    #.  For the :guilabel:`CD/DVD Drive 1` setting, uncheck the
+    #.  For the :guilabel:`CD/DVD Drive 1` setting, uncheck the 
        :guilabel:`Connect` checkbox.

        .. figure:: figures/vmware-esxi/vmware-esxi-install-cl-14.png
@@ -248,7 +248,7 @@ enable UEFI support.

    #.  Click the :guilabel:`VM Options` button. See Figure 15.
    #.  Expand the :guilabel:`Boot Options` setting.
-    #.  For the :guilabel:`Firmware` setting, click the drop-down list to the right
+    #.  For the :guilabel:`Firmware` setting, click the drop-down list to the right 
        of it and select the :guilabel:`EFI` option.

        .. figure:: figures/vmware-esxi/vmware-esxi-install-cl-15.png
@@ -262,14 +262,14 @@ enable UEFI support.
 Power on the VM and boot |CL|
 *****************************

-After configuring the settings above, power on the VM.
+After configuring the settings above, power on the VM.  

 #.  Under the :guilabel:`Navigator` window, select :guilabel:`Virtual Machines`.
    See Figure 16.
 #.  In the right window, select the VM.
-#.  Click the :guilabel:`Power on` button.
+#.  Click the :guilabel:`Power on` button.  
 #.  Click on the icon representing the VM to bring it into view and maximize
-    its window.
+    its window.  

    .. figure:: figures/vmware-esxi/vmware-esxi-install-cl-16.png
      :scale: 100 %
@@ -20,7 +20,7 @@ and run |CL-ATTR| virtual machines at scale.
 We provide a pre-configured |CL| VMware image that can be run on a VMware ESXi
 6.5 host.

-If manual installation is preferred, refer to :ref:`vmware-esxi-install-cl`.
+If manuall installation is preferred, refer to :ref:`vmware-esxi-install-cl`.

 .. note::

@@ -47,8 +47,8 @@ For more information, refer to :ref:`download-verify-decompress`.
 Upload the |CL| image to the VMware server
 ******************************************

-Once the |CL| VMware prebuilt image has been downloaded and
-decompressed on your local system, it must be uploaded to a datastore
+Once the |CL| VMware prebuilt image has been downloaded and 
+decompressed on your local system, it must be uploaded to a datastore 
 on the VMware ESXi server.

 The steps in this section can also be referenced from the VMware documentation
@@ -57,11 +57,11 @@ The steps in this section can also be referenced from the VMware documentation
 #. Connect to the VMware ESXi server and login to an account with sufficient
   permission to create and manage VMs.

-#. Under the :guilabel:`Navigator` window on the left side,
+#. Under the :guilabel:`Navigator` window on the left side, 
   select :guilabel:`Storage`.
   See Figure 1

-#. Under the :guilabel:`Datastores` tab, click
+#. Under the :guilabel:`Datastores` tab, click 
   the :guilabel:`Datastore browser` button.

   .. figure:: figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-1.png
@@ -95,8 +95,8 @@ Convert the |CL| image to an ESXi-supported format
 **************************************************

 Once the |CL| VMware prebuilt image has been uploaded to the VMware ESXi
-datastore, it must be converted to a format for use with VMware's ESXi
-hypervisor.
+datastore, it must be converted to a format for use with VMware's ESXi 
+hypervisor. 

 The steps in this section can also be referenced from the VMware documentation on `Cloning and converting virtual machine disks with vmkfstools`_

@@ -105,11 +105,11 @@ The steps in this section can also be referenced from the VMware documentation o

   .. note::

-      If there is no :abbr:`vMA (vSphere Management Assistant)` appliance or :abbr:`vCLI (vSphere CLI)` configured and available,
+      If there is no :abbr:`vMA (vSphere Management Assistant)` appliance or :abbr:`vCLI (vSphere CLI)` configured and available, 
      you can temporarily enable SSH directly on the ESXi host by following the
      steps described in `Enable the Secure Shell (SSH) in the VMware Host Client`_.

-      As a security best practice, remember to disable SSH access after following the steps in this section.
+      As a security best practice, remember to disable SSH access after following the steps in this section. 


 #. Locate the uploaded image, which is typically found in
@@ -134,10 +134,10 @@ Create and configure a new VM
 *****************************

 In this section, you will create a new VM, configure its basic parameters
-such as number of CPUs, memory size, and then attach the converted |CL|
-VMware image. Also, in order to boot |CL|, you must enable UEFI support.
+such as number of CPUs, memory size, and then attach the converted |CL| 
+VMware image. Also, in order to boot |CL|, you must enable UEFI support. 

-#. Under the :guilabel:`Navigator` window, select
+#. Under the :guilabel:`Navigator` window, select 
   :guilabel:`Virtual Machines`. See Figure 4.

 #. In the right window, click the :guilabel:`Create / Register VM` button.
@@ -165,10 +165,10 @@ VMware image. Also, in order to boot |CL|, you must enable UEFI support.

 #. Give the new VM a name in the :guilabel:`Name` field. See Figure 6.

-#. Set the :guilabel:`Compatibility` option to
+#. Set the :guilabel:`Compatability` option to
   :guilabel:`ESXi 6.5 virtual machine`.
 #. Set the :guilabel:`Guest OS family` option to :guilabel:`Linux`.
-#. Set the :guilabel:`Guest OS version` option to
+#. Set the :guilabel:`Guest OS version` option to 
   :guilabel:`Other 3.x or later Linux (64-bit)`.
 #. Click the :guilabel:`Next` button.

@@ -186,8 +186,8 @@ VMware image. Also, in order to boot |CL|, you must enable UEFI support.
 #. On the :guilabel:`Customize settings` step:

   #. Click the :guilabel:`Virtual Hardware` button. See Figure 7.
-   #. Expand the :guilabel:`CPU` setting and enable
-      :guilabel:`Hardware virtualization` by checking
+   #. Expand the :guilabel:`CPU` setting and enable 
+      :guilabel:`Hardware virtualization` by checking 
      :guilabel:`Expose hardware assisted virtualization to the guest OS`.

   .. figure:: figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-7.png
@@ -205,8 +205,8 @@ VMware image. Also, in order to boot |CL|, you must enable UEFI support.

      Figure 8: VMware ESXi - Remove hard drive

-   #. Since a pre-configured image will be used,
-      the :guilabel:`CD/DVD Drive 1` setting will not be needed.  Disable it
+   #. Since a pre-configured image will be used, 
+      the :guilabel:`CD/DVD Drive 1` setting will not be needed.  Disable it 
      by unchecking the :guilabel:`Connect` checkbox. See Figure 9.

   .. figure:: figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-9.png
@@ -228,14 +228,14 @@ VMware image. Also, in order to boot |CL|, you must enable UEFI support.
      Figure 10: VMware ESXi - Add an existing hard drive

      #. Select the converted :file:`clear-[version number]-esxi.vmdk`
-         file. Do not use the original unconverted
+         file. Do not use the original unconverted 
         :file:`clear-[version number]-vmware.vmdk` file. See Figure 11.

   .. figure:: figures/vmware-esxi/vmware-esxi-preconfigured-cl-image-11.png
      :scale: 100 %
      :alt: VMware ESXi - Select the converted `vmdk` file

-      Figure 11: VMware ESXi - Select the converted
+      Figure 11: VMware ESXi - Select the converted 
      :file:`clear-[version number]-esxi.vmdk` file

 #. |CL| needs UEFI support in order to boot.  Enable UEFI boot support.
@@ -260,7 +260,7 @@ Power on the VM and boot |CL|

 After configuring the settings above, power on the VM.

-#. Under the :guilabel:`Navigator` window, select
+#. Under the :guilabel:`Navigator` window, select 
   :guilabel:`Virtual Machines`. See Figure 13.
 #. In the right window, select the newly-created VM.
 #. Click the :guilabel:`Power on` button.
@@ -54,16 +54,16 @@ environment settings are respected and no time is wasted trying to resolve a
 proxy. All these steps happen in the background with no user interaction.

 Troubleshooting
-***************
+===============

 Autoproxy allows |CL| to operate seamlessly behind a proxy
 because :ref:`swupd <swupd-guide>` and other |CL| tools are implemented on
 top of libcurl. Tools that do not use libcurl, like git, must
-be configured independently.
+be configured independently. 

 If you are familiar with PAC files and WPAD, you can use
 :command:`pacdiscovery` and :command:`FindProxyForURL` to
-troubleshoot problems with autoproxy.
+troubleshoot problems with autproxy.

 .. note::

@@ -71,29 +71,24 @@ troubleshoot problems with autoproxy.

 .. _findproxyforurl: http://findproxyforurl.com/

+Run :command:`pacdiscovery` with no arguments to indicate

-Run :command:`pacdiscovery` with no arguments to indicate |br|
-
-#. if there is a problem resolving the :command:`WPAD` host name resolution:
+1. if there is a problem resolving the :command:`WPAD` host name resolution: 

   .. code-block:: bash

-      sudo pacdiscovery
-
-   Sample output:
+      pacdiscovery

   .. code-block:: console

      failed getaddrinfo: No address associated with hostname
      Unable to find wpad host

-#. or if the :command:`pacrunner` service is disabled (masked).
+2. or if the :command:`pacrunner` service is disabled (masked).

   .. code-block:: bash

-      sudo pacdiscovery
-
-   Sample output:
+      pacdiscovery

   .. code-block:: console

@@ -104,65 +99,55 @@ Unmask the :command:`pacrunner` service by running:

 .. code-block:: bash

-   sudo systemctl unmask pacrunner.service
+   systemctl unmask pacrunner.service

+:command:`FindProxyForURL` with :command:`busctl` can also indicate if the
+:command:`pacrunner.service` is masked.

+.. code-block:: bash

-Use :command:`FindProxyForURL` with :command:`busctl` to indicate |br|
+   busctl call org.pacrunner /org/pacrunner/client org.pacrunner.Client 

-#. the URL and port of the proxy server when an external URL and host are
-   provided as arguments:
+.. code-block:: console
+   
+   FindProxyForURL ss "http://www.google.com" "google.com"
+   Unit pacrunner.service is masked.
+   dig wpad, dig wpad.<domain>

-   .. code-block:: bash
+:command:`FindProxyForURL` returns the URL and port of the proxy server when
+an external URL and host are provided as arguments.

-      busctl call org.pacrunner /org/pacrunner/client org.pacrunner.Client FindProxyForURL ss "http://www.google.com" "google.com"
+.. code-block:: bash

-   Sample output showing proxy was found:
+   busctl call org.pacrunner /org/pacrunner/client org.pacrunner.Client 

-   .. code-block:: console
+.. code-block:: console

-      s "PROXY proxy.your.domain.com:<port>"
+   FindProxyForURL ss "http://www.google.com" "google.com"
+   s "PROXY proxy.your.domain.com:<port>"

-#. if the :command:`pacrunner.service` is masked:
+If a proxy server is not avialable, or if :command:`pacrunner` is running
+without a PAC file, :command:`FindProxyForURL` will return "DIRECT". 

-   .. code-block:: bash
+.. code-block:: bash

-      busctl call org.pacrunner /org/pacrunner/client org.pacrunner.Client FindProxyForURL ss "http://www.google.com" "google.com"
+   busctl call org.pacrunner /org/pacrunner/client org.pacrunner.Client 

-   Sample output:
+.. code-block:: console 

-   .. code-block:: console
-
-      Unit pacrunner.service is masked.
-      dig wpad, dig wpad.<domain>
-
-#. if a proxy server is not available, or if :command:`pacrunner` is running
-   without a PAC file:
-
-   .. code-block:: bash
-
-      busctl call org.pacrunner /org/pacrunner/client org.pacrunner.Client FindProxyForURL ss "http://www.google.com" "google.com"
-
-   Sample output, indicating connection made directly, without proxy:
-
-   .. code-block:: console
-
-      s "DIRECT"
+   FindProxyForURL ss "http://www.google.com" "google.com"
+   s "DIRECT"

 Once :command:`pacdiscovery` is able to look up :command:`WPAD`, restart the
 :command:`pacrunner` service:

 .. code-block:: bash

-   sudo systemctl stop pacrunner
-   sudo systemctl restart pacdiscovery
+   systemctl stop pacrunner
+   systemctl restart pacdiscovery

 .. note::

   A "domain" or "search" entry in :file:`/etc/resolv.conf` is required
   for short name lookups to resolve. The :file:`resolv.conf` man page has
-   additional details.
-
-.. |br| raw:: html
-
-   <br><br>
+   additional details.
@@ -16,22 +16,19 @@ tarball and package name to start.
 Description
 ***********

-The autospec tool attempts to infer the requirements of the :file:`.spec`
-file by analyzing the source code and :file:`Makefile` information. It
-continuously runs updated builds based on new information discovered from
-build failures until it has a complete and valid :file:`.spec` file. If
-needed, you can influence the behavior of autospec and customize the build by providing optional `control files`_ to the autospec tool.
+The autospec tool attempts to infer the requirements of the :file:`.spec` file
+by analyzing the source code and :file:`Makefile` information. It 
+continuously runs updated builds based on new information discovered from build
+failures until it has a complete and valid :file:`.spec` file. If needed, you
+can influence the behavior of autospec and customize the build by providing
+optional `control files`_ to the autospec tool.

-autospec uses **mock** as a sandbox to run the builds. Visit the `mock wiki`_
-for additional information on using mock.
+autospec uses **mock** as a sandbox to run the builds. Visit the `mock wiki`_ for
+additional information on using mock.

-For a general understanding of how an RPM works, visit
+For a general understanding of how an RPM works, visit 
 the `rpm website`_ or the `RPM Packaging Guide`_.

-.. raw:: html
-
-   <iframe width="560" height="315" src="https://www.youtube.com/embed/qrUpt1D1YAw" frameborder="0" allow="accelerometer; autoplay; encrypted-media; gyroscope; picture-in-picture" allowfullscreen style="padding:10px; background-color: #fff;"></iframe>
-
 How it works
 ************

@@ -55,11 +52,13 @@ Create an RPM

 The basic autospec process is described in the following steps:

-#. The :command:`make autospec` command generates a :file:`.spec` file based
-   on the analysis of code and existing control files.
+#. The :command:`make autospec` command generates a :file:`.spec` file based on
+   the analysis of code and existing control files.

   Any control files should be located in the same directory as the resulting
-   :file:`.spec` file. View the `autospec README`_ for more information on `control files`_.
+   :file:`.spec` file.
+
+   View the `autospec README`_ for more information on `control files`_.

 #. autospec creates a build root with mock config.

@@ -100,8 +99,8 @@ Complete `Setup environment to build source`_ before using these examples.
 Example 1: Build RPM with an existing spec file
 ===============================================

-This example shows how to build a RPM from a pre-packaged upstream package
-with an existing spec file. The example uses the ``dmidecode`` package.
+This example shows how to build a RPM from a pre-packaged upstream package with
+an existing spec file. The example uses the ``dmidecode`` package.

 #. Navigate to the autospec workspace and clone the ``dmidecode`` package:

@@ -130,8 +129,8 @@ with an existing spec file. The example uses the ``dmidecode`` package.
      cd ~/clearlinux/packages/dmidecode/
      make build

-#. The resulting RPMs are in :file:`./rpms`. Build logs and additional RPMs
-   are in :file:`./results`.
+#. The resulting RPMs are in :file:`./rpms`. Build logs and additional RPMs are
+   in :file:`./results`.

 Example 2: Build a new RPM
 ==========================
@@ -141,23 +140,23 @@ create a simple helloclear RPM.

 #. Navigate to the autospec workspace and build the helloclear RPM. The
   :file:`Makefile` provides a :command:`make autospecnew` that can
-   automatically generate an RPM package using the autospec tool. You must
-   pass the URL to the source tarball and the NAME of the RPM you wish to
-   create:
+   automatically generate an RPM package using the autospec tool. You must pass
+   the URL to the source tarball and the NAME of the RPM you wish to create:

   .. code-block:: bash

      cd ~/clearlinux
      make autospecnew URL="https://github.com/clearlinux/helloclear/archive/helloclear-v1.0.tar.gz" NAME="helloclear"

-   The resulting RPMs are in :file:`./packages/helloclear/rpms`. Build logs and additional RPMs are in :file:`./packages/helloclear/results`.
+   The resulting RPMs are in :file:`./packages/helloclear/rpms`. Build logs and
+   additional RPMs are in :file:`./packages/helloclear/results`.

 Example 3: Generate a new spec file with a pre-defined package
 ==============================================================

-This example shows how to modify an existing package to create a custom RPM.
-In this example you will make a simple change to the ``dmidecode`` package
-and rebuild the package.
+This example shows how to modify an existing package to create a custom RPM. In
+this example you will make a simple change to the ``dmidecode`` package and
+rebuild the package.

 #. Navigate to the autospec workspace and clone the ``dmidecode`` package:

@@ -188,8 +187,7 @@ and rebuild the package.
      These files aren't needed by dmidecode, so we can remove them without
      any issues.

-#. In the :file:`dmidecode` directory, build the modified ``dmidecode``
-   package:
+#. In the :file:`dmidecode` directory, build the modified ``dmidecode`` package:

   .. code-block:: bash

@@ -201,8 +199,8 @@ Example 4: Provide control files to autospec
 ============================================

 This example shows how to modify control files to correct build failures that
-autospec is unable to resolve. In this example, you will add a missing
-license and dependencies so autospec can complete a successful build.
+autospec is unable to resolve. In this example, you will add a missing license
+and dependencies so autospec can complete a successful build.

 #. Navigate to the autospec workspace:

@@ -220,8 +218,8 @@ license and dependencies so autospec can complete a successful build.

   .. note::

-      In a later step of this example, we will search the cloned package
-      repos for a missing dependency.
+      In a later step of this example, we will search the cloned package repos
+      for a missing dependency.

 #. Build the opae-sdk RPM:

@@ -243,7 +241,7 @@ license and dependencies so autospec can complete a successful build.

 #. Add one or more valid license identifiers from the
   `SPDX License List <https://spdx.org/licenses/>`_.
-   In the example below, two different licenses are appropriate based on the
+   In the example below, two different licenses are appropriate based on the 
   opae-sdk project licensing:

   .. code-block:: bash
@@ -273,9 +271,7 @@ license and dependencies so autospec can complete a successful build.

   .. code-block:: console

-      CMake Error: The following variables are used in this project, but
-      they are set to NOTFOUND.  Please set them or make sure they are set and tested correctly in the CMake files:
-
+      CMake Error: The following variables are used in this project, but they are set to NOTFOUND.  Please set them or make sure they are set and tested correctly in the CMake files:
      CJSON_LIBRARY
         linked by target "opae-c++-utils" in directory /builddir/build/BUILD/opae-sdk-0.13.0/tools/c++utilslib
      json-c_LIBRARIES
@@ -283,8 +279,9 @@ license and dependencies so autospec can complete a successful build.
      libuuid_LIBRARIES
         linked by target "opae-c" in directory /builddir/build/BUILD/opae-sdk-0.13.0/libopae

-#. Search the spec files of upstream |CL| packages to see if the json-c
-   library is available. In this case, it does exist and we'll add the json-c 'dev' package into the buildreq_add:
+#. Search the spec files of upstream |CL| packages to see if the json-c library
+   is available. In this case, it does exist and we'll add the json-c 'dev'
+   package into the buildreq_add:

   .. code-block:: bash

@@ -293,26 +290,31 @@ license and dependencies so autospec can complete a successful build.

   .. note::

-      This search step works only if the user cloned all of the upstream package repos. In this example, upstream package repos were cloned in a previous step.
+      This search step works only if the user cloned all of the upstream package
+      repos. In this example, upstream package repos were cloned in a previous
+      step.

-#. Search the spec files of upstream |CL| packages to see if the libuuid
-   library is available. In this case, it exists in the util-linux package, so we'll add util-linux-dev package into the buildreq_add:
+#. Search the spec files of upstream |CL| packages to see if the libuuid library
+   is available. In this case, it exists in the util-linux package, so we'll add
+   util-linux-dev package into the buildreq_add:

   .. code-block:: bash

      grep 'libuuid\.so$' ~/clearlinux/packages/*/*.spec
      echo "util-linux-dev" >> buildreq_add

-#. Run autospec again and find the successfully-generated RPMs in the
-   :file:`rpms` directory:
+#. Run autospec again and find the successfully-generated RPMs in the :file:`rpms`
+   directory:

   .. code-block:: bash

      make autospec

-   .. note::
+.. note::

-      If you need a dependency that does not exist in the |CL| repo, you must first build it manually (see `Example 2: Build a new RPM`_), then add the repo so that autospec knows the package exists. For example:
+   If you need a dependency that does not exist in the |CL| repo, you must first
+   build it manually (see `Example 2: Build a new RPM`_), then add the repo so
+   that autospec knows the package exists. For example:

   .. code-block:: bash

@@ -320,102 +322,9 @@ license and dependencies so autospec can complete a successful build.
      make repoadd
      make repostatus

-   You only need to add the dependency to the :file:`buildreq_add` control
-   file if autospec is not able to automatically find the correct dependency
-   on its own.
-
-.. TODO: Document how to set up a license server for use with autospec.
-.. TODO: Demonstrate control file management. Establish specific use cases.
-
-Example 5: Update an existing package
-=====================================
-
-The |CL| team prefers to carry no patches and seeks to make the latest
-releases work. If we do need patches, we use :command:`autospec` to add,
-remove, or manage patches. The :command:`autospec` control files are
-integral to the patch management process. Developers can expect a more
-streamlined approach to managing a large collection of packages with
-:command:`autospec`.
-
-Adding and submitting patches
-----------------------------
-
-* To add patches to |CL| upstream, follow `patching source code`_.
-
-* To submit a patch to upstream, follow
-  `contributing to an existing software package`_.
-
-If you maintain a downstream derivative of |CL| and you want to integrate
-new or patched packages into your mix, follow the process in :ref:`mixer`.
-
-Assuming you have followed the above process, :command:`autospec` has
-generated a new spec file.
-
-Refresh a package and inspect
-----------------------------
-
-In this example, we use autospec to refresh the :command:`m4` package and
-recreate RPM files.
-
-#. Navigate to the top-level directory of the workspace
-
-   .. code-block:: bash
-
-      cd clearlinux
-
-   - where :command:`clearlinux` is the top level of the tooling workspace
-
-#. Run the make_clone command and then navigate to the package.
-
-   .. code-block:: bash
-
-      make clone_m4
-
-      cd packages/m4
-
-#. Make desired changes to the package, its control files, or
-   other files.
-
-#. Finally, run:
-
-   .. code-block:: bash
-
-      make autospec
-
-#. To view spec file changes, run:
-
-   .. code-block:: bash
-
-      git show m4.spec
-
-   The output shows:
-
-   .. code-block:: console
-
-      m4: Autospec creation for version 1.4.18
-
-      diff --git a/m4.spec b/m4.spec
-      index f76c78d..97b846a 100644
-      --- a/m4.spec
-      +++ b/m4.spec
-      @@ -6,15 +6,14 @@
-      #
-      Name     : m4
-      Version  : 1.4.18
-      -Release  : 88
-      +Release  : 89
-      URL      : http://mirrors.kernel.org/gnu/m4/m4-1.4.18.tar.xz
-      Source0  : http://mirrors.kernel.org/gnu/m4/m4-1.4.18.tar.xz
-      -Source99 : http://mirrors.kernel.org/gnu/m4/m4-1.4.18.tar.xz.sig
-      +Source1 : http://mirrors.kernel.org/gnu/m4/m4-1.4.18.tar.xz.sig
-      Summary  : No detailed summary available
-      Group    : Development/Tools
-      ...
-
-#. The following commands provide a more complete view of the changes.
-
-   * :command:`git log -p`
-   * :command:`gitk`
+   You only need to add the dependency to the :file:`buildreq_add` control file
+   if autospec is not able to automatically find the correct dependency on its
+   own.

 Test packaged software
 **********************
@@ -429,7 +338,7 @@ generated RPMs.

 .. note::
   The methods outlined below should only be used for temporary testing on
-   development systems.
+   development systems. 


 Test in a |CL| virtual machine
@@ -437,7 +346,7 @@ Test in a |CL| virtual machine

 The |CL| development tooling includes a method to install RPMs into a |CL|
 virtual machine running on the KVM hypervisor. Using a :abbr:`VM (Virtual
-Machine)` allows testing in a completely isolated environment.
+Machine)` allows testing in a completely isolated environment. 

 To test an autospec-created package inside a VM:

@@ -493,8 +402,8 @@ To test an autospec-created package inside a VM:
   deleted:

   .. code-block:: bash
-
-      poweroff
+      
+      poweroff 
      rm clear.img


@@ -595,16 +504,9 @@ Related topics

 * :ref:`Mixer tool <mixer>`

-.. _contributing to an existing software package: https://github.com/clearlinux/distribution/blob/master/contributing.md#contributing-to-an-existing-software-package
-
-.. _patching source code: https://github.com/clearlinux/distribution/blob/master/contributing.md#patching-source-code
-
 .. _`Makefile.common`: https://github.com/clearlinux/common/blob/master/Makefile.common
 .. _autospec README: https://github.com/clearlinux/autospec
 .. _control files: https://github.com/clearlinux/autospec#control-files
 .. _mock wiki: https://github.com/rpm-software-management/mock/wiki
 .. _rpm website: http://rpm.org
 .. _RPM Packaging Guide: https://rpm-packaging-guide.github.io/
-
-
-.. TODO:  Add link to how to submit a new package: https://github.com/clearlinux/distribution/blob/master/contributing.md#contributing-a-new-software-package
@@ -34,22 +34,20 @@ between user-owned areas and |CL|-owned areas.

   Figure 2: With stateless, user and system files are separated on the filesystem.

-System area
-===========
-Files under the :file:`/usr` directory are managed by |CL| as system files
-(except :file:`/usr/local`).
+System areas
+============
+File under the :file:`/usr` directory are managed by |CL| as system files.
 Files written under the :file:`/usr` directory by users can get removed
 through system updates with :ref:`swupd <swupd-guide>`. This operating
 assumption allows |CL| to verify and maintain integrity of system files.

 User areas
 ==========
-Files under the :file:`/usr/local`, :file:`/etc/`, :file:`/opt`, :file:`/home`,
-and :file:`/var` directories are owned and managed by the user. A freshly
-installed |CL| system will only have a minimal set of files in the
-:file:`/etc/` directory and software installed by |CL| does not write to
-:file:`/etc`. This operating assumption allows |CL| users to clearly identify
-the configuration that makes their system unique.
+Files under the :file:`/etc/`, :file:`/home`, and :file:`/var` directories are
+owned and managed by the user. A freshly installed |CL| system will only have
+a minimal set of files in the :file:`/etc/` directory and software installed
+by |CL| does not write to :file:`/etc`. This operating assumption allows |CL|
+users to clearly identify the configuration that makes their system unique.


 Software configuration
@@ -135,7 +133,6 @@ Additional information
 **********************

 * `stateless man page`_
-* :ref:`firmware`

 .. _`stateless man page`: https://github.com/clearlinux/clr-man-pages/blob/master/stateless.7.rst

@@ -7,13 +7,12 @@ This guide describes the |CL-ATTR| telemetry solution.

 .. important::

-   Telemetry in |CL| is **opt-in**. The telemetry client is **not** active
+   Telemetry in |CL| is **opt-in**. The telemetry client is **not**  active
   and sends **no** data until you explicitly enable it.

 .. note::

-   The telemetry functionality adheres to
-   `Intel privacy policies <https://www.intel.com/content/www/us/en/privacy/intel-privacy-notice.html>`_
+   The telemetry functionality adheres to `Intel privacy policies <https://www.intel.com/content/www/us/en/privacy/intel-privacy-notice.html>`_
   regarding the collection and use of :abbr:`PII (Personally Identifiable Information)` and is open source.

   No intentionally identifiable information about the user or system owner is
@@ -34,8 +33,7 @@ client side for instrumenting your code for debug and analysis.
 Telemetry, one of the key features of |CL|, enables developers to observe and
 proactively address issues in the OS before end users are impacted.

-Telemetrics is a
-`portmanteau word <https://en.wikipedia.org/wiki/Portmanteau>`_ made from:
+Telemetrics is a combination word made from:

 * Telemetry, which is sensing and reporting data.
 * Analytics, which is using visualization and statistical inferencing to make
@@ -47,12 +45,11 @@ error checks, and the BIOS error report table for unhandled hardware
 failures. Telemetry enables real-time issue reporting to allow system
 developers to focus quickly on an issue and monitor corrective actions.

-|CL| telemetry is fully customizable and can also be used during software
+|CL| telemetry is fully customizable and can be used during software
 development for debugging purposes. You can use the libtelemetry library in
 your code to create custom telemetry records. You can also use the
 telem-record-gen utility in script files for light-touch record creation
-where instrumenting code files doesn't make sense. For more information on
-configuring the telemetry client, refer to section `Client Configuration`_.
+where instrumenting code files doesn't make sense.

 The |CL| telemetrics solution is an **opt-in** choice on the client side.
 By default, the telemetry client is disabled until you choose to enable it.
@@ -63,11 +60,10 @@ Architecture

 |CL| telemetry has two fundamental components, which are shown in Figure 1:

-* Client, which generates and delivers records to the backend server via the
-  network.
+* Client: generates and delivers records to the backend server via the network.

-* Backend, which receives records sent from the client and displays the
-  cumulative content through a specialized web interface.
+* Backend: receives records sent from the client and displays the cumulative
+  content through a specialized web interface.

 .. figure:: /_figures/telemetrics/telemetry-e2e.png
   :alt: Figure 1, Telemetry Architecture
@@ -82,8 +78,7 @@ includes the following components:
 * telempostd, which is a daemon that manages spooled telemetry records and
  delivers these records according to configurable settings.
 * probes, which collect specific types of data from the operating system.
-* libtelemetry, which is the API that telemetrics probes use to create
-  records.
+* libtelemetry, which is the API that telemetrics probes use to create records.

 The telemetry backend provides the server-side component of the telemetrics
 solution and consists of:
@@ -99,10 +94,9 @@ solution and consists of:

 .. note::

-   The default telemetry backend server is hosted by the Intel |CL|
-   development team and is not viewable outside the Intel firewall. To
-   collect your own records, you must set up your own telemetry backend
-   server.
+   The default telemetry backend server is hosted by the Intel |CL| development
+   team and is not viewable outside the Intel firewall. To collect your own
+   records, you must set up your own telemetry backend server.

 How to use
 **********
@@ -110,36 +104,33 @@ How to use
 From a workflow perspective, the |CL| telemetrics system is straightforward.
 On the client side, the main decisions after installation and enabling
 telemetry involve what to do with the record data generated by the probes.
-You can send the data to the default telemetry server or a custom backend
-server, keep the data local to the system, or both. The backend server has a
-more complex setup, but once it's running, it is simple to configure and use.
+You can send the data to the default or a custom backend server, keep the data
+local to the system, or both. The backend server has a more complex setup, but
+once it's running, it is simple to use and configure.

 This section describes some of the possible scenarios for configuring
 the |CL| telemetrics system, and suggests which ones make sense according to
 your needs.

-For more information on configuring the telemetry client, refer to section
-`Client Configuration`_.
-
 Scenarios
 =========

 #. Enable telemetry:

-   You must opt-in and start telemetry before probes can generate records.
-   You can configure the client before starting telemetry by creating a
-   custom :file:`telemetrics.conf` file that you place in the
-   :file:`/etc/telemetrics` directory. If you choose to use the built-in
-   default settings, records will be sent to the telemetrics backend server
-   managed by the |CL| development team at Intel.
+   Before probes can generate records, the telemetry client daemons must be
+   enabled. You can configure the client before enabling by creating a custom
+   :file:`telemetrics.conf` file that you place in the :file:`/etc/telemetrics`
+   directory. If you choose to use the default settings, records will be sent
+   to the telemetrics backend server managed by the |CL| development team at
+   Intel.

 #. Save record data locally:

   You can configure the telemetry client to save records locally. This is
-   convenient when you want instant feedback during a development cycle, or
-   to track system issues if you believe there is a machine-specific problem.
-   The client can be set not to send records at all or to both keep the
-   records locally and send to the backend server.
+   convenient when you want instant feedback during a development cycle, or to
+   track system issues if you believe there is a machine specific problem. The
+   client can be set not to send records at all, or to both keep the records
+   locally and send to the backend server.

 #. Set up a server to collect data:

@@ -151,11 +142,10 @@ Scenarios

 #. Instrument your code with the libtelemetry API:

-   The :command:`telemetrics` bundle includes the libtelemetry C library,
-   which exposes an API used by the telemprobd and telempostd daemons. You
-   can use these in your applications as well. The API documentation is
-   located in the :file:`telemetry.h` file in `Telemetrics client`_
-   repository.
+   The :command:`telemetrics` bundle includes the libtelemetry C library, which
+   exposes an API used by the telemprobd and telempostd daemons. You can use
+   these in your applications as well. The API documentation is found in the
+   :file:`telemetry.h` file in `Telemetrics client`_ repository.


 Examples
@@ -171,29 +161,25 @@ Enable or disable telemetry
 #. Enabling during installation:

   During the initial installation of |CL|, you are requested to join the
-   stability enhancement program and allow |CL| to collect anonymous reports
-   to improve system stability. If you choose not to join this program, then
-   the telemetry software bundle is not added to your system. If you do
-   choose to join the program, the installer will automatically enable
-   telemetry on your system by installing the telemetrics bundle, creating
-   the file :file:`/etc/telemetrics/opt-in`, and enabling the telemetrics
-   systemd services to run after installation is complete and the system is
-   restarted.
+   stability enhancement program and allow |CL| to collect anonymous reports to
+   improve system stability. If you choose not to join this program, then the
+   telemetry software bundle is not added to your system. Choosing to join will
+   automatically enable telemetry on your system after installation is
+   complete.

 #. Enabling after install:

-   To install telemetry on your system, run the following commands:
+   To start telemetry on your system, run the following command:

   .. code-block:: bash

-      sudo swupd bundle-add telemetrics
-      sudo telemctl opt-in
      sudo telemctl start

-   This installs the necessary software, enables telemetry by creating the
-   file :file:`/etc/telemetrics/opt-in`, and starts the :command:`telemprobd`
-   and :command:`telempostd` daemons. Your system will begin to send
-   telemetry data to the backend server.
+   This enables and starts the :command:`telemprobd` and :command:`telempostd`
+   daemons. Your system will begin to send telemetry data to the server defined
+   in the file :file:`/etc/telemetrics/telemetrics.conf`. If this file does not
+   exist, the :command:`telemprobd` and :command:`telempostd` daemons will use
+   the file :file:`/usr/share/defaults/telemetrics/telemetrics.conf`.

 #. Disabling after install:

@@ -205,27 +191,33 @@ Enable or disable telemetry

 #. Opt in to telemetry:

-   To opt-in to the telemetry services, simply enter the opt-in command:
+   To opt-in to the telemetry services, simply enter the opt-in command, which  
+   also starts the service:

   .. code-block:: bash

      sudo telemctl opt-in
-      sudo telemctl start

-   This creates the :file:`/etc/telemetrics/opt-in` file, if it doesn't
-   already exist. You will need to explicitly start the telemetry services
-   after you have opted in.
+   This removes the :file:`/etc/telemetrics/opt-out` file, if it exists, and
+   starts the telemetry services.
+
+   .. note::
+
+      To opt-in but not immediately start telemetry services, you must
+      run the command :command:`sudo telemctl stop` after the :command:`opt-in`
+      command is entered. Once you are ready to start the service, enter the
+      command :command:`sudo telemctl start`.

 #. Opt out of telemetry:

-   To stop sending telemetrics data from your system, opt out of the
-   telemetry service:
+   To stop sending telemetrics data from your system, opt out of the telemetry
+   service:

   .. code-block:: bash

      sudo telemctl opt-out

-   This removes the file :file:`/etc/telemetrics/opt-in` and stops the
+   This creates the file :file:`/etc/telemetrics/opt-out` and stops the
   telemetry services.


@@ -238,12 +230,11 @@ system.
 To change how records are managed, copy the default
 :file:`/usr/share/defaults/telemetrics/telemetrics.conf` file to
 :file:`/etc/telemetrics/telemetrics.conf` and edit it. The changes in the
-:file:`/etc/telemetrics/telemetrics.conf` file will override the built-in
-defaults referenced in the
-:file:`/usr/share/defaults/telemetrics/telemetrics.conf` file.
-You will need root permissions to create and edit files in :file:`/etc`. For
-each example, and for any time you make changes to the configuration file,
-you must restart the client daemons to pick up the changes:
+:file:`/etc/telemetrics/telemetrics.conf` file will override the defaults in
+the :file:`/usr/share/defaults/telemetrics/telemetrics.conf` file. You may need
+root permissions to create and edit files in :file:`/etc`. For each
+example, and for any time you make changes to the configuration file, you must
+restart the client daemons to pick up the changes:

 .. code-block:: bash

@@ -281,8 +272,8 @@ Use :command:`-h` or :command:`--help` to view usage options.
   this, you can use an IP address or fully qualified domain name.


-Set up a backend server to collect telemetry records
-====================================================
+Set up a back-end server to collect telemetry records
+=====================================================

 For this example, start with a clean installation of |CL| on a new system
 using the :ref:`bare-metal-install-server` getting started guide and:
@@ -296,7 +287,7 @@ using the :ref:`bare-metal-install-server` getting started guide and:
   * Create an administrative user named :guilabel:`clear` and add this user
     to sudoers

-#. Log in with your administrative user, from your :file:`$HOME` directory,
+#. Log 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:

@@ -309,12 +300,9 @@ using the :ref:`bare-metal-install-server` getting started guide and:
      You may need to set up the :envvar:`https_proxy` environment variable if
      you have issues reaching github.com.

-#. Change your current working directory to
-   :file:`telemetrics-backend/scripts`.
-
-#. Before you install the telemetrics backend with the :file:`deploy.sh`
-   script file in the next step, here is an explanation of the options to be
-   specified:
+#. Change your current working directory to :file:`telemetrics-backend/scripts`.
+#. Before you install the telemetrics backend with the :file:`deploy.sh` script
+   file in the next step, here is an explanation of the options to be specified:

   * :command:`-a install` to perform an install
   * :command:`-d clr` to install to a |CL| distro
@@ -332,6 +320,8 @@ using the :ref:`bare-metal-install-server` getting started guide and:

      ./deploy.sh -H localhost -a install -d clr

+
+
   The script starts and lists all the defined options and prompts you for
   the :guilabel:`PostgreSQL` database password.

@@ -351,10 +341,10 @@ using the :ref:`bare-metal-install-server` getting started guide and:

   .. note::

-      The :file:`deploy.sh` 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.
+      The :file:`deploy.sh` 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.


 #. After all the server components have been installed, you are prompted to
@@ -369,13 +359,13 @@ using the :ref:`bare-metal-install-server` getting started guide and:
      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.
+   password, retype it to verify the new password and the :guilabel:`PostgreSQL`
+   database password will be updated.

-#. After the installation is complete, you can use your web browser to view
-   the new server by opening the browser on the system and typing in
-   :command:`localhost` in the address bar. You should see a web page similar
-   to the one shown in Figure 2 below.
+#. After the installation is complete, you can use your web browser to view the
+   new server by opening the browser on the system and typing in localhost
+   in the address bar. You should see a web page similar to the one shown in
+   Figure 2 below.

   .. figure:: /_figures/telemetrics/telemetry-backend-1.png
      :alt: Telemetry UI
@@ -385,12 +375,12 @@ using the :ref:`bare-metal-install-server` getting started guide and:
 Create records with telem-record-gen
 ====================================

-The :command:`telemetrics` bundle provides a record generator tool called
+The telemetrics bundle provides a record generator tool called
 `telem-record-gen`. This tool can be used to create records from shell
-scripts or the command line when it is not desirable to write a probe in C.
+scripts or the command line when writing a probe in C is not desirable.
 Records are sent to the backend server, and can also be echoed to stdout.

-There are three ways to supply the payload to the record:
+There are three ways to supply the payload to the record.

 #. On the command line, use the :command:`-p <string>` option:

@@ -474,16 +464,15 @@ There are three ways to supply the payload to the record:

      payload read from stdin

-
 Set a static machine id
 =======================

 The machine id reported by the telemetry client is rotated every three days
 for privacy reasons. If you wish to have a static machine id for testing
-purposes, you can opt in by creating a file named
-:file:`opt-in-static-machine-id` in the directory  :file:`/etc/telemetrics/`.
+purposes, you can opt in by creating a file named `opt-in-static-machine-id`
+in the directory  :file:`/etc/telemetrics/`.

-#. Create a directory :file:`telemetrics`.
+#. Create a directory `telemetrics`.

   .. code-block:: bash

@@ -499,7 +488,7 @@ purposes, you can opt in by creating a file named

 .. note::

-   The machine ID is different from the system hostname.
+   The machine ID is different than the system hostname.

 Instrument your code with the libtelemetry API
 ==============================================
@@ -508,9 +497,9 @@ Prerequisites
 -------------

 Confirm that the telemetrics header file is located on the system at
-:file:`usr/include/telemetry.h`. The `latest version`_ of the file can also
-be found on github for reference, but installing the :command:`telemetrics`
-bundle will install the header file that matches your |CL| version.
+:file:`usr/include/telemetry.h`  The `latest version`_ of the file can also be
+found on github for reference, but installing the :command:`telemetry` bundle
+will install the header file that matches your |CL| version.

 #. Includes and variables:

@@ -542,33 +531,33 @@ bundle will install the header file that matches your |CL| version.
   Severity:
    Type: uint32_t
    Value:  Severity field value. Accepted values are in the range 1-4, with
-    1 being the lowest severity and 4 being the highest severity. Values
-    provided outside of this range are clamped to 1 or 4 [low, med, high,
-    crit].
+    1 being the lowest severity, and 4 being the highest severity. Values
+    provided outside of this range are clamped to 1 or 4. [low, med, high,
+    crit]

   Payload_version:
    Type: uint32_t
-    Value: Payload format version. The only currently supported value is 1,
+    Value: Payload format version. The only supported value right now is 1,
    which indicates that the payload is a freely-formatted (unstructured)
    string. Values greater than 1 are reserved for future use.

   Classification:
     Type: char array
-     Value: It should have the form, DOMAIN/PROBENAME/REST: DOMAIN is the
+     Value: It should have the form, DOMAIN/PROBENAME/REST: DOMAIN is the 
     reverse domain to use as a namespace for the probe (e.g. org.clearlinux),
     PROBENAME is the name of the probe, and REST is an arbitrary value that
     the probe should use to classify the record. The maximum length for the
     classification string is 122 bytes. Each sub-category may be no longer
-     than 40 bytes long. Two \'/\' delimiters are required.
+     than 40 bytes long. Two / delimiters are required.

   Tm_handle:
     Type: Telem_ref struct pointer
-     Value:  Struct pointer declared by the caller. The struct is initialized
+     Value:  Struct pointer declared by the caller, The struct is initialized
     if the function returns success.

   Payload:
     Type: char pointer
-     Value: The payload to set.
+     Value: The payload to set

 #. For this example, we'll set the payload to “hello” by using
   :command:`asprintf()`:
@@ -579,20 +568,19 @@ bundle will install the header file that matches your |CL| version.
           exit(EXIT_FAILURE);
            }

-   The functions :command:`asprintf()` and :command:`vasprintf()` are analogs
-   of :command:`sprintf(3)` and :command:`vsprintf(3)`, except that they
-   allocate a string large enough to hold the output including the
-   terminating null byte ('\0'), and return a pointer to it via the first
-   argument. This pointer should be passed to :command:`free(3)` to release
-   the allocated storage when it is no longer needed.
+   The functions :command:`asprintf()` and :command:`vasprintf()` are analogs of
+   :command:`sprintf(3)` and :command:`vsprintf(3)`, except that they allocate a
+   string large enough to hold the output including the terminating null byte
+   ('\0'), and return a pointer to it via the first argument. This pointer
+   should be passed to :command:`free(3)` to release the allocated storage when
+   it is no longer needed.

 #. Create the new telemetry record:

-   The  function  :command:`tm_create_record()` initializes a telemetry
-   record and sets the severity and classification of that record, as well as
-   the payload version number. The memory needed to store the telemetry
-   record is allocated and should be freed with :command:`tm_free_record()`
-   when no longer needed.
+   The  function  :command:`tm_create_record()` initializes a telemetry record and
+   sets the severity and classification of that record, as well as the payload
+   version number. The memory needed to store the telemetry record is allocated
+   and should be freed with :command:`tm_free_record()` when no longer needed.

   .. code-block:: console

@@ -604,9 +592,8 @@ bundle will install the header file that matches your |CL| version.

 #. Set the payload field of a telemetrics record:

-   The function :command:`tm_set_payload()` attaches the provided telemetry
-   record data to the telemetry record. The current maximum payload size is
-   8192b.
+   The function :command:`tm_set_payload()` attaches the provided telemetry record
+   data to the telemetry record. The current maximum payload size is 8192b.

   .. code-block:: console

@@ -617,8 +604,8 @@ bundle will install the header file that matches your |CL| version.
      }
      free(payload);

-   The :command:`free()` function frees the memory space pointed to by `ptr`,
-   which must have been returned by a previous call to :command:`malloc()`,
+   The :command:`free()` function frees the memory space pointed to by `ptr`, which
+   must have been returned by a previous call to :command:`malloc()`,
   :command:`calloc()`, or :command:`realloc()`. Otherwise, or if
   :command:`free(ptr)` has already been called before, undefined behavior
   occurs. If `ptr` is NULL, no operation is performed.
@@ -626,9 +613,9 @@ bundle will install the header file that matches your |CL| version.
 #. Send a record to the telemetrics daemon:

   The function :command:`tm_send_record()` delivers the record to the local
-   :command:`telemprobd(1)` service. Since the telemetry record was allocated
-   by the program it should be freed with :command:`tm_free_record()` when it
-   is no longer needed.
+   :command:`telemprobd(1)` service. Since the telemetry record was allocated by
+   the program it should be freed with :command:`tm_free_record()` when it is no
+   longer needed.

   .. code-block:: console

@@ -733,109 +720,88 @@ Reference
 The telemetry API
 =================

-Installing the :command:`telemetrics` bundle includes the libtelemetry C
-library, which exposes an API used by the telemprobd and telempostd daemons.
-You can use these in your applications as well. The API documentation is found
-in the :file:`telemetry.h` file in `Telemetrics client`_ repository.
+Installing the :command:`telemetrics` bundle includes the libtelemetry C library,
+which exposes an API used by the telemprobd and telempostd daemons. You can
+use these in your applications as well. The API documentation is found in the
+:file:`telemetry.h` file in `Telemetrics client`_ repository.

 Client configuration
 ====================

 The telemetry client will look for the configuration file located at
 :file:`/etc/telemetrics/telemetrics.conf` and use it if it exists. If the
-file does not exist, the client will use the default configuration defined
-at build time. There is a sample configuration file located at
-:file:`/usr/share/defaults/telemetrics/telemetrics.conf` and represents the
-default values that are used when the programs are built. To modify or
+file does not exist, the client will use the default configuration located
+at :file:`/usr/share/defaults telemetrics/telemetrics.conf`. To modify or
 customize the configuration, copy the file from
-:file:`/usr/share/defaults/telemetrics/telemetrics.conf` to the file
-:file:`/etc/telemetrics/telemetrics.conf` and edit it to add your
-customizations.
-
-.. code-block:: bash
-
-   sudo mkdir -p /etc/telemetrics
-   cp /usr/share/defaults/telemetrics/telemetrics.conf /etc/telemetrics/telemetrics.conf
-
-.. note::
-
-   Telemetrics configuration is a layered mechanism since the defaults are
-   defined at build time and each field can be overwritten individually.
-   Therefore you only need to add the specific field that you want to change
-   from the default value to your customized value in the
-   :file:`/etc/telemetrics/telemetrics.conf` file.
+:file:`/usr/share/defaults/telemetrics` to :file:`/etc/telemetrics` and edit it.

 Configuration options
 ---------------------

-The client can use the following configuration options from the config file:
+The client uses the following configuration options from the config file:

 server
-   This specifies the web server to which telempostd sends the telemetry
-   records.
+   This specifies the web server to which telempostd sends the telemetry records.
 socket_path
-   This specifies the path of the unix domain socket on which telemprobd
+   This specifies the path of the unix domain socket on which the telemprobd
   listens for connections from the probes.
 spool_dir
-   This configuration option is related to spooling. If the daemon is not
-   able to send the telemetry records to the backend server due to reasons
-   such as the network availability, then it stores the records in a spool
-   directory. This option specifies the path of the spool directory. This
-   directory should be owned by the same user as the daemon.
+   This configuration option is related to spooling. If the daemon is not able
+   to send the telemetry records to the backend server due to reasons such as
+   the network availability, then it stores the records in a spool directory.
+   This option specifies the path of the spool directory. This directory should
+   be owned by the same user as the daemon.
 record_expiry
-   This is the time, in minutes, after which the records in the spool
-   directory are deleted by the daemon.
+   This is the time, in minutes, after which the records in the spool directory
+   are deleted by the daemon.
 spool_process_time
-   This specifies the time interval, in seconds, that the daemon waits
+   This specifies the time interval, in seconds, that the daemon waits for
   before checking the spool directory for records. The daemon picks up the
-   records in the order of modification date and tries to send the record to
-   the server. It sends a maximum of 10 records at a time. If it was able to
-   send a record successfully, it deletes the record from the spool. If the
-   daemon finds a record older than the "record_expiry" time, then it deletes
-   that record. The daemon looks at a maximum of 20 records in a single spool
-   run loop.
+   records in the order of modification date and tries to send the record to the
+   server. It sends a maximum of 10 records at a time. If it was able to send a
+   record successfully, it deletes the record from the spool. If the daemon
+   finds a record older than the "record_expiry" time, then it deletes that
+   record. The daemon looks at a maximum of 20 records in a single spool run loop.
 rate_limit_enabled
-   This determines whether rate-limiting is enabled or disabled. When
-   enabled, there is a threshold on both records sent within a window of
-   time, and record bytes sent within a window a time.
+   This determines whether rate-limiting is enabled or disabled. When enabled,
+   there is a threshold on both records sent within a window of time, and record
+   bytes sent within a window a time.
 record_burst_limit
   This is the maximum amount of records allowed to be passed by the daemon
-   within the record_window_length of time. If set to -1, the rate-limiting
-   for record bursts is disabled.
+   within the record_window_length of time. If set to -1, the rate-limiting for
+   record bursts is disabled.
 record_window_length
   The time, in minutes (0-59), that establishes the window length for the
   record_burst_limit. For example, if record_burst_window=1000 and
-   record_window_length=15, then no more than 1000 records can be passed
-   within any given fifteen-minute window.
+   record_window_length=15, then no more than 1000 records can be passed within
+   any given fifteen-minute window.
 byte_burst_limit
-   This is the maximum amount of bytes that can be passed by the daemon
-   within the byte_window_length of time. If set to -1, the rate-limiting
-   for byte bursts is disabled.
+   This is the maximum amount of bytes that can be passed by the daemon within
+   the byte_window_length of time. If set to -1, the rate-limiting for byte
+   bursts is disabled.
 byte_window_length
-   This is the time, in minutes (0-59), that establishes the window length
-   for the byte_burst_limit.
+   This is the time, in minutes (0-59), that establishes the window length for
+   the byte_burst_limit.
 rate_limit_strategy
   This is the strategy chosen once the rate-limiting threshold has been
   reached. Currently the options are 'drop' or 'spool', with spool being the
-   default. If spool is chosen, records will be spooled and sent at a later
-   time.
+   default. If spool is chosen, records will be spooled and sent at a later time.
 record_retention_enabled
-   When this key is enabled (true), the daemon saves a copy of the payload on
-   disk from all valid records. To avoid the excessive use of disk space,
-   only the latest 100 records are kept. The default value for this
-   configuration key is false.
+   When this key is enabled (true) the daemon saves a copy of the payload on
+   disk from all valid records. To avoid the excessive use of disk space only
+   the latest 100 records are kept. The default value for this configuration key
+   is false.
 record_server_delivery_enabled
-   This key controls the delivery of records to the server; when enabled
-   (default value), the record will be posted to the address in the
-   configuration file. If this configuration key is disabled (false),
-   records will not be spooled or posted to backend. This configuration key
-   can be used in combination with record_retention_enabled to keep copies
-   of telemetry records locally only.
+   This key controls the delivery of records to server; when enabled (default
+   value), the record will be posted to the address in the configuration file.
+   If this configuration key is disabled (false), records will not be spooled or
+   posted to backend. This configuration key can be used in combination with
+   record_retention_enabled to keep copies of telemetry records locally only.

  .. note::

  	 Configuration options may change as the telemetry client evolves.
-  	 Please use the comments in the default file itself as the most accurate
+  	 Please use the comments in the file itself as the most accurate
  	 reference for configuration.


@@ -865,7 +831,7 @@ for managing the telemetry services and probes. The tool is located in
 start/stop/restart
 ------------------

-The commands to start, stop, and restart the telemetry services manage all
+The commands to start, stop and restart the telemetry services manage all
 required services and probes on the system. There is no need to separately
 start/stop/restart the two client daemons telemprobd and telempostd.
 The :command:`restart` command option will call :command:`telemctl stop`
@@ -1,96 +0,0 @@
-.. _firmware:
-
-Firmware
-########
-
-This guide shows how |CL-ATTR| handles firmware and microcode loading.
-
-.. contents::
-   :local:
-   :depth: 1
-
-Overview 
-********
-
-Many devices and system components require firmware or microcode, software
-that runs directly on the device, to function correctly. Because firmware
-loading requires privileged hardware access, the kernel is involved in the
-process.
-
-Firmware does not typically come with source code. Instead, firmware is
-provided as binary blobs which are licensed for free or non-free use.
-
-In |CL| firmware is loaded during device initialization which typically
-happens at boot time. 
-
-
-Included firmware
-*****************
-
-The Linux kernel project contains a repository for firmware binaries that are
-licensed to allow free redistribution. |CL| packages these firmware binaries
-in the `linux-firmware bundles
-<https://clearlinux.org/software?search_api_fulltext=linux-firmware>`_ and
-automatically includes them with the kernel.
-
-The Linux kernel's firmware repository can be found here:
-https://git.kernel.org/pub/scm/linux/kernel/git/firmware/linux-firmware.git
-
-If the firmware for your device is included upstream, no action is required
-for it to be automatically detected and loaded. 
-
-
-Additional firmware loading
-***************************
-
-Some device hardware manufacturers have a license that limits redistribution
-of firmware. This means |CL| is unable to distribute those firmware and you
-must manually obtain them from the manufacturer or another source.
-
-You can place additional firmware in :file:`/etc/firmware`. |CL| reads this
-directory for additional firmware files in conjunction with the typical
-:file:`/lib/firmware` path to provide a :ref:`stateless design <stateless>`.
-
-
-#. Create the :file:`/etc/firmware` directory
-
-   .. code-block:: bash
-
-      sudo mkdir -p /etc/firmware
-
-#. Obtain the additional firmware binary from a trusted source.
-
-#. Copy the firmware files including any subdirectories to
-   :file:`/etc/firmware`. It is important to place the firmware files in
-   expected path for proper loading. 
-
-   .. code-block:: bash
-
-      sudo cp -Rv <directory>/<filename>.<fw|bin> /etc/firmware 
-
-
-CPU microcode loading
-*********************
-
-Microcode is low level code for processors loaded during the boot process that
-contain stability and security updates. 
-
-Microcode updates can be updated by motherboard firmware however this is not
-always feasible or does not happen in a timely fashion. The `Linux microcode
-loader`_ included in the Linux kernel allows for more flexibility and more
-frequent updates.
-
-|CL| uses the *early loading* mechanism described in the `Linux microcode
-loader`_ documented by which the CPU microcode is loaded as early as possible
-in the boot process by using an initial RAM disk (initrd). 
-
-
-Troubleshooting
-***************
-
-Look at the output of :command:`sudo dmesg` to see device initialization and
-expected firmware paths
-
-
-
-.. _`Linux microcode loader`: https://www.kernel.org/doc/Documentation/x86/microcode.txt
@@ -34,7 +34,7 @@ Maintaining a |CL| derivative requires:
 * Integrating Quality Assurance for testing and validation

 Coordinated infrastructure is deployed to automate the life-cycle
-of your |CL| derivative. We divide deployment of this infrastructure in two
+of your |CL| derivative. We divide deployment of this infrastucture in two
 parts: *Content Workflow*; and *Release Workflow*, shown in Figure 1.

 .. figure:: figures/architect-lifecycle-1.png
@@ -1,469 +0,0 @@
-.. _container-image-modify:
-
-Modify a |CL|-based container image
-###################################
-
-This guide describes how to customize |CL-ATTR|-based container
-`images on Docker Hub`_, which include popular applications and runtimes.
-
-.. contents::
-   :local:
-   :depth: 1
-
-Overview
-********
-
-Most of these images utilize a Docker build feature called a `multi-stage
-build to reduce image size`_ while some use single-stage build Dockerfiles. An
-official base `clearlinux image on Docker Hub`_ is also available. To create a
-generic |CL| container image, see :ref:`our guide <container-image-new>`.
-
-Prerequisites
-*************
-
-* Set up a functional Docker environment as described in :ref:`docker`.
-
-* Download the |CL| microservice Dockerfile repo with the following
-  command:
-
-  .. code-block:: bash
-
-     git clone https://github.com/clearlinux/dockerfiles.git
-
-* Navigate to and operate from the cloned :file:`dockerfiles` directory.
-
-   .. code-block:: bash   
-
-      cd dockerfiles/
-
-
-Example 1: Add a bundle
-***********************
-
-In this example, we add :command:`wget` to the **clearlinux/redis**
-Dockerfile.
-
-#. Enter :command:`swupd search wget` to discover which |CL| bundle includes
-   the software. The output should tell you that :command:`wget` is available
-   in the *wget* bundle.
-
-#. Open a an editor to modify the Dockerfile.
-
-   .. code-block:: bash   
-
-      $EDITOR redis/Dockerfile
-
-#. Append the :command:`wget` bundle to the :command:`--bundles=` parameter
-   of the :command:`swupd os-install` command.
-
-#. Run :command:`git diff`.
-
-   The output shows the edits made after adding :command:`wget` in the
-   clearlinux/redis Dockerfile.
-
-   .. code-block:: diff
-
-      diff --git a/redis/Dockerfile b/redis/Dockerfile
-      index af977cb..b1effab 100644
-      --- a/redis/Dockerfile
-      +++ b/redis/Dockerfile
-      @@ -15,7 +15,7 @@ RUN source /os-release && \
-          mkdir /install_root \
-          && swupd os-install -V ${VERSION_ID} \
-          --path /install_root --statedir /swupd-state \
-       -    --bundles=redis-native,findutils,su-exec --no-boot-update
-       +    --bundles=redis-native,findutils,su-exec,wget --no-boot-update
-
-#. Build the Dockerfile and apply a unique tag name. In this this example,
-   we use :command:`wget_added` and add proxies.
-
-   .. code-block:: bash
-
-      docker build \
-      --no-cache \
-      --build-arg http_proxy=$http_proxy \
-      --build-arg https_proxy=$https_proxy \
-      --tag clearlinux/redis:wget_added \
-      redis/
-
-#. Run the Dockerfile with the `wget --version` command to verify that
-   :command:`wget` has been added to the image.
-
-   .. code-block:: bash
-
-      docker run clearlinux/redis:wget_added wget --version
-
-#. The output shows:
-
-   .. code-block:: console
-
-      GNU Wget 1.20.3 built on linux-gnu.
-
-      -cares +digest -gpgme +https +ipv6 -iri +large-file -metalink +nls
-      -ntlm +opie -psl +ssl/openssl
-
-Example 2: Change |CL| version (single-stage build)
-***************************************************
-
-This example shows how to rebuild single-stage containers against a specific
-OS version, :file:`<CL_VERSION>`, by adding a new argument to the Docker build
-command line. 
-
-#. Rebuild the :file:`clearlinux/machine-learning-ui`. Add an extra build
-   argument :command:`swupd_args="-m <CL_VERSION>"`; in this case, the build
-   version is 31110.
-
-   .. code-block:: bash
-      :linenos:
-      :emphasize-lines: 5
-
-      docker build \
-      --no-cache \
-      --build-arg http_proxy=$http_proxy \
-      --build-arg https_proxy=$https_proxy \
-      --build-arg swupd_args="-m 31110" \      
-      --tag clearlinux/machine-learning-ui:31110 \
-      machine-learning-ui/
-
-#. Run the docker container image:
-
-   .. code-block:: bash
-
-      docker run clearlinux/machine-learning-ui:31110 swupd info
-
-#. Sample output shows:
-
-   .. code-block:: console
-
-      Distribution:      Clear Linux OS
-      Installed version: 31110
-      Version URL:       https://cdn.download.clearlinux.org/update
-      Content URL:       https://cdn.download.clearlinux.org/update
-
-
-Example 3: Change |CL| version (multi-stage build)
-**************************************************
-
-This example shows how to rebuild the cgit Dockerfile to use a specific |CL|
-version. The clearlinux/cgit Dockerfile has a multi-stage build with multiple
-layers: *os-core*, *httpd*, and *cgit*. This can be used as reference for
-building other multi-stage images with any number of layers. 
-
-
-.. important::
-
-   All upper layers of multi-stage Dockerfiles inherit the |CL| version from
-   the base layer. Rebuild the all underlying base layers against the desired
-   OS version. In this example, four base layers must be rebuilt.
-
-
-First layer: os-core
--------------------
-
-#. Rebuild the first layer, *os-core*. Add an extra build argument
-   :command:`swupd_args="-m <CL_VERSION>"`; in this case, the build
-   version is 31110.
-
-   .. code-block:: bash
-      :linenos:
-      :emphasize-lines: 5
-
-      docker build \
-      --no-cache \
-      --build-arg http_proxy=$http_proxy \
-      --build-arg https_proxy=$https_proxy \
-      --build-arg swupd_args="-m 31110" \      
-      --tag clearlinux/os-core:31110 \
-      os-core/
-
-#. Verify the version-specific image is available:
-
-   .. code-block:: bash
-      
-       docker images clearlinux/os-core:31110
-
-
-Second layer: httpd
-------------------
-
-The next layer is :file:`clearlinux/httpd`.
-
-#. Change the :file:`httpd/Dockerfile` to use the version-specific
-   *os-core:31110* image that was previously built.
-
-   .. code-block:: bash
-
-      $EDITOR httpd/Dockerfile
-
-#. Run :command:`git diff`.
-
-   The output shows a diff of a modified :file:`clearlinux/httpd` Dockerfile
-   that uses the previously built clearlinux/os-core:31110.
-
-   .. code-block:: diff
-
-      diff --git a/httpd/Dockerfile b/httpd/Dockerfile
-      index 6b2a6bf..9df89e4 100644
-      --- a/httpd/Dockerfile
-      +++ b/httpd/Dockerfile
-      @@ -7,7 +7,7 @@ RUN swupd update --no-boot-update $swupd_args
-
-      # Grab os-release info from the minimal base image so
-      # that the new content matches the exact OS version
-      -COPY --from=clearlinux/os-core:latest /usr/lib/os-release /
-      +COPY --from=clearlinux/os-core:31110 /usr/lib/os-release /
-
-      # Install additional content in a target directory
-      # using the os version from the minimal base
-      @@ -26,7 +26,7 @@ COPY --from=clearlinux/os-core:latest / /
-      os_core_install/
-      RUN cd / && \
-          find os_core_install | sed -e 's/os_core_install/install_root/' | xargs rm -d &> /dev/null || true
-
-      -FROM clearlinux/os-core:latest
-      +FROM clearlinux/os-core:31110
-
-#. Build Dockerfile.
-
-   .. code-block:: bash
-
-      docker build \
-      --no-cache \
-      --build-arg http_proxy=$http_proxy \
-      --build-arg https_proxy=$https_proxy \
-      --tag clearlinux/httpd:31110 \
-      httpd/
-
-Third layer: cgit
-----------------
-
-The next layer is :file:`clearlinux/cgit`.
-
-#. Change the :file:`cgit/Dockerfile` to use the desired OS
-   version; in this case, the build version is 31110.
-
-   .. code-block:: bash
-
-      $EDITOR cgit/Dockerfile
-
-#. Run :command:`git diff`.
-
-   The output shows:
-
-   .. code-block:: diff
-
-      diff --git a/cgit/Dockerfile b/cgit/Dockerfile
-      index 9a3796d..59260fe 100644
-      --- a/cgit/Dockerfile
-      +++ b/cgit/Dockerfile
-      @@ -7,7 +7,7 @@ RUN swupd update --no-boot-update $swupd_args
-
-      # Grab os-release info from the minimal base image so
-      # that the new content matches the exact OS version
-      -COPY --from=clearlinux/httpd:latest /usr/lib/os-release /
-      +COPY --from=clearlinux/httpd:31110 /usr/lib/os-release /
-
-      # Install additional content in a target directory
-      # using the os version from the minimal base
-      @@ -22,11 +22,11 @@ RUN source /os-release && \
-      # file exists on different layers. To minimize docker
-      # image size, remove the overlapped files before copy.
-      RUN mkdir /os_core_install
-      -COPY --from=clearlinux/httpd:latest / /os_core_install/
-      +COPY --from=clearlinux/httpd:31110 / /os_core_install/
-      RUN cd / && \
-          find os_core_install | sed -e 's/os_core_install/install_root/' | xargs rm -d &> /dev/null || true
-
-      -FROM clearlinux/httpd:latest
-      +FROM clearlinux/httpd:31110
-
-#. Build Dockerfile.
-
-   .. code-block:: bash
-
-      docker build \
-      --no-cache \
-      --build-arg http_proxy=$http_proxy \
-      --build-arg https_proxy=$https_proxy \
-      --tag clearlinux/cgit:31110 \
-      cgit/
-
-#. Verify the installed OS version by noting the :command:`VERSION_ID` value
-   in the :file:`/usr/lib/os-release` file in the container filesystem.
-
-   .. code-block:: bash
-      :linenos:
-      :emphasize-lines: 6
-
-      docker run clearlinux/cgit:31110 cat /usr/lib/os-release
-      NAME="Clear Linux OS"
-      VERSION=1
-      ID=clear-linux-os
-      ID_LIKE=clear-linux-os
-      VERSION_ID=31110
-      PRETTY_NAME="Clear Linux OS"
-      ANSI_COLOR="1;35"
-      HOME_URL="https://clearlinux.org"
-      SUPPORT_URL="https://clearlinux.org"
-      BUG_REPORT_URL="mailto:dev@lists.clearlinux.org"
-      PRIVACY_POLICY_URL=http://www.intel.com/privacy
-
-
-Example 4: Customize an application image at runtime
-****************************************************
-
-This section describes how to modify a published |CL| container at runtime.
-In this example, we add Tensorflow\* into a :command:`clearlinux/python`
-container. This approach can help accelerate the feature development process.
-
-In this example, three separate console windows are used to easily interact
-inside and outside of the container.
-
-First console: Start the container
----------------------------------
-
-#. Launch the clearlinux/python container.
-
-   .. code-block:: bash
-
-      docker run -it --rm clearlinux/python
-      Python 3.7.3 (default, Jun 17 2019, 00:47:04)
-      [GCC 9.1.1 20190616 gcc-9-branch@272336] on linux
-      Type "help", "copyright", "credits" or "license" for more information.
-
-#. Try to import Tensorflow inside the container using the command:
-   :command:`import tensorflow as tf`. The example below shows the expected
-   error message because the Docker image does not yet include the Tensorflow
-   module.
-
-   .. code-block:: bash
-
-      >>> import tensorflow as tf
-      Traceback (most recent call last):
-      File "<stdin>", line 1, in <module>
-      ModuleNotFoundError: No module named 'tensorflow'
-      >>>
-
-Second console: Add a bundle
----------------------------
-
-#. In another console, find the :command:`<Container_ID>` of
-   clearlinux/python launched. This example Container ID is d4ce9d526fa6.
-
-   .. code-block:: bash
-
-      docker ps
-
-#. The output shows:
-
-   .. code-block:: console
-
-     CONTAINER ID   IMAGE               COMMAND   CREATED             STATUS              PORTS          NAMES
-     d4ce9d526fa6   clearlinux/python   python3   About a minute ago  Up About a minute                  amazing_villani
-
-#. Connect to the running clearlinux/python container.
-
-   .. code-block:: bash
-
-      docker exec -it d4ce9d526fa6 /usr/bin/bash
-      root@d4ce9d526fa6/ #
-
-
-#.  Use :command:`swupd` to install the machine-learning-tensorflow bundle.
-
-    .. code-block:: bash
-
-       root@d4ce9d526fa6/ # swupd bundle-add machine-learning-tensorflow
-       Loading required manifests...
-       Downloading packs (692.32 Mb) for:
-       - machine-learning-tensorflow
-       … …
-       ...100%
-       Finishing packs extraction...
-       No extra files need to be downloaded
-       Installing bundle(s) files...
-       ...100%
-       Calling post-update helper scripts.
-       Successfully installed 1 bundle
-
-#. After the machine-learning-tensorflow bundle is installed in the
-   container, in the first console, import Tensorflow, which will be
-   successful now. You could also save the updated container using the
-   command :command:`docker commit <Container_ID>`.
-
-   .. code-block:: bash
-
-      >>> import tensorflow as tf
-      >>> tf.__version__
-      '1.13.1'
-
-Third console: Save the modified container
------------------------------------------
-
-#. In a third console, save the container with a new tag. Our example uses
-   the tag `tensorflow_added` to identify our modified container.
-
-   .. code-block:: bash
-
-      docker commit d4ce9d526fa6 clearlinux/python:tensorflow_added
-
-#. Launch the modified container, and then import Tensorflow with success.
-
-   .. code-block:: bash
-
-      docker run -it clearlinux/python:tensorflow_added
-      Python 3.7.3 (default, Jun 17 2019, 00:47:04)
-      [GCC 9.1.1 20190616 gcc-9-branch@272336] on linux
-      Type "help", "copyright", "credits" or "license" for more information.
-
-   .. code-block:: bash
-
-      >>> import tensorflow as tf
-      >>> tf.__version__
-      '1.13.1'
-      >>>
-
-Background
-**********
-
-Multi-stage Dockerfiles contain more than one :command:`FROM` directive. All
-of the multi-stage Clear Linux OS Dockerfiles share a common base layer
-called :command:`clearlinux/os-core:latest`. All of the higher level layers
-inherit the Clear Linux OS version from this base layer.
-
-For details on how we leveraged multi-stage Docker builds, see the article
-`Minimizing Clear Linux OS container sizes`_.
-
-#. :command:`clearlinux/os-core` is built once per day. It is a container
-   containing a minimal Linux userspace.
-
-#. The target container image uses either :command:`clearlinux/os-core` as a
-   base layer or another container image :command:`clearlinux/` as a base
-   layer.
-
-#. Bundle(s) containing the application are downloaded during the first stage
-   of the build process using :command:`swupd`.
-
-#. The final container image is a composition of its base layer and the
-   specific feature layer, via :command:`FROM clearlinux/<base layer>:latest
-   , such as: os-core, httpd, and via :command:`COPY --from=builder /
-   install_root /`. Using this method, the target container images are kept
-   up to date without file duplication. For application-centric containers,
-   `os-core-update` is excluded to improve size optimization.
-
-Related topics
-**************
-
-*	:ref:`docker`
-*	:ref:`container-image-new`
-
-.. _images on Docker Hub: https://hub.docker.com/u/clearlinux
-.. _GitHub\*: https://github.com/clearlinux/dockerfiles
-.. _clearlinux image on Docker Hub: https://hub.docker.com/_/clearlinux
-.. _clearlinux microservice dockerfile repo: https://github.com/clearlinux/dockerfiles
-
-.. _multi-stage build: https://docs.docker.com/develop/develop-images/multistage-build/
-
-.. _Minimizing Clear Linux OS container sizes: https://clearlinux.org/blogs-news/minimizing-clear-linux-os-container-sizes
-
-.. _multi-stage build to reduce image size: https://clearlinux.org/blogs-news/minimizing-clear-linux-os-container-sizes
@@ -1,11 +1,11 @@
-.. _container-image-new:
+.. _custom-clear-container:

-Build a new |CL|-based container image
-######################################
+Build a custom |CL-ATTR| based Docker container image
+#######################################################

-This guide describes how to build a new |CL-ATTR|-based container image. The
-official base |CL-ATTR| container image is published on Docker\* Hub and is
-updated on a regular basis.
+This guide contains the steps to build a custom container image. The official
+base |CL-ATTR| container image is published on Docker\* Hub and is updated on
+a regular basis.

 .. contents::
   :local:
@@ -90,14 +90,16 @@ Build the base container image

   .. code-block:: bash

-      swupd os-install --url https://cdn.download.clearlinux.org/update --statedir "$PWD"/swupd-state --no-boot-update -B os-core-update,editors,network-basic base
+      swupd os-install --url https://cdn.download.clearlinux.org/update --statedir "$PWD"/swupd-state --no-boot-update --version 29790 -B os-core-update,editors,network-basic base


   The swupd example uses the following flags:

   * :command:`os-install` tells swupd to download and install.
+   * :command:`-V / --version` specifies the version of the |CL| bundles.
   * :command:`--url` specifies the URL of the bundles repository.
-   * :command:`--statedir` specifies the state directory where downloaded bundles and any state information are stored.
+   * :command:`--statedir` specifies the state directory where downloaded bundles
+     and any state information are stored.
   * :command:`--no-boot-update` tells swupd to skip updating boot files because
     boot files are not required for a container.

@@ -322,3 +324,4 @@ Example output:
   Removing intermediate container 7694989e97de
   Successfully built ec23189ef954
   Successfully tagged my-clearlinux-remove-pxe-server-bundle:latest
+
--- a/Show More
+++ b/Show More