rtems/docs Texinfo Update Report

Fri Mar 1 18:52:51 UTC 2013

Hi,

After reading both rtemsramblings posts, I have to agree... although there are many benefits to using old tools, at some point they no longer meet our needs... 

For example, the build system:

Suppose there are 100 patches a day committed to RTEMS, that would mean the build system would have to 100+ bsps in less than 14 minutes and 24 seconds, or an average of less than 9 seconds per bsp, to include bootstrap, configure, make, and make install for a maintainer build.  Performance of various build systems can be found at: http://www.retropaganda.info/~bohan/work/psycle/branches/bohan/wonderbuild/benchmarks/time.xml

A start towards a solution might be to:
1. identify a smaller subproject, (like cpukit/pppd) 
2. update it's build system, and 
3. link that into the RTEMS Autotools system per http://www.gnu.org/software/automake/manual/html_node/Third_002dParty-Makefiles.html.

Even though I've studied autotools for months, and love the idea of a build system that works across ALL Linux platforms, I'd suggest we use a build system significantly faster than autotools, so we can:
1. build faster, 
2. do continuous integration, and finally look into 
3. splitting off small changes for review.

If that's agreeable with others, we should identify another build system that will bring us closer to the time requirements...

Thanks,
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

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

_______________________________________________
rtems-devel mailing list
rtems-devel at rtems.org
http://www.rtems.org/mailman/listinfo/rtems-devel