rtems/docs Texinfo Update Report

Cynthia Rempel cynt6007 at vandals.uidaho.edu
Fri Mar 1 04:03:12 UTC 2013

Hi Dr. Sherrill,
A documentation sprint sounds interesting, how do I sign up?
Cynthia Rempel
From: rtems-devel-bounces at rtems.org [rtems-devel-bounces at rtems.org] on behalf of Joel Sherrill [joel.sherrill at OARcorp.com]
Sent: Tuesday, February 26, 2013 6:41 AM
To: rtems-devel at rtems.org; rtems-users at rtems.org
Subject: rtems/docs Texinfo Update Report


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


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

rtems-devel mailing list
rtems-devel at rtems.org

More information about the devel mailing list