rtems/docs Texinfo Update Report
Joel Sherrill
joel.sherrill at OARcorp.com
Tue Feb 26 14:41:10 UTC 2013
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
More information about the devel
mailing list