Divergence in menu appearance between Emacs Info and standalone Info

Divergence in menu appearance between Emacs Info and standalone Info

[Richard Stallman]

Emacs Info has a feature that hides some of the text in a menu.  As a
result, the explanation of menus in info.texi is not really accurate
for Emacs any more.  The message below explains the details.  The
question is what to do about this.

One idea is to take out the Emacs feature that hides this text, so the
text becomes visible again.  Another idea is to change the stand-alone
Info to hide this text too, and then change info.texi accordingly.

A third option is to put conditionals into info.texi and have
two versions of it, one for Emacs and one for standalone info.
But I think that divergence is probably a bad idea.

What do you think?

Meanwhile, Emacs already modifies the Info buffer for display, so
instead of making that text invisible, perhaps it should delete the
text and put the information from it into text properties of the menu
item names.


Date: Mon, 2 Jun 2003 23:45:56 -0500 (CDT)
X-Authentication-Warning: eel.dms.auburn.edu: teirllm set sender to teirllm@dms.auburn.edu using -f
From: Luc Teirlinck <teirllm@dms.auburn.edu>
To: rms@gnu.org
CC: emacs-devel@gnu.org
In-reply-to: <E19N34O-0006SH-2L@fencepost.gnu.org> (message from Richard
	Stallman on Tue, 03 Jun 2003 00:06:44 -0400)
Subject: Re: Problems with info (emacs version)
X-Spam-Status: No, hits=-7.1 required=5.0
	tests=EMAIL_ATTRIBUTION,IN_REP_TO,REFERENCES,SPAM_PHRASE_01_02,
	      X_AUTH_WARNING
	version=2.41
X-Spam-Level: 

Richard Stallman wrote:

       1.  Easiest one to fix:

	   (info)Help-M

	   which is used in the tutorial, *only* describes menus as they
	   appear in the standalone info, not as they appear in the emacs
	   version and the two are very different.

   Would you please tell me the specific differences?  I scanned through
   that none and did not notice anything incorrect.

Yes. From (info)Help-M:

       * Foo:  Node about FOO.      This tells about FOO.

     The subtopic name is Foo, and the node describing it is `Node about
  FOO'.  The rest of the line is just for the reader's Information.  [[
  But this line is not a real menu item, simply because there is no line
  above it which starts with `* Menu:'.]]

     When you use a menu to go to another node (in a way that will be
  described soon), what you specify is the subtopic name, the first
  thing
  in the menu line.  Info uses it to find the menu line, extracts the
  node name from it, and goes to that node.  The reason that there is
  both a subtopic name and a node name is that the node name must be
  meaningful to the computer and may therefore have to be ugly looking.
  The subtopic name can be chosen just to be convenient for the user to
  specify.  Often the node name is convenient for the user to specify
  and
  so both it and the subtopic name are the same.  There is an
  abbreviation for this:

       * Foo::   This tells about FOO.

  This means that the subtopic name and node name are the same; they are
  both `Foo'.

My own remarks:

Note that this goes into quite some length explaining why the user
sees both a 

"*Foo:" and a "Node about Foo" and what the difference is,

but the user using Emacs, sees only:

"*Foo".  Nowhere is it told that ":   Node about FOO" is normally
invisible in Emacs.  The user looks for it, can not find it and does
not know what is going on.

       * Foo::   This tells about FOO.

  This means that the subtopic name and node name are the same; they
  are
  both `Foo'.

Again, only:

* Foo is visible in Emacs, not the "::" The Emacs info user has no
  idea what all of this stuff about special meaning of "::" is about.

Of course, the entire discussion *is* correct if you know about the
invisible text.  One would not have to make a lot of changes in the
documentation if one would provide the user with convenient commands
in Info to toggle invisibility, say `v'. All one would have to do
would be to tell the user that in Emacs you first have to type `v' to
see the text being talked about.  I could easily implement such a
visibility toggling feature myself, if you would agree with it.

Sincerely,

Luc.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Miles Bader]

Richard Stallman <rms@gnu.org> writes:
> Meanwhile, Emacs already modifies the Info buffer for display, so
> instead of making that text invisible, perhaps it should delete the
> text and put the information from it into text properties of the menu
> item names.

That would solve a lot of minor problems the current method causes, and
generally be more robust, I think.  Are there any downsides to doing it
that way?

-Miles
-- 
Fast, small, soon; pick any 2.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Karl Berry]

    One idea is to take out the Emacs feature that hides this text, so the
    text becomes visible again.  

I'm afraid that I have some sympathy for this approach, despite the work
that's gone into it.  I recognize that the node names are, in some
sense, `extra' information and removing them makes for fewer things for
the reader to see.  That much is good.  But the downside is that Texinfo
is completely based on node names, and hiding them seems to me like it
could easily cause more confusion than it solves.

In the example at hand,
* Foo: A Node about Foo: ...
the user will select `Foo', but then end up at `A Node about Foo', with
no real way of making the connection between them.

    Another idea is to change the stand-alone
    Info to hide this text too, and then change info.texi accordingly.

I won't be able to do this myself any time soon.  However, I'll ask the
other Info programmer volunteers if they'd like to work on it.

    A third option is to put conditionals into info.texi and have
    two versions of it, one for Emacs and one for standalone info.
    But I think that divergence is probably a bad idea.

I don't like the divergent conditionals either.  However, I think it
would be ok to simply say in info.texi, `Emacs Info does it this way,
and standalone Info does it that way'.  I think that would be clear to
users of both programs.  Better than (effectively) having two different
manuals with the same name, anyway.

    What do you think?

I gather the default is to hide the node names.  Because of the problems
above, I suggest making the default to show them, i.e., the traditional
behavior.

Also, from previous mail, I think that node names can also now be hidden
in xrefs?  Anywhere else?  The Texinfo manual will also need to mention
this new feature, lest authors be confused when Emacs does not show them
what the manual says to expect.

Thanks,
karl

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Miles Bader]

On Wed, Jun 04, 2003 at 10:04:28AM -0400, Karl Berry wrote:
> I gather the default is to hide the node names.  Because of the problems
> above, I suggest making the default to show them, i.e., the traditional
> behavior.

I'm absolutely against this.  The info text is _far_ more readable with the
various info verbiage (both menu entries and footnotes) hidden, and the
current problems, annoying as they are, are quite secondary to the main goal
of making readable manuals.

I think there are inevitably going to be differences between emacs and other
info readers, so we may as well suck up and admit it, and provide separate
manuals (perhaps through conditional compilation).

-Miles
-- 
Fast, small, soon; pick any 2.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Stefan Monnier]

> In the example at hand,
> * Foo: A Node about Foo: ...
> the user will select `Foo', but then end up at `A Node about Foo', with
> no real way of making the connection between them.

I don't understand what's the problem.  How many users currently
actively use node names ?  From what I can tell, these seem to be mostly
used internally, much like URLs in HTML.  And if they want to make the
connection, they can just look at the `Node:' at the top of the
buffer which tells them where they landed.

Also, the actual node is mentioned in the tooltip that pops up
when the mouse is over `Foo' (or at least it should since the
patch I installed yesterday).

The main reason for hiding the text AFAIK is to clean up the menu,
and I think it's very effective at that.  Maybe it's only needed
for the `dir' file, tho, since the other menus are generally well
aligned already (because they are not made up of disparate pieces
like `dir' is).  But I also like the hiding in xrefs, it makes the
text much more pleasant to read.

> I don't like the divergent conditionals either.  However, I think it
> would be ok to simply say in info.texi, `Emacs Info does it this way,
> and standalone Info does it that way'.  I think that would be clear to
> users of both programs.  Better than (effectively) having two different
> manuals with the same name, anyway.

Indeed.  After all there are other Info readers, besides `info'
and `emacs' and they don't necessarily look alike.


	Stefan

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Andreas Schwab]

Miles Bader <miles@lsi.nec.co.jp> writes:

|> Richard Stallman <rms@gnu.org> writes:
|> > Meanwhile, Emacs already modifies the Info buffer for display, so
|> > instead of making that text invisible, perhaps it should delete the
|> > text and put the information from it into text properties of the menu
|> > item names.
|> 
|> That would solve a lot of minor problems the current method causes, and
|> generally be more robust, I think.  Are there any downsides to doing it
|> that way?

While we are at it we should refrain from refilling paragraphs, because
that frequently messes up the formatting in a way such that the result is
misleading or difficult to read.

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux AG, Deutschherrnstr. 15-19, D-90429 Nürnberg
Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Eli Zaretskii]

> From: "Stefan Monnier" <monnier+gnu/emacs@rum.cs.yale.edu>
> Date: Wed, 04 Jun 2003 11:01:29 -0400
> 
> I don't understand what's the problem.  How many users currently
> actively use node names ?  From what I can tell, these seem to be mostly
> used internally, much like URLs in HTML.

I'm not sure that's true.  The `g' command, for example, accepts node
names (with completion) and is an effective way of going if you know
where, or remember the initial word(s) of the node name.

Please don't take the above as meaning that I suggest to restore the
node names' display.  But let's not exaggerate the situation even if
we need that to make a point.

> After all there are other Info readers, besides `info'
> and `emacs' and they don't necessarily look alike.

The other readers aren't GNU software, so we don't have to describe
them in the Texinfo manual.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Eli Zaretskii]

> Date: Wed, 4 Jun 2003 10:04:28 -0400
> From: karl@freefriends.org (Karl Berry)
> 
> I don't like the divergent conditionals either.  However, I think it
> would be ok to simply say in info.texi, `Emacs Info does it this way,
> and standalone Info does it that way'.

I'd go with this suggestion.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Stefan Monnier]

> > I don't understand what's the problem.  How many users currently
> > actively use node names ?  From what I can tell, these seem to be mostly
> > used internally, much like URLs in HTML.
> 
> I'm not sure that's true.  The `g' command, for example, accepts node
> names (with completion) and is an effective way of going if you know

I never claimed it was true, if you read what I wrote.
I'm genuinely asking how important it is.  I'm by far the most
sophisticated user of `info' among the few people I know around here
and I never use `g' other than to visit a particular info *file*
(which is why I added completion inside the (...) ;-).


	Stefan

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Luc Teirlinck]

Karl Berry wrote:

   I don't like the divergent conditionals either.  However, I think it
   would be ok to simply say in info.texi, `Emacs Info does it this way,
   and standalone Info does it that way'.  I think that would be clear to
   users of both programs.  Better than (effectively) having two different
   manuals with the same name, anyway.

I usually use the Emacs version of Info.  Occasionally I will invoke
the standalone version from an xterm.  Because the manual tends to say:

`Emacs Info does it this way, and standalone Info does it that way'

(although in the case I pointed out, it forgot to do so),  I can use
both in an effective way without being surprised by the differences.
Presenting the user with two different manuals (regardless of how this
would be implemented internally) would make this nearly impossible to
achieve (instead of nearly trivial, as it is now).

In the case at hand, I believe it would probably have to say
(depending on what we decide to do):

"If you use standalone Info or use Emacs Info and set
Info-hide-note-references to nil..."

Sincerely,

Luc.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Luc Teirlinck]

Stefan Monnier wrote:

   I never claimed it was true, if you read what I wrote.
   I'm genuinely asking how important it is.  I'm by far the most
   sophisticated user of `info' among the few people I know around here
   and I never use `g' other than to visit a particular info *file*
   (which is why I added completion inside the (...) ;-).

The `g' command, in combination with the `c' command, is, in as far as
I know, the most effective way of referring somebody else to a
particular node.

I noticed the following problem:

C-h C-i C-h C-m:

First line of "Advanced commands":

q     Quit Info: reselect previously selected buffer.

The exact same line already appears earlier.  Moreover, `q' is not an
advanced command (at least not by my standards).  Moreover the `c'
command is nowhere mentioned.

I propose to replace this line with:

c     Put name of current info node in the kill ring.

I could commit this change if one would want me to do so.

Sincerely,

Luc.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Stefan Monnier]

> Stefan Monnier wrote:
> 
>    I never claimed it was true, if you read what I wrote.
>    I'm genuinely asking how important it is.  I'm by far the most
>    sophisticated user of `info' among the few people I know around here
>    and I never use `g' other than to visit a particular info *file*
>    (which is why I added completion inside the (...) ;-).
> 
> The `g' command, in combination with the `c' command, is, in as far as
> I know, the most effective way of referring somebody else to a
> particular node.

1 - This does not rely on having the node names visible in the menus
    and xrefs, but only in the the "Node:" on the first line of the node.
2 - (info "<node name>") is a better way than using `g' since the `somebody'
    can just click on it (or hit C-x C-e).


	Stefan

Re: Divergence in menu appearance between Emacs Info and standalone Info

[David Kastrup]

Andreas Schwab <schwab@suse.de> writes:

> Miles Bader <miles@lsi.nec.co.jp> writes:
> 
> |> Richard Stallman <rms@gnu.org> writes:
> |> > Meanwhile, Emacs already modifies the Info buffer for display, so
> |> > instead of making that text invisible, perhaps it should delete the
> |> > text and put the information from it into text properties of the menu
> |> > item names.
> |> 
> |> That would solve a lot of minor problems the current method causes, and
> |> generally be more robust, I think.  Are there any downsides to doing it
> |> that way?
> 
> While we are at it we should refrain from refilling paragraphs, because
> that frequently messes up the formatting in a way such that the result is
> misleading or difficult to read.

TeXinfo has provisions for tables and preformatted code.  Normal text
should be reflown to fit the window width, and it is done in the
standalone info generation, too.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Karl Berry]

    Presenting the user with two different manuals (regardless of how this
    would be implemented internally) would make this nearly impossible to

I agree wholeheartedly.  That's the only thing I feel really strongly
about, that we shouldn't have two manuals (especially not both named
info.texi!) for the two programs.

I believe many users use both standalone Info and Emacs info.el, and
those two interfaces are so very similar (by design, after all) it is
good to just describe the discrepancies where they exist, in a single
manual.  And we should work to minimize any such discrepancies.

By contrast, the other Info readers such as pinfo and tkinfo (besides
not being GNU software, as Eli says), have (I believe) quite different
interfaces.  So they need different manuals.

    "If you use standalone Info or use Emacs Info and set
    Info-hide-note-references to nil..."

There could/should also be a description of the Emacs Info behavior
with the node hiding.  Especially if it's the default.


As for whether the hiding is the default or not, that's your collective
decision.  rms asked my opinion, so I gave it, that's all :).

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Luc Teirlinck]

Karl Berry wrote:

       "If you use standalone Info or use Emacs Info and set
       Info-hide-note-references to nil..."

   There could/should also be a description of the Emacs Info behavior
   with the node hiding.  Especially if it's the default.

I did not want to suggest otherwise.  My only point was that we should
point out all options that the Emacs user has, including ones that
differ from the default, especially ones that make it look more like
the standalone version, which is useful for people using both.

Sincerely,

Luc.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Luc Teirlinck]

Stefan Monnier wrote:

       (info "<node name>") is a better way than using `g' since the
       `somebody' can just click on it (or hit C-x C-e).

That is, assuming the `somebody' receives mail in an emacs buffer.
In general, I would not consider M-: (info "<node name>") to be more
convenient or intuitive than C-h i g <node-name>.

But, your question was:

   How many users currently actively use node names ?  From what I can
   tell, these seem to be mostly used internally, much like URLs in
   HTML.

(info "<node-name>") uses a node name just as actively as g, or not?
The point I am trying to make is that it is useful for an Info user to
know the concept of a node name, it is not something of purely
internal importance.  This does not mean that it is the first thing a
beginning Info user should worry about.  It does also not necessarily
mean that node names should be displayed in menus, that is a separate
question.

Sincerely,

Luc.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Kim F. Storm]

Andreas Schwab <schwab@suse.de> writes:

> While we are at it we should refrain from refilling paragraphs, because
> that frequently messes up the formatting in a way such that the result is
> misleading or difficult to read.

I just installed patches to make the refilling more robust, so that
it should now preserve menus and other "standard" info formatting.

If you find specific examples which still fail to get refilled
correctly, please report them.

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

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Miles Bader]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:
> The point I am trying to make is that it is useful for an Info user to
> know the concept of a node name, it is not something of purely
> internal importance.  It does also not necessarily mean that node
> names should be displayed in menus, that is a separate question.

I think that's the important point -- for users and the `g' command,
node names are something associated with a node, and the fact that menus
also use them is just an implementation detail.

-Miles
-- 
P.S.  All information contained in the above letter is false,
      for reasons of military security.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Eli Zaretskii]

> From: "Stefan Monnier" <monnier+gnu/emacs@rum.cs.yale.edu>
> Date: Wed, 04 Jun 2003 11:31:09 -0400
> 
> I'm genuinely asking how important it is.  I'm by far the most
> sophisticated user of `info' among the few people I know around here
> and I never use `g' other than to visit a particular info *file*
> (which is why I added completion inside the (...) ;-).

FWIW, I use `g' quite a lot.  YMMV, of course.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Eli Zaretskii]

> From: "Stefan Monnier" <monnier+gnu/emacs@rum.cs.yale.edu>
> Date: Wed, 04 Jun 2003 13:14:30 -0400
> 
> 2 - (info "<node name>") is a better way than using `g' since the `somebody'
>     can just click on it (or hit C-x C-e).

That requires to use "M-:", which, I think, many Emacs users don't use
(if they even know about it).

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Richard Stallman]

    In the example at hand,
    * Foo: A Node about Foo: ...
    the user will select `Foo', but then end up at `A Node about Foo', with
    no real way of making the connection between them.

Actually I don't think the user would be very surprised if he followed
a link named "foo" and ended up in a node named "A Node about Foo".
They are clearly about the same topic.

    I gather the default is to hide the node names.  Because of the problems
    above, I suggest making the default to show them, i.e., the traditional
    behavior.

Since experienced people won't be bothered by the node names,
this is tantamount to taking out the feature of hiding them.

I would rather make standalone Info hide them too.  So please do
ask the other developers.

      However, I think it
    would be ok to simply say in info.texi, `Emacs Info does it this way,
    and standalone Info does it that way'.

That is fine when both descriptions are short, but in this case the
differences are in numerous places in the node.  It may look very ugly
to describe both alternatives.  Could you try?

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Richard Stallman]

I would think that use of the g command is pretty rare.
I use it occasionally to visit a file, as you do.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Robert J. Chassell]

   I gather the default is to hide the node names.  

Yes.  This is and has been a mistake.  It harms GNU documentation.

Texinfo uses node names to structure an Info file, and section headers
to structure a typeset file.  Although the two may be the same, they
should be different in every GNU manual.

The Texinfo manual talks about this in a node called:

    (texinfo)Menu Location

which does *not* have a section title.  While the text of the node
appears in a printed manual, the title does not.  The text appears as
part of the first section of the chapter on Menus.

There is good reason for this:

      By convention, a menu is put at the end of a node since a reader
    who uses the menu may not see text that follows it.  Furthermore,
    a node that has a menu should not contain much text. If you have a
    lot of text and a menu, move most of the text into a new
    subnode--all but a few lines.  Otherwise, a reader with a terminal
    that displays only a few lines may miss the menu and its
    associated text.  As a practical matter, you should locate a menu
    within 20 lines of the beginning of the node.

      The short text before a menu may look awkward in a printed
    manual.  To avoid this, you can write a menu near the beginning of
    its node and follow the menu by an `@node' line, and then an
    `@heading' line located within `@ifinfo' and `@end ifinfo'.  This
    way, the menu, `@node' line, and title appear only in the Info
    file, not the printed document.


It does not matter to readers so much that the printed manual looks
different from the online manual; after all, people expect a printed
manual to be more limited in many ways -- for example, you cannot
conveniently navigate through a printed manual using regular
expression searches.  

(You cannot conveniently navigate through a multi-page HTML site
either, which is why Web sites are still more backward than Info.
Hiding node names in Info may lead some people to think falsely that
Texinfo is as bad as HTML.)

The surface expression of Info should reflect its deep representation
more closely than a printed surface expression.  Quite simply, it is
dangerous to provide a online manual that does not tell users
implicitly that node names are more important than section titles.

Rather than hide node names, it would make more sense to modify Info
to hide section titles than the reverse.

Note that the first part of a menu entry is the menu entry name; that
first part is *not* the section title.  (I sometimes get the
impression that poor writers think a menu entry is the name of a
section.)

A menu does not contain a obligatory section title slot.  The `C-c C-c
C-d' (`texinfo-start-menu-description') Texinfo mode command inserts a
node's section or chapter title in the space for the description in a
menu entry line in the far right hand part of the line -- in the
`description' slot, not in the entry name or node name slots.  This
makes it easy to modify the section title text to provide a better
description.

Since we want good GNU documentation, and since node names are such an
important part of good Texinfo writing, we should keep node names
visible in Info.  It is and has been a mistake to hide the node names
in Info.

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

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Karl Berry]

    in this case the
    differences are in numerous places in the node.  It may look very ugly
    to describe both alternatives.  Could you try?

It would be better for someone who has actually used or programmed this
feature to write at least the first draft.  I don't know any of the details.

Luc, perhaps you make a first cut at changing info.texi, and then I'll
review it?

Thanks,
karl

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Andreas Schwab]

storm@cua.dk (Kim F. Storm) writes:

|> I just installed patches to make the refilling more robust, so that
|> it should now preserve menus and other "standard" info formatting.

Thanks, looks much better now.

|> If you find specific examples which still fail to get refilled
|> correctly, please report them.

There are still some problems when references are wrapped between "see"
and the reference name.  The invisible property makes the indentation
invisible.  See (elisp)Functions for Key Lookup or (libc)Error Codes for
examples.

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux AG, Deutschherrnstr. 15-19, D-90429 Nürnberg
Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Stefan Monnier]

> > From: "Stefan Monnier" <monnier+gnu/emacs@rum.cs.yale.edu>
> > Date: Wed, 04 Jun 2003 13:14:30 -0400
> > 
> > 2 - (info "<node name>") is a better way than using `g' since the `somebody'
> >     can just click on it (or hit C-x C-e).
> 
> That requires to use "M-:", which, I think, many Emacs users don't use
> (if they even know about it).

Funny, I never thought about using M-: to evaluate it.
I'd only ever seen mentioned C-x C-e.
But the thing is (or should be if it's not for you) highlighted
and clickable, provided you read it in Gnus.  And it's a lot
more user-readable than C-h i g (you don't have to interpret it
as a command, but just as a special syntax).


	Stefan

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Luc Teirlinck]

Karl Berry wrote:

       in this case the
       differences are in numerous places in the node.  It may look very ugly
       to describe both alternatives.  Could you try?

   It would be better for someone who has actually used or programmed this
   feature to write at least the first draft.  I don't know any of the details.

   Luc, perhaps you make a first cut at changing info.texi, and then I'll
   review it?

I would be willing to help.  But does it make any sense to do this
right now?  We have not yet decided how either the Emacs or the
standalone versions are going to look like.  Would the first task at
hand not be to worry about those two questions?  Otherwise, we might
just keep rewriting the manual continuously, as we keep changing our
minds.  The relevant changes in the Emacs version of Info do not
appear in any released Emacs version and should (in my opinion) not
appear in any released Emacs version until we have made a decision on
how the Emacs version of Info is going to look.  It would be very bad
to just keep switching the behavior back and forth on the user, in as
far as released versions are concerned.  CVS users know (or should
know) that some features could change back and forth depending on the
unexpected problems that they turn out to cause.

In other words to me it would seem that the order should be:

1.  First decide how the Emacs version is going to look.

2.  Decide how the standalone version is going to look.

3.  Implement 1 and 2.

4.  Rewrite the documentation accordingly.

Is there any reason to do things in a different order, unless 3. is
scheduled for the extremely vague and extremely distant future?  I do
not believe implementation of 1. should be put off until then.
Implementation of 2. conceivably might, if nobody can find the time.
In that case, I would rewrite the manual based on current behavior of
the standalone version.

Sincerely,

Luc.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Luc Teirlinck]

To be somewhat more precise than in my previous reply:

Even if it is decided to retain note hiding in the Emacs version and
that the standalone version is not going to be changed very soon, I
still would need to know, before rewriting the manual, whether we are
going to reimplement note hiding by using Stefan's suggestion or by
deletion, whether Info-hide-note-references is going to keep getting
supported and in which form and so on.

Sincerely,

Luc.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Karl Berry]

    1.  First decide how the Emacs version is going to look.

I had the impression that the decision had been made, namely to hide
those node names by default.  Are there other issues?

    2.  Decide how the standalone version is going to look.

In principle, I would like it to operate the same as Emacs, as much as
possible.  However, the other programmers haven't responded to my
request, so I don't know when this will happen.

I don't know when the next release of Emacs is likely to happen, but I
bet it will be (long) before any Texinfo release incorporating the
changes.

    3.  Implement 1 and 2.
    4.  Rewrite the documentation accordingly.

I think the documentation may need to be updated after 1 is done and
before 2, because whatever info.texi gets shipped with Emacs should
reflect what's in that Emacs, and yet also still be relevant to
standalone Info.

I wish I could say otherwise, that standalone Info will track Emacs
immediately and we could release at the same time, but I just don't have
the person-hours to make it happen ...

Thanks,
karl

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Luc Teirlinck]

Karl Berry wrote:

   I had the impression that the decision had been made, namely to hide
   those node names by default.  Are there other issues?

Yes, as I pointed out in a follow-up, which crossed your reply in
transit.

   I don't know when the next release of Emacs is likely to happen, but I
   bet it will be (long) before any Texinfo release incorporating the
   changes.

So I will rewrite based on the current version of standalone Info.

   I think the documentation may need to be updated after 1 is done

I will take a look at it after 1. is done (and preferably
implemented).  Again, to do a good job, I believe I need to know the
details of 1. , not just the "big picture".  I might have some further
suggestions about these details, depending on the actual chosen
reimplementation of node hiding.

Sincerely,

Luc.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Kai Großjohann]

karl@freefriends.org (Karl Berry) writes:

> In the example at hand,
> * Foo: A Node about Foo: ...
> the user will select `Foo', but then end up at `A Node about Foo', with
> no real way of making the connection between them.

People using web browsers are well aware of this discrepancy.  I see
the above as being conceptually similar to <a href="about_foo.html">Foo</a>.

A tooltip or displaying the target node name (of the xref at point) in
the echo area might be useful as a visual cue, though.
-- 
This line is not blank.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Luc Teirlinck]

>From my previous message:

   I still would need to know, before rewriting the manual, whether we
   are going to reimplement note hiding by using Stefan's suggestion
   or by deletion, whether Info-hide-note-references is going to keep
   getting supported and in which form and so on.

Stefan informed me that he already committed his changes the day
before yesterday.  (I should have checked the Change Log more
carefully.)  I looked at it briefly and I probably will have various
comments and suggestions to make.  I will take a closer look at it
later (maybe this evening).  Let us first make sure that we can get
the exact behavior we want, and then I can describe that behavior in
the manual.

With this particular reimplementation, there is no problem with
Info-hide-note-references.  I mentioned it because I was wondering
how deletion would affect it.

Sincerely,

Luc.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Luc Teirlinck]

Kai Grossjohann wrote:

   A tooltip or displaying the target node name (of the xref at point) in
   the echo area might be useful as a visual cue, though.

I believe that is already implemented, if you use today's CVS.
(Stefan inplemented this.)

Sincerely,

Luc.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Miles Bader]

On Fri, Jun 06, 2003 at 02:11:48AM +0200, Kim F. Storm wrote:
> I don't see how it can harm documentation to make it easier to read!
> 
> And IMO the traditional *Note format definitely doesn't make info
> documents easy to read.

You can probably guess this based on my previous posts, but I strongly agree
with Kim.  The old style is _hard to read_; this is especially true for
documents with verbose node-names, where xrefs can become enourmously
distracting.

There was once some technical reason for showing embedded node names --
keeping out-of-band data was too annoying -- but now that there isn't, we
should get rid of them.

[Though I favor the `destructively modify the text' approach, as I thik it
would lead to future weird artifacts]

-Miles
-- 
We live, as we dream -- alone....

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Robert J. Chassell]

   With users (including myself) becoming more and more used to web
   browsers, the traditional "info way" of presenting references looks
   old-fashioned, and is IMHO a real obstackle to a "natural reading
   flow".

There is the difference.  The more often I read a document with a Web
browser, the more angry I get at Berners-Lee for inventing a broken
format!  It is impossible to navigate through a multi-page HTML
document using regular expression searches!  

In a Web browser, there is no way you can get into a "natural reading
flow" in which you move around a document using the comforts and
efficiency provided by computers over the past two decades.

A Web browser is a time machine into the dark ages.

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

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Stefan Monnier]

>    With users (including myself) becoming more and more used to web
>    browsers, the traditional "info way" of presenting references looks
>    old-fashioned, and is IMHO a real obstackle to a "natural reading
>    flow".
> 
> There is the difference.  The more often I read a document with a Web
> browser, the more angry I get at Berners-Lee for inventing a broken
> format!  It is impossible to navigate through a multi-page HTML
> document using regular expression searches!

Sure, I love Info for all those things and more.
But what does it have to do with whether or not node names are shown
prominently in menus and xrefs ?
I've been benefitting from the structure offered by Texinfo,
I've been benefitting from the whole-document-regexp-search,
.... and all this without ever worrying about node names.



	Stefan


PS: BTW, node names do not reflect any of the structure either.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Kim F. Storm]

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

> I will take a look at it after 1. is done (and preferably
> implemented).  Again, to do a good job, I believe I need to know the
> details of 1. , not just the "big picture".  I might have some further
> suggestions about these details, depending on the actual chosen
> reimplementation of node hiding.

Since I implemented the node hiding in the first place, I'm probably
biased here, but I honestly don't see why the description of the node
hiding needs a lot of changes to the documentation.

I would simply write -- early in the documentation -- something like
this:

----------------------- snip ------------------------

Notice that starting with GNU emacs version 21.5, the emacs info
reader usually replaces the elaborate menu and node references
desscribed in the following sections by simpler `hyperlinks'.  

If you prefer to see the elaborate references in emacs info too, you
need to customize the Info-hide-note-references variable.

-----------------------------------------------------

What more do you need to say?



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

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Robert J. Chassell]

"Stefan Monnier" <monnier+gnu/emacs@rum.cs.yale.edu> wrote:

    Sure, I love Info for all those things and more.
    But what does it have to do with whether or not node names are shown
    prominently in menus and xrefs ?

You probably don't have any trouble writing good Texinfo, but I have
read too much bad documentation to like an output format that does not
help a novice writer understand Texinfo.  I fear the Web browser
mindset, which is to accept an inefficient and obsolete tool as if it
were modern.

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

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Kim F. Storm]

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

>    I gather the default is to hide the node names.  
> 
> Yes.  This is and has been a mistake.  It harms GNU documentation.

I don't see how it can harm documentation to make it easier to read!

And IMO the traditional *Note format definitely doesn't make info
documents easy to read.

I agree that good node references are very important when reading
documentation searching for specific information, but if you are
reading larger sections of the manual in a sequential manner, you
shouldn't really care about node references, and in that context, the
elaborate note references are _very_ disturbing to the normal reading
flow.  Replacing them with "(see XXX)" is much less disctractive IMO.

And the "(see XXX)" references are IMO perfectly adequate also when
searching through documentation for a specific feature ... personally,
I don't care a bit about what section of the manual the information
I'm searching for is written -- as long as I can get there with a
single click on the hyperlink.

With users (including myself) becoming more and more used to web
browsers, the traditional "info way" of presenting references looks
old-fashioned, and is IMHO a real obstackle to a "natural reading
flow".  That's why I implemented the node hiding feature.

I strongly prefer seeing something like this when looking at a web
page:

 For more information, see _tips_and_tricks_.

rather than

 For more information, URL: http://www.gnu.org/info/emacs/tips-and-tricks.html



I have tried to read your arguments against the node hiding, but I
really don't understand what's so bad about it.

> The surface expression of Info should reflect its deep representation
> more closely than a printed surface expression.  Quite simply, it is
> dangerous to provide a online manual that does not tell users
> implicitly that node names are more important than section titles.

That structure is an important topic for the author of the info file
(making it easy for the user to navigate), but I really don't see why
the user has to be bothered seeing that structure.

> 
> Rather than hide node names, it would make more sense to modify Info
> to hide section titles than the reverse.

Could be.  I admit that I looked at the info files _as a user_, and as
such, I took the part of the nodes that looked most useful to me.  I
probably found the section names too verbose for my personal taste...

And I haven't had problems with the result so far...  

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

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Miles Bader]

"Robert J. Chassell" <bob@rattlesnake.com> writes:
> You probably don't have any trouble writing good Texinfo, but I have
> read too much bad documentation to like an output format that does not
> help a novice writer understand Texinfo.

You're not making much sense here; how does the verbiage surrounding
traditional info xrefs help a novice writer understand Texinfo?

The extra verbiage _does_ make info documents harder to read as simple
documents, which for the great majority of users (who aren't texinfo
authors) is the crucial point.

[and note that Kim's code doesn't change texinfo into html -- links
still have a standard textual form, simply one that's less intrusive
than the traditional form]

-Miles
-- 
"Though they may have different meanings, the cries of 'Yeeeee-haw!' and
 'Allahu akbar!' are, in spirit, not actually all that different."

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Eli Zaretskii]

> From: "Stefan Monnier" <monnier+gnu/emacs@rum.cs.yale.edu>
> Date: Thu, 05 Jun 2003 09:35:42 -0400
> 
> > > From: "Stefan Monnier" <monnier+gnu/emacs@rum.cs.yale.edu>
> > > Date: Wed, 04 Jun 2003 13:14:30 -0400
> > > 
> > > 2 - (info "<node name>") is a better way than using `g' since the `somebody'
> > >     can just click on it (or hit C-x C-e).
> > 
> > That requires to use "M-:", which, I think, many Emacs users don't use
> > (if they even know about it).
> 
> Funny, I never thought about using M-: to evaluate it.
> I'd only ever seen mentioned C-x C-e.

You are nitpicking, Stefan: does the difference really matter, except
if you want to annoy at all costs?  M-: and C-x C-e are equally unused
by many Emacs users.  I'd dare to say that only those of them who
wrote some Lisp know about these commands (or evaluation in general).

> But the thing is (or should be if it's not for you) highlighted
> and clickable, provided you read it in Gnus.

So we have 2 conditions: read it in Gnus and on a graphics display.
What about when these conditions are not met?

> And it's a lot
> more user-readable than C-h i g (you don't have to interpret it
> as a command, but just as a special syntax).

I have a difficulty parsing this, but you don't have to explain, since
it seems like a moot point anyway.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Eli Zaretskii]

> Date: Thu, 5 Jun 2003 19:56:40 -0400 (EDT)
> From: "Robert J. Chassell" <bob@rattlesnake.com>
> 
> I fear the Web browser mindset, which is to accept an inefficient
> and obsolete tool as if it were modern.

So let's make Info documents look and feel modern, like HTML does,
without losing any of the wonderful features HTML lacks.

With that attitude in mind, I don't see how hiding node names could be
a step in the wrong direction.  Granted, it should be possible to
reveal the node names, but I don't think it means we should show them
unconditionally as part of the displayed text.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Andreas Schwab]

"Eli Zaretskii" <eliz@elta.co.il> writes:

|> > But the thing is (or should be if it's not for you) highlighted
|> > and clickable, provided you read it in Gnus.
|> 
|> So we have 2 conditions: read it in Gnus and on a graphics display.

You don't need a graphics display for that, just hit RET instead if you
don't have a mouse.

Andreas.

-- 
Andreas Schwab, SuSE Labs, schwab@suse.de
SuSE Linux AG, Deutschherrnstr. 15-19, D-90429 Nürnberg
Key fingerprint = 58CA 54C7 6D53 942B 1756  01D3 44D5 214B 8276 4ED5
"And now for something completely different."

Re: Divergence in menu appearance between Emacs Info and standalone Info

[David Kastrup]

"Eli Zaretskii" <eliz@elta.co.il> writes:

> > Date: Thu, 5 Jun 2003 19:56:40 -0400 (EDT)
> > From: "Robert J. Chassell" <bob@rattlesnake.com>
> > 
> > I fear the Web browser mindset, which is to accept an inefficient
> > and obsolete tool as if it were modern.
> 
> So let's make Info documents look and feel modern, like HTML does,
> without losing any of the wonderful features HTML lacks.
> 
> With that attitude in mind, I don't see how hiding node names could
> be a step in the wrong direction.  Granted, it should be possible to
> reveal the node names, but I don't think it means we should show
> them unconditionally as part of the displayed text.

Quite so.  The purpose of an info reader is _not_ just to provide a
syntax highlighted info source file, but to render the structure
expressed in it.

I'd make a much more radical proposal: image support.  At the current
point of time, images can only be placed within the printed manual,
and only in jpeg format.  Obviously, for things like screen shots and
so on, png would also be desirable, but the main point is that in an
Emacs buffer, only ASCII art renditions are allowed in info files.
While the ASCII rendition will of course be needed as a fallback in
the standalone terminal reader and on text consoles, there is no
reason to press the same restriction in Emacs buffers.  In particular
screen shots (perhaps optionally in thumbnail form) could help in a
lot in some explanatory texts.

More ambitious, for example, would be mechanisms for automatically
rendering equations and similar material as bitmaps, like
preview-latex does in LaTeX source buffers.  However, the latter might
possibly better be done "live", since one does not know in advance
what size and colors the screen of a user might have.  Alternatively,
one could generate a scalable format (like PostScript with Type1
fonts, or SVG).

Sorry for spinning out of control, but stuff like that could decrease
the advantages of a printout further and thus save trees.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Robert J. Chassell]

   You're not making much sense here; how does the verbiage surrounding
   traditional info xrefs help a novice writer understand Texinfo?

As far as I can see, many people are absorbing, often without
realizing it, the broken design model of HTML, and are not gaining a
sense of the importance of nodes.

When Buffer-menu-use-header-line is set to t, in the following, some
novices do not realize that they do not have to connect to the
Internet to see "Overview" and "Change Log", but that they are in
different manuals:

    Patches are most welcome; if possible, please make them with `diff -c'
    (see Overview.) and include `ChangeLog' entries (see Change Log.).

They think that `Overview' and `ChangeLog' are the node names.

I agree that there is a problem with fully formed parenthetical cross
references:  too many parentheses.

The historical format moves the inner parentheses further away
from the outer parentheses, but does not look good:

    (see *note Overview: (diffutils)Top.)

One advantage of the historical format is that it is obviously
different from the format used by `g' (Info-goto-node) and by a menu.

Perhaps the cross reference output formats should look more like the
menu format. Here is what I mean where `_' suggests the printed output
of @cite:

@xref{Indicating, , Indicating Definitions, texinfo, Texinfo Manual}.

  In Info 
    when Buffer-menu-use-header-line is set to t:
            See (texinfo)Indicating.

    when Buffer-menu-use-header-line is set to nil:
            See Indicating Definitions: (texinfo)Indicating.

  In HTML:  See <a href="texinfo.html#Indicating">Indicating Definitions</a>.

  In XML with texinfo.dtd:

            See
            <xref>
              <xrefnodename>Indicating</xrefnodename>
              <xrefprinteddesc>Indicating Definitions</xrefprinteddesc>
              <xrefinfofile>texinfo</xrefinfofile>
            </xref>.

  Printed:  See "Indicating Definitions" in the _Texinfo Manual_.

(see @pxref{Indicating, , Indicating Definitions, texinfo, Texinfo Manual})

  In Info 
    when Buffer-menu-use-header-line is set to t:
            (see (texinfo)Indicating)

    when Buffer-menu-use-header-line is set to nil:
            (see Indicating Definitions: (texinfo)Indicating)

  In HTML:  (see <a href="texinfo.html#Indicating">Indicating Definitions</a>)

  In XML with texinfo.dtd:

            (see
            <xref>
              <xrefnodename>Indicating</xrefnodename>
              <xrefprinteddesc>Indicating Definitions</xrefprinteddesc>
              <xrefinfofile>texinfo</xrefinfofile>
            </xref>)

  Printed:  (see "Indicating Definitions" in the _Texinfo Manual_)


and in a menu:

    * Indicating Definitions: (texinfo)Indicating.   How to indicate
                                                     definitions, files, 
                                                     etc.

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

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Robert J. Chassell]

Eli Zaretskii <eliz@elta.co.il> writes

   So let's make Info documents look and feel modern, like HTML does,
   without losing any of the wonderful features HTML lacks.

You are right.

The problem is, what is meant by `look and feel modern'?  To me HTML
looks more than two decades old, even though I know it is not.  This
is because output expressions do not distinguish between references to
the same document on a different page and distant documents, and
because I cannot go to next, previous, and subsequent nodes readily,
or do regular expression searches through a multi-page document.

It looks to me that HTML was designed by someone who thought everyone
would always be on one planet on the same, fast local area network.

    I don't see how hiding node names could be a step in the wrong
    direction.

Because node names tell you where a file is located.  Sometimes a file
on on someone else's local area network, and your connection to it is
slow or non-existant.

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

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Stefan Monnier]

> > > > 2 - (info "<node name>") is a better way than using `g' since the `somebody'
> > > >     can just click on it (or hit C-x C-e).
> > > 
> > > That requires to use "M-:", which, I think, many Emacs users don't use
> > > (if they even know about it).
> > 
> > Funny, I never thought about using M-: to evaluate it.
> > I'd only ever seen mentioned C-x C-e.
> 
> You are nitpicking, Stefan:

No, I was just speaking to myself:  I use M-: all the time (contrary
to C-x C-e), but somehow I never thought of using it for (info "...").

> > And it's a lot
> > more user-readable than C-h i g (you don't have to interpret it
> > as a command, but just as a special syntax).
> 
> I have a difficulty parsing this, but you don't have to explain, since
> it seems like a moot point anyway.

Maybe it's moot, indeed.  The point is that I find (info "(foo)bar")
much more readable than C-h i g (foo)bar.  The first looks like
human language with a bit of extra annotations while the second looks
like line noise with a bit of human language embedded.  More
specifically "info" gives me a hint it's an info page, while C-h i g
just tells me there's a set of keystrokes that does something with
the rest.


	Stefan

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Eli Zaretskii]

> Date: Fri, 6 Jun 2003 14:00:01 +0000 (UTC)
> From: "Robert J. Chassell" <bob@rattlesnake.com>
> 
> The problem is, what is meant by `look and feel modern'?

Whatever HTML browsers do: display the links in a special typeface
that makes it clear they are links, pop up a menu when you press
mouse-2 or mouse-3 that allow you to display the referenced node in a
separate frame, keep a list of recently visited nodes in a menu, etc.

> To me HTML
> looks more than two decades old, even though I know it is not.  This
> is because output expressions do not distinguish between references to
> the same document on a different page and distant documents

I don't get this: to me, the URL displayed at the bottom of the HTML
display (an area roughly equivalent to Emacs's echo area), celarly
states whether the refenced document belongs to the same document or
not.

> because I cannot go to next, previous, and subsequent nodes readily,

HTML doesn't have inherent support for tree-like structure, it only
supports graphs.  But that doesn't mean that Info's support of the
tree structure interferes in any way with the other features.

>     I don't see how hiding node names could be a step in the wrong
>     direction.
> 
> Because node names tell you where a file is located.  Sometimes a file
> on on someone else's local area network, and your connection to it is
> slow or non-existant.

I did say that a node name should be accssible, but that doesn't mean
it needs to be visible at all times, or for every user.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Luc Teirlinck]

>From my previous message:

   Kai Grossjohann wrote:

      A tooltip or displaying the target node name (of the xref at point) in
      the echo area might be useful as a visual cue, though.

   I believe that is already implemented, if you use today's CVS.
   (Stefan inplemented this.)

I misunderstood Kai's remark.  This is only implemented in menus.

Sincerely,

Luc.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Luc Teirlinck]

   From my previous message:

      Kai Grossjohann wrote:

	 A tooltip or displaying the target node name (of the xref at
	 point) in the echo area might be useful as a visual cue,
	 though.

      I believe that is already implemented, if you use today's CVS.
      (Stefan inplemented this.)

   I misunderstood Kai's remark.  This is only implemented in menus.

The above was nonsense.  It is implemented everywhere.  Sorry for the
confusion.

Sincerely,

Luc.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Robert J. Chassell]

Eli Zaretskii <eliz@elta.co.il> wrote:

   ... to me, the URL displayed at the bottom of the HTML
   display (an area roughly equivalent to Emacs's echo area), celarly
   states whether the refenced document belongs to the same document or
   not.

Yes, it does clearly state, and I look there frequently.  That is the
trouble.  

To me, it is a poor user interface since it means that I must move my
eye away from the text, and then when I come back, rediscover where I
was.

By the way, I agree with David Kastrup that Info for the sighted
should have high-resolution images.  (No one using Emacspeak will
listen to either plain text or high-resolution images, so even if no
one works on high-resolution images, people who write in Texinfo
should consider using `@ifset sighted' and `@ifset blind' conditionals
in their work.)  I think this task should be added to the TODO list.

(Truth is, for better or worse, I think many of the current items on
the TODO list are more important than changing Info, although I
personally really like the idea of high-resolution images.  I would
like to see Emacs incorporate the other image-related enhancements
mentioned in the TODO list, as well as add a `visual dired' that uses
little thumbnails to the current Dired mode.)

Must go -- am traveling and will be somewhat out of touch the next few
days.

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

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Richard Stallman]

    Even if it is decided to retain note hiding in the Emacs version and
    that the standalone version is not going to be changed very soon, I
    still would need to know, before rewriting the manual, whether we are
    going to reimplement note hiding by using Stefan's suggestion or by
    deletion, whether Info-hide-note-references is going to keep getting
    supported and in which form and so on.

Precisely how we implement this feature internally in Emacs Info
makes no difference to the manual.  The only real question is whether
we have get rid of the refilling in Emacs Info because we cannot make
it work entirely correctly.  But that shouldn't affect what you say
about menus.

Meanwhile, the standalone Info won't change in the short term.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Richard Stallman]

    Notice that starting with GNU emacs version 21.5, the emacs info
    reader usually replaces the elaborate menu and node references
    desscribed in the following sections by simpler `hyperlinks'.  

That is a clear description for you and me, but it won't be clear to
the sort of beginner who might need to read that part of the Info
documentation.  Also, the section has several examples which are just
plain wrong for Emacs Info now.  Inaccurate examples will tend to
leave beginners wondering what they did wrong so as to get results
that don't match the manual.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Richard Stallman]

    Rather than hide node names, it would make more sense to modify Info
    to hide section titles than the reverse.

The feature hides node names in menus and xrefs, but it does not hide
the name of the current node.

I don't see any problem in doing this, not in principle at least.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Kevin Rodgers]

Robert J. Chassell wrote:

> It is impossible to navigate through a multi-page HTML
> document using regular expression searches!  

Precisely what is a multi-page HTML document?


-- 
<a href="mailto:&lt;kevin.rodgers&#64;ihs.com&gt;">Kevin Rodgers</a>

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Kevin Rodgers]

Robert J. Chassell wrote:

> It looks to me that HTML was designed by someone who thought everyone
> would always be on one planet on the same, fast local area network.

Yes, it's called the World Wide Web.

-- 
<a href="mailto:&lt;kevin.rodgers&#64;ihs.com&gt;">Kevin Rodgers</a>

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Kai Großjohann]

Kevin Rodgers <ihs_4664@yahoo.com> writes:

> Robert J. Chassell wrote:
>
>> It is impossible to navigate through a multi-page HTML
>> document using regular expression searches!  
>
> Precisely what is a multi-page HTML document?

HTML does not really support this concept, but some people try to
emulate it.  HTML only supports so-called "pages", and does not
further distinguish between related and non-related "pages".  But
nevertheless, some people have ideas to express that need to be
expressed on more than one page.  Then they will create navigation
bars giving a "next" and a "previous" button, plus "up" and perhaps
"table of contents".

It would be most convenient if several such pages could be bundled to
become a "document" such that it is possible to search, say, the
whole document at once.  Now, if a book is put online on 534 pages,
you have to use Ctrl-F (find) 534 times and click the next button 533
times to search for a string in the whole book.
-- 
This line is not blank.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Richard Stallman]

    Because node names tell you where a file is located.  Sometimes a file
    on on someone else's local area network, and your connection to it is
    slow or non-existant.

That is not normal for Info files that are distributed.  Normally
every crossreference in Info goes to a file on your own machine.

So what is significant here is not a distinction between same-manual
and other-manual cross references.  Rather, it is simply that
following an Info reference never requires downloading a file.

I am not sure of the best way to teach people about that, but
I don't see how showing node names would do it.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Richard Stallman]

    I'd make a much more radical proposal: image support.

We certainly want this.  Someone needs to design the format
in Info, and then implement the support in Emacs and in Makeinfo.
I think the images should be stored in separate files,
so that they won't make the Info files bigger or require changes
in the other aspects of the Info implementations.

I suspect that will also be the easiest thing to implement in
Makeinfo.  Karl, do you agree?

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Stefan Monnier]

>     I'd make a much more radical proposal: image support.
> 
> We certainly want this.  Someone needs to design the format
> in Info, and then implement the support in Emacs and in Makeinfo.
> I think the images should be stored in separate files,
> so that they won't make the Info files bigger or require changes
> in the other aspects of the Info implementations.

Huh?  Have I been dreaming when I saw image support added to info.el
a few weeks ago ?


	Stefan

Re: Divergence in menu appearance between Emacs Info and standalone Info

[David Kastrup]

"Stefan Monnier" <monnier+gnu/emacs@rum.cs.yale.edu> writes:

> >     I'd make a much more radical proposal: image support.
> > 
> > We certainly want this.  Someone needs to design the format in
> > Info, and then implement the support in Emacs and in Makeinfo.  I
> > think the images should be stored in separate files, so that they
> > won't make the Info files bigger or require changes in the other
> > aspects of the Info implementations.
> 
> Huh?  Have I been dreaming when I saw image support added to info.el
> a few weeks ago ?

Well, not everybody watches all the files all of the time.  And I
don't find something in the documention yet.  But nice to hear that
something appears to be underfoot.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Karl Berry]

        I'd make a much more radical proposal: image support.

Yes, this was added to Texinfo (makeinfo, info.el) a little while ago,
implemented by janneke@gnu.org, and will be in the next release of
Texinfo and Emacs.  As for documentation, I wrote about it in
texinfo.txi.  It didn't seem like any documentation for info readers was
needed -- it just happens.

I guess I missed the context here.  What does this have to do with
hiding node names, anything?

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Eli Zaretskii]

> Date: Sun, 8 Jun 2003 09:48:56 -0400
> From: karl@freefriends.org (Karl Berry)
> 
> I guess I missed the context here.  What does this have to do with
> hiding node names, anything?

The thread swerved into discussion of measures to make Info look more
like a modern hypertext browser.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Richard Stallman]

    Huh?  Have I been dreaming when I saw image support added to info.el
    a few weeks ago ?

Indeed, I see there is code in info.el for this.
It isn't mentioned in etc/NEWS, though, or in man/info.texi.
Is the format documented anywhere?  If not, could someone
send an explanation of it, to document it?

Is there makeinfo support for this yet?

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Richard Stallman]

    Yes, this was added to Texinfo (makeinfo, info.el) a little while ago,
    implemented by janneke@gnu.org, and will be in the next release of
    Texinfo and Emacs.  As for documentation, I wrote about it in
    texinfo.txi.  It didn't seem like any documentation for info readers was
    needed -- it just happens.

We need to document the format in info.texi.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Karl Berry]

        karl>
        Yes, this was added to Texinfo (makeinfo, info.el) a little
        while ago, implemented by janneke@gnu.org, and will be in the
        next release of Texinfo and Emacs.  As for documentation, I
        wrote about it in texinfo.txi.  It didn't seem like any
        documentation for info readers was needed -- it just happens.

    rms>
    We need to document the format in info.texi.

I assume you mean the specific implementation in the .info files
(^H^[image src=...^H^]).  Ok, I can work on that, although in general
info.texi's description of Info format looks quite idiosyncratic to me,
being done in the context of writing an Info file by hand (which no one
does any more), and/or explaining certain Info user interface commands.

So, do you mind if I rewrite it so that there's a clear appendix simply
describing the file format?  If you don't want me to go that far, then I'll
just stick in the image information somewhere.

I see that the anchor implementation is not mentioned in info.texi
either.  I'll document that as well.  (I didn't think of it when I added
the feature since I never thought of info.texi as documenting the file
format before now, just the user interface.)

k

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Kim F. Storm]

Andreas Schwab <schwab@suse.de> writes:
 
> There are still some problems when references are wrapped between "see"
> and the reference name.  The invisible property makes the indentation
> invisible.  See (elisp)Functions for Key Lookup or (libc)Error Codes for
> examples.

I have fixed those now.

I made the refilling less aggressive, and also made the invisible
property is non-sticky to ensure that filling add _visible_ whitespace.

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

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Richard Stallman]

    I assume you mean the specific implementation in the .info files
    (^H^[image src=...^H^]).  Ok, I can work on that, although in general
    info.texi's description of Info format looks quite idiosyncratic to me,
    being done in the context of writing an Info file by hand (which no one
    does any more), and/or explaining certain Info user interface commands.

    So, do you mind if I rewrite it so that there's a clear appendix simply
    describing the file format?

That is ok.

    I see that the anchor implementation is not mentioned in info.texi
    either.  I'll document that as well.

Thanks.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Karl Eichwalder]

David.Kastrup@t-online.de (David Kastrup) writes:

> TeXinfo has provisions for tables and preformatted code.

Yes.

> Normal text should be reflown to fit the window width, and it is done
> in the standalone info generation, too.

No, please don't spread it over the window width!  Even if you cannot
stay away from reflowing, restrict it to 79 characters.

-- 
                                                         |      ,__o
http://www.gnu.franken.de/ke/                            |    _-\_<,
ke@suse.de (work) / keichwa@gmx.net (home)               |   (*)/'(*)

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Luc Teirlinck]

Karl Eichwalder wrote:   
   
   > Normal text should be reflown to fit the window width, and it is done
   > in the standalone info generation, too.

   No, please don't spread it over the window width!  Even if you cannot
   stay away from reflowing, restrict it to 79 characters.

Does the standalone version really work as described?  I am using:
info (GNU texinfo) 4.5
and do not notice any such "reflowing" in the standalone info.

Or is meant: to fit a "normal" window width rather than "the" window width?

Sincerely,

Luc.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Karl Eichwalder]

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

> Or is meant: to fit a "normal" window width rather than "the" window width?

Refilling to fit normal window width (fill-column) is okay; but
spreading all over a 132 or more width window is not.  It might be
worth introducing a new variable like `info-fill-column'.

-- 
                                                         |      ,__o
http://www.gnu.franken.de/ke/                            |    _-\_<,
ke@suse.de (work) / keichwa@gmx.net (home)               |   (*)/'(*)

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Luc Teirlinck]

Karl Eichwalder wrote:

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

   > Or is meant: to fit a "normal" window width rather than "the"
   > window width?

   Refilling to fit normal window width (fill-column) is okay; but
   spreading all over a 132 or more width window is not.  It might be
   worth introducing a new variable like `info-fill-column'.

I was actually asking the question to whomever the original quote:

      > Normal text should be reflown to fit the window width, and it
      > is done in the standalone info generation, too.

came from.  You seemed to attribute it to David Kastrup, but I seemed
unable to find this quote in David's old messages.

I agree with you that spreading text all over the window width could
look ugly.  But note that `fill-column' can be given mode-local values
using mode hooks, so there would not seem to be any particular need
for hyper-specialized variables like `info-fill-column'.

Sincerely,

Luc.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Luc Teirlinck]

>From my previous message:

   But note that `fill-column' can be given mode-local values
   using mode hooks, so there would not seem to be any particular need
   for hyper-specialized variables like `info-fill-column'.

Except maybe for Custom's sake.  But still, I believe that once one
starts with this, the flood gates would be open for countless similar
special-file-fill-column variables, and the user who really wants this
can use mode hooks, even though this might be less convenient than
using Custom.

Sincerely,

Luc.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Stefan Monnier]

> >From my previous message:
> 
>    But note that `fill-column' can be given mode-local values
>    using mode hooks, so there would not seem to be any particular need
>    for hyper-specialized variables like `info-fill-column'.
> 
> Except maybe for Custom's sake.  But still, I believe that once one
> starts with this, the flood gates would be open for countless similar
> special-file-fill-column variables, and the user who really wants this
> can use mode hooks, even though this might be less convenient than
> using Custom.

It would be much more worthwhile to teach custom how to do such things
so that users will be able to set all variables per-mode via custom.


	Stefan

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Karl Eichwalder]

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

> This is because output expressions do not distinguish between
> references to the same document on a different page and distant
> documents,

In lynx, press '=' and you will see what's up with the link (or switch
to "advanced user" and the status line will show useful info).

> and because I cannot go to next, previous, and subsequent nodes
> readily,

HTML has LINK in HEAD; LINK is meant to serve those purposes and lynx
supports it since ages.

> or do regular expression searches through a multi-page document.

Use grep to go thru local file (etags and tags-search might work as
well); if you are interested in remote files, either make use of a
search engine or install an http index tool like htdig -- question: how
to you browse remotely installed info files? ;)

Of course, I don't want to deny that Texinfo is very strong for
certain tasks.

> It looks to me that HTML was designed by someone who thought everyone
> would always be on one planet on the same, fast local area network.

It's simply impossible to store _all_ docs locally.

>     I don't see how hiding node names could be a step in the wrong
>     direction.
>
> Because node names tell you where a file is located.

This isn't always true.  To be sure, I must enter the node and then
call C-x C-f (or a similar command)--glancing at the node name does not
tell me whether it's under /usr/share/info or /gnu/share/info; I use
thise setting (abbreviated):

(add-to-list 'Info-additional-directory-list "/gnu/share/info")

-- 
                                                         |      ,__o
http://www.gnu.franken.de/ke/                            |    _-\_<,
ke@suse.de (work) / keichwa@gmx.net (home)               |   (*)/'(*)

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Stefan Monnier]

> HTML has LINK in HEAD; LINK is meant to serve those purposes and lynx
> supports it since ages.

I don't know exactly what "supports it" means, but I know that in all
browsers I've used (thatdoes not include Lynx), they either didn't
pay attention to those <LINK> tags, or if they did, they didn't
do much useful with them.  At best, they get put in some submenu
where nobody will ever see them.
I've asked for better support for such things in Galeon, but was
basically ignored.  It would be great to bind keys to "next", "up",
"prev", "index", or have toolbar entries to follow those special
links: you could then browse documents almost as well as with Info,
but nobody in the webbrowsers world seems to understand.


	Stefan

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Robert J. Chassell]

   In lynx, press '=' and you will see what's up with the link ....

That tells me the information, but as far as I know, no one has
written a regular expression search tool that figures out whether the
link is to another section within the same document, and if so, runs a
search in it.

In other words, I want to navigate via a regexp search through all and
only those files that are part of the `same document'.

Have I missed something?  Does the Lynx `/' command do what I want?
(I just tried it, and it does not seem to.)

   ... if you are interested in remote files, either make use of a
   search engine or install an http index tool like htdig ....

That is the solution I use, and it is broken!  That is the point.  By
default, you must either use a search engine or create one, like
htdig.

Perhaps it is possible to write a regexp search function that reads
the LINK info and figures out from it whether the cross reference
goes to a continuation of the same document or not.  

That would be great, if it is possible.  (The task is beyond me.)
Certainly, you can download all the pages for a site; that is done,
for example, by `wget' with mirroring.  That is fine for a small site
devoted to one topic.  My problem is that I cannot figure out how to
avoid pages on a site that are not part of the document in question
and which I do not want to download.

Perhaps an initial scheme would be just to search within pages in
subdirectories of the current page:

Thus a search through `http://www.gnu.org/gnu/' would go through its
sup-pages, which might mean downloading all 13 of them, over 210
kilobytes.  But it would have to do this without doing what `wget -m'
just tried to do, which is go to a page outside the
`http://www.gnu.org/gnu/' directory, and also, to avoid downloading
non-searchable files.

If someone did this and it worked well, and the feature got
incorporated into Galeon or other graphical Web browser as well as
Lynx and Emacs W3 mode, then it might completely change the Web!
People could navigate and read much more easily than they do now.

Moreover, with working next, previous, and up bindings, HTML could
become a competitor to Texinfo as a deep representation medium.

   It's simply impossible to store _all_ docs locally.

No, it is not possible.  But when you view a page using HTML, you
download that page.  The idea is to download the other pages in a book
as needed (not all the pages on a site, because that could be too
many), and to enable searches through them.  

Ideally, of course, you only download the page that your regular
expression search found; but I cannot see how to ensure that Web sites
provide the right tools -- after all, even now, not every one of them
provides for an htdig binding or text entry box on every page.

(Does htdig provide a mechanism for remote keybinding in some Web
browsers?  As far as I know, it doesn't for Emacs W3M mode, for Lynx,
or for Galeon.  But maybe I have missed something.  Is there a Web
browser or Emacs mode I can use such that when I visit the
`http://www.gnu.org/gnu/' or `http://savannah.gnu.org/forum/' Web
pages, I can type `C-s' or an equivalent and get an htdig search?  It
should be pretty obvious that you are better off than reading
typewritten sheets when you can type a string into a form, as the
built in Galeon find command requires, or as htdig requires, but that
`M-x' (Info-search) is a generation ahead.)


   >     I don't see how hiding node names could be a step in the wrong
   >     direction.
   >
   > Because node names tell you where a file is located.

   This isn't always true.  ... glancing at the node name does not
   tell me whether it's under /usr/share/info or /gnu/share/info ...

You are right.  That is the case for a default configuration.

However, I have my mode line set to tell me the full path name of any
info document -- to do automatically what you do by calling C-x C-f
(or a similar command).  (I cannot understand why so many people like
the default configuration; to me it is as if they decided to be like
horses who pull carriages and wear blinders over their eyes.)

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

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Kai Großjohann]

Karl Eichwalder <keichwa@gmx.net> writes:

> Use grep to go thru local file (etags and tags-search might work as
> well); if you are interested in remote files, either make use of a
> search engine or install an http index tool like htdig -- question: how
> to you browse remotely installed info files? ;)

This is not a real solution.  When you find something, how do you
jump to the match?  It's just too difficult to use.
-- 
This line is not blank.

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Miles Bader]

On Sun, Jun 15, 2003 at 12:08:15PM -0400, Stefan Monnier wrote:
> I don't know exactly what "supports it" means, but I know that in all
> browsers I've used (thatdoes not include Lynx), they either didn't
> pay attention to those <LINK> tags, or if they did, they didn't
> do much useful with them.  At best, they get put in some submenu
> where nobody will ever see them.

I believe mozilla (don't know about galeon; same renderer, but pretty
different framework) has an option to display a toolbar with these -- but
it's turned off by default.  I had it turned on for a while, and it ended up
being rather annoying; not only do most sites not define these links, but
some define _bogus_ ones!

-miles
-- 
"1971 pickup truck; will trade for guns"

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Karl Eichwalder]

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

> In other words, I want to navigate via a regexp search through all and
> only those files that are part of the `same document'.

HTML/HTTP does not offer such a funtionallity; one must make use iof a
search engine.

> Have I missed something?  Does the Lynx `/' command do what I want?
> (I just tried it, and it does not seem to.)

I guess noboby asked for a regex search until now.

> That is the solution I use, and it is broken!  That is the point.  By
> default, you must either use a search engine or create one, like
> htdig.

Yes, but for info files remote access does not exist at all!  One must
not compare info-search with features an arbitrary browser offers;
those browser are not optimized for local file access ;)

> That would be great, if it is possible.  (The task is beyond me.)

me too.

> Certainly, you can download all the pages for a site; that is done,
> for example, by `wget' with mirroring.  That is fine for a small site
> devoted to one topic.  My problem is that I cannot figure out how to
> avoid pages on a site that are not part of the document in question
> and which I do not want to download.

For sane site '--no-parent' should do the trick (maybe in combination
with --reject or --level; yes, there are many a lot insance sites out
there...

HTML/HTTP technologie isn't that bad, but since most content providers
are more interested in serving advertisements than documents, useful
features are often ignored.  And then there is lack in knowledge
(cf. the problems with the LINK tag).

And actually, now Emacs is ready to catch up -- I guess we can use
proportional fonts (and refilling) by now and things should work well
for English speakers.  Users not that much familiar with the English
language are still a little bit in trouble.

> (Does htdig provide a mechanism for remote keybinding in some Web
> browsers?  As far as I know, it doesn't for Emacs W3M mode, for Lynx,
> or for Galeon.

lynx is able to call external commands like wget.

> However, I have my mode line set to tell me the full path name of any
> info document -- to do automatically what you do by calling C-x C-f
> (or a similar command).  (I cannot understand why so many people like
> the default configuration; to me it is as if they decided to be like
> horses who pull carriages and wear blinders over their eyes.)

I guess the regular user isn't interested in a file name of an info
file.

-- 
                                                         |      ,__o
http://www.gnu.franken.de/ke/                            |    _-\_<,
ke@suse.de (work) / keichwa@gmx.net (home)               |   (*)/'(*)

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Reiner Steib]

On Sun, Jun 15 2003, Stefan Monnier wrote:

> I've asked for better support for such things in Galeon, but was
> basically ignored.  
> It would be great to bind keys to "next", "up", "prev", "index", 

Yes, key bindings would be nice (AFAICS, this isn't possible in
Galeon yet).

> or have toolbar entries to follow those special links: you could
> then browse documents almost as well as with Info, but nobody in the
> webbrowsers world seems to understand.

In Galeon (Mozilla/5.0 Galeon/1.2.8) you can add the "Links" control
element to the toolbar (Preferences/User Interface/Toolbars).

An example page is this one:
<URL:http://www.w3.org/TR/html4/types.html#type-links>.

Bye, Reiner.
-- 
       ,,,
      (o o)
---ooO-(_)-Ooo--- PGP key available via WWW   http://rsteib.home.pages.de/

Re: Divergence in menu appearance between Emacs Info and standalone Info

[Robert J. Chassell]

reiner.steib@gmx.de wrote:

   In Galeon (Mozilla/5.0 Galeon/1.2.8) you can add the "Links" control
   element to the toolbar (Preferences/User Interface/Toolbars).

   An example page is this one:
   <URL:http://www.w3.org/TR/html4/types.html#type-links>.

Yes!  Thank you.  I had not realized that the W3C consortium had
included this in the current official recommendation.

Links like this should enable someone to write a program that does
regular expression searches within a multipage document, just like
`M-s' (Info-search) does in Info.

The main problem is that use of such links is voluntary, which means
many people won't bother.  If they write in Texinfo, then such links
can be generated automatically, with no extra effort on the part of
the author; but many people do not write in Texinfo.
(Hmmm... presumably such links can be generated automatically for
documents written in an appropriate XML, too, which helps.)
Regardless, links are a step forward.

Karl, could you modify `makeinfo' to generate such links automatically
when it creates a split HTML document (i.e., when you do not use the
`--no-split' option to `makeinfo'.)?

As far as I see the requirement is to include next, previous, and
contents pointers in the <head> ... </head> segment, right after the
<title> ... </title> segment, like this for the
`Forbidden-to-Study.html' file:

    <head>
    <title>Rah! Rah! Forbidden to Study</title>
    <link rel="previous" href="Selfish-by-Law.html#Selfish%20by%20Law">
    <link rel="next"     href="discovery-cost.html#discovery%20cost">
    <link rel="contents" href="index.html">
    </head>

At the moment, `makeinfo' does much of the work; it already finds the
next and previous pages when it creates a node line with next and
previous pointers.  `makeinfo' does not point you to the table of
contents page, but I think that is always in `index.html#Top'.

Here is the code that `makeinfo --html' currently generates for the
`Forbidden-to-Study.html' file:

    <div class="node">
    <p>
    Node:&nbsp;<a name="Forbidden%20to%20Study">Forbidden to Study</a>,
    Next:&nbsp;<a rel="next" accesskey="n"
        href="discovery-cost.html#discovery%20cost">discovery cost</a>,
    Previous:&nbsp;<a rel="previous" accesskey="p"
        href="Selfish-by-Law.html#Selfish%20by%20Law">Selfish by Law</a>,
    Up:&nbsp;<a rel="up" accesskey="u"
        href="costs-of-restriction.html#costs%20of%20restriction">costs of
        restriction</a>
    <hr>
    <br>
    </div>

The idea would be to add a `links' to the <head> ... </head> segment
(but also keep the current pointers as shown).  This way, someone who
wrote a regexp searcher would know that it works for all such fully
conforming HTML documents, not only for those formatted by `makeinfo'
from a Texinfo source (which could be written now, but would have a
more limited number of users).

Earlier, keichwa@gmx.net wrote

    ... but for info files remote access does not exist at all!  One
    must not compare info-search with features an arbitrary browser
    offers; those browser are not optimized for local file access ;)

This is partially true, but orthogonal to the issue.  (It is partially
false, because you can access Info files remotely if you have a fast
enough Internet connection.  I have done so using VNC.  But Info is
not designed for Internet connectivity other than NFS or VNC, so few
think of it as working remotely.)

For remote files, the key navigation issue is that you must download
them to search them.  That is to say, you must do this unless the file
provider has set up a regexp search engine for you on his site and you
have an interface to it.  Since I doubt the latter will happen, I
think that Web browsing will require downloading pages to search, and
that is unavoidable albeit awkward and slow for people like me, who
have slow net connections.

But the good news is that a next/prev/contents link structure enables
someone to write a search facility that enables you to navigate
through a World Wide Web document without the fear that the search
will spread through the Internet and not halt in a humanly reasonable
time.

And it means that if you have a multi-page Web document on your site
-- such as most GNU distributions provide, like Debian I know for
sure, and Red Hat, I am pretty sure -- then you can read it through
page by page conveniently, like existing `makeinfo --html' produced
documents.

And if someone writes a regexp searcher, then you could navigate it as
conveniently as Info.

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