rtems/docs Texinfo Update Report

[Ralf Corsepius]

On 02/26/2013 05:26 PM, Joel Sherrill wrote:
> 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.
>
Well, the current upstream maintainer had a history in Fedora - He is 
known to be hyperactive ;)

> 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?
I don't know. I want something, which can easily be handled by make-rules.

This used to be $(PROJECT)*.html, but now there doesn't seem to be any 
connection between the generated *.html files and the texinfo files.
This would mean, we'd have to resort to either using "*.html" in 
CLEANFILES (i.e. no prebuilt *.html allowed) or to explicitly list all 
files (Hardly maintainable).

>> 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.
Here it is:

TEXINPUTS=".:$TEXINPUTS" \
dvips -o networking.ps networking.dvi
This is dvips(k) 5.992 Copyright 2012 Radical Eye Software 
(www.radicaleye.com)
' TeX output 2013.02.26:1753' -> networking.ps
dvips: ! Couldn't find header file: groff.enc
make: *** [networking.ps] Error 1

Googling led me to: 
http://comments.gmane.org/gmane.linux.redhat.fedora.texlive/191
where the Fedora/RH texlive maintainer is telling to "yum install 
texlive-metapost". And indeed it fixes the networking breakdown.

I guess, this is one of the side-effects of TeX having gone through 
"exciting times" in recent years and not all issues having been ironed 
out, yet ;)
In short, I am inclined to believe this to be a Fedora packaging bug.

>
> [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
>
6 years old :) :

# rpm -qf /usr/bin/dvips
texlive-dvips-bin-svn26509.0-16.20130205_r29034.fc18.x86_64

... the bleeding edge.


>> 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).
Sorry, I of course, I meant texi2www ;)
> 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.
>
Hmm, ... I thought, texi2any was supposed to be compatible to texi2html?

>
>> 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.
>
Correct. "maintainer" job.
> 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.
>
Exactly.

Ralf