Building All Output Formats for RTEMS Docs

[Chris Johns]

On 5/11/16 1:27 am, Joel Sherrill wrote:
> On Fri, Nov 4, 2016 at 1:35 AM, Sebastian Huber
> <sebastian.huber at embedded-brains.de
> <mailto:sebastian.huber at embedded-brains.de>> wrote:
> 
>     Hello Chris,
> 
>     works fine on openSUSE 13.1. I installed a couple of texinfo
>     packages:

Ouch that is not great. Needing that package exposes how fragile this
stuff is, ie the random inclusion of a specific texlive package in that
host package is specific to that distro and a small change in that
package breaks us. Without the ability to do something like install
texlive-full and get all the packages from texlive there is always going
to be holes a host's packages.

On the other hand I am glad you can build the docs.

Could you please send me the c-user.pdf file so I can check it?

Could you please add the packages needed for SUSE to the README.txt?

> and did a "pip install -U Sphinx".

Excellent. I will update the README.txt with this.

> Chris was trying on one of our CentOS 7 machines. I tried on a Fedora 23
> machine and it had the same issue. CentOS 6 appears to be the same.

I have hacked a solution however there are quality issues in the output
generated on CentOS. I am not sure allowing the generation of lesser
quality manuals long term is a good idea however for now it allows us to
see what is involved in resolving the issue.

The current approach is us providing the missing texlive packages and
this works to a limited extent. It breaks down then the missing packages
are fonts. Maybe users will need to install the fonts or maybe we need
to look into our styles and use a font that is known to be available.
For now production quality is created on FreeBSD.

> 
> I am happy to test if you put something together. The docs being
> challenging to build is not good.
> 

I suppose this will happen now we are starting to generate nice looking
docs and that in turn uses different features in Tex or Latex. I could
argue this is a per host issue and it should be raised as bugs against
the distros however I am being pragmatic and attempting to find a
solution we can absorb.

> I checked and Fedora is only at 24. We usually alternate versions for Fedora
> so we aren't on a treadmill. I don't expect any differences.

Shame.

Chris