RTEMS Texinfo Tools Update

A couple of years ago, Chris Johns and I began to discuss that RTEMS has had a long and successful history as a free software project. One aspect of this discussion resulted in the Open Source and Generational Differences. This post reflected on how new developers can have a tendency to avoid projects that use "uncool" tools. They want to be on the leading edge of technology. However, another aspect of using uncool tools is that they are old. RTEMS-based applications often have lifespans measured in decades from development, through fielding, to long term sustainment. This insight lead us to begin to review the tools we depended upon for long-term viability and that they continued to offer a high quality solution. The transition from CVS to git has been the most visible outcome of this effort.

But lurking within the RTEMS source tree was a dependency on a long dead tool - texi2www. RTEMS was the last user of this and had to include the source code in our own tree. This was exactly the type of situation Chris and I had realized could happen and it already had without us noticing. In November 2011, I posted to the GNU Texinfo Help Mailing list asking for advice on converting to the more modern texi2html program. Unfortunately, I learned that texi2html was considered deprecated and being re-implemented in Perl and the new implementation would be known as texi2any. This led to me converting us away from the stone cold dead texi2www to texi2html. With the recent release of texinfo 5.0, I began to ensure that our documentation would build with either texi2html 1,82 or texi2any from texinfo 5.0 and that the build infrastructure could detect which to use.

The goal of this post is to point out how we invoke tools, initialization file differences and the minor changes to our documentation required to support both tools. The other tools in the texinfo package such as makeinfo did require us to make changes to the source but did not change their invocation. I will detail the changes to our texinfo source files after showing the command line differences for the html converters.

The commands executed by our build infrastructure are generated by an autoconf based build infrastructure. This sometimes leads to longer than absolutely necessary command lines. I have made no attempt to shorten or clean these command lines up. These are for the RTEMS C User's Guide whose main texinfo file is c_user.texi.

The following is the invocation of texi2html 1.82:

 texi2html -D use-html --split node --node-files -o ./ --top-file index.html --init-file=../texi2html_init \  
   -I /home/joel/rtems-4.11-work/rtems//doc/user -I /home/joel/rtems-4.11-work/rtems//doc \  
   -I .. -I . --menu /home/joel/rtems-4.11-work/rtems//doc/user/c_user.texi \  
   /home/joel/rtems-4.11-work/rtems//doc/user/c_user.texi  

This is the corresponding invocation of texi2any from texinfo 5.0:

 texi2any --html -D use-html --split node -o ./ --init-file=../texi2any_init \  
   -I /home/joel/rtems-4.11-work/rtems//doc/user -I /home/joel/rtems-4.11-work/rtems//doc \  
   -I .. -I . /home/joel/rtems-4.11-work/rtems//doc/user/c_user.texi  

Notice that both command lines are quite similar. However, texi2html requires the --node-files argument to produce individual html file names which are based on the section or chapter name. By default, they will be named using a pattern line DOC_nnn.html.

The other thing to note is that they both accept initialization files. However, the format of the initialization files is very different between the two implementations. Texinfo supports hierarchically structured documents and allows the author to provide links to the next section, previous section, and the section that contains or is logically above the current one. The RTEMS Project has a tool which automatically constructs the node markups based on chapter, section, and subsection headings. Thus, the RTEMS documentation is fully hierarchically linked with no manual node definition required. The RTEMS documentation build system uses the initialization file to define a custom header, footer and to modify the navigation buttons.

This is the file texi2html_init generated by our build infrastructure:

 my $button_text = '<a href="../index.html">Library</a>';  
 push @SECTION_BUTTONS, \$button_text;  
 push @CHAPTER_BUTTONS, \$button_text;  
 push @MISC_BUTTONS, \$button_text;  
 push @TOP_BUTTONS, \$button_text;  
 $AFTER_BODY_OPEN =  
 '<A HREF="http://www.rtems.com" target="Text Frame">  
 <IMG align=right BORDER=0 SRC="../images/rtems_logo.jpg" ALT="RTEMS  
 Logo"> </A>  
 <H1>RTEMS 4.10.99.0 On-Line Library</H1>  
 ';  
 $PRE_BODY_CLOSE =  
 'Copyright &copy; 1988-2011  
 <A HREF="http://www.oarcorp.com" target="Text Frame">OAR Corporation</A>  
 ';  
 1;  

The initialization files reflects the internal implementation of the two programs and the format used by texi2any is different. We have an initialization file which accomplishes similar things in the generated HTML files but looks different. For example, the texi2html output has navigation icons while the texi2any output has textual links.

This is the file texi2any_init generated by our build infrastructure:

 set_from_init_file ('AFTER_BODY_OPEN',  
 '<A HREF="http://www.rtems.com" target="Text Frame">  
 <IMG align=right BORDER=0 SRC="../images/rtems_logo.jpg" ALT="RTEMS  
 Logo">  </A>  
 <H1>RTEMS 4.10.99.0 On-Line Library</H1>  
 ');  
 texinfo_register_handler('setup', \&add_button);  
 my $button_text = '<a href="../dir.html">Directory</a>';  
 sub add_button($)  
 {  
  my $self = shift;  
  foreach my $button_type ('SECTION_BUTTONS', 'CHAPTER_BUTTONS',   
               'MISC_BUTTONS', 'TOP_BUTTONS') {  
   my $buttons = $self->get_conf($button_type);  
   push @$buttons, \$button_text;  
  }  
  return 1;  
 }  

There were only a couple of issues encountered with our use of texinfo which required modifying the source.

• Missing @item in @itemize lists now results in warnings. 
• The order of menu definition, @top and its @node, and file @include statements in the top level texinfo files had to be reordered. Texinfo 5.0 is not as forgiving on this.

In addition, I spotted mistakes in our documentation when reviewing the various output forms. The entire range of patches can be viewed online here.

NOTE: As of 24 February 2013, these have not been committed. When they are committed, links will be provided to the git repository.

We would like to take advantage of features in the newer tools and are investigating using a print on demand service for RTEMS manuals. I hope there is experience in the texinfo community about this but, if not, I suppose I will pester the maintainers until the results are satisfactory and report on what I had to do.

Thanks to the Texinfo maintainers Patrice Dumas, Karl Berry, and Eli Zaretskii folyzr being incredibly patient and helpful through this process.

GSOC Presentation at University of Tennessee at Chattanooga

Earlier today, I returned to my alma mater, the University of Tennessee at Chattanooga, to give presentations on RTEMS and the Google Summer of Code 2013 (download here). About 25 people were in attendance including two faculty members. Thankfully, my wife Michele had driven and let me do final review on the presentations. Chattanooga is about a two hour drive from Huntsville and in a different time zone (Eastern not Central). We had allowed time for traffic and parking problems but had no traffic. We ending up arriving about forty-five minutes early.   We were met in the parking lot by a student who provided a visitor’s parking pass. This greatly simplified having a car on campus. Parking at any university seems to be a challenge.

After no A/V difficulties, I put up a montage of pictures from some of the projects which use RTEMS.  Those who attended the GSOC 2012 Mentor Summit will remember the slide from the lightning talks. It is memorable because someone from another project presented it. I had forgotten the talks and went to the Google Store. The montage highlights awesome projects based on RTEMS including the BMW Superbike, Curiosity, Herschel, Milkymist, Solar Dynamic Observatory, and MMS. As students came in, there were plenty of questions about the projects.  I created the slide to give at an RTEMS friendly workshop where most knew what RTEMS was and I wanted to highlight users. It turns out this is a great slide to get conversations going. If other FLOSS organizations can brag on where there software is used, then a user montage is a good thing to have.

I presented the official GSOC slides first. I felt it was important to emphasize that all types of FLOSS software was represented and that all of the organizations were interested in student participation. Being effective and appropriate to participate in GSOC requires organizations to provide wish lists, mentors, regular interaction with students, friendly communities, etc..

I then moved to the RTEMS specific presentation which very briefly introduces RTEMS but focuses more on recent activities, ongoing activities, and our wish list. It highlights areas we want improvements to occur even in software development process areas. As the last slide came up, I realized I was finishing on time and had presented thirty minutes, leaving fifteen to twenty minutes for questions. I ended my talk by reminding them that I would love to see them all as RTEMS contributors but would be just as happy to see them involved in the FLOSS community on ANY project. We are a collection of organizations but do have common goals.

There were a lot of questions on GSOC followed by some on RTEMS. One student asked where GSOC work occurred. There were questions on how the mentoring worked and what mechanisms were used to communicate with the mentors. I noticed students were packing up and realized they had ten minutes to get to their next class. There were no more questions but I hung around a while.

The big surprise was when a student came up to me while I was packing up. He asked about real-time and SMP as a potential area for Ph.D. work. I told him that I thought it was an open area of research and with some literature research he should be able to find a good area. Years of research into uniprocessor real-time systems and scheduling have given us practical engineering solutions. But the complexities of modern pipelines, caching, and interactions of multiple cores break some of the underlying assumptions. I am concerned that this same level of maturity has not been reached in SMP embedded systems which require rigorous analysis of predictability.

My wife generously waited in the presentation room while I visited with the only faculty member left from when I was a student there Dr. Jack Thompson. Then my wife and I walked around campus, enjoying a pretty day and reminiscing. After all, it was only one day after Valentines Day and we met one another while students here.