Refilling overrides texinfo commands

Refilling overrides texinfo commands

[Luc Teirlinck]

There are problems with refilling as currently implemented and it
seems impossible to get around these problems, unless Emacs would
start operating directly on the Texinfo source files rather than on
the info files.  (Or if Emacs would give up on its refilling
attempts.)

The problem is that refilling seems to completely undo the
functionality described in (texinfo)Breaks.

Example:

===File ~/refillbug.texi====================================
\input texinfo    @c -*-texinfo-*-
@comment %**start of header
@setfilename refillbug.info
@settitle Refilling Bug
@comment %**end of header

@node Top
@top Only Node

@xref{makeinfo advantages,,,texinfo}, where is written:@*
@code{makeinfo} is a C program that is independent of Emacs.

@bye
============================================================

Which yields the following Info file:

===File ~/refillbug.info====================================
This is refillbug.info, produced by makeinfo version 4.6 from
/home/teirllm/info/refillbug.texi.

\x1f
File: refillbug.info,  Node: Top,  Up: (dir)

Only Node
*********

*Note makeinfo advantages: (texinfo)makeinfo advantages, where is
written:
`makeinfo' is a C program that is independent of Emacs.


\x1f
Tag Table:
Node: Top\x7f98
\x1f
End Tag Table
============================================================

THe stand-alone Info reader respects the @*, the current Emacs CVS
does not.

Sincerely,

Luc.

Re: Refilling overrides texinfo commands

[Kim F. Storm]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:

> There are problems with refilling as currently implemented and it
> seems impossible to get around these problems, unless Emacs would
> start operating directly on the Texinfo source files rather than on
> the info files.  (Or if Emacs would give up on its refilling
> attempts.)

Please notice that refilling _ONLY_ happens in paragraphs (or parts of
those) where a reference is rewritten/hidden, i.e. its doesn't
generally refill any paragraphs which don't contain rewritten
references.

Your example illustrates such a case, but I have been unable to find
any actual examples in the existing texi files (I haven't looked at
every @*, but I'd say it seems like a non-problem in practice).

There are still problems with the hiding of note references which I
need to address, but I haven't seen any (obvious) examples of breaks
being undone.


> THe stand-alone Info reader respects the @*, the current Emacs CVS
> does not.

Emacs info does respect @* in general -- it is only in connection with
note references that it may accidentally be undone.


-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Refilling overrides texinfo commands

[Luc Teirlinck]

Kim Storm wrote:

   Your example illustrates such a case, but I have been unable to find
   any actual examples in the existing texi files (I haven't looked at
   every @*, but I'd say it seems like a non-problem in practice).

and:

   Emacs info does respect @* in general -- it is only in connection with
   note references that it may accidentally be undone.

Yes, but we have to worry not just about present info files included
with the Emacs distribution, but about future info files and about
`Texinfo' as a language.  It reduces the attractiveness of a language
if one of its main readers respects its commands "most of the time" as
opposed to "all of the time".  If commands not working as specified
does not even get considered a "bug", reliability is gone.

Sincerely,

Luc.

Re: Refilling overrides texinfo commands

[Richard Stallman]

    > THe stand-alone Info reader respects the @*, the current Emacs CVS
    > does not.

    Emacs info does respect @* in general -- it is only in connection with
    note references that it may accidentally be undone.

Note references can appear anywhere.  It is just chance whether a
cross reference appears near an @*.

I have another solution to propose:

1. Change the standalone info to hide the same text as Emacs info does.

2. Change Makeinfo to recognize when filling that that text will be
   hidden.

None of this is terribly hard, and it will work totally reliably.

Re: Refilling overrides texinfo commands

[Luc Teirlinck]

Richard Stallman wrote:
   
   I have another solution to propose:

   1. Change the standalone info to hide the same text as Emacs info does.

   2. Change Makeinfo to recognize when filling that that text will be
      hidden.

That would have the negative effect of effectively disabling
Info-hide-note-references and making the text-hiding "mandatory"
instead of having it as an optional feature.  Several people prefer
not to have the information in question hidden and they have valid
reasons for that.

I have the impression that some people on this list believe that the
only reason one could probably want to have Info-hide-note-references
set to anything else but t is to satisfy some strange ideological
obsession.  This is extremely far from the truth.  I am not speaking
in the abstract here.  I am using Info extensively.  For instance, I
used Info recently to learn Texinfo.  I was reluctant to just set
Info-hide-note-references to nil, because I am rewriting parts of the
tutorial and for that reason, I prefer to use all-default settings in
Info.  But I tended to leave vis-mode on in the presence of
cross-references.  The reason is that several cross-references in the
Texinfo manual led to the Emacs manual.  Knowing that information
saved me the time and trouble to follow these cross-references: I
already knew that stuff anyway.  Similar situations occur in various
other manuals I studied using Info.

Also, if we want to maximize quality of appearance to the fullest then
there are tons of things we might want to do.  _This is really
important stuff_ would look a lot better if it were written in the
font used by texinfo-mode than enclosed in _..._. Same for *...*.  It
would look nicer if @code, @kbd and several others would yield
different fonts and/or colors, rather than all being enclosed in
`...'.  Same for various different stuff enclosed in "...".  In the
case of @code, @kbd and the like, and even for _..._ and *...*, the
information can not be reliably recovered from the Info file, but it
is all in the source file.  (I am not familiar with XML and DocBook.)

So one question is: how far do we want to go longer term?  Is the
current hiding and refilling a first step to "better things to come"?
Are we happy with the Info format for the long term or do we want a
separate "Emacs format"?

I believe that trying to reformat Info files, as currently being
attempted, makes no sense.  Info is an output format, not a mark up
language.  Texinfo is a mark up language.  So are XML and DocBook.

Sincerely,

Luc.

Re: Refilling overrides texinfo commands

[Luc Teirlinck]

>From my previous message:

   I believe that trying to reformat Info files, as currently being
   attempted, makes no sense.

To avoid confusion, I was referring to reformatting Info files by
editing them using Emacs (to do refilling and potentially other
things) before presenting them in an Emacs buffer.

Sincerely,

Luc.

Re: Refilling overrides texinfo commands

[Richard Stallman]

    That would have the negative effect of effectively disabling
    Info-hide-note-references and making the text-hiding "mandatory"
    instead of having it as an optional feature.  Several people prefer
    not to have the information in question hidden and they have valid
    reasons for that.

You are right.

So I have gone back to my conclusion of a week ago, that we should
stop refilling paragraphs in Info.  When some xref text is hidden, the
line will be shorter.  That looks a little strange, but it is not
really wrong.  When refilling is done, the results can be positively
wrong.

    I believe that trying to reformat Info files, as currently being
    attempted, makes no sense.  Info is an output format, not a mark up
    language.  Texinfo is a mark up language.  So are XML and DocBook.

Perhaps makeinfo is fast enough now that we could stop installing
Info files and have them regenerated when users want them.
If so, we could have an option to generate them in various ways
(hiding xrefs, showing xrefs, etc).

Re: Refilling overrides texinfo commands

[Kim F. Storm]

Richard Stallman <rms@gnu.org> writes:

>     That would have the negative effect of effectively disabling
>     Info-hide-note-references and making the text-hiding "mandatory"
>     instead of having it as an optional feature.  Several people prefer
>     not to have the information in question hidden and they have valid
>     reasons for that.
> 
> You are right.
> 
> So I have gone back to my conclusion of a week ago, that we should
> stop refilling paragraphs in Info.  When some xref text is hidden, the
> line will be shorter.  That looks a little strange, but it is not
> really wrong.  When refilling is done, the results can be positively
> wrong.

I agree.  Rather than completely removing the refilling, I have added
a new variable Info-refill-paragraphs (default disabled) with suitable
warnings about its potential ill effects.

Take a look at the end of "(texinfo)makeinfo in Emacs" for a really
extreme example of how bad the text can look _without_ refilling.



> 
>     I believe that trying to reformat Info files, as currently being
>     attempted, makes no sense.  Info is an output format, not a mark up
>     language.  Texinfo is a mark up language.  So are XML and DocBook.
> 
> Perhaps makeinfo is fast enough now that we could stop installing
> Info files and have them regenerated when users want them.
> If so, we could have an option to generate them in various ways
> (hiding xrefs, showing xrefs, etc).

We could do that always, provided that the result is cached.

However, we would then require specific (very new) versions of
makeinfo to be installed on the user's system.  That would be a
problem for many users.

So I think we should still install info files as a fall-back, and only
require to run makeinfo when some option (like
Info-hide-note-references) is explicitly turned on.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Refilling overrides texinfo commands

[Robert J. Chassell]

   Take a look at the end of "(texinfo)makeinfo in Emacs" for a really
   extreme example of how bad the text can look _without_ refilling.

It looks good when Info-hide-note-references is nil.

It looks bad when Info-hide-note-references is t.  

Please always specify the value of such variables, since it took me a
long time to confirm the circumstances in which your statement is true.

-- 
    Robert J. Chassell                         Rattlesnake Enterprises
    http://www.rattlesnake.com                  GnuPG Key ID: 004B4AC8
    http://www.teak.cc                             bob@rattlesnake.com

Re: Refilling overrides texinfo commands

[Kim F. Storm]

"Robert J. Chassell" <bob@rattlesnake.com> writes:

>    Take a look at the end of "(texinfo)makeinfo in Emacs" for a really
>    extreme example of how bad the text can look _without_ refilling.
> 
> It looks good when Info-hide-note-references is nil.
> 
> It looks bad when Info-hide-note-references is t.  
> 
> Please always specify the value of such variables, since it took me a
> long time to confirm the circumstances in which your statement is true.

Sorry to be imprecise ... I thought this was obvious from the context
since the refilling only happens when xref hiding is active.

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Refilling overrides texinfo commands

[Richard Stallman]

       Take a look at the end of "(texinfo)makeinfo in Emacs" for a really
       extreme example of how bad the text can look _without_ refilling.

    It looks good when Info-hide-note-references is nil.

    It looks bad when Info-hide-note-references is t.  

That mode is the default, so by default it looks bad (I guess).
But there seems to be nothing feasible that we can do about it.

Re: Refilling overrides texinfo commands

[Richard Stallman]

    However, we would then require specific (very new) versions of
    makeinfo to be installed on the user's system.  That would be a
    problem for many users.

    So I think we should still install info files as a fall-back, and only
    require to run makeinfo when some option (like
    Info-hide-note-references) is explicitly turned on.

That could be a good idea.

Anything that involves installing Texinfo files needs work
at the system architecture level--to arrange to install
them alongside the info files.

Re: Refilling overrides texinfo commands

[Kim F. Storm]

Richard Stallman <rms@gnu.org> writes:

>     > THe stand-alone Info reader respects the @*, the current Emacs CVS
>     > does not.
> 
>     Emacs info does respect @* in general -- it is only in connection with
>     note references that it may accidentally be undone.
> 
> Note references can appear anywhere.  It is just chance whether a
> cross reference appears near an @*.
> 

True, but @* isn't widely used, so it doesn't really cause that much
trouble in practice...

> I have another solution to propose:
> 
> 1. Change the standalone info to hide the same text as Emacs info does.
> 
> 2. Change Makeinfo to recognize when filling that that text will be
>    hidden.

Brilliant idea!

-- 
Kim F. Storm <storm@cua.dk> http://www.cua.dk

Re: Refilling overrides texinfo commands

[Karl Berry]

    unless Emacs would
    start operating directly on the Texinfo source files 

That isn't a viable alternative, because then the Texinfo language
couldn't change independent of Emacs.  That's more or less the whole
reason that Info format exists.

    (Or if Emacs would give up on its refilling attempts.)

Although I appreciate the desire to refill the info files according to
the window size (I assume that's the point), there isn't enough
information in the Info files to do this, as you say.

If you want to completely rewrite the output, Emacs could (in theory)
use the xml or docbook output.  In practice, I doubt it is ready for
such critical use, nor do I think it's a good idea, all I'm saying is
that that's the extent to which we'd have to go to do it right.

Re: Refilling overrides texinfo commands

[Karl Berry]

    > 1. Change the standalone info to hide the same text as Emacs info does.

    > 2. Change Makeinfo to recognize when filling that that text will be
    >    hidden.

I suppose, although one of the whole purposes of Info format was to make
as simple to display as possible.  If any info reader now has to
magically know which text to hide, that makes the format that much less
transparent.

Also, this will be the first time regular paragraphs will be treated
differently in Info and in plain text.  I guess that's not exactly a
problem, but it seems somewhat strange.

Finally, and most importantly, isn't the whole hiding feature optional?
In that case, if the user turns off hiding, they will have lines that
are too long.  What then?  They lose because they want to use Info as
originally designed?  Doesn't seem right.  Likewise, old info readers
won't know they're now supposed to hide text, so their display of new
info files will be suboptimal, although still usable.


Thinking more generally, it seems to me that a number of these new Emacs
Info features, including this one, are trying to intuit document
structure/information out of the plain text output, and that way lies
madness.

For example, what if next month someone decides they want to display
code fragments in a monospaced font and regular text in a variable-width
font?  (Heck, for all I know, maybe you already put in other magic
variables to try to do that.)  Or, what if someone resizes their window
to be wider or narrower, wouldn't it be nice if Emacs refilled all the
text to the new window size?  I'm sure we could dream up many other
features along these lines, based on analogous features in web browsers.

These are very reasonable things to want to do, but Info format just was
never designed to support any of this stuff, and grafting it on now
seems wrong to me.  As I said before, parsing the XML or docbook output
from makeinfo seems like a much more viable approach, since those
formats preserve the document structure.  (In theory, anyway, I'm sure
the implementation is not 100% correct at present.)

And, following that path, we might as well abandon the original Info
format entirely, instead of trying to add this or that feature to it.
We could leave Emacs Info and standalone Info basically alone, and
implement fancy new features in some new Emacs module that isn't
hampered by compatibility constraints.


One thing that would help is if the people who are working on these new
features could give a brief summary of where they want Info to go.  Kim,
anyone?  That way, we (I) won't be surprised after the fact when it
turns out makeinfo or standalone info need changes, etc.

Sorry this is so long.

k