rtems/docs Texinfo Update Report

[Joel Sherrill]

Hi,

I just realized I posted a status report in the middle
of a reply to Ralf. Texinfo 5.0 has been released. This
is a complete reimplementation of texinfo and there were
issues. Ralf was addressing warnings reported by the
new makeinfo and my local branch had similar fixes.
So I decided it was time to push my branch and send
a community report.

Since updating to texi2any is going to eventually be faced
by others, I wrote a blog entry this weekend about my
experiences:

http://rtemsramblings.blogspot.com/2013/02/rtems-texinfo-tools-update.html

Overall, it builds with old or new texinfo and the PDF output is
much improved with either texinfo version.

In looking at the C Users Guide, I think we are due for a "group
documentation review sprint". With a bit of group participation,
maybe we can split up documents by chapter and get a reviewer per
chapter. With a standard check list of things to do, we could ensure
that this manual is of high quality.  We could follow that with a
similar review of the POSIX User's Manual.

The summary of changes I just pushed are:

+ If texi2any (e.g. texinfo 5.0) is in $PATH, use it instead of texi2html.
     This includes a handful of fairly small and tedious changes:
        - added texi2any init file
        - added some autoconf logic
        - added texi2any invocation
+ I switched us to an html file naming convention recommended by
     the texinfo maintainers for stable URLs. This means generated html
     files are based on section names rather than $(PROJECT)_nnn.html.
     This is based on a standard from around 2004 per them.   This is
     the preferred way of doing things now and the old way isn't supported
     by texi2any.
       - This required modification of the html dependency rules.
         I don't know if they are 100% correct but they work.
+ I updated two figures which were rotated 90% incorrectly in the manual.
+ I did a fair amount of rework on the master document files $(PROJECT).texi
     because we apparently got away with some incorrect texinfo with the
     older tools.
+ Many PDFs included a page with nothing but the title page. This was
     the @top node incorrectly being included in the PDF and other printable
     formats.
+ Multiple minor issues I spotted while reviewing:
    - I updated the preface to add a couple of architectures.
    - I fixed the overview since it didn't list all the chapters
      and those that it did list were not always in the right order.
    - I fixed a few places where the lines were too long and
      ran into the gutter.
    - I corrected at least one code example which was clearly out of date.
    - Copyright and modified dates touched

Ralf is looking into a minor build issue I spotted and I hope he
will review my autoconf/automake changes.

-- 
Joel Sherrill, Ph.D.             Director of Research & Development
joel.sherrill at OARcorp.com        On-Line Applications Research
Ask me about RTEMS: a free RTOS  Huntsville AL 35805
Support Available                (256) 722-9985