rtems/docs Texinfo Update Report

Tue Feb 26 18:56:14 UTC 2013

 From help-texinfo

Adding a document specific prefix will require coding in both
texi2any and texi2html init files.

Also based on our directory name usage, you would have
ended up with ".../c_user/c_user-SECTION.html" which is
redundant.

My decision was to build into a subdirectory. I just committed
a patch to do this. It appears to work correctly for both old
and new tools plus "make clean" does work.

If you spot anything else, just yell.

--joel

On 2/26/2013 11:20 AM, Ralf Corsepius wrote:
> 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
>
>

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