rtems/rtems-docs
1
0
Fork 0
mirror of https://git.rtems.org/rtems-docs/ synced 2025-05-14 18:55:59 +08:00
Code Issues Packages Projects Releases Wiki Activity

README: Update with more host specific details.

Browse Source
This commit is contained in:
Chris Johns 2016-11-06 12:53:07 +11:00
parent 25c0a23445
commit ee086511cf
1 changed files with 40 additions and 18 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

58
README.txt
View File

@ -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