[PATCH rtems-docs v1] readme: Minor clarifications and fixes

Thu Jul 15 15:07:56 UTC 2021

On Wed, Jul 14, 2021 at 8:44 AM Stephen Clark <stephen.clark at oarcorp.com> wrote:
>
> Added some instructions for setting up CentOS 8.
> Fixed some minor typographical errors.
> Updated a dead link.
> Reworded some sentences for clarity
> ---
>  README.txt | 58 ++++++++++++++++++++++++++++++------------------------
>  1 file changed, 32 insertions(+), 26 deletions(-)
>
> diff --git a/README.txt b/README.txt
> index 03f57ed..53549f2 100644
> --- a/README.txt
> +++ b/README.txt
> @@ -1,16 +1,17 @@
>  RTEMS Project Documentation
>  ===========================
>
> -The documents are written in ReST and built using Sphinx. The build system will
> -check the version of Sphinx and ensure you have a suitable version
> -available. If your host does not provide a packaged version use PIP to fetch a
> +The documents are written in ReST and built using Sphinx. The waf build system
> +will check the version of Sphinx and ensure you have a suitable version
> +available. If your host does not provide a packaged version, use PIP to fetch a
>  recent version. The Sphinx website provides details on doing this.
>
> -ReST is the Re-Structured-Text format. It is a simple markup language that allows
> -us to create quality documentaion. It is flexible and powerful however does not
> -attempt to train it to create a specific format. You need to test any new way
> -of presenting something on all output formats. What may look great in one
> -format may not translate with the same clarity to another output format.
> +ReST is the Re-Structured-Text format. It is a simple markup language that
> +allows us to create quality documentation which can easily be converted to
> +multiple different formats. This flexibility is convenient, but you still need
> +to test any new way of presenting something on all output formats. What may look
> +great in one format may not translate with the same clarity to another output
> +format.
>
>  The RTEMS Documentation output formats are:
>
> @@ -26,7 +27,7 @@ Images can be created from source using PlantUML and Ditaa.
>
>  A Sphinx checksheet is:
>
> - http://docs.sphinxdocs.com/en/latest/cheatsheet.html#rst-cheat-sheet
> + https://sphinx-tutorial.readthedocs.io/cheatsheet/#rst-cheat-sheet
>
>  Production Quality Hosts
>  ------------------------
> @@ -45,7 +46,7 @@ NOTE: RedHat Enterprise Linux (RHEL) and Fedora should be the same as CentOS.
>  Images
>  ------
>
> -All images should be placed int he 'images' directory and referenced from the
> +All images should be placed in the 'images' directory and referenced from the
>  ReST with a relative path. This lets us shared and control images.
>
>  We prefer being able to build images from source. This is not always possible
> @@ -85,7 +86,7 @@ The home page contain the language options. The PlantUML online demo server
>  supports Ditaa so use that resource as an online tool. The Ditaa image source
>  extension is '.ditaa'.
>
> -You do not need PlantUML or Ditaa install to build our documentation. The
> +You do not need PlantUML or Ditaa installed to build our documentation. The
>  online resources can be used. Save the source and the generated PNG file in the
>  same directory under 'images'.
>
> @@ -94,12 +95,12 @@ Host Setup
>
>  HTML builds directly with Sphinx, PDF requires a full Latex (texlive) install,
>  and building a Single HTML page requires the 'inliner' tool. The
> -sphinxcontrib-bibtex extension is mandatory. PlantUML requres the Node.js
> +sphinxcontrib-bibtex extension is mandatory. PlantUML requires the Node.js
>  package called 'node-plantuml' which installs the 'puml' command and Ditaa needs
>  the 'ditaa' command and package. Ditaa images are built using the 'puml'
>  command.
>
> -Please add your host as you set it up.
> +Please add your host to this section as you set it up.
>
>  The best results are produced with Python3 and a virtual environment`. It can
>  create a specific python environment using `pip`.
> @@ -107,7 +108,7 @@ create a specific python environment using `pip`.
>  Virtual Environment
>  ~~~~~~~~~~~~~~~~~~~
>
> -Create a directory to house the virtual environment, create the envrionment
> +Create a directory to house the virtual environment, create the environment
>  and the activate it. This example assumes Python3 and the `venv` module:
>
>    $ mkdir sphinx
> @@ -120,7 +121,7 @@ Alternatively you can use the `virtualenv` command:
>    $ virtualenv sphinx
>    $ . ./sphinx/bin/activate
>
> -The prompt will now change. You can install Sphinx with:
> +Either way, the prompt will now change. You can install Sphinx with:
>
>    $ pip install sphinx
>    $ pip install sphinxcontrib-bibtex
> @@ -207,8 +208,8 @@ Ditaa:
>
>    # pkg install ditaa
>
> -CentOS 7
> -~~~~~~~~
> +CentOS 7 & 8
> +~~~~~~~~~~~~
>

I think add a section below for CentOS 8, and refer the reader back to
CentOS 7 with the differences noted?

Does & typeset properly in the generated documentation? Not that it
matters if you refactor the CentOS 8 part out.

Maybe send this change separately from the reformatting/typo/URL
fixes. Prefer to separate new content from fixes to existing content.
>  PDF Quality: production
>
> @@ -221,6 +222,8 @@ software. As root,
>    # yum install centos-release-scl
>    # yum install rh-python36
>
> +On CentOS 8, this is unnecessary as Python 3.x is the default.
> +
>  Then you can create your own virtual Python environment
>  for use with the Sphinx toolchain.
>
> @@ -263,7 +266,8 @@ PDF:
>  Single HTML:
>
>  NOTE: npm appears to be part of the EPEL repository for RHEL and CentOS.
> -You may have to add that repository to your configuration.
> +You may have to add that repository to your configuration. Install npm with
> +dnf instead of yum on Centos 8.
>
>    # yum install npm
>    # npm install -g inliner
> @@ -278,6 +282,8 @@ Spell check:
>
>    # yum install aspell
>
> +Use dnf instead of yum on Centos8.
> +
>  PATH:
>
>    Ensure the appropriate directories are PREPENDED to your PATH before
> @@ -321,11 +327,11 @@ packages. There is no common naming and no real way to figure what texlive
>  package is present in a host's packaging. It seems not all of texlive is
>  available.
>
> -The RTEMS Documentation waf configure phase check for each texlive package used
> +The RTEMS Documentation waf configure phase checks for each texlive package used
>  in the generated output and the styles. If you complete configure with the
>  --pdf option you should be able to build PDF documentation.
>
> -The texlive package requirments come from the Latex styles we are using and
> +The texlive package requirements come from the Latex styles we are using and
>  Sphinx.
>
>  An example of failures are:
> @@ -450,7 +456,7 @@ existing documentation for an example and if unsure ask.
>
>  2. Do not insert tab characters, use spaces, no trailing white space.
>
> -3. Pasted text such as console output can exceed 80 columns however it is
> +3. Pasted text such as console output can exceed 80 columns; however, it is
>     preferred even this text is wrapped at 80 columns. Long lines in code block
>     text causes issues with the PDF output.
>
> @@ -464,7 +470,7 @@ existing documentation for an example and if unsure ask.
>        5  ^^^^^^ Sub-sub-sub-section
>        6  ~~~~~~ Sub-sub-sub-sub-section
>
> -5. For literal output, such as shell commands and code do not use '::'
> +5. For literal output such as shell commands and code, do not use '::'
>     at the trailing edge of the previous paragraph as it generates
>     warnings as the autodetect fails to find a suitable format. Use the
>     '.. code-block::' with a suitable lexical label. The lexers are:
> @@ -511,8 +517,8 @@ existing documentation for an example and if unsure ask.
>         :align: center
>         :alt: This is the alt text for some output types.
>
> -8. Callouts can be implemented manually using a literal block which can use
> -   '::' or a code block and topic block is used for the items. For
> +8. Callouts can be implemented manually using a literal block ('::')
> +   or a code block. Either way, a topic block is used for the items. For
>     example:
>
>       .. code-block: c
> @@ -535,9 +541,9 @@ existing documentation for an example and if unsure ask.
>         4. Exit with an exit code of 0. This value can be checked by the
>            caller of this program.
>
> -   Note, the topic items are manually numbered, which makes it easier to see
> +   Note the topic items are manually numbered, which makes it easier to see
>     which item matches the text. Use <> for the number and align at a position
> -   that works and makes the number as visible as possible. Use hanging indents
> +   that makes the number as visible as possible. Use hanging indents
>     if an items extends past a single line.
>
>  9. Use the RTEMS domain references for URLs and mailing lists. For example to
> --
> 2.27.0
>
> _______________________________________________
> devel mailing list
> devel at rtems.org
> http://lists.rtems.org/mailman/listinfo/devel