summaryrefslogtreecommitdiffstats
path: root/README.txt
diff options
context:
space:
mode:
authorChris Johns <chrisj@rtems.org>2016-11-06 12:53:07 +1100
committerChris Johns <chrisj@rtems.org>2016-11-06 12:53:07 +1100
commitee086511cf4d4cf3b398aa369295445fe4659bc6 (patch)
treeadb459038eee448d3d819b589604f116b29461a2 /README.txt
parent25c0a23445b1477bb06fa879ad4740bab3212822 (diff)
downloadrtems-docs-ee086511cf4d4cf3b398aa369295445fe4659bc6.tar.bz2
README: Update with more host specific details.
Diffstat (limited to 'README.txt')
-rw-r--r--README.txt58
1 files changed, 40 insertions, 18 deletions
diff --git a/README.txt b/README.txt
index 5639329..35c938b 100644
--- a/README.txt
+++ b/README.txt
@@ -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
+production level.
+
+The hosts which produce production quality is:
+
+ FreeBSD
+
Host Setup
----------
-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
+
FreeBSD
~~~~~~~
+PDF Quality: production
+
Sphinx:
# pkg install py27-sphinx
@@ -45,6 +70,12 @@ Single HTML:
CentOS 7
~~~~~~~~
+PDF Quality: poor
+
+Sphinx:
+
+ $ pip install -U sphinx
+
PDF:
# 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:
-
- capt-of
- eqparbox
- ifplatform
- inconsolata
- lato
- upquote
-
Latex Setup
~~~~~~~~~~~
@@ -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
Sphinx.
-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