rtems/docs Texinfo Update Report

[Joel Sherrill]

On 2/26/2013 9:41 AM, Ralf Corsepius wrote:
> On 02/26/2013 03:41 PM, Joel Sherrill wrote:
>
>> Ralf is looking into a minor build issue I spotted and I hope he
>> will review my autoconf/automake changes.
> FWIW: Based upon a very hasty glance (without looking into details)
> there are quite a few issues with the current status in git:
>
> 1. "make clean" doesn't clean up the *.html
> Openly said, I dislike the new file naming scheme. Is there a way to
> have a consistent naming (e.g. like the one we used to have, i.e. all
> files sharing a common prefix)?
I was investigating that but don't know the answer.  I just committed what
I had.

texi2html has a --prefix option which looks promising
texi2any has -c to set customization variables and NODE_FILENAMES looks 
like
it might be OK.

But when I tried those by hand, I didn't see any change. I can ask on the
texinfo list. They have been very helpful.

Personally, I like the idea of splitting them into a subdirectory 
$(PROJECT)/
and I know this works. It just has impact on clean and install. But looking
in a build directory, it is much less cluttered.

Which do you prefer?
> 2. networking/ fails to build networking.ps with a dvips error.
> I haven't yet checked, but this could be a local Fedora issue.
I am on Centos 6.x and I have been building with both old and new texinfo.
I didn't see anything like this. Here are the versions.

[joel at localhost user]$ dvips
This is dvips(k) 5.96.1 Copyright 2007 Radical Eye Software 
(www.radicaleye.com)
Missing DVI file argument (or -f).
Try --help for more information.
[joel at localhost user]$ rpm -qf /usr/bin/dvips
texlive-dvips-2007-57.el6_2.i686

> 3. The texi2*_init[.in] handling is questionable and error-prone.
> I'll likely commit a patch later this week.
The texi2html_init has been that way for at least a year. Improvements 
welcomed.
> 4. It's once again time to investigate whether it's possible to switch
> to automake's standard texi* rules and to stop using custom rules
> (Formerly, texi2html prevented from RTEMS doing so).
Fine with me. The entire goal of my documentation work for the past 
18-24 months
has been to get us pushed up to newer and current tools. texi2www was 
stone cold
dead.

Unfortunately, the reality is that texi2html is out there but dead. We 
will continue
to see it for years though. But texi2any is also likely to take years to 
be common
in distributions.

As long as we can support both, I am happy. We will have to do this for an
unknown length of time.
> 5. It's once again time, to consider shipping prebuilt *.texi's and to
> make the *.t->*.texi conversion a "packager-maintainer"'s job (This is
> what the GCS demands and likely is a prerequist for 4.)
This might be problematic because if you add a section or subsection, this
has to be run.

In principle, I don't have an issue with it. In practice, 
--enable-maintainer-mode
may be required just to edit and regenerate the documentation.

Just needs to be thought through. That's it.
>
> Ralf
>
>
>
> _______________________________________________
> rtems-devel mailing list
> rtems-devel at rtems.org
> http://www.rtems.org/mailman/listinfo/rtems-devel


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