|author||Chris Johns <firstname.lastname@example.org>||2016-11-06 12:53:07 +1100|
|committer||Chris Johns <email@example.com>||2016-11-06 12:53:07 +1100|
README: Update with more host specific details.
Diffstat (limited to 'README.txt')
1 files changed, 40 insertions, 18 deletions
@@ -1,16 +1,16 @@
RTEMS Project Documentation
-The documents is written in ReST and built using Sphinx. The build system will
-check the version and ensure you have a suitable version. If your host does not
-provide a packaged version use PIP to fetch a recent version. The Sphinx
-website provides details on doing this.
+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
+recent version. The Sphinx website provides details on doing this.
ReST is the Re-Structed-Text format. It is a simple markup language that allows
us to create quality documentaion. It is flexible and powerful however do not
attempt to train it to create a specific format. You need to test any new way
-of present something on all output formats. What may look great in one format
-may not translate with the same clarity to another output format.
+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:
@@ -18,17 +18,42 @@ The RTEMS Documentation output formats are:
PDF - Single PDF per manual.
SIngle HTML - Single HTML, one file per manual.
+The PDF format is cerated using Latex and that uses texlive packages. This
+exposes us to the complex world of Latex however the quality of the documents
+created is worth it.
+Production Quality Hosts
+We allow the building of PDF documentation on hosts that do not have a fully
+suitable texlive environment and this results in quality that is not at the
+The hosts which produce production quality is:
-HTML builds directly with Sphinx, PDF requires a full Latex install, and
-building a Single HTML page requires the 'inliner' tool.
+HTML builds directly with Sphinx, PDF requires a full Latex (texlive) install,
+and building a Single HTML page requires the 'inliner' tool.
Please add your host as you set it up.
+Sphinx Per User Install
+You can use this method to install a personal version of Sphinx if your host
+does not provide a suitable package:
+ $ pip install -U Sphinx
+PDF Quality: production
# pkg install py27-sphinx
@@ -45,6 +70,12 @@ Single HTML:
+PDF Quality: poor
+ $ pip install -U sphinx
# yum install -y texlive-*
@@ -54,15 +85,6 @@ Single HTML:
# yum install npm
# npm install -g inliner
-This does not provide all the require packages. Missing are:
@@ -79,7 +101,7 @@ in the generated output and the styles. If you complete configure with the
The texlive package requirments come from the Latex styles we are using and
-An example of a failure is a default CentOS 7:
+An example of failures are:
Checking for Tex package 'Bjarne' : ok
Checking for Tex package 'alltt' : ok