Building All Output Formats for RTEMS Docs

[Chris Johns]

Hi,

Help needed so please read.

Building the RTEMS Documentation for HTML is easy. You need to install 
Sphnix and it should run. There is a README.txt in the top directory of 
rtems-docs.git repo and I have add FreeBSD and a little bit for CentOS 
7. I would welcome patches to the README.txt for new host operating systems.

There is a way to install Sphinx as a user using 'pip' which is 
currently not documented. I would welcome a patch detailing how to do this.

Building a Single HTML file is a little more complex but it is not too 
bad. I have added instructions for FreeBSD and CentOS. I suspect most 
Linux systems will just work. Please test and report.

Building PDF is more complex and will take a little time to be supported 
on a range of host operating systems. PDF is built using pdflatex which 
uses Latex and that is part of texlive. It seems texlive is packaged in 
various ways depending on the base OS and the distro. Some distributions 
such as CentOS are missing 6 texlive packages.

I think the way to solve this is to add the missing packages to our docs 
repo on a per host basis. This has to be per host because of a possible 
version skew on hosts where the package is available at the system 
level. Another concern is dependences where a package requires more and 
more. We need to limit what is needed. My hope it only a few are needed, 
for example the 6 missing on CentOS 7. The only way to tell is to start 
to add the packages and see.

I can add support to the waf build system to manage this but I cannot 
test and create the various data sets for the hosts who need additional 
texlive packages.

To test install Sphinx for your host, clone the docs repo, install as 
much or as little of texlive as you think is needed, configure with the 
--pdf option. If you get any failures post back here with the details of 
your host and the failures. For CentOS 7 I installed all 600+ texlive 
packages (which I think just package madness).

Chris