Re: terminal escapes in Info files?

Re: terminal escapes in Info files?

[Karl Berry]

    > if we want to add font markup to info fmt, let's not use something as
    > ugly as terminal escape squences.  please design something clean!

Since Info is inherently limited to what can be displayed on a terminal,
it seems like ANSI escape sequences are as reasonable specification of
the capabilities as anything else?  Easy to implement, too.  Admittedly
the ESC [ blah blah sequences are ugly, though.

    How about using what Enriched-Text mode uses in Emacs?  See
    etc/enriched.doc in the Emacs distro.

That is indeed a lot cleaner (also quite a bit more verbose :).  Thanks
for mentioning it, I wasn't aware of it.

It seems using this would imply a new non-backward-compatible output
format, though, since every literal < needs to be escaped in enriched
format, and existing info readers don't know how to do that.

Using the ugly terminal escape sequences, on the other hand, is
backward-compatible because I'm sure that no real document has literal
terminal escape sequences (Texinfo hasn't had @ctrl for years ...).

Hmm.  As always, it seems there is no easy answer.

Thanks,
k

Re: terminal escapes in Info files?

[Alper Ersoy]

Karl Berry:
>     How about using what Enriched-Text mode uses in Emacs?  See
>     etc/enriched.doc in the Emacs distro.

> That is indeed a lot cleaner (also quite a bit more verbose :).  Thanks
> for mentioning it, I wasn't aware of it.

I think we can summarize the possible directions in two groups:

  1) Older versions friendly,
  2) Future versions friendly.

(1) is using ANSI escapes directly in Info files.  The benefit is,
these files will still be displayed correctly by older versions of
info when -R option is given (though I'm not sure about emacs.) Also
no further processing is necessary in info.  Minimal set of changes,
most will be in makeinfo.

The downside is, GUI browsers will be limited severely by an
inexpansible markup on what can be done when rendering.  For example
two elements having the same ANSI escapes (@var{} and @env{} are good
candidates) may become indistinguishable even though there's enough
room in the display environment to associate different styles with
these elements.  Also ANSI is a frozen specification, so we may hit
its limits pretty soon.

(2) is using a specialized markup.  The benefit is of course Info
files will take advantage of the medium they are presented in to its
maximum, provided that the browser is aware of this markup.

The downside is, Info becomes an intermediate format rather than
a final one, always asking for an additional step in the browsers.
Display will be totally screwed in older versions[1].

So, the decision really is on the part of Info history we can discard
rather than the markup format.  The bad thing about standards is it's
very hard to break them ;)

Thanks,

[1] We must give a visual clue about this to avoid possible
frustration.  Perhaps something like the following at the top
of each node?

  ^H^[ignore]
    Your browser relies on an obsolete Info specification.
    See *note bla bla::.
  ^H^[/ignore] (or some other markup)

And a hidden DON'T PANIC! "bla bla" node that gives information about
where to find new versions of browsers.  Compliant browsers will
conceal this text and also hide "bla bla" node from tab completions,
next/prev commands, etc.  completely.  But I digress.

-- 
Alper Ersoy

Re: terminal escapes in Info files?

[Oliver Scholz]

Alper Ersoy <dirt@gtk.org> writes:

[...]
> (2) is using a specialized markup.  The benefit is of course Info
> files will take advantage of the medium they are presented in to its
> maximum, provided that the browser is aware of this markup.

Most notably the markup could be syntactical rather than specifying
the colours to use. I *hate* it, if a document tells me the best
colour for me to read a certain syntactic element. Let the document
specify the syntactical element and let me customize the colour.

However, I would be nice at least, if the info format and the Emacs
info reader would distinguish `example' and `code' and the like from
the rest of the text. So that I can use a fixed width font for those
parts and a proportional font for the rest.

Another old wish of mine is that the info format could specify the
type of code, for example (I am using an XML-like notation here,
because I am not familiar with the info file format):

<code type="lisp">
   (defun bar (a &optional b &rest c)
     (list a b c))
</code>

Then the info reader in Emacs could even fontify the code.
[There's probably a better choice than XML-like markup, but you get
the idea. I guess it should be done in a way that a tty reader may
simply strip the markup.]

    Oliver
-- 
Oliver Scholz               7 Brumaire an 212 de la Révolution
Taunusstr. 25               Liberté, Egalité, Fraternité!
60329 Frankfurt a. M.       http://www.jungdemokratenhessen.de
Tel. (069) 97 40 99 42      http://www.jdjl.org

Re: terminal escapes in Info files?

[Alper Ersoy]

Hi!

Oliver Scholz:
> Most notably the markup could be syntactical rather than specifying
> the colours to use. I *hate* it, if a document tells me the best
> colour for me to read a certain syntactic element. Let the document
> specify the syntactical element and let me customize the colour.

Ok.  If we lean towards a syntactical markup, it should _also_ specify
the best colour, typeface, etc. too.  We must do this, otherwise
whenever there's a new command in Texinfo, readers will be unaware of
how to handle it.  Something like (notation aside):

  ^H^[var bi^H^]Variable^H^[/var^H^]

So it's bold-italic.  But you (info reader) know it's a var, so you
can use whatever style you want.  Sometime in the future, when we have
this @funky command:

  ^H^[funky sb,red^H^]Art Vandelay^H^[/funky^H^]

You don't know what a funky text is, but you can use the style
provided there.

However, I suggested ANSI escapes in the first place because of the
star characters around strong text.  One can use @strong only, and
still get a flowing text in display environments supporting bold
typeface.  Not with Info though.

Introducing syntactical markup elements is IMHO burning your blanket
because of one flea.

The only way to justify changes this level is to also identify the
other problems in Info, and to address them all at once, then declare
it as Info2.  After all, we are breaking compatibility here, so it
_must_ have to offer more.

Currently though, Info serves as the 'final destionation of
documents.'  So what's wrong with using a widely adopted and frozen
standard? (ECMA-48)

> Another old wish of mine is that the info format could specify the
> type of code, for example (I am using an XML-like notation here,
> because I am not familiar with the info file format):

This has to be addressed in Texinfo first.  Admittedly, I could never
understand @lisp.  Why not

  @example lisp
  ...
  @end example

  @example C++
  ...
  @end example

Like @itemize, @example can accept an optional parameter.  @lisp can
be an alias to ``@example lisp'' internally.  What do you think?

Info doesn't have to format each of these differently, so makeinfo can
omit the rest of @example lines.  However, HTML and XML backends can
clearly make use of this information.

-- 
Alper Ersoy

HTML as info format (was: terminal escapes in Info files?)

[Oliver Scholz]

[-- Attachment #1: Type: text/plain, Size: 3478 bytes --]

Alper Ersoy <dirt@gtk.org> writes:
[...]
> Oliver Scholz:
>> Most notably the markup could be syntactical rather than specifying
>> the colours to use. I *hate* it, if a document tells me the best
>> colour for me to read a certain syntactic element. Let the document
>> specify the syntactical element and let me customize the colour.
>
> Ok.  If we lean towards a syntactical markup, it should _also_ specify
> the best colour, typeface, etc. too.  We must do this, otherwise
> whenever there's a new command in Texinfo, readers will be unaware of
> how to handle it.  Something like (notation aside):
>
>   ^H^[var bi^H^]Variable^H^[/var^H^]
>
> So it's bold-italic.  But you (info reader) know it's a var, so you
> can use whatever style you want.  Sometime in the future, when we have
> this @funky command:
>
>   ^H^[funky sb,red^H^]Art Vandelay^H^[/funky^H^]
>
> You don't know what a funky text is, but you can use the style
> provided there.

You have a point here. If the format would be HTML, it would also be
possible to address that, by using <h1>, <b>, <i> etc. with the class
attribute extensivly. The class attribute would specify the
syntactical information, the raw element name would specify the
fallback.

> However, I suggested ANSI escapes in the first place because of the
> star characters around strong text.  One can use @strong only, and
> still get a flowing text in display environments supporting bold
> typeface.  Not with Info though.
>
> Introducing syntactical markup elements is IMHO burning your blanket
> because of one flea.
>
> The only way to justify changes this level is to also identify the
> other problems in Info, and to address them all at once, then declare
> it as Info2.  After all, we are breaking compatibility here, so it
> _must_ have to offer more.

I don't know the "other problems".  I have to admit that I am just an
end user as far as info is concerned.  I even hardly ever use
texinfo.  I'd like to see nicer syntactical fontification,
proportional fonts for paragraph text etc. in the Emacs info reader.
To get this properly would require changes to the info format.

If this is towards HTML with a heavy use of the `class' attribute,
then--I believe--it could provide everything necessary for future
improvement.

Well, since everybody seemed to agree that modifying the standalone
info reader would be the hard part, I decided to give it a try and
hacked a bit on it. I append both a patch to nodes.c in texinfo-4.6
and the file sample3x.info (in html) which I used for testing.

Unfortunately I am probably the person least apt for this task, being
unfamiliar with C, unfamiliar with the info source code, unfamiliar
with the info format, unfamiliar with texinfo and, finally, unfamiliar
with HTML. In fact this is the first larger chunk of C code that I
ever wrote. (My thanks go to the people on the IRC channel #emacs for
their help, BTW.)

I did it in the most primitive way I could think of: it acts like a
filter to convert HTML-info files to the current info format on the
fly when reading the file contents. Obviously it is far from being
complete (I didn't try even). It is rather proof-of-concept code. But
if this approach is not absolutely insane, and if my C code is
somewhere near of what a real C programmer could accept, then it could
serve as a starting point, because I did it in a way that should be
easily extensible.

It should be simple enough to add ANSI colour sequences for certain
tags.


[-- Attachment #2: nodes.diff.gz --]
[-- Type: application/octet-stream, Size: 6408 bytes --]

[-- Attachment #3: sample3x.info.gz --]
[-- Type: application/octet-stream, Size: 1370 bytes --]

[-- Attachment #4: Type: text/plain, Size: 254 bytes --]



    Oliver
-- 
Oliver Scholz               20 Brumaire an 212 de la Révolution
Taunusstr. 25               Liberté, Egalité, Fraternité!
60329 Frankfurt a. M.       http://www.jungdemokratenhessen.de
Tel. (069) 97 40 99 42      http://www.jdjl.org

[-- Attachment #5: Type: text/plain, Size: 141 bytes --]

_______________________________________________
Emacs-devel mailing list
Emacs-devel@gnu.org
http://mail.gnu.org/mailman/listinfo/emacs-devel

Re: HTML as info format

[Juri Linkov]

Oliver Scholz <epameinondas@gmx.de> writes:
> You have a point here. If the format would be HTML, it would also be
> possible to address that, by using <h1>, <b>, <i> etc. with the class
> attribute extensivly. The class attribute would specify the
> syntactical information, the raw element name would specify the
> fallback.

There are many other arguments for using HTML as Info format.

Current Info format can't make a link to another part of the same
Info node.  For example, look at the following node:

Default Coding Systems
----------------------
...
 - Variable: auto-coding-regexp-alist
...
 - Variable: file-coding-system-alist
...
 - Variable: process-coding-system-alist
...
     This function looks up the target in `file-coding-system-alist',
     `process-coding-system-alist', or `network-coding-system-alist',
     depending on OPERATION.  *Note Default Coding Systems::.

Currently it has the reference to the top of the same node, which is
pretty useless.  However, evidently the intention was to refer
separately to every of these variables described in the same node.
With HTML it's very easy to achieve by using the character # in href.

The same problem appears in the Glossary node of the Emacs manual,
where links to the same node are marked by the "(q.v.)".  It can be
justified to place such text on paper media, but for electronic
documents, where there are no obstacles to make a link to follow to
another part of the same node, such surrogate links look very dumb.

There are other problems with the current Info format.  For example,
currently there is no way to hide the address part of the link without
corrupting the paragraph formatting.  After hiding the address part of
the link lines become either too short or too long.  For example, lines:

   See *Note Customizing Indentation: (ccmode)Customizing Indentation, for
more information on customizing indentation for C and related modes,

in Info the first line becomes too short:

   See Customizing Indentation for
more information on customizing indentation for C and related modes,

or

     using the `C-x 8' prefix, see *Note C-x 8: Single-Byte Character
     Support.  On X Window systems, your locale should be set to an

in Info it becomes too long, because the newline character in the reference
is hidden:

     using the `C-x 8' prefix, see C-x 8.  On X Window systems, your locale should be set to an

-- 
http://www.jurta.org/emacs/

Re: HTML as info format

[Richard Stallman]

    There are many other arguments for using HTML as Info format.

We are certainly not going to abandon Info format in this way,
so I suggest people not spend a lot of time arguing about the idea.

Changes to Texinfo DTD [Was: Re: HTML as info format]

[Robert J. Chassell]

Juri Linkov <juri@jurta.org> wrote

    There are many other arguments for using HTML as Info format.

Before trying to persuade people to change the current Info format,
please tell us what changes should be made to the current Texinfo DTD.

This will tell us what needs to be added, if need be, to the current
Texinfo format.  At the same time, it does not embroil you or us in
the contentious question of whether the format of a well established
surface expression should be changed.  As far as I know, the issues
are less fraught when they involve makeinfo's XML output with the
Texinfo DTD than with the Info format.

The current Texinfo DTD is in:

    texinfo-4.6/makeinfo/texinfo.dtd

[Also, how do you view an XML file with a DTD in a manner that looks
like graphically displayed HTML, as in Mozilla; how do you do the same
in Emacs?]

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

Re: Changes to Texinfo DTD

[Oliver Scholz]

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

> Juri Linkov <juri@jurta.org> wrote
>
>     There are many other arguments for using HTML as Info format.
>
> Before trying to persuade people to change the current Info format,
> please tell us what changes should be made to the current Texinfo DTD.

I was not aware of makeinfo's XML output when I hacked my little
proof-of-concept patch. After Karl Berry mentioned it in private mail,
I had a quick look at it. I think now that it would be a good idea to
use that rather than HTML.

That is because texinfo's HTML output would need to be
changed. Currently it is not easy to parse for an info reader which
would have to identify menus, the beginnings of nodes etc.. And it
does not provide enough of the kind of syntactical information that
only make a change of the format desirable, IMO.

The texinfo XML OTOH would be easy to parse AFAICS and it provides all
syntactical information that I would like to see. And it is already
implemented in makeinfo.

If all other things were equal, HTML would have been nice, because
people were free to choose their suboptimal browser to view the info
files. That might be a small benefit, but it is a benefit. But things
are not equal: the texinfo format is already implemented and up to
the task.  For HTML on the other hand it would be necessary to design
an specify special conventions and to implement those conventions in
makeinfo.

So I have offered to hack the standalone info reader so that it would
support the XML format in the same way that I have chosen in my
patch. But I got not response so far.

[...]
> [Also, how do you view an XML file with a DTD in a manner that looks
> like graphically displayed HTML, as in Mozilla; how do you do the same
> in Emacs?]
[...]

One could write a CSS for texinfo XML, so that at least some browsers,
like Mozilla, could render it.

As for Emacs: I could write a parser and trivial renderer (applying
text-properties) for texinfo XML in on a sunday afternoon.

    Oliver
-- 
Oliver Scholz               28 Brumaire an 212 de la Révolution
Taunusstr. 25               Liberté, Egalité, Fraternité!
60329 Frankfurt a. M.       http://www.jungdemokratenhessen.de
Tel. (069) 97 40 99 42      http://www.jdjl.org

Re: Changes to Texinfo DTD

[Robert J. Chassell]

Oliver Scholz <epameinondas@gmx.de> wrote:

   So I have offered to hack the standalone info reader so that it
   would support the XML format in the same way that I have chosen in
   my patch. But I got not response so far.

Heh... that might be a good idea.  However, I don't think I know of
anyone who uses the standalone Info reader; they all use Emacs Info
instead....  So I cannot give you any useful advice on this.

   [...]
   > [Also, how do you view an XML file with a DTD in a manner that looks
   > like graphically displayed HTML, as in Mozilla; how do you do the same
   > in Emacs?]
   [...]

   One could write a CSS for texinfo XML, so that at least some browsers,
   like Mozilla, could render it.

That would be useful.  I use Galeon (which I presume would also use
the CSS).  The next step would be to persuade the Mozilla/Galeon
developers to make it easy to bind next, prev, up, last,
regexp-search, and spacebar to keystrokes, so you could avoid the
mouse.  As for me, the most vital capability is to be able to regexp
search through a complete document that is in multiple files (i.e.,
the equivalent of the Info-search command), and not attempt to go
outside the document.

   As for Emacs: I could write a parser and trivial renderer (applying
   text-properties) for texinfo XML in on a sunday afternoon.

That would be very useful.  If you provide similar commands to Info,
so similar bindings can be made, people might express all their
Texinfo files in XML with the Texinfo DTD, and try it your renderer,
in place of the current Info.

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

Re: Changes to Texinfo DTD

[Nic Ferrier]

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

>    > [Also, how do you view an XML file with a DTD in a manner that looks
>    > like graphically displayed HTML, as in Mozilla; how do you do the same
>    > in Emacs?]
>    [...]
> 
>    One could write a CSS for texinfo XML, so that at least some browsers,
>    like Mozilla, could render it.
> 
> That would be useful.  I use Galeon (which I presume would also use
> the CSS).  The next step would be to persuade the Mozilla/Galeon
> developers to make it easy to bind next, prev, up, last,
> regexp-search, and spacebar to keystrokes, so you could avoid the
> mouse.  As for me, the most vital capability is to be able to regexp
> search through a complete document that is in multiple files (i.e.,
> the equivalent of the Info-search command), and not attempt to go
> outside the document.

It would be better to provide an XSLT. The XSL could handle things
like keystrokes by associating javascript actions with markup (eg:
nodes).

When I write articles I use an XSLT for transforming the Texinfo
XML. I could adapt that if you like.


Nic

Re: Changes to Texinfo DTD

[Robert J. Chassell]

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

   > .... The next step would be to persuade the Mozilla/Galeon
   > developers to make it easy to bind next, prev, up, last,
   > regexp-search, and spacebar to keystrokes, so you could avoid the
   > mouse. ....

   It would be better to provide an XSLT. The XSL could handle things
   like keystrokes by associating javascript actions with markup (eg:
   nodes).

Does that mean we would not have to ask the Mozilla/Galeon developers
to do anything, but that the XSLT file would provide all that is
needed?  

If so, this sounds like an excellent idea, since it would mean that
the documentation on remote Web sites could be navigated through,
searched, and read nearly as easily as Info documentation locally.

I would especially like to see keystrokes for navigation, like `M-s'
for the equivalent of `Info-search', n, p, u, and spacebar.  Then I
could read a great deal that is remote from my machine and, as a
consequence, from me.

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

Re: Changes to Texinfo DTD

[Nic Ferrier]

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

> "Robert J. Chassell" <bob@rattlesnake.com> writes:
> 
>    > .... The next step would be to persuade the Mozilla/Galeon
>    > developers to make it easy to bind next, prev, up, last,
>    > regexp-search, and spacebar to keystrokes, so you could avoid the
>    > mouse. ....
> 
>    It would be better to provide an XSLT. The XSL could handle things
>    like keystrokes by associating javascript actions with markup (eg:
>    nodes).
> 
> Does that mean we would not have to ask the Mozilla/Galeon developers
> to do anything, but that the XSLT file would provide all that is
> needed?  

Well, enough that it makes adding code to Moz look overkill.

 
> If so, this sounds like an excellent idea, since it would mean that
> the documentation on remote Web sites could be navigated through,
> searched, and read nearly as easily as Info documentation locally.
> 
> I would especially like to see keystrokes for navigation, like `M-s'
> for the equivalent of `Info-search', n, p, u, and spacebar.  Then I
> could read a great deal that is remote from my machine and, as a
> consequence, from me.

You'd be limited on the emulation of emacs keys... I suspect ESC-s
wouldn't work for example, but ALT-S might.

I'm not sure how web standards hold up on modifier keys.


Search is an interesting one... I'm not sure how you'd implement
search. Modern Javascript does have regular expressions... so it
might be possible. XSLT 2.0 has regexs too, as do many XSLT 1.0
implementations out there... so it might be possible with XSLT as
well.

Straight forward would be:

- next/prev
- begin/end 
- index and menu lookups


Nic

Re: Changes to Texinfo DTD

[Oliver Scholz]

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

> Oliver Scholz <epameinondas@gmx.de> wrote:
>
>    So I have offered to hack the standalone info reader so that it
>    would support the XML format in the same way that I have chosen in
>    my patch. But I got not response so far.
>
> Heh... that might be a good idea.  However, I don't think I know of
> anyone who uses the standalone Info reader; they all use Emacs Info
> instead....  So I cannot give you any useful advice on this.

My proposal is to keep the current text/plain info format as an
internal representation in the standalone info reader. 

The reader would then check whether a particular file is in the
text/plain info format or in the XML format. If the former: business
as usual. If the latter, it would convert this XML to plain/text with
the necessary ^_ and the necessary "tags:" section and whatever else
is required *on the fly*. That's the way the patch works that I sent
earlier. Since I won't touch the code of the standalone reader at any
other place, I would need advice mainly on the specification of the
current info format.

IMO this change is the easiest and the least intrusive. I believe that
the transition to a new format would be painless this way. You could
have both the current (then old) info format and the new XML format in
/usr/info and other directories at the same time. The info reader
would just DTRT.

As I said: writing a non-conforming parser for a particular,
machine-generated XML in Emacs Lisp is very, very easy. So info.el
should probably do something slightly more sophisticated with the XML
format and provide more bells&whistles. Or at least we could add the
bells&whistles at a later time. I am not familiar with the code of
info.el and I don't want to deal with it right now.  But I'd offer to
implement any API for dealing with the XML that somebody who wants to
hack info.el would specify.

So. I have stated my cause now. :-)


    Oliver
-- 
Oliver Scholz               30 Brumaire an 212 de la Révolution
Taunusstr. 25               Liberté, Egalité, Fraternité!
60329 Frankfurt a. M.       http://www.jungdemokratenhessen.de
Tel. (069) 97 40 99 42      http://www.jdjl.org

Re: Changes to Texinfo DTD

[Robert J. Chassell]

Oliver Scholz <epameinondas@gmx.de> refers to the standalone Info
reader when he talks about enabling that renderer to determine
whether a document is in Info format or in XML format.

First, it seems to me cleaner to write an XML renderer that can
standalone, and then write separate code to enable the standalone Info
to choose whether to use its current renderer or the new one.

Second, you could write code to enable GNU Emacs to run a standalone
XML renderer, the way it now runs W3M mode -- the advantage of this is
that more people would test the standalone XML renderer than they
would if it only worked outside of Emacs.

Third, ... I don't know whether this is readily possible, but it looks
to me to be a good idea ...  you could add a standalone XML renderer
to Mozilla and related browsers.

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

Re: Changes to Texinfo DTD

[Oliver Scholz]

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

> First, it seems to me cleaner to write an XML renderer that can
> standalone, and then write separate code to enable the standalone Info
> to choose whether to use its current renderer or the new one.

I take that to mean: to write an entirely new program that does the
same job as the current standalone reader, but renders XML. I fail to
see the benefit. I admit that it would be conceptually nicer to have
the program keep the XML document as a DOM-like tree of nodes in
memory rather than as a flat string of characters (for the internal
representation would be the only difference to my proposal). But I do
not see what difference it would make for a user. But maybe I am
missing something.

More importantly: it would be a *lot* of work and you would need
somebody who implements it.  I am certainly not going to write an
entirely new standalone XML browser in C.  But I am willing to
implement my proposal and I am willing to do it now.

> Second, you could write code to enable GNU Emacs to run a standalone
> XML renderer, the way it now runs W3M mode -- the advantage of this is
> that more people would test the standalone XML renderer than they
> would if it only worked outside of Emacs.
[...]

That would also be a *lot* more work and maybe it could even be worse
performance-wise than rendering the XML directly in Elisp. You'd have
the process communication *and* you would still need to parse and
render some ad hoc made markup from the standalone reader.

    Oliver
-- 
Oliver Scholz               30 Brumaire an 212 de la Révolution
Taunusstr. 25               Liberté, Egalité, Fraternité!
60329 Frankfurt a. M.       http://www.jungdemokratenhessen.de
Tel. (069) 97 40 99 42      http://www.jdjl.org

Re: Changes to Texinfo DTD

[Nic Ferrier]

Oliver Scholz <epameinondas@gmx.de> writes:

> "Robert J. Chassell" <bob@rattlesnake.com> writes:
> [...]
> 
> > First, it seems to me cleaner to write an XML renderer that can
> > standalone, and then write separate code to enable the standalone Info
> > to choose whether to use its current renderer or the new one.
> 
> I take that to mean: to write an entirely new program that does the
> same job as the current standalone reader, but renders XML. I fail to
> see the benefit. I admit that it would be conceptually nicer to have
> the program keep the XML document as a DOM-like tree of nodes in
> memory rather than as a flat string of characters (for the internal
> representation would be the only difference to my proposal). But I do
> not see what difference it would make for a user. But maybe I am
> missing something.
> 
> More importantly: it would be a *lot* of work and you would need
> somebody who implements it.  I am certainly not going to write an
> entirely new standalone XML browser in C.  But I am willing to
> implement my proposal and I am willing to do it now.

It wouldn't be a lot of work. It would be trivial with XSLT. There
are basically 2 ways of doing it:


Method 1.
a) patch makeinfo so the XML output can be chunked.

b) prepend an xml-stylesheet processing-instruction to each chunked
   file

c) write an XSLT stylesheet to turn the XML into HTML with navigation
   written in Javascript (so key bindings can be used)

d) serve the files to Mozilla (or IE or any other XSLT aware browser)
   and it will render the XML using the stylesheet

e) For Emacs/W3 we'd have to write an XSLT processing solution, they
   are being worked on I understand. It would be very trivial to write
   one using a command line XSLT tool but see method 2.


Method 2.

a) use a command line XSLT tool such as xsltproc (from the GNOME
   libxml2 project: http://www.xmlsoft.org) to chunk AND style to HTML
   the output of makeinfo --xml.  
   The styling would be as method 1, part c.

b) serve the files, they would be HTML so Emacs/W3 would be able to
   read them without alteration.




> > Second, you could write code to enable GNU Emacs to run a standalone
> > XML renderer, the way it now runs W3M mode -- the advantage of this is
> > that more people would test the standalone XML renderer than they
> > would if it only worked outside of Emacs.
> [...]
> 
> That would also be a *lot* more work and maybe it could even be worse
> performance-wise than rendering the XML directly in Elisp. You'd have
> the process communication *and* you would still need to parse and
> render some ad hoc made markup from the standalone reader.

Nah. Just call out to a command line XSLT engine to turn the XML into
HTML.

This project needs doing anyway because most browsers do it. I'd be
happy to undertake this work on Emacs/W3.



Nic

Re: Changes to Texinfo DTD

[Oliver Scholz]

Nic Ferrier <nferrier@tapsellferrier.co.uk> writes:

> Oliver Scholz <epameinondas@gmx.de> writes:
[...]
>> I take that to mean: to write an entirely new program that does the
>> same job as the current standalone reader, but renders XML. I fail to
>> see the benefit.
[...]
>> More importantly: it would be a *lot* of work and you would need
>> somebody who implements it.

[...]
> It wouldn't be a lot of work. It would be trivial with XSLT. There
> are basically 2 ways of doing it:
>
>
> Method 1.
[...]
> c) write an XSLT stylesheet to turn the XML into HTML with navigation
>    written in Javascript (so key bindings can be used)
>
> d) serve the files to Mozilla (or IE or any other XSLT aware browser)
>    and it will render the XML using the stylesheet
>
> e) For Emacs/W3 we'd have to write an XSLT processing solution, they
>    are being worked on I understand. It would be very trivial to write
>    one using a command line XSLT tool but see method 2.

It seems to me that we are talking about entirely different things. I
wrote under the assumption that a small and lightweight standalone
info reader that works on a console is necessary. It is not that I am
particulary fond of that reader. In fact I have never used it before
this thread started. It is just that I believe that such a
minimalistic reader must exist, because info is the GNU system's
primary help and documentation system. Since everybody in this thread
seemed to agree that getting the standalone console reader to support
a new format would be the hart part, I focused only on this reader.

I think your proposal to enable XSLT aware web browsers to serve as
full info readers is great. But I also think that there has to be at
least one simple, independent solution with minimum requirements that
works under all circumstances, including working on a Linux tty.

If you can make your solution for Emacs work without a significant
performance loss (Emacs/W3 is not the fastest html renderer known to
mankind), then this is fine for me, personally. Though, I don't like
the idea of making C-h i depend on yet another external program,
unless this program ships with the Emacs tarball.


[...]
>> That would also be a *lot* more work and maybe it could even be worse
>> performance-wise than rendering the XML directly in Elisp. You'd have
>> the process communication *and* you would still need to parse and
>> render some ad hoc made markup from the standalone reader.
>
> Nah. Just call out to a command line XSLT engine to turn the XML into
> HTML.
[...]

That's still process communication + rendering.

    Oliver
-- 
Oliver Scholz               30 Brumaire an 212 de la Révolution
Taunusstr. 25               Liberté, Egalité, Fraternité!
60329 Frankfurt a. M.       http://www.jungdemokratenhessen.de
Tel. (069) 97 40 99 42      http://www.jdjl.org

Re: Changes to Texinfo DTD

[Nic Ferrier]

Oliver Scholz <epameinondas@gmx.de> writes:

> It seems to me that we are talking about entirely different things. I
> wrote under the assumption that a small and lightweight standalone
> info reader that works on a console is necessary. It is not that I am
> particulary fond of that reader. In fact I have never used it before
> this thread started. It is just that I believe that such a
> minimalistic reader must exist, because info is the GNU system's
> primary help and documentation system. Since everybody in this thread
> seemed to agree that getting the standalone console reader to support
> a new format would be the hart part, I focused only on this reader.

I am not arguing for a removal of the info reader. I use the info
reader A LOT. Much more than other people in this thread seem to (and
I do mean the info reader, not the emacs info tool).

But why does the info reader have to be adapted to support a new
format?


> If you can make your solution for Emacs work without a significant
> performance loss (Emacs/W3 is not the fastest html renderer known to
> mankind), then this is fine for me, personally. Though, I don't like
> the idea of making C-h i depend on yet another external program,
> unless this program ships with the Emacs tarball.

We don't need to make W3 support XSLT for reading local info files,
only remote ones that you read over the web.

And even then... as Bob was saying, we don't NEED to make Emacs read
the files because there are other solutions for doing it.

I think we're looking at a fairly small problem space here.

 
> > Nah. Just call out to a command line XSLT engine to turn the XML into
> > HTML.
> [...]
> 
> That's still process communication + rendering.

You could say that... but here's the elisp to do the XSL bit:
  
  (let ((x (make-temp-file "xmlout"))
        (n (get-buffer-create "html")))
     (write-region (point-min) (point-max) x)
     (shell-command 
        (concat "xsltproc --html emacsw3-xml-html.xsl "  x)
        n)
     ;; now buffer n contains html so render that...)
 

Nic

Re: Changes to Texinfo DTD

[Robert J. Chassell]

Oliver Scholz <epameinondas@gmx.de> wrote

    It seems to me that we are talking about entirely different
    things. I wrote under the assumption that a small and lightweight
    standalone info reader that works on a console is necessary.

Indeed, there are different issues.  One is rendering Texinfo into a
surface expression which a display program can handle as efficiently
as Info.  The second is providing such a display program, or several
of them.

If my understanding is correct, Nic Ferrier is proposing a standard
for an XML format that is a moderate extension of the current XML
format produced by makeinfo.

Also, if I understand correctly, he thinks that the new XML format
will enable existing browsers such as Mozilla to be as efficient as
the current Info mode in Emacs.  And, in addition, with the use of an
appropriate CGI on the Web servers, people will be able to read Info
documents over a slow connection as well as they can read Info on a
local machine.

As Karl Eichwalder <ke@gnu.franken.de> said

    yelp, the GNOME help browser, works directly with XML files
    conforming to a DocBook subset - it starts a little bit slow, be
    warned.

This is good news, since it means that not too much work will be
needed to create a decent renderer for a surface expression of
Texinfo.

Put another way, Info is designed for a fast connection between the
program doing the rendering and the file serving the Info file.  But
HTML is designed for a slow connection between the program doing the
rendering and the Web server providing the HTML file.

As far as I know, the current HTML produced by `makeinfo --html'
permits search/navigation only within a single HTML `page' or file,
not within a document spread over multiple files, as with Info.  So
you need to create HTML documents using the `--no-split' option, which
means as a practical matter, that HTML works quickly only in the same
circumstance as Info, namely that there be a fast connection between
the program doing the rendering and the file server.

The goal is to produce an XML output that not only overcomes the
disadvantages of HTML and Info, but goes ahead of them.

So, to return to Oliver's comment:

    ... I wrote under the assumption that a small and lightweight
    standalone info reader that works on a console is necessary.

Yes, this is necessary, as one of the various display programs that
the new XML could use.  

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

Re: Changes to Texinfo DTD

[Nic Ferrier]

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

> Put another way, Info is designed for a fast connection between the
> program doing the rendering and the file serving the Info file.  But
> HTML is designed for a slow connection between the program doing the
> rendering and the Web server providing the HTML file.

I don't really understand this. But maybe I'm not seeing it at the
right level of detail.

No matter, what I'm saying is that we can *easily* make an HTML
representation of Texinfo which is better for people with slow network
connections than the current format.

The representation will operate in a Javascript/XSLT aware browser
and have:

- keyboard navigation
- index term lookup
- node sized downloads

Search will also be included but only with the addition of a web
application (a CGI script probably) held on the same server which is
serving the Texinfo files.

We can do this *because* we have the XML output and don't have to
write complicated HTML rendering code, we can write simply HTML
rendering code with XSLT.


> Oliver said:
>     ... I wrote under the assumption that a small and lightweight
>     standalone info reader that works on a console is necessary.
> 
> Yes, this is necessary, as one of the various display programs that
> the new XML could use.  

You're not saying we have to write a new console info reader for XML
are you? 

If you are saying that: why? The current info reader is fine for
consoles, surely it's okay that it uses a different data format than
XML or HTML?


Nic

Re: Changes to Texinfo DTD

[Robert J. Chassell]

Nic Ferrier <nferrier@tapsellferrier.co.uk> wrote

   Method 1.
   a) patch makeinfo so the XML output can be chunked.
   ....

This sounds the best in the long run.  Some one should be able to take
your code in ten years time and work with it usefully, for some
purpose you never thought of.

   Method 2.
   a) use a command line XSLT tool such as xsltproc (from the GNOME
      libxml2 project: http://www.xmlsoft.org) to chunk AND style to HTML
      the output of makeinfo --xml.  
      The styling would be as method 1, part c.

How is this different from the existing `makeinfo --html' which also
does chunking and styling to HTML?

Without knowing much about `xsltproc', the method scares me.  Does
this method enable me to use keybindings in Mozilla to navigate via
regexp searching within a document that is spread over multiple files?
If so, good and I stop being scared.  Indeed, then the suggestion
becomes very attractive.  But if not, it is a distraction.

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

Re: Changes to Texinfo DTD

[Nic Ferrier]

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

> Nic Ferrier <nferrier@tapsellferrier.co.uk> wrote
> 
>    Method 1.
>    a) patch makeinfo so the XML output can be chunked.
>    ....
> 
> This sounds the best in the long run.  Some one should be able to take
> your code in ten years time and work with it usefully, for some
> purpose you never thought of.

Yeah... it seems that:

    makeinfo --xml --split 

should work because one expects it to.

 
>    Method 2.
>    a) use a command line XSLT tool such as xsltproc (from the GNOME
>       libxml2 project: http://www.xmlsoft.org) to chunk AND style to HTML
>       the output of makeinfo --xml.  
>       The styling would be as method 1, part c.
> 
> How is this different from the existing `makeinfo --html' which also
> does chunking and styling to HTML?
> 
> Without knowing much about `xsltproc', the method scares me.  Does
> this method enable me to use keybindings in Mozilla to navigate via
> regexp searching within a document that is spread over multiple files?
> If so, good and I stop being scared.  Indeed, then the suggestion
> becomes very attractive.  But if not, it is a distraction.

It's different because now one can attach javascript to elements on
the page whevever one needs it. The existing HTML doesn't do that,
nor should it because it has an existing purpose.

It's not scary - it's trivial. XSLT is very easy to read and
implement.

The XSLT solution isn't the end. To support regex searches some sort
of webapplication IS needed as well. But XSLT is exactly the best
choice for turning the Texinfo XML into something that would work with
a webapp.

Note that for method 1 and method 2 a webapplication would be needed,
but only for regexp search. All the other tools, navigation, index
lookup, etc... could be solved by javascript within the page.


Nic

Re: Changes to Texinfo DTD

[Juri Linkov]

Nic Ferrier <nferrier@tapsellferrier.co.uk> writes:
> "Robert J. Chassell" <bob@rattlesnake.com> writes:
>> Nic Ferrier <nferrier@tapsellferrier.co.uk> wrote
>>    Method 2.
>>    a) use a command line XSLT tool such as xsltproc (from the GNOME
>>       libxml2 project: http://www.xmlsoft.org) to chunk AND style to HTML
>>       the output of makeinfo --xml.  
>>       The styling would be as method 1, part c.
>> 
>> How is this different from the existing `makeinfo --html' which also
>> does chunking and styling to HTML?
>> 
>> Without knowing much about `xsltproc', the method scares me.  Does
>> this method enable me to use keybindings in Mozilla to navigate via
>> regexp searching within a document that is spread over multiple files?
>> If so, good and I stop being scared.  Indeed, then the suggestion
>> becomes very attractive.  But if not, it is a distraction.
>
> It's different because now one can attach javascript to elements on
> the page whevever one needs it. The existing HTML doesn't do that,
> nor should it because it has an existing purpose.

BTW, do you know that HTML files generated from Texinfo files already
have keys for navigation?  The <a> tag has an attribute "accesskey"
which assigns keys to "u" (up), "n" (next), "p" (prev), "[1-5]" (menu).
These keys can be pressed e.g. in Mozilla as M-u, M-n, M-p, M-[1-5]
to navigate to the corresponding HTML node.

There is another useful scheme for navigation in HTML by specifying
a "link" tag in meta section, e.g. <link rel="next" href="next.html" />,
but currently this is not generated in info HTML files.

> The XSLT solution isn't the end. To support regex searches some sort
> of webapplication IS needed as well. But XSLT is exactly the best
> choice for turning the Texinfo XML into something that would work with
> a webapp.

Some indexing programs like swish++ is needed here.  BTW, this was
recently suggested to me, when I asked about searching a mail archive.
I don't know what indexing programs can index info files.

-- 
http://www.jurta.org/emacs/

Re: Changes to Texinfo DTD

[Nic Ferrier]

Juri Linkov <juri@jurta.org> writes:

> BTW, do you know that HTML files generated from Texinfo files already
> have keys for navigation?  The <a> tag has an attribute "accesskey"
> which assigns keys to "u" (up), "n" (next), "p" (prev), "[1-5]" (menu).
> These keys can be pressed e.g. in Mozilla as M-u, M-n, M-p, M-[1-5]
> to navigate to the corresponding HTML node.
> 
> There is another useful scheme for navigation in HTML by specifying
> a "link" tag in meta section, e.g. <link rel="next" href="next.html" />,
> but currently this is not generated in info HTML files.

Yes. I did know that.

But what you can't do is lookup a value in an index, do a secondary
lookup (",") or a search or a follow on search. You can't lookup a
menu item or travel through the document by node (I'm not sure the new
system will allow travel by node though).

In addition those keys, while being good standard HTML can probably
be improved on by using the key event model of the modern web browser
DOM (Document Object Model).


> > The XSLT solution isn't the end. To support regex searches some sort
> > of webapplication IS needed as well. But XSLT is exactly the best
> > choice for turning the Texinfo XML into something that would work with
> > a webapp.
> 
> Some indexing programs like swish++ is needed here.  BTW, this was
> recently suggested to me, when I asked about searching a mail archive.
> I don't know what indexing programs can index info files.

I think it can probably be achieved by grep or awk initially.


Nic

Re: Changes to Texinfo DTD

[Richard Stallman]

    e) For Emacs/W3 we'd have to write an XSLT processing solution, they
       are being worked on I understand. It would be very trivial to write
       one using a command line XSLT tool but see method 2.

I can't begin to make sense of that.  How would you propose
that Emacs display one of these XML files?

It can't depend on W3 because W3 is not part of Emacs.

Re: Changes to Texinfo DTD

[Nic Ferrier]

Richard Stallman <rms@gnu.org> writes:

>     e) For Emacs/W3 we'd have to write an XSLT processing solution, they
>        are being worked on I understand. It would be very trivial to write
>        one using a command line XSLT tool but see method 2.
> 
> I can't begin to make sense of that.  How would you propose
> that Emacs display one of these XML files?
> 
> It can't depend on W3 because W3 is not part of Emacs.

One of two ways:

1. use a command line XSLT processor (such as xsltproc, part of
   GNOME's libxsl project) to turn the XML into plain text (or
   specifically marked up text). 

2. write an XSLT processor in Emacs Lisp. This wouldn't be as
   difficult as it sounds and I'm not sure it isn't done already (by
   one of the various XML/Emacs projects going on).


These are only technical possibilites. From an administrative
standpoint the second one is probably the only option since you
wouldn't want to depend the Emacs info reader on xsltproc.


Nic

Re: Changes to Texinfo DTD

[Miles Bader]

On Sat, Nov 22, 2003 at 09:41:39PM +0000, Nic Ferrier wrote:
> 2. write an XSLT processor in Emacs Lisp. This wouldn't be as
>    difficult as it sounds and I'm not sure it isn't done already (by
>    one of the various XML/Emacs projects going on).

The main question in my mind is whether this would be fast enough -- the
current info mechanism, though it has its problems, can display info pages
very quickly.  As a point of contrast, W3 is _very_ slow (I think it would be
completely unsuitable for use in displaying info files).

-Miles
-- 
The secret to creativity is knowing how to hide your sources.
  --Albert Einstein

Re: Changes to Texinfo DTD

[Nic Ferrier]

Miles Bader <miles@gnu.org> 
 writes:

> On Sat, Nov 22, 2003 at 09:41:39PM +0000, Nic Ferrier wrote:
> > 2. write an XSLT processor in Emacs Lisp. This wouldn't be as
> >    difficult as it sounds and I'm not sure it isn't done already (by
> >    one of the various XML/Emacs projects going on).
> 
> The main question in my mind is whether this would be fast enough -- the
> current info mechanism, though it has its problems, can display info pages
> very quickly.  As a point of contrast, W3 is _very_ slow (I think it would be
> completely unsuitable for use in displaying info files).
 
In this response to rms I was not suggesting W3. I was talking about
writing an XSLT processor in emacs lisp. XSLT is pretty quick unless
memory is very limited or the transformation it is given is
particularly complex.


Bob Chassell and I are intending that Emacs/W3 be used as a platform
for viewing our new HTML version of Texinfo. And yes, speed is a
concern.


Nic

Re: Changes to Texinfo DTD

[Juri Linkov]

Nic Ferrier <nferrier@tapsellferrier.co.uk> writes:
> Miles Bader <miles@gnu.org> writes:
>> On Sat, Nov 22, 2003 at 09:41:39PM +0000, Nic Ferrier wrote:
>> > 2. write an XSLT processor in Emacs Lisp. This wouldn't be as
>> >    difficult as it sounds and I'm not sure it isn't done already (by
>> >    one of the various XML/Emacs projects going on).
>> 
>> The main question in my mind is whether this would be fast enough -- the
>> current info mechanism, though it has its problems, can display info pages
>> very quickly.  As a point of contrast, W3 is _very_ slow (I think it would be
>> completely unsuitable for use in displaying info files).
>  
> In this response to rms I was not suggesting W3. I was talking about
> writing an XSLT processor in emacs lisp. XSLT is pretty quick unless
> memory is very limited or the transformation it is given is
> particularly complex.

Why do you want to write an XSLT processor in emacs lisp?
The XSL is a poor and ugly copy of Lisp.  I once was enthusiastic
about XSL too, but soon I realized that it's simply a parody of Lisp.
Much better alternative for XML transformation and style formatting
could be the DSSSL, but unfortunately it is not popular now.
So, if you are going to do something in Emacs, please, do it
in Emacs Lisp, not in XSL or JavaScript.

-- 
http://www.jurta.org/emacs/

Why XSLT in Emacs Lisp? (was Re: Changes to Texinfo DTD)

[Nic Ferrier]

Juri Linkov <juri@jurta.org> writes:

> Nic Ferrier <nferrier@tapsellferrier.co.uk> writes:
> > Miles Bader <miles@gnu.org> writes:
> >> On Sat, Nov 22, 2003 at 09:41:39PM +0000, Nic Ferrier wrote:
> >> > 2. write an XSLT processor in Emacs Lisp. This wouldn't be as
> >> >    difficult as it sounds and I'm not sure it isn't done already (by
> >> >    one of the various XML/Emacs projects going on).
> >> 
> >> The main question in my mind is whether this would be fast enough -- the
> >> current info mechanism, though it has its problems, can display info pages
> >> very quickly.  As a point of contrast, W3 is _very_ slow (I think it would be
> >> completely unsuitable for use in displaying info files).
> >  
> > In this response to rms I was not suggesting W3. I was talking about
> > writing an XSLT processor in emacs lisp. XSLT is pretty quick unless
> > memory is very limited or the transformation it is given is
> > particularly complex.
> 
> Why do you want to write an XSLT processor in emacs lisp?
> The XSL is a poor and ugly copy of Lisp.  I once was enthusiastic
> about XSL too, but soon I realized that it's simply a parody of Lisp.
> Much better alternative for XML transformation and style formatting
> could be the DSSSL, but unfortunately it is not popular now.
> So, if you are going to do something in Emacs, please, do it
> in Emacs Lisp, not in XSL or JavaScript.

Yes, XML syntax is clearly derived from s-expressions. But this is not
the same as saying that XSLT is a parody of Lisp.

The reason I might consider writing an XSLT processor in Emacs Lisp is
that W3 will need one in the future. Modern web browsers (such as
Mozilla) allow you to render XML inside the browser, but they only do
that using XSLT.

Emacs/W3 could easily use an external program for doing such a
transformation, but that would complicate it's instal by making it
dependant on such an external XSLT.

Therefore an XSLT engine written in Emacs Lisp would be beneficial.


As an aside, because XML is basically s-expressions then an XSLT
wouldn't be _that_ difficult to write in Emacs Lisp. As I said in my
original email, I think it may already have been done.


DSSL would be much more work because it is, essentially, Scheme. All
the problems associated with integrating Scheme into Emacs would rear
their heads, how to do lexical scoping for example.

And anyway, there isn't a standard for transforming XML in a web
browser with DSSL.


Nic

Re: Why XSLT in Emacs Lisp?

[Alex Schroeder]

Nic Ferrier <nferrier@tapsellferrier.co.uk> writes:

> The reason I might consider writing an XSLT processor in Emacs Lisp is
> that W3 will need one in the future. Modern web browsers (such as
> Mozilla) allow you to render XML inside the browser, but they only do
> that using XSLT.

A long time ago I wrote a dom implementation and a simple xslt
implementation in elisp.  It is still available from the emacs wiki.

Alex.
-- 
.O.  http://www.emacswiki.org/alex/
..O  Schroeder's first law:
OOO  The coffee at the office shall taste terrible.

Re: Changes to Texinfo DTD

[Robert J. Chassell]

Miles Bader <miles@gnu.org> wrote

    The main question in my mind is whether this would be fast enough
    -- the current info mechanism, though it has its problems, can
    display info pages very quickly.

Yes, you are right.  The goal is to provide an alternative to Info
that is as efficient as Info and as fast.

This will help both those who prefer the markup they see in Web
browsers to what they get in Info, and those who use Web browsers,
such as Mozilla, for reading documentation.  (And as a side effect, it
may inspire people to improve W3 mode or another Web browser for
Emacs.)

Right now, it is impossible for any HTML mechanism to be as efficient
as Info, since (as a practical matter) HTML lacks the concept of `one
document in many files'.  HTML runs via a `one document in one file'
schema.  (I am told that in theory a hypertext link can point to one
document that is spread over several files, but I have never seen
this.)

Moreover, a browser, such as Mozilla 1.0, lacks even a regexp search
mechanism for navigating within one page!

However, HTML does have a great advantage over Info: HTML is designed
for the situation in which the rendering computer is separated from the
server by a slow connection.

Info depends on a fast connection between the rendering machine and
the source of the Info file.  Indeed the Info file is often on a disk
on the rendering machine; if not, it is connected via a fast NFS or
similar link.

Here are the two topologies:

Info:
                      fast      rendering       fast
 terminal/display ---  or  ---  computer  --- connection --- Info source
                      slow                      only
                   connection
                                \________ often one computer __________/



HTML:
                                                    fast
                        fast         rendering       or
 terminal/display --- connection --- computer  ---- slow ---- Web server
                                                  connection
  \____________ often one computer __________/

                                     \______ often two computers ______/
                                             connected over the
                                                 Internet


On my current connection, it takes 17 minutes to download the Emacs
Lisp Reference Manual.  There is no way I would wait that long before
beginning to browse the manual remotely.  For remote use, the manual
needs to be divided into smaller files, as Texinfo files are now when
converted to HTML.

Moreover, even with splitting, a search will take too long, unless the
search regexp is sent to the remote site.

I mention search because `Info-search' is still the most efficient way
to navigate through a GNU manual.  String searches through a complete
document (and indices) are very helpful, but simply not good enough.

Consequently, both to help documentation readers who want the kind of
markup they see in a Web browser, and also to help those who want to
read their documentation over the Internet via a slow connection,
current HTML needs to be improved in two ways:

  1. The Texinfo to HTML conversion process needs to ensure that key
     bindings as well as mouse bindings exist for moving from one node
     to another, for index lookups, etc., for a document that is
     spread over several files. 

     Without keybindings, you have to move the mouse, which is fine
     for novices or those who don't mind spending their time doing so,
     but which is not as efficient as simply pressing the spacebar or
     other key, regardless where point is.

     This can be done by providing the document as one or more HTML
     pages, appropriately chunked and formatted and with Javascript
     for the keybindings.  Nothing need be done to the Web server.

  2. The Web server needs a CGI that enables regular expression
     searches/navigation through a single document split among
     several files.  Info has the wonderful `Info-search' command,
     usually bound to `M-s'.  This feature provides the equivalent.

     Since whole documents are often large -- as I said, the Emacs
     Lisp Reference Manual takes me 17 minutes to download -- and HTML
     works by downloading files that are then rendered, the only way
     to provide quick regular expression search and navigation is by
     sending only a search command, such as an `s', to the Web server,
     and having the Web server run the search itself.

     This feature does require adding a module to the Web server.
     This is difficult, since only some Web masters will provide the
     added convenience.  However, it is easy to install CGI scripts on
     Apache.  If the master of the Web server has not installed the
     CGI script, then the Javascript in the Texinfo HTML file tell the
     user that the Web server to which he or she is connected is
     lacking.  And perhaps, eventually, the people who distribute
     Apache will be persuaded to include this module with the others,
     as part of their standard distribution.

I think the far more difficult issue is learning by people who want to
make use of efficient searches and navigation.  Partly, the difference
is preference; but partly the difference is learning.

The kind of efficiency provided by Info is beyond most people's dreams
-- they do not even imagine that an equivalent of `Info-search' could
be useful.  It does not occur them to learn.  Consquently, for many of
the people who want to take advantage of their computer, fundamental
relearning is required.  (For others it is preference, as I said.
Indeed, some people who use Info do not much use `Info-search'.)

On the other hand, Info was not designed for the kind of network we
now have, in which people have their own rendering machines, but
download files from a Web server over a slow connection.  Info was
designed for a network in which the connection between a display or
terminal and the rendering machine may be over a slow connection, but
the connection between the rendering machine and the disk providing
the Info files is fast.

Put another way, both Info and HTML have deficiencies.  The goal here
is make use of HTML's features and add those needed to match Info.

Next, the problem will be to encourage writers to write for all
potential users, not only those who look at documentation on a high
resolution/fast redisplay screen:  to write for people driving cars or
otherwise blind, to write for those working over a really slow
connection, to write for those using limited equipment.

For example, people are going to listen to documents spoken to them
over a cell phone while they drive a car.

Currently, Texinfo files tend to be written for such people, but I see
more and more use of @image without an alternative for those who do
not want images.

But that is a problem for another day.

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

Re: Changes to Texinfo DTD

[Juri Linkov]

Miles Bader <miles@gnu.org> writes:
> On Sat, Nov 22, 2003 at 09:41:39PM +0000, Nic Ferrier wrote:
>> 2. write an XSLT processor in Emacs Lisp. This wouldn't be as
>>    difficult as it sounds and I'm not sure it isn't done already (by
>>    one of the various XML/Emacs projects going on).
>
> The main question in my mind is whether this would be fast enough -- the
> current info mechanism, though it has its problems, can display info pages
> very quickly.  As a point of contrast, W3 is _very_ slow (I think it would be
> completely unsuitable for use in displaying info files).

The current info mechanism is very fast mostly because some formatting
is already done at info files generation time, where the most important
preformatting is the lines filling to 70 columns.  So, if it is
acceptable limitation, the same could be applied to XML solution,
i.e. to generate from Texinfo source such XML files that after
stripping all markup the remaining plain text is already properly
aligned without reformatting.  This will solve the current problem in
Info files, where some lines change their length after hiding a part
of reference.  In XML all additional information can be freely
included into tag attributes without affecting the filling of plain
text.  For example, <a xref="(elisp)Menu Keymaps">Menu Keymaps</a>.

-- 
http://www.jurta.org/emacs/

Re: Changes to Texinfo DTD

[Luc Teirlinck]

I am jumping in a thread I have not been following from the beginning
which always carries the danger of completely missing the point, but I
believe that the quote below is talking about alternatives to the
present reformatting of Info files when `Info-hide-note-references' is
t.  If yes, I have a point I want to make to make sure that this
alternative does not make the same mistake as the present
reformatting.  If not, sorry.

Juri Linkov wrote:

   This will solve the current problem in Info files, where some lines
   change their length after hiding a part of reference.  In XML all
   additional information can be freely included into tag attributes
   without affecting the filling of plain text.  For example, <a
   xref="(elisp)Menu Keymaps">Menu Keymaps</a>.

I hope it will also solve the other problem with the current situation
in Emacs with Info-hide-note-references set to t.  Namely, in the
above example, it would just print "Menu Keymaps" without any
indication that this is going to carry you out of the manual you are
reading into the Elisp manual.

Take (elisp)Locales as an example.  The texinfo source contains:

@xref{Locales,,, libc, GNU Libc Manual}, for more information about
locales and locale items.

With Info-hide-note-references set to t this gives:

See Locales for more information about locales and locale items.

"Locales" is the node we are looking at.  So the user thinks:  "This
is silly.  This just offers to carry me to the node I am already
staring at." and does not follow the reference.

With Info-hide-note-references set to nil, we see:

*Note Locales: (libc)Locales, for more information about locales and
locale items.

Oh, it is actually _not_ the node we are staring at, but a node with
exactly the same name in the libc manual!  Now, if we are not sure
what all this "locale" stuff is really about, here is a useful link to
follow.

"*Note Locales: (libc)Locales" is actually OK with me, but other
people consider it too ugly.  That is OK with me too as long as it
does not get replaced with something pretty but misleading.  Replacing
it with "See Locales in the (libc) manual" would be OK.  I am not sure
whether it would be safe to replace it with the "fully pretty":
"See Locales in the GNU Libc Manual", because that refers to the
printed manual. It would look OK in this example, but I do not believe
it is guaranteed to always be OK.

Sincerely,

Luc.

Re: Changes to Texinfo DTD

[Robert J. Chassell]

Luc Teirlinck <teirllm@dms.auburn.edu> makes a very good point when he
says that with `Info-hide-note-references' set to t in Emacs, you can
lose track of which files hold which nodes.  I hope that Nic's
implementation does not repeat the mistake.

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

Re: Changes to Texinfo DTD

[Miles Bader]

On Mon, Nov 24, 2003 at 10:32:45PM +0000, Robert J. Chassell wrote:
> Luc Teirlinck <teirllm@dms.auburn.edu> makes a very good point when he
> says that with `Info-hide-note-references' set to t in Emacs, you can
> lose track of which files hold which nodes.  I hope that Nic's
> implementation does not repeat the mistake.

I know you have a bug up your butt about this, but it has nothing to do with
the discussion at hand -- it's a user interface issue, not an implementation
issue.

If you want to bitch about it again, start a new thread.

-Miles
-- 
Run away!  Run away!

Re: Changes to Texinfo DTD

[Juri Linkov]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:
> Juri Linkov wrote:
>    This will solve the current problem in Info files, where some lines
>    change their length after hiding a part of reference.  In XML all
>    additional information can be freely included into tag attributes
>    without affecting the filling of plain text.  For example,
>    <a xref="(elisp)Menu Keymaps">Menu Keymaps</a>.
>
> I hope it will also solve the other problem with the current situation
> in Emacs with Info-hide-note-references set to t.  Namely, in the
> above example, it would just print "Menu Keymaps" without any
> indication that this is going to carry you out of the manual you are
> reading into the Elisp manual.

The same is true for web browsers too.  They display only a link title
without URL in the text area.  But when you move the mouse pointer
over a link, the browser displays the URL in the status bar.
Emacs Info currently works in the same way: it puts the help-echo
text property on a reference, so you can see the full address in the
echo area after moving mouse over a reference.

BTW, recently there was a discussion on the emacs-devel list about
displaying help-echo in the echo area after point movements over a
text property.  What was the decision?  This could be useful for Info
buffers too, i.e. when point moves to a reference with help-echo text
property, then Emacs could display the full address in the echo area.

-- 
http://www.jurta.org/emacs/

Re: Changes to Texinfo DTD

[Luc Teirlinck]

Juri Linkov wrote:

   BTW, recently there was a discussion on the emacs-devel list about
   displaying help-echo in the echo area after point movements over a
   text property.  What was the decision?  This could be useful for Info
   buffers too, i.e. when point moves to a reference with help-echo text
   property, then Emacs could display the full address in the echo area.

I just asked Richard whether it was OK to install the new file
"help-at-pt.el" that implements this.  Richard had still some questions
about details concerning help-for-help and the name of a function.

Sincerely,

Luc.

Re: Changes to Texinfo DTD

[Juri Linkov]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:
> Juri Linkov wrote:
>
>    BTW, recently there was a discussion on the emacs-devel list about
>    displaying help-echo in the echo area after point movements over a
>    text property.  What was the decision?  This could be useful for Info
>    buffers too, i.e. when point moves to a reference with help-echo text
>    property, then Emacs could display the full address in the echo area.
>
> I just asked Richard whether it was OK to install the new file
> "help-at-pt.el" that implements this.  Richard had still some questions
> about details concerning help-for-help and the name of a function.

But will this work in Info buffers?  As I remember, there is some
additional text property with a help text such that if point moves
over a character with such property, then a help text is displayed in
the echo area.  Is it so?  This would be useful to display references
to external info manuals in the echo area when references are hidden
in the Info buffer and user navigates between references by keyboard.

-- 
http://www.jurta.org/emacs/

Re: Changes to Texinfo DTD

[Luc Teirlinck]

Yuri Linkov wrote:

   But will this work in Info buffers?  As I remember, there is some
   additional text property with a help text such that if point moves
   over a character with such property, then a help text is displayed in
   the echo area.  Is it so?  This would be useful to display references
   to external info manuals in the echo area when references are hidden
   in the Info buffer and user navigates between references by keyboard.

Essentially, the same text as the one provided on mouse-over by the
help-echo property can get printed on point-over, in the echo area, if
the user sets a timer.  The timer is customizable in various ways.
Without a timer, the text can be printed on demand using "C-h ."  Even
without the timer there are movement functions that move to the next
or previous `help-echo' region and print the help-echo of that region
in the echo area.

So my file is mainly concerned with the help-echo property, although
it provides for a more keyboard oriented alternative kbd-help, in case
help-echo is too exclusively mouse-oriented.

While all of this can be useful when Info-hide-note-references is t, I
do not believe that it is a full substitute for the ability to
customize that variable to nil.

Making invisible text temporarily visible is something different.
There you have reveal-mode, which, if I understand correctly, requires
overlays and does not work well with Info's text properties.  You have
visible-mode which toggles invisibility regardless of whether text or
overlay properties are used.  If one winds up enabling visible-mode
too often in Info however, one probably wants to set
Info-hide-note-references to nil.

Sincerely,

Luc.

Re: Changes to Texinfo DTD

[Luc Teirlinck]

Yuri Linkov wrote:

   The same is true for web browsers too.  They display only a link title
   without URL in the text area.  But when you move the mouse pointer
   over a link, the browser displays the URL in the status bar.
   Emacs Info currently works in the same way: it puts the help-echo
   text property on a reference, so you can see the full address in the
   echo area after moving mouse over a reference.

Info file names are usually very short, URL's tend to be long.  True,
I can get the full information, but it requires some extra effort.  I
may not take the trouble because I expect it to go to a section of the
manual I am reading, because that is the "normal" situation.  Hence, I
do not worry about it because I have already read it and miss out on
necessary information.  The suggestions in my previous message might
make things too long, but there are other possibilities.  For
instance, one could replace:

*Note Locales: (libc)Locales, for more ...

with:

See Locales (libc) for more ...

instead of with just:

See Locales for more ...

Anyway, if not, then the question is whether your proposed new
implementation will work fine, filling and everything, with all
possible values of Info-hide-note-references.  In that case, everybody
can customize.  (I believe I understood that this thread is talking
about a format that could potentially be used by Emacs, unlike the "A
new online publishing ... " thread.)

Sincerely,

Luc.

Re: Changes to Texinfo DTD

[Juri Linkov]

>    The same is true for web browsers too.  They display only a link title
>    without URL in the text area.  But when you move the mouse pointer
>    over a link, the browser displays the URL in the status bar.
>    Emacs Info currently works in the same way: it puts the help-echo
>    text property on a reference, so you can see the full address in the
>    echo area after moving mouse over a reference.
>
> Info file names are usually very short, URL's tend to be long.  True,
> I can get the full information, but it requires some extra effort.  I
> may not take the trouble because I expect it to go to a section of the
> manual I am reading, because that is the "normal" situation.  Hence, I
> do not worry about it because I have already read it and miss out on
> necessary information.

This looks like a complaint about how all current web browsers work :-)
You don't see in the text area of web browsers whether a link leads
to to same site or not.  Well, some sites (like slashdot.org) adds
the name of external site after a link in the text if link leads outside.
This is actually similar to what you are proposing.

> Anyway, if not, then the question is whether your proposed new
> implementation will work fine, filling and everything, with all
> possible values of Info-hide-note-references.  In that case, everybody
> can customize.  (I believe I understood that this thread is talking
> about a format that could potentially be used by Emacs, unlike the "A
> new online publishing ... " thread.)

I wanted to clarify what is the best way to display references in the
current Info format or XML output of Texinfo without refilling and
without changing line lengths.

-- 
http://www.jurta.org/emacs/

Re: Changes to Texinfo DTD

[Luc Teirlinck]

Yuri Linkov wrote:

   I wanted to clarify what is the best way to display references in the
   current Info format or XML output of Texinfo without refilling and
   without changing line lengths.

I do not know XML.  But it would seem to me that keeping
Info-hide-note-references in its present form and having the XML output
already "pre-filled" correctly for all values of the variable might
require passing the value as an extra option to makeinfo --xml.  If
one then would convert Texinfo source files to such pre-filled XML
files as part of the Emacs make process, like they are now converted
to .info files (I do not know whether this is the intention), then one
would have to change Info-hide-note-references from a customizable
variable to an option given to configure (and passed along to 
makeinfo --xml).  One could keep Info-hide-note-references as a
customizable variable by regenerating the pre-filled XML files from
the Texinfo source files as needed, but I do not know whether that
would be fast enough.

Alternatively, Info could consult the value of
Info-hide-note-references and do the filling itself using an XML file
that still contained enough information to respect any @* or @w
commands present in the original Texinfo source.  Or one could
regenerate the pre-filled XML from non pre-filled XML, as needed, in
some other way.  The problem with present refilling attempts with
Info-hide-note-references set to t is not speed, but the fact that the
information contained in @*, @w and the like is not preserved in the
.info files and currently the .info files is all Info has to work
with.  I believe to recall from previous discussions that one of the
benefits of XML would be that it still would contain the XML
equivalents of @*, @w and the like.

Or am I misunderstanding something?  (Again, I do not know XML.)

Sincerely,

Luc.

Re: Changes to Texinfo DTD

[Eli Zaretskii]

> Date: Mon, 24 Nov 2003 10:19:06 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
> Take (elisp)Locales as an example.  The texinfo source contains:
> 
> @xref{Locales,,, libc, GNU Libc Manual}, for more information about
> locales and locale items.
> 
> With Info-hide-note-references set to t this gives:
> 
> See Locales for more information about locales and locale items.
> 
> "Locales" is the node we are looking at.

We could as well treat this as a case of unfortunate wording in the
ELisp manual.  The above sentence could be modified to solve the
problem at hand:

  The GNU C library manual (@pxref{Locales,,, libc, GNU Libc Manual})
  has more information about locales and locale items.

I notice in passing that a reference to a manual that might not be
installed at all, because it describes a library that is only used by
some platforms, might not be a good idea for purely didactic reasons:
suppose my system doesn't use glibc---how would I learn more about
Locales without the manual being available?

More generally, if the underlying C library is something other than
glibc, I might wonder whether the discussion in the glibc manual is at
all relevant to the treatment of locales I will see on my system.

So the offending sentence seems to be a rather singular case that, as
worded, is troubled to begin with.  We might as well not develop any
theories based on it.

Re: Changes to Texinfo DTD

[Luc Teirlinck]

Eli Zaretskii wrote:

   We could as well treat this as a case of unfortunate wording in the
   ELisp manual.  The above sentence could be modified to solve the
   problem at hand:

     The GNU C library manual (@pxref{Locales,,, libc, GNU Libc Manual})
     has more information about locales and locale items.

That would look terrible in the printed manual with a double nearly
identically worded reference to the GNU Libc manual, once outside
parentheses and once inside parentheses.  The reference in its present
form seems to come out OK in the printed manual, except that maybe
"@xref{Locales,,, libc, GNU Libc Manual}," should be replaced by:
"@xref{Locales,,, libc, The GNU Libc Manual},".  I believe the latter
would look better (in the printed manual).  Anyway, Juri's patch
would solve the problem I complained about.

   I notice in passing that a reference to a manual that might not be
   installed at all, because it describes a library that is only used by
   some platforms, might not be a good idea for purely didactic reasons:
   suppose my system doesn't use glibc---how would I learn more about
   Locales without the manual being available?

How would you learn about Locales without _any_ manual being
referenced?  Of course, the user needs to be alerted that the
reference leads to another manual that may or may not be available
and, if Juri's patch gets installed, they will be.  But why deprive
users that do have the manual installed of this information because
other users do not have the manual installed?  That manual is free
software.  People who do not have it installed can install it.  It is
good to inform them that it is available.

    More generally, if the underlying C library is something other than
    glibc, I might wonder whether the discussion in the glibc manual is at
    all relevant to the treatment of locales I will see on my system.

That manual pays considerable attention to portability.  So my best
guess is that it will be relevant.

Sincerely,

Luc.

Re: Changes to Texinfo DTD

[Eli Zaretskii]

> Date: Tue, 2 Dec 2003 19:47:30 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
>      The GNU C library manual (@pxref{Locales,,, libc, GNU Libc Manual})
>      has more information about locales and locale items.
> 
> That would look terrible in the printed manual with a double nearly
> identically worded reference to the GNU Libc manual, once outside
> parentheses and once inside parentheses.

That just means my wording should perhaps be improved further, or
maybe we should use @ifinfo and @ifnotinfo to make the text loog good
in both online and hard-copy version.

But I don't think the text I suggested will ``look terrible'', it will
just look a bit awkward.  It is my experience that Texinfo does that
quite a bit: it doesn't make it easy to write cross-references that
look good in all supported formats.  I think the reason for this is
that each format has its own rules for good style, and it isn't easy
to write text that will be compatible with all of them.

> How would you learn about Locales without _any_ manual being
> referenced?

We should first ask ourselves what is there for the user to learn
before she understands what the ELisp manual says in that section.
It's possible that the amount of additional info is small, in which
case we could simply put it into the ELisp manual.  It could also be
that the user doesn't need to know anything else to understand the
ELisp facilities enough to use them.

Do we know what information from the glibc manual is required reading
for the reader of the ELisp manual?

> But why deprive users that do have the manual installed of this
> information because other users do not have the manual installed?

If you mention the manual, the user might think that she must read it
because it contains some crucial information without which it is
impossible to understand the text in point.  I doubt that this is the
case.

>     More generally, if the underlying C library is something other than
>     glibc, I might wonder whether the discussion in the glibc manual is at
>     all relevant to the treatment of locales I will see on my system.
> 
> That manual pays considerable attention to portability.

Portability has nothing to do with this.  The glibc manual can
describe facilities provided only by glibc and not found anywhere
else.  The question is, again, what exactly we want the user to pick
up in the glibc manual.

Re: Changes to Texinfo DTD

[Luc Teirlinck]

   That just means my wording should perhaps be improved further, or
   maybe we should use @ifinfo and @ifnotinfo to make the text loog good
   in both online and hard-copy version.

It would be silly (and impossible) to try to manually rewrite all
references to other manuals in all currently existing .texi files this
way, when the xrefs contain enough information for an Info reader
(actually "makeinfo --xml" reader) to rewrite these sentences
_automatically_ the way you want them rewritten, without requiring any
changes in .texi files and, hence, without any danger of messing up
any other formats.  That was exactly what I proposed in the message
you reacted too.

If you want to do that though, you can not use the Info format.  In
fact, you can not use the Info format to correctly implement a value
of t for Info-hide-note-references.  I do not believe that the main
intent of the Info format ever was to "look cool".  If I understand
correctly, the main intent was that even Info readers with minimal
capabilities should be able to handle it.  That is not very compatible
with making things look "cool", "modern", "beautiful" or whatever you
want to call it.  For me Emacs info does not need to look "cool", it
needs to be easy and efficient to use, but for other people it is
extremely important that it looks as "cool" as possible.  OK with me,
but then it needs to use another format.

If we use XML, we can not only make these and other xrefs come out the
way you want them too, we can do so while filling correctly,
respecting all @*, @w, @verb and the like.  In addition to everything
else people wanted to use XML for in this thread.

Sincerely,

Luc.

Re: Changes to Texinfo DTD

[Eli Zaretskii]

> Date: Wed, 3 Dec 2003 20:53:15 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
> It would be silly (and impossible) to try to manually rewrite all
> references to other manuals in all currently existing .texi files this
> way

In general, I see nothing silly about making the manual look better.
More specifically, references to other manuals are relatively rare, to
the best of my memory.  And there's no need to rewrite all of them at
once: we could do that whenever we find a problem.

> when the xrefs contain enough information for an Info reader
> (actually "makeinfo --xml" reader) to rewrite these sentences
> _automatically_ the way you want them rewritten

As long as XML didn't replace the current Info format, this option is
a bit academic, IMHO.

Re: Changes to Texinfo DTD

[Luc Teirlinck]

Does anybody have any idea where we stand now with this thread and its
various relatives?  Is the following a reasonable summary?

1. The Info format is "here to stay".  It is intended for readers with
   minimal capabilities and it is important that people can access
   documentation via these readers.

2. Emacs is not a reader with minimal capabilities.  It could use XML
   to make Emacs info look as pretty as it can be, without paying a
   price in terms of functionality.

3. Oliver Scholz has a patch to allow the standalone reader to convert
   XML to Info format "on the fly", so people would only need to have
   the XML files installed to use both Emacs Info and standalone Info.
   Oliver's patch would add some "color" to standalone Info.  (Unless
   these colors would be very customizable, or maybe even if they are,
   please provide a command line option to disable this.  Not
   everybody can read yellow on white, cyan on white or red on black.)

4. Oliver is not volunteering to rewrite info.el to be able to use XML
   himself, although he has offered help, as explained in his earlier
   message.  (I do not know XML and am not volunteering either.)
   Would there be anybody feeling comfortable with this, assuming this
   is really what we wanted to do?
 
5. Emacs will still need to be able to handle .info files, if no XML
   file is available, but certainly if we produce XML files from the
   .texi files, that case becomes marginal enough that we should not
   waste a lot of energy trying to do the impossible by attempting to
   present .info files in "nicer" ways than theoretically possible.

Sincerely,

Luc.

Re: Changes to Texinfo DTD

[Eli Zaretskii]

> Date: Wed, 3 Dec 2003 20:54:45 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
> Does anybody have any idea where we stand now with this thread and its
> various relatives?

IMHO, to make this discussion useful, it needs to be conducted on a
Texinfo forum first and foremost.  This is mostly because the
following item:

> 3. Oliver Scholz has a patch to allow the standalone reader to convert
>    XML to Info format "on the fly", so people would only need to have
>    the XML files installed to use both Emacs Info and standalone Info.
>    Oliver's patch would add some "color" to standalone Info.  (Unless
>    these colors would be very customizable, or maybe even if they are,
>    please provide a command line option to disable this.  Not
>    everybody can read yellow on white, cyan on white or red on black.)

is related to the stand-alone reader, not to Emacs (for which no
equivalent changes are available).

Personally, I think that a move to XML is a good idea, but such a
transition would take a non-trivial period of time, during which we
will need to support installations where some or all of the manuals
are in Info format.

Re: Changes to Texinfo DTD

[Oliver Scholz]

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

>> Date: Wed, 3 Dec 2003 20:54:45 -0600 (CST)
>> From: Luc Teirlinck <teirllm@dms.auburn.edu>
[...]
> IMHO, to make this discussion useful, it needs to be conducted on a
> Texinfo forum first and foremost.  This is mostly because the
> following item:
>
>> 3. Oliver Scholz has a patch to allow the standalone reader to convert
>>    XML to Info format "on the fly", so people would only need to have
>>    the XML files installed to use both Emacs Info and standalone Info.
>>    Oliver's patch would add some "color" to standalone Info.  (Unless
>>    these colors would be very customizable, or maybe even if they are,
>>    please provide a command line option to disable this.  Not
>>    everybody can read yellow on white, cyan on white or red on black.)
>
> is related to the stand-alone reader, not to Emacs (for which no
> equivalent changes are available).
>
> Personally, I think that a move to XML is a good idea, but such a
> transition would take a non-trivial period of time, during which we
> will need to support installations where some or all of the manuals
> are in Info format.

Now that you mention it ... It is probably a better idea to implement
the feature in Emacs first. 

So people who want it can put XML files into their /usr/local/info
directories on their single-user machines and gain experiences with
it. If it works as advertised, then my proposed compatibility feature
could be added to standalone info afterwards. Maybe this is a more
sensible road-map.

[For testing this extensively, it would be nice if "makeinfo
my-texinfo-source.texi" would produce XML instead of info format,
dependend on the value of some environment variable. Most of my local
info files have been generated by makefiles.]

    Oliver
-- 
Oliver Scholz               14 Frimaire an 212 de la Révolution
Taunusstr. 25               Liberté, Egalité, Fraternité!
60329 Frankfurt a. M.       http://www.jungdemokratenhessen.de
Tel. (069) 97 40 99 42      http://www.jdjl.org

Re: Changes to Texinfo DTD

[Oliver Scholz]

Oliver Scholz <epameinondas@gmx.de> writes:

> Eli Zaretskii <eliz@elta.co.il> writes:
>
[...]
>> Personally, I think that a move to XML is a good idea, but such a
>> transition would take a non-trivial period of time, during which we
>> will need to support installations where some or all of the manuals
>> are in Info format.

In my previous message I forgot to add: I think you are right. Both
the standalone info and `C-h i' should check for each file whether it
is info XML or the current info format and DTRT.

Maybe they should never (i.e. not for a very, very long period of
time) cease to do so.  However efficient XML rendering may become, it
will take more space and more CPU cycles than the current info
format.  Some people still use i486 processors with 8 MB of
core. text/plain info will continue to be a good alternative on low
end machines.

> Now that you mention it ... It is probably a better idea to implement
> the feature in Emacs first. 
[...]


    Oliver
-- 
Oliver Scholz               14 Frimaire an 212 de la Révolution
Taunusstr. 25               Liberté, Egalité, Fraternité!
60329 Frankfurt a. M.       http://www.jungdemokratenhessen.de
Tel. (069) 97 40 99 42      http://www.jdjl.org

Re: Changes to Texinfo DTD

[Eli Zaretskii]

> From: Oliver Scholz <epameinondas@gmx.de>
> Date: Thu, 04 Dec 2003 10:39:27 +0100
> 
> Now that you mention it ... It is probably a better idea to implement
> the feature in Emacs first. 

It's certainly much easier, so I'm in full agreement with you here.

> [For testing this extensively, it would be nice if "makeinfo
> my-texinfo-source.texi" would produce XML instead of info format,
> dependend on the value of some environment variable. Most of my local
> info files have been generated by makefiles.]

One way to do that is to build a hacked version of makeinfo where XML
output is the default.  Then at least you can test this on your
machine(s) with minimal fuss.

Re: Changes to Texinfo DTD

[Oliver Scholz]

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

[...]
> 3. Oliver Scholz has a patch to allow the standalone reader to convert
>    XML to Info format "on the fly", so people would only need to have
>    the XML files installed to use both Emacs Info and standalone Info.
>    Oliver's patch would add some "color" to standalone Info.  (Unless
>    these colors would be very customizable, or maybe even if they are,
>    please provide a command line option to disable this.  Not
>    everybody can read yellow on white, cyan on white or red on black.)

More precisely: I have an incomplete patch that does this for a
specialised subset of HTML that I invented ad hoc for demonstrational
purposes. It could be extended to support nearly any
pointy-brackets format that's suitable. Thus it should be
straight-forward to make it work with info XML and I have offered to
do that.

> 4. Oliver is not volunteering to rewrite info.el to be able to use XML
>    himself
[...]

Not yet, at least. I do want to make some progress in my pet project
in the next few weeks and months ...

    Oliver
-- 
Oliver Scholz               14 Frimaire an 212 de la Révolution
Taunusstr. 25               Liberté, Egalité, Fraternité!
60329 Frankfurt a. M.       http://www.jungdemokratenhessen.de
Tel. (069) 97 40 99 42      http://www.jdjl.org

Re: Changes to Texinfo DTD

[Robert J. Chassell]

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

   1. The Info format is "here to stay".  It is intended for readers with
      minimal capabilities and it is important that people can access
      documentation via these readers.

Yes.  That is true, but understates Info capabilities:  Info is also,
at the moment, the single most efficient online help mechanism in
existance -- and has been for a generation.  Nic and my goal is to
improve HTML (via XML) to be as efficient or nearly as efficient as
Info was in the 1980s.

(Incidentally, Nic, I still cannot send messages to you via either
nferrier@tapsellferrier.co.uk or nferrier@80.168.156.73.  Please
suggest some other address.)


   2. Emacs is not a reader with minimal capabilities.  It could use XML
      to make Emacs info look as pretty as it can be, without paying a
      price in terms of functionality.

This is mixing the Info renderer with an XML renderer.  It makes more
sense to have them separate.  (It helps keep purposes clearer by
separating the notion of an `info' mechanism for rendering documents,
on line from the `info' format.)  Later, if people want to mix the
two, someone could write a wrapper so that the reader detects whether
the document is in XML format rather than Info format, and, if so,
switches to the XML renderer, or whether it is man page format and, if
so, switches to the man page renderer.

   5. Emacs will still need to be able to handle .info files, if no
      XML file is available, ...

Yes: we currently produce Info, XML, HTML, plain text, and DVI files
directly from the Texinfo files and indirectly PS and PDF and maybe
others.  Info needs to be kept.  Unfortunately, the HTML output does
not equal Info in efficiency.  As I said, Nic and my goal is to
improve it via XML.

(In this case rather than think of the XML output as a `surface
expression' of the Texinfo `deep representation', the XML serves as an
`intermediate representation'.  But clearly, if Emacs gains an XML
renderer, then the XML output from Texinfo acts a surface expression.)

(It is rather interesting to consider the historic transformation of
Emacs from an environment that displayed nearly everything `literally'
to one in which some buffer displays are not literal, but are surface
expressions of a different deep representation.  Nowadays, we even
have a `find-file-literally' command that was not necessary
initially.  But this is off-topic.)

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

Re: Changes to Texinfo DTD

[Richard Stallman]

    5. Emacs will still need to be able to handle .info files, if no XML
       file is available, but certainly if we produce XML files from the
       .texi files, that case becomes marginal enough that we should not
       waste a lot of energy trying to do the impossible by attempting to
       present .info files in "nicer" ways than theoretically possible.

It is conceivable that this situation will come to pass,
but we should not presume it unless/until it actually happens.

For the moment, Info format is important and is worth improving.

If it happens some day that use of XML makes Info format unimportant, we
can act accordingly.

Re: Changes to Texinfo DTD

[Kim F. Storm]

>     5. Emacs will still need to be able to handle .info files, if no XML
>        file is available, but certainly if we produce XML files from the
>        .texi files, that case becomes marginal enough that we should not
>        waste a lot of energy trying to do the impossible by attempting to
>        present .info files in "nicer" ways than theoretically possible.

In practice, you could also go another route -- and let makeinfo
produce two files, a .info and a .markup file.  The .info file will be
identical to what we have today, while the .markup file will contain a
simple list of "tagging info" for the .info file, which reflects what
@-commands were used to produce each part of the .info file.

something like

@code 341 345
@xref 359 371 378 389    (list each section in the *Note .... output)
@* 459
@page 1033

etc.

i.e. something which a reader (like emacs' info reader) can use
more or less directly to propertize the .info file.


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

Re: Changes to Texinfo DTD

[Alfred M. Szmidt]

   >     5. Emacs will still need to be able to handle .info files, if
   >        no XML file is available, but certainly if we produce XML
   >        files from the .texi files, that case becomes marginal
   >        enough that we should not waste a lot of energy trying to
   >        do the impossible by attempting to present .info files in
   >        "nicer" ways than theoretically possible.

   In practice, you could also go another route -- and let makeinfo
   produce two files, a .info and a .markup file.  The .info file will
   be identical to what we have today, while the .markup file will
   contain a simple list of "tagging info" for the .info file, which
   reflects what @-commands were used to produce each part of the
   .info file.

If going that route, don't make it a seperate file.  Instead make it
something similar to the "tag table" which exists in info files
already; and call it "markup table". 

Cheers.

Re: Changes to Texinfo DTD

[Eli Zaretskii]

> Date: Sat, 6 Dec 2003 17:11:20 +0100 (MET)
> From: "Alfred M. Szmidt" <ams@kemisten.nu>
> 
>    In practice, you could also go another route -- and let makeinfo
>    produce two files, a .info and a .markup file.  The .info file will
>    be identical to what we have today, while the .markup file will
>    contain a simple list of "tagging info" for the .info file, which
>    reflects what @-commands were used to produce each part of the
>    .info file.
> 
> If going that route, don't make it a seperate file.  Instead make it
> something similar to the "tag table" which exists in info files
> already; and call it "markup table". 

But that would break old versions of the standalone reader, right?
The whole point of Kim's suggestion was to make a change that cannot
possibly break old versions of Info.

Re: Changes to Texinfo DTD

[Alfred M. Szmidt]

   > If going that route, don't make it a seperate file.  Instead make
   > it something similar to the "tag table" which exists in info
   > files already; and call it "markup table".

   But that would break old versions of the standalone reader, right?

I don't think that they should break the standalone read, but I am not
that familiar with the info format.  But I don't think that it should
break anything.


Cheers.

Re: Changes to Texinfo DTD

[Eli Zaretskii]

> Date: Tue, 9 Dec 2003 17:47:43 +0100 (MET)
> From: "Alfred M. Szmidt" <ams@kemisten.nu>
> 
>    > If going that route, don't make it a seperate file.  Instead make
>    > it something similar to the "tag table" which exists in info
>    > files already; and call it "markup table".
> 
>    But that would break old versions of the standalone reader, right?
> 
> I don't think that they should break the standalone read, but I am not
> that familiar with the info format.

I think it will break the standalone reader.  The way the code that
reads the tag tables is written is not very robust to changes in that
part of the Info file.

Re: Changes to Texinfo DTD

[Luc Teirlinck]

Eli Zaretskii wrote:

   Do we know what information from the glibc manual is required reading
   for the reader of the ELisp manual?

None.  Some readers _might_ need to know more about locales (hence the
reference), but the _reason_ they would need that knowledge would
definitely not be to understand the Elisp manual.  The same is (or so
I believe) true for all external references in the Elisp manual,
except references to the Emacs manual.  The Emacs manual is a
prerequisite to understanding the Elisp manual, other manuals are not.

Note that this is one more reason why, if a reference refers to another
manual, the reader needs to know that and needs to know which manual.

   If you mention the manual, the user might think that she must read it
   because it contains some crucial information without which it is
   impossible to understand the text in point.  I doubt that this is the
   case.

As I already said, it indeed is not the case.

But (elisp)Locales says as the very last sentence of the note and of
the chapter:

*Note Locales: (libc)Locales, for more information about locales and
locale items.

It says: "for more information", it does not say: "If you want to
understand anything of what you just read".

   Portability has nothing to do with this.

Portability has a lot to do with this.  This is the Elisp manual, not
the Emacs manual.  The author may want his code to not just work, as
efficiently as possible, for his computer and for his locale, but for
other people's as well.

   The question is, again, what exactly we want the user to pick up in
   the glibc manual.

Whichever information the reader happens to need.  The reference means:
If you need to know something we did not tell you above, here is a
reasonable place to search for that information.

Sincerely,

Luc.

Re: Changes to Texinfo DTD

[Eli Zaretskii]

> Date: Wed, 3 Dec 2003 21:35:56 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
>    Do we know what information from the glibc manual is required reading
>    for the reader of the ELisp manual?
> 
> None.  Some readers _might_ need to know more about locales (hence the
> reference), but the _reason_ they would need that knowledge would
> definitely not be to understand the Elisp manual.

In that case, we should consider removing the xref or maybe
rewording it so that its importance is minimized.

> Note that this is one more reason why, if a reference refers to another
> manual, the reader needs to know that and needs to know which manual.

I don't need to note this, since I agreed with you in the first place:
that's why I suggested to change the wording to make this point clear.

> But (elisp)Locales says as the very last sentence of the note and of
> the chapter:
> 
> *Note Locales: (libc)Locales, for more information about locales and
> locale items.
> 
> It says: "for more information", it does not say: "If you want to
> understand anything of what you just read".

"@xref{Something}, for more information" is a standard wording, we
use it for many references that are quite important.

>    Portability has nothing to do with this.
> 
> Portability has a lot to do with this.  This is the Elisp manual, not
> the Emacs manual.  The author may want his code to not just work, as
> efficiently as possible, for his computer and for his locale, but for
> other people's as well.

In that case, we should provide information (or a pointer to a source
of such information) that describes the locale issue in a manner that
is independent of any particular implementation.  The glibc manual is
an unlikely place to find such a description, as the glibc
implementation of locale-specific stuff differs in many aspects from
other implementations.

>    The question is, again, what exactly we want the user to pick up in
>    the glibc manual.
> 
> Whichever information the reader happens to need.  The reference means:
> If you need to know something we did not tell you above, here is a
> reasonable place to search for that information.

See above: when we say "see elsewhere for more info", we normally
invite the user to actually go there.

Re: Changes to Texinfo DTD

[Stefan Monnier]

> 1. use a command line XSLT processor (such as xsltproc, part of
>    GNOME's libxsl project) to turn the XML into plain text (or
>    specifically marked up text). 

The original reason for discussing such things is that the Info format
has serious limitations w.r.t. additional markup.

"Markup" in this context in the Emacs viewer means "text-properties"
or "overlays", neither of which can be provided directly from a process's
output, so it would just bring us back to square one: which text
representation top use for the markup (either HTML-like or
ANSI-escape-sequences-like, or something else).

I'm not necessarily opposed to using an external tool, but it won't solve
the problem at hand.


        Stefan

Re: Changes to Texinfo DTD

[Nic Ferrier]

Stefan Monnier <monnier@IRO.UMontreal.CA> writes:

> > 1. use a command line XSLT processor (such as xsltproc, part of
> >    GNOME's libxsl project) to turn the XML into plain text (or
> >    specifically marked up text). 
> 
> The original reason for discussing such things is that the Info format
> has serious limitations w.r.t. additional markup.
> 
> "Markup" in this context in the Emacs viewer means "text-properties"
> or "overlays", neither of which can be provided directly from a process's
> output, so it would just bring us back to square one: which text
> representation top use for the markup (either HTML-like or
> ANSI-escape-sequences-like, or something else).
> 
> I'm not necessarily opposed to using an external tool, but it won't solve
> the problem at hand.

I thought I remembered that you could generate saved files with
embedded text properties (they're lisp expressions aren't they?)


Nic

Re: Changes to Texinfo DTD

[Oliver Scholz]

Nic Ferrier <nferrier@tapsellferrier.co.uk> writes:

> Stefan Monnier <monnier@IRO.UMontreal.CA> writes:
>
>> > 1. use a command line XSLT processor (such as xsltproc, part of
>> >    GNOME's libxsl project) to turn the XML into plain text (or
>> >    specifically marked up text). 
>> 
>> The original reason for discussing such things is that the Info format
>> has serious limitations w.r.t. additional markup.
>> 
>> "Markup" in this context in the Emacs viewer means "text-properties"
>> or "overlays", neither of which can be provided directly from a process's
>> output, so it would just bring us back to square one: which text
>> representation top use for the markup (either HTML-like or
>> ANSI-escape-sequences-like, or something else).
>> 
>> I'm not necessarily opposed to using an external tool, but it won't solve
>> the problem at hand.
>
> I thought I remembered that you could generate saved files with
> embedded text properties (they're lisp expressions aren't they?)

Well, the canonical way to save embedded text properties is with M-x
enriched-mode. Or otherwise with the framework provided by format.el
or with (info "(elisp)Saving Properties"). This is technically what I
proposed for Emacs.

But yes, there is a print and read syntax for strings with text
properties: 

(let ((str "#(\"Lirum larum.\" 0 12 
	     (fontified t font-lock-face (variable-pitch :foreground \"Blue\")))"))
  (insert (car (read-from-string str))))

So if it is possible to generate this with XSLT it could be done with
XSLT only. Mostly, at least.

[I'd just like to point out that improving the info file format and
serving info files over the web are two orthogonal issues. It might
be good two use two different approaches to these different goals.
However, if it is feasible to have the same technical solution for
both, then this is fine for me and I'll shut up.]

    Oliver
-- 
Oliver Scholz               3 Frimaire an 212 de la Révolution
Taunusstr. 25               Liberté, Egalité, Fraternité!
60329 Frankfurt a. M.       http://www.jungdemokratenhessen.de
Tel. (069) 97 40 99 42      http://www.jdjl.org

Re: Changes to Texinfo DTD

[Nic Ferrier]

Oliver Scholz <epameinondas@gmx.de> writes:

> [I'd just like to point out that improving the info file format and
> serving info files over the web are two orthogonal issues. It might
> be good two use two different approaches to these different goals.
> However, if it is feasible to have the same technical solution for
> both, then this is fine for me and I'll shut up.]

Absolutely. Bob and I have aimed to solve the web problem, not
improve info in anyway.


Personally, I don't think Info is broken. I use it a lot in
preference to web based tools.


Nic

Re: Changes to Texinfo DTD

[Richard Stallman]

    1. use a command line XSLT processor (such as xsltproc, part of
       GNOME's libxsl project) to turn the XML into plain text (or
       specifically marked up text). 

That's much better than making Emacs link with an additional library.

    2. write an XSLT processor in Emacs Lisp. This wouldn't be as
       difficult as it sounds and I'm not sure it isn't done already (by
       one of the various XML/Emacs projects going on).

If someone wants to do it, and it gives good performance, it's an
ok solution.

Re: Changes to Texinfo DTD

[Karl Eichwalder]

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

> Third, ... I don't know whether this is readily possible, but it looks
> to me to be a good idea ...  you could add a standalone XML renderer
> to Mozilla and related browsers.

yelp, the GNOME help browser, works directly with XML files conforming
to a DocBook subset - it starts a little bit slow, be warned.

-- 
                                                         |      ,__o
                                                         |    _-\_<,
http://www.gnu.franken.de/ke/                            |   (*)/'(*)

Re: Changes to Texinfo DTD

[Richard Stallman]

    My proposal is to keep the current text/plain info format as an
    internal representation in the standalone info reader. 

    The reader would then check whether a particular file is in the
    text/plain info format or in the XML format. If the former: business
    as usual. If the latter, it would convert this XML to plain/text with
    the necessary

If this method can be implemented in both the standalone reader and Emacs,
and runs fast enough, then I see no objection.

Re: HTML as info format

[Eli Zaretskii]

[I have no idea why mailman sent me this message from 2 weeks ago.]
> From: Juri Linkov <juri@jurta.org>
> Date: Mon, 17 Nov 2003 15:29:54 +0200
> 
> Current Info format can't make a link to another part of the same
> Info node.

I think you miss the @anchor directive, introduced in Texinfo 4.x.

> The same problem appears in the Glossary node of the Emacs manual,
> where links to the same node are marked by the "(q.v.)".

Arguably, we could modify the Glossary by using anchors in the online
formats.

> There are other problems with the current Info format.  For example,
> currently there is no way to hide the address part of the link without
> corrupting the paragraph formatting.

IMHO, the current way to hide the address of the link is still
experimental and needs further work.

> After hiding the address part of
> the link lines become either too short or too long.  For example, lines:
> 
>    See *Note Customizing Indentation: (ccmode)Customizing Indentation, for
> more information on customizing indentation for C and related modes,
> 
> in Info the first line becomes too short:
> 
>    See Customizing Indentation for
> more information on customizing indentation for C and related modes,

Doing this in some other way, like physically erasing the text we now
hide and then re-filling the paragraph, would solve this.  In any
case, this problem is not relevant to Info format per se, it is due to
the way the Emacs Info reader renders an Info document.

Info enhancements

[Juri Linkov]

I would like to submit a patch that fixes some problems in the Emacs
Info reader and adds features most web browsers already have.
This patch don't change the existing Info file format.  It improves
usability of the Emacs Info reader with the current Info file format.
Any comments are welcome.

New features:

- distinguish visited nodes from unvisited by displaying their
  references in a different color.  Standard colors of web browsers
  are used: blue - for unvisited links, magenta - for visited links.

- show full history list or tree of visited Info nodes.  This list is
  displayed in the Info buffer using "*Note" references, so standard
  Info functions can be used for navigation to visited nodes from the
  history buffer.

- http links are fontified and available for navigation by calling the
  `browse-url' function.

- a new argument `fork' is added to Info-follow-reference,
  Info-follow-nearest-node and Info-try-follow-nearest-node functions,
  so if these functions are called interactively with a prefix arg,
  they show the node in a new info buffer.  This feature is copied
  from the `Info-menu' which works only for menu items.  But this is
  useful for references too, especially for references that carry out
  of the current manual.

- use reference names to move point to the place within the current
  node where reference name is defined.  For example, by following the
  reference "*Note file-coding-system-alist: Default Coding Systems,"
  Info finds a node with the name "Default Coding Systems" and moves
  point to the line where reference name "file-coding-system-alist" is
  defined.  This feature uses the function `Info-find-index-name' that
  currently works only for the function `Info-index'.  Now it works
  also for index items and cross references.  This feature solves
  problems in the Glossary node of the Emacs manual, where links to
  the same node are marked by the "(q.v.)" or "See `text'".  Such text
  can be replaced in references to the same node with this text as a
  reference name.  For example, the text "is shared by an indirect
  buffer (q.v.@:)" can be replaced with "is shared by an
  @ref{Glossary,indirect buffer}", and text "See `filling.'" can be
  replaced with "@xref{Glossary,filling}.".  Following such a
  reference will move point to the place in the same node where this
  glossary term is defined.

- rebind `M-s' key to a new function `Info-search-next' that searches
  for another occurrence of regular expression from a previous
  `Info-search' command (key `s').  Pressing only one key to repeat
  a search is more convenient than pressing two keys (`s RET').

Fixed problems:

- don't hide the newline (with following whitespace) in references when
  Info-hide-note-references is t.  This fixes the problem where hidden
  newlines cause too long (and truncated) lines.

- don't hide the name of external Info file in references in case
  when Info-hide-note-references is t and references lead outside
  the current Info file.  It's important for user to know about
  such situation.

- don't insert the text "See" instead of "Note" because inserting a
  new text in Info buffer breaks the stored point positions. This bug
  can be observed by calling `Info-last', `Info-search' where point is
  moved with some offset to its correct position (the offset is the sum
  of lengths of strings "See" inserted in the buffer above the point).

- add a character ` to the list of prefix characters used to escape
  the literal meaning of the text "*Note".  The wrong fontification
  caused by this bug can be observed in (info "(info)Cross-refs").

Index: emacs/lisp/info.el
===================================================================
RCS file: /cvsroot/emacs/emacs/lisp/info.el,v
retrieving revision 1.374
diff -c -r1.374 info.el
*** emacs/lisp/info.el	 7 Oct 2003 00:04:45 -0000	1.374
--- emacs/lisp/info.el	 1 Dec 2003 11:48:03 -0000
***************
*** 48,53 ****
--- 48,60 ----
    "List of info nodes user has visited.
  Each element of list is a list (FILENAME NODENAME BUFFERPOS).")
  
+ (defvar Info-history-tree nil
+   "Tree of info nodes user has visited.
+ Each element of list is a list (FILENAME NODENAME PARENT-INDEX).")
+ 
+ (defvar Info-history-node -1
+   "Position of the current node on the info nodes tree user has visited.")
+ 
  (defcustom Info-enable-edit nil
    "*Non-nil means the \\<Info-mode-map>\\[Info-edit] command in Info can edit the current node.
  This is convenient if you want to write info files by hand.
***************
*** 76,87 ****
    :group 'info)
  
  (defface info-xref
!   '((((class color) (background light)) (:foreground "magenta4" :weight bold))
!     (((class color) (background dark)) (:foreground "cyan" :weight bold))
!     (t (:weight bold)))
    "Face for Info cross-references."
    :group 'info)
  
  (defcustom Info-fontify-maximum-menu-size 100000
    "*Maximum size of menu to fontify if `font-lock-mode' is non-nil."
    :type 'integer
--- 83,107 ----
    :group 'info)
  
  (defface info-xref
!   '((((class color) (background light)) (:foreground "blue"))
!     (((class color) (background dark)) (:foreground "cyan"))
!     (t (:underline t)))
    "Face for Info cross-references."
    :group 'info)
  
+ (defface info-xref-visited
+   '((((class color) (background light)) (:foreground "magenta4"))
+     (((class color) (background dark)) (:foreground "magenta4"))
+     (t (:underline t)))
+   "Face for visited Info cross-references."
+   :group 'info)
+ 
+ (defcustom Info-visited-nodes t
+   "*Non-nil means to fontify visited nodes in a different color."
+   :version "21.4"
+   :type 'boolean
+   :group 'info)
+ 
  (defcustom Info-fontify-maximum-menu-size 100000
    "*Maximum size of menu to fontify if `font-lock-mode' is non-nil."
    :type 'integer
***************
*** 155,161 ****
  
  (defcustom Info-hide-note-references t
    "*If non-nil, hide the tag and section reference in *note and * menu items.
- Also replaces the \"*note\" text with \"see\".
  If value is non-nil but not t, the reference section is still shown."
    :version "21.4"
    :type '(choice (const :tag "No reformatting" nil)
--- 175,180 ----
***************
*** 205,210 ****
--- 224,232 ----
  (defvar Info-index-alternatives nil
    "List of possible matches for last `Info-index' command.")
  
+ (defvar Info-reference-name nil
+   "Name of the current reference.")
+ 
  (defvar Info-standalone nil
    "Non-nil if Emacs was started solely as an Info browser.")
  \f
***************
*** 787,793 ****
  		       nodename)))
  
  	    (Info-select-node)
! 	    (goto-char (or anchorpos (point-min))))))
      ;; If we did not finish finding the specified node,
      ;; go back to the previous one.
      (or Info-current-node no-going-back (null Info-history)
--- 809,820 ----
  		       nodename)))
  
  	    (Info-select-node)
! 	    (goto-char (or anchorpos (point-min)))
! 
!             ;; Move point to the place where the referer name points to
!             (when Info-reference-name
!               (Info-find-index-name Info-reference-name)
!               (setq Info-reference-name nil)))))
      ;; If we did not finish finding the specified node,
      ;; go back to the previous one.
      (or Info-current-node no-going-back (null Info-history)
***************
*** 1176,1181 ****
--- 1203,1225 ----
  	(if Info-enable-active-nodes (eval active-expression))
  	(Info-fontify-node)
  	(Info-display-images-node)
+ 
+         ;; Add a new history node or use old node from the history tree
+         (let ((tree Info-history-tree)
+               (i 0) res)
+           (while tree
+             (if (and (equal (nth 0 (car tree)) Info-current-file)
+                      (equal (nth 1 (car tree)) Info-current-node))
+                 (setq res i tree nil))
+             (setq tree (cdr tree) i (1+ i)))
+           (if res
+               (setq Info-history-node res)
+             (setq Info-history-tree
+                   (nconc Info-history-tree
+                          (list (list Info-current-file Info-current-node
+                                      Info-history-node)))
+                   Info-history-node (1- (length Info-history-tree)))))
+ 
  	(run-hooks 'Info-selection-hook)))))
  
  (defun Info-set-mode-line ()
***************
*** 1207,1212 ****
--- 1251,1258 ----
    (if fork
        (set-buffer
         (clone-buffer (concat "*info-" (if (stringp fork) fork nodename) "*") t)))
+   (if (equal (buffer-name) "*info-history*")
+       (switch-to-buffer "*info*"))
    (let (filename)
      (string-match "\\s *\\((\\s *\\([^\t)]*\\)\\s *)\\s *\\|\\)\\(.*\\)"
  		  nodename)
***************
*** 1409,1414 ****
--- 1455,1468 ----
  	       (equal ofile Info-current-file))
  	  (setq Info-history (cons (list ofile onode opoint)
  				   Info-history))))))
+ 
+ (defun Info-search-next ()
+   "Search for next regexp from a previous `Info-search' command."
+   (interactive)
+   (if Info-search-history
+       (Info-search (car Info-search-history))
+     ;; If no history then read search string in Info-search
+     (call-interactively 'Info-search)))
  \f
  (defun Info-extract-pointer (name &optional errorname)
    "Extract the value of the node-pointer named NAME.
***************
*** 1481,1495 ****
      (setq Info-history (cdr Info-history))
      (goto-char opoint)))
  
  ;;;###autoload
  (defun Info-directory ()
    "Go to the Info directory node."
    (interactive)
    (Info-find-node "dir" "top"))
  \f
! (defun Info-follow-reference (footnotename)
    "Follow cross reference named FOOTNOTENAME to the node it refers to.
! FOOTNOTENAME may be an abbreviation of the reference name."
    (interactive
     (let ((completion-ignore-case t)
  	 (case-fold-search t)
--- 1535,1594 ----
      (setq Info-history (cdr Info-history))
      (goto-char opoint)))
  
+ ;;;###autoload (add-hook 'same-window-buffer-names "*info-history*")
+ 
+ (defun Info-history-buffer (&optional tree-p)
+   "Create the buffer *info-history* with references to visited nodes.
+ Optional argument TREE-P creates a tree of nodes; the default
+ creates the plain list of nodes."
+   (interactive "P")
+   (let ((curr-node Info-history-node)
+         p)
+     (pop-to-buffer
+      (with-current-buffer (get-buffer-create "*info-history*")
+        (let ((Info-hide-note-references t)
+              (Info-visited-nodes t)
+              (inhibit-read-only t))
+          (erase-buffer)
+          (goto-char (point-min))
+          (setq p (Info-insert-history-tree -1 0 (or curr-node 0) tree-p))
+          (if (not (bobp)) (Info-fontify-node))
+          (or (eq major-mode 'Info-mode) (Info-mode))
+          (let ((Info-current-file "history")
+                (Info-current-node "History"))
+            (Info-set-mode-line))
+          (current-buffer))))
+     (goto-char (or p (point-min)))))
+ 
+ (defun Info-insert-history-tree (index indent curr-node tree-p)
+   "Insert the tree or list of references to visited nodes.
+ Return the position of the current node on the generated tree."
+   (let ((tree Info-history-tree)
+         (i 0) p)
+     (while tree
+       (when (or (null tree-p) (eq (nth 2 (car tree)) index))
+         (if tree-p (insert (make-string indent ?\040)))
+         (if (eq i curr-node) (setq p (point)))
+         (insert  "*Note " (nth 1 (car tree)) ": ("
+                  (file-name-nondirectory (nth 0 (car tree)))
+                  ")" (nth 1 (car tree)) ".\n")
+         (if tree-p (setq p (or (Info-insert-history-tree
+                                 i (1+ indent) curr-node tree-p) p))))
+       (setq tree (cdr tree) i (1+ i)))
+     p))
+ 
  ;;;###autoload
  (defun Info-directory ()
    "Go to the Info directory node."
    (interactive)
    (Info-find-node "dir" "top"))
  \f
! (defun Info-follow-reference (footnotename &optional fork)
    "Follow cross reference named FOOTNOTENAME to the node it refers to.
! FOOTNOTENAME may be an abbreviation of the reference name.
! If FORK is non-nil (interactively with a prefix arg), show the node in
! a new info buffer.  If FORK is a string, it is the name to use for the
! new buffer."
    (interactive
     (let ((completion-ignore-case t)
  	 (case-fold-search t)
***************
*** 1539,1545 ****
  					 "Follow reference named: ")
  				       completions nil t)))
  	   (list (if (equal input "")
! 		     default input)))
         (error "No cross-references in this node"))))
  
    (unless footnotename
--- 1638,1644 ----
  					 "Follow reference named: ")
  				       completions nil t)))
  	   (list (if (equal input "")
! 		     default input) current-prefix-arg))
         (error "No cross-references in this node"))))
  
    (unless footnotename
***************
*** 1561,1567 ****
        (setq target (concat (substring target 0 i) " "
  			   (substring target (match-end 0))))
        (setq i (+ i 1)))
!     (Info-goto-node target)))
  
  (defconst Info-menu-entry-name-re "\\(?:[^:]\\|:[^:,.;() \t\n]\\)*"
    ;; We allow newline because this is also used in Info-follow-reference,
--- 1660,1666 ----
        (setq target (concat (substring target 0 i) " "
  			   (substring target (match-end 0))))
        (setq i (+ i 1)))
!     (Info-goto-node target fork)))
  
  (defconst Info-menu-entry-name-re "\\(?:[^:]\\|:[^:,.;() \t\n]\\)*"
    ;; We allow newline because this is also used in Info-follow-reference,
***************
*** 1968,1974 ****
  (defun Info-next-reference (&optional recur)
    "Move cursor to the next cross-reference or menu item in the node."
    (interactive)
!   (let ((pat "\\*note[ \n\t]*\\([^:]*\\):\\|^\\* .*:")
  	(old-pt (point))
  	(case-fold-search t))
      (or (eobp) (forward-char 1))
--- 2067,2073 ----
  (defun Info-next-reference (&optional recur)
    "Move cursor to the next cross-reference or menu item in the node."
    (interactive)
!   (let ((pat "\\*note[ \n\t]*\\([^:]*\\):\\|^\\* .*:\\|http://")
  	(old-pt (point))
  	(case-fold-search t))
      (or (eobp) (forward-char 1))
***************
*** 1988,1994 ****
  (defun Info-prev-reference (&optional recur)
    "Move cursor to the previous cross-reference or menu item in the node."
    (interactive)
!   (let ((pat "\\*note[ \n\t]*\\([^:]*\\):\\|^\\* .*:")
  	(old-pt (point))
  	(case-fold-search t))
      (or (re-search-backward pat nil t)
--- 2087,2093 ----
  (defun Info-prev-reference (&optional recur)
    "Move cursor to the previous cross-reference or menu item in the node."
    (interactive)
!   (let ((pat "\\*note[ \n\t]*\\([^:]*\\):\\|^\\* .*:\\|http://")
  	(old-pt (point))
  	(case-fold-search t))
      (or (re-search-backward pat nil t)
***************
*** 2209,2220 ****
         (save-excursion (forward-line 1) (eobp))
         (Info-next-preorder)))
  
! (defun Info-follow-nearest-node ()
    "Follow a node reference near point.
  If point is on a reference, follow that reference.  Otherwise,
  if point is in a menu item description, follow that menu item."
!   (interactive)
!   (or (Info-try-follow-nearest-node)
        (when (save-excursion
  	      (search-backward "\n* menu:" nil t))
  	(save-excursion
--- 2308,2319 ----
         (save-excursion (forward-line 1) (eobp))
         (Info-next-preorder)))
  
! (defun Info-follow-nearest-node (&optional fork)
    "Follow a node reference near point.
  If point is on a reference, follow that reference.  Otherwise,
  if point is in a menu item description, follow that menu item."
!   (interactive "P")
!   (or (Info-try-follow-nearest-node fork)
        (when (save-excursion
  	      (search-backward "\n* menu:" nil t))
  	(save-excursion
***************
*** 2223,2257 ****
  	    (beginning-of-line 0))
  	  (when (looking-at "\\* +\\([^\t\n]*\\):")
  	    (Info-goto-node
! 	     (Info-extract-menu-item (match-string-no-properties 1)))
  	    t)))
        (error "Point neither on reference nor in menu item description")))
  
  ;; Common subroutine.
! (defun Info-try-follow-nearest-node ()
    "Follow a node reference near point.  Return non-nil if successful."
    (let (node)
      (cond
       ((setq node (Info-get-token (point) "\\*note[ \n]"
  				 "\\*note[ \n]\\([^:]*\\):"))
!       (Info-follow-reference node))
       ;; menu item: node name
       ((setq node (Info-get-token (point) "\\* +" "\\* +\\([^:]*\\)::"))
!       (Info-goto-node node))
       ;; menu item: index entry
       ((Info-get-token (point) "\\* +" "\\* +\\(.*\\): ")
        (beginning-of-line)
        (forward-char 2)
        (setq node (Info-extract-menu-node-name))
!       (Info-goto-node node))
       ((setq node (Info-get-token (point) "Up: " "Up: \\([^,\n\t]*\\)"))
!       (Info-goto-node node))
       ((setq node (Info-get-token (point) "Next: " "Next: \\([^,\n\t]*\\)"))
!       (Info-goto-node node))
       ((setq node (Info-get-token (point) "File: " "File: \\([^,\n\t]*\\)"))
!       (Info-goto-node "Top"))
       ((setq node (Info-get-token (point) "Prev: " "Prev: \\([^,\n\t]*\\)"))
!       (Info-goto-node node)))
      node))
  \f
  (defvar Info-mode-map nil
--- 2322,2363 ----
  	    (beginning-of-line 0))
  	  (when (looking-at "\\* +\\([^\t\n]*\\):")
  	    (Info-goto-node
! 	     (Info-extract-menu-item (match-string-no-properties 1)) fork)
  	    t)))
        (error "Point neither on reference nor in menu item description")))
  
  ;; Common subroutine.
! (defun Info-try-follow-nearest-node (&optional fork)
    "Follow a node reference near point.  Return non-nil if successful."
    (let (node)
      (cond
+      ((and (Info-get-token (point) "http://" "\\(http://\\)")
+            (or (featurep 'browse-url) (require 'browse-url nil t)))
+       (setq node t)
+       (browse-url (browse-url-url-at-point)))
       ((setq node (Info-get-token (point) "\\*note[ \n]"
  				 "\\*note[ \n]\\([^:]*\\):"))
!       (setq Info-reference-name (replace-regexp-in-string
!                                  "[ \t\n]+" " " (match-string-no-properties 1)))
!       (Info-follow-reference node fork))
       ;; menu item: node name
       ((setq node (Info-get-token (point) "\\* +" "\\* +\\([^:]*\\)::"))
!       (Info-goto-node node fork))
       ;; menu item: index entry
       ((Info-get-token (point) "\\* +" "\\* +\\(.*\\): ")
+       (setq Info-reference-name (match-string-no-properties 1))
        (beginning-of-line)
        (forward-char 2)
        (setq node (Info-extract-menu-node-name))
!       (Info-goto-node node fork))
       ((setq node (Info-get-token (point) "Up: " "Up: \\([^,\n\t]*\\)"))
!       (Info-goto-node node fork))
       ((setq node (Info-get-token (point) "Next: " "Next: \\([^,\n\t]*\\)"))
!       (Info-goto-node node fork))
       ((setq node (Info-get-token (point) "File: " "File: \\([^,\n\t]*\\)"))
!       (Info-goto-node "Top" fork))
       ((setq node (Info-get-token (point) "Prev: " "Prev: \\([^,\n\t]*\\)"))
!       (Info-goto-node node fork)))
      node))
  \f
  (defvar Info-mode-map nil
***************
*** 2295,2306 ****
    (define-key Info-mode-map "p" 'Info-prev)
    (define-key Info-mode-map "q" 'Info-exit)
    (define-key Info-mode-map "s" 'Info-search)
!   ;; For consistency with Rmail.
!   (define-key Info-mode-map "\M-s" 'Info-search)
    (define-key Info-mode-map "\M-n" 'clone-buffer)
    (define-key Info-mode-map "t" 'Info-top-node)
    (define-key Info-mode-map "u" 'Info-up)
    (define-key Info-mode-map "," 'Info-index-next)
    (define-key Info-mode-map "\177" 'Info-scroll-down)
    (define-key Info-mode-map [mouse-2] 'Info-mouse-follow-nearest-node)
    )
--- 2401,2412 ----
    (define-key Info-mode-map "p" 'Info-prev)
    (define-key Info-mode-map "q" 'Info-exit)
    (define-key Info-mode-map "s" 'Info-search)
!   (define-key Info-mode-map "\M-s" 'Info-search-next)
    (define-key Info-mode-map "\M-n" 'clone-buffer)
    (define-key Info-mode-map "t" 'Info-top-node)
    (define-key Info-mode-map "u" 'Info-up)
    (define-key Info-mode-map "," 'Info-index-next)
+   (define-key Info-mode-map "\\" 'Info-history-buffer)
    (define-key Info-mode-map "\177" 'Info-scroll-down)
    (define-key Info-mode-map [mouse-2] 'Info-mouse-follow-nearest-node)
    )
***************
*** 2335,2344 ****
     ("Reference" ["You should never see this" report-emacs-bug t])
     ["Search..." Info-search
      :help "Search for regular expression in this Info file"]
     ["Go to Node..." Info-goto-node
      :help "Go to a named node"]
!    ["Last" Info-last :active Info-history
      :help "Go to the last node you were at"]
     ("Index..."
      ["Lookup a String" Info-index
       :help "Look for a string in the index items"]
--- 2441,2454 ----
     ("Reference" ["You should never see this" report-emacs-bug t])
     ["Search..." Info-search
      :help "Search for regular expression in this Info file"]
+    ["Search Next" Info-search-next
+     :help "Search for another occurrence of regular expression"]
     ["Go to Node..." Info-goto-node
      :help "Go to a named node"]
!    ["Last (Back)" Info-last :active Info-history
      :help "Go to the last node you were at"]
+    ["History" Info-history-buffer :active Info-history-tree
+     :help "Go to the history buffer"]
     ("Index..."
      ["Lookup a String" Info-index
       :help "Look for a string in the index items"]
***************
*** 2476,2481 ****
--- 2586,2592 ----
  \\[Info-directory]	Go to the Info directory node.
  \\[Info-follow-reference]	Follow a cross reference.  Reads name of reference.
  \\[Info-last]	Move to the last node you were at.
+ \\[Info-history-buffer]	Go to the history buffer.
  \\[Info-index]	Look up a topic in this file's Index and move to that node.
  \\[Info-index-next]	(comma) Move to the next match from a previous `i' command.
  \\[Info-top-node]	Go to the Top node of this file.
***************
*** 2504,2509 ****
--- 2615,2622 ----
  \\[universal-argument] \\[info]	Move to new Info file with completion.
  \\[Info-search]	Search through this Info file for specified regexp,
  	  and select the node in which the next occurrence is found.
+ \\[Info-search-next]	Search for another occurrence of regexp
+ 	  from a previous `Info-search' command.
  \\[Info-next-reference]	Move cursor to next cross-reference or menu item.
  \\[Info-prev-reference]	Move cursor to previous cross-reference or menu item."
    (kill-all-local-variables)
***************
*** 2524,2529 ****
--- 2637,2643 ----
    (make-local-variable 'Info-tag-table-buffer)
    (setq Info-tag-table-buffer nil)
    (make-local-variable 'Info-history)
+   (make-local-variable 'Info-history-node)
    (make-local-variable 'Info-index-alternatives)
    (setq header-line-format
  	(if Info-use-header-line
***************
*** 2833,2841 ****
    "Keymap to put on the Up link in the text or the header line.")
  
  (defun Info-fontify-node ()
!   ;; Only fontify the node if it hasn't already been done.
!   (unless (let ((where (next-property-change (point-min))))
!             (and where (not (= where (point-max)))))
      (save-excursion
        (let ((inhibit-read-only t)
  	    (case-fold-search t)
--- 2947,2957 ----
    "Keymap to put on the Up link in the text or the header line.")
  
  (defun Info-fontify-node ()
!   ;; Only fontify the node if it hasn't already been done
!   ;; or always fontify visited nodes (because of their dynamic nature).
!   (when (or Info-visited-nodes
!             (not (let ((where (next-property-change (point-min))))
!                    (and where (not (= where (point-max)))))))
      (save-excursion
        (let ((inhibit-read-only t)
  	    (case-fold-search t)
***************
*** 2911,2961 ****
  	    (add-text-properties (1- (match-beginning 2)) (match-end 2)
  				 '(invisible t front-sticky nil rear-nonsticky t))))
  	(goto-char (point-min))
! 	(while (re-search-forward "\\(\\*Note[ \t]*\\)\n?[ \t]*\\([^:]*\\)\\(:[^.,:(]*\\(([^)]*)[^.,:]*\\)?[,:]?\n?\\)" nil t)
! 	  (unless (= (char-after (1- (match-beginning 0))) ?\") ; hack
  	    (let ((start (match-beginning 0))
! 		  (next (point))
! 		  (hide-tag Info-hide-note-references)
! 		  other-tag)
! 	      (when hide-tag
! 		;; *Note is often used where *note should have been
! 		(goto-char start)
! 		(skip-syntax-backward " ")
! 		(setq other-tag
! 		      (cond ((memq (char-before) '(nil ?\. ?! ??))
! 			     "See ")
! 			    ((memq (char-before) '(?\, ?\; ?\: ?-))
! 			     "see ")
! 			    ((memq (char-before) '(?\( ?\[ ?\{))
! 			     ;; Check whether the paren is preceded by
! 			     ;; an end of sentence
! 			     (skip-syntax-backward " (")
! 			     (if (memq (char-before) '(nil ?\. ?! ??))
! 				 "See "
! 			       "see "))
! 			    ((save-match-data (looking-at "\n\n"))
! 			     "See ")))
! 		(goto-char next))
! 	      (if hide-tag
! 		  (add-text-properties (match-beginning 1) (match-end 1)
! 				       '(invisible t front-sticky nil rear-nonsticky t)))
  	      (add-text-properties
  	       (match-beginning 2) (match-end 2)
! 	       (cons 'help-echo
! 		     (cons (if (match-end 4)
! 			       (concat "mouse-2: go to " (match-string 4))
! 			     "mouse-2: go to this node")
! 			   '(font-lock-face info-xref
! 			     mouse-face highlight))))
  	      (when (eq Info-hide-note-references t)
  		(add-text-properties (match-beginning 3) (match-end 3)
! 				     '(invisible t front-sticky nil rear-nonsticky t)))
! 	      (when other-tag
! 		(save-excursion
! 		  (goto-char (match-beginning 1))
! 		  (insert other-tag)))
! 	      (when (and Info-refill-paragraphs
! 			 (or hide-tag (eq Info-hide-note-references t)))
  		(push (set-marker (make-marker) start)
  		      paragraph-markers)))))
  
--- 3027,3101 ----
  	    (add-text-properties (1- (match-beginning 2)) (match-end 2)
  				 '(invisible t front-sticky nil rear-nonsticky t))))
  	(goto-char (point-min))
! 	(while (re-search-forward "\\(\\*Note[ \t]*\\)\n?[ \t]*\\([^:]*\\)\\(:[^.,:(]*\\((\\([^)]*\\))\\([^.,:]*\\)\\)?[,:]?\n?\\)" nil t)
! 	  (unless (memq (char-after (1- (match-beginning 0))) '(?\" ?\`)) ; hack
  	    (let ((start (match-beginning 0))
! ;; 		  (next (point))
! ;; 		  other-tag
!                   )
! 	      (when Info-hide-note-references
! ;; 		;; *Note is often used where *note should have been
! ;; 		(goto-char start)
! ;; 		(skip-syntax-backward " ")
! ;; 		(setq other-tag
! ;;                       (cond ((memq (char-before) '(nil ?\. ?! ??))
! ;;                              "See ")
! ;;                             ((memq (char-before) '(?\, ?\; ?\: ?-))
! ;;                              "see ")
! ;;                             ((memq (char-before) '(?\( ?\[ ?\{))
! ;;                              ;; Check whether the paren is preceded by
! ;;                              ;; an end of sentence
! ;;                              (skip-syntax-backward " (")
! ;;                              (if (memq (char-before) '(nil ?\. ?! ??))
! ;;                                  "See "
! ;;                                "see "))
! ;;                             ((save-match-data (looking-at "\n\n"))
! ;;                              "See ")))
! ;; 		(goto-char next)
!                 (add-text-properties (match-beginning 1) (match-end 1)
!                                      '(invisible t front-sticky nil rear-nonsticky t)))
  	      (add-text-properties
  	       (match-beginning 2) (match-end 2)
!                (list
!                 'help-echo (if (match-end 4)
!                                (concat "mouse-2: go to " (match-string 4))
!                              "mouse-2: go to this node")
!                 'font-lock-face
!                 ;; Display visited nodes in a different face
!                 (if (and Info-visited-nodes
!                          (save-match-data
!                            (let* ((file (concat (or (match-string 5) Info-current-file) "$"))
!                                   (node (replace-regexp-in-string
!                                          "[ \t\n]+" " "
!                                          (or (match-string 6) (match-string 2))))
!                                   (l Info-history-tree)
!                                   res)
!                              (while l
!                                (if (and (equal (cadr (car l)) node)
!                                         (string-match file (caar l)))
!                                    (setq res (car l) l nil))
!                                (setq l (cdr l)))
!                              res))) 'info-xref-visited 'info-xref)
!                 'mouse-face 'highlight))
  	      (when (eq Info-hide-note-references t)
  		(add-text-properties (match-beginning 3) (match-end 3)
! 				     '(invisible t front-sticky nil rear-nonsticky t))
!                 ;; Unhide the file name of the reference in parens
!                 (if (match-string 5)
!                     (remove-text-properties (1- (match-beginning 5)) (1+ (match-end 5))
!                                             '(invisible t front-sticky nil rear-nonsticky t)))
!                 ;; Unhide newline because hidden newlines cause too long lines
!                 (save-match-data
!                   (let ((start3 (match-beginning 3)))
!                     (if (string-match "\n[ \t]*" (match-string 3))
!                         (remove-text-properties (+ start3 (match-beginning 0)) (+ start3 (match-end 0))
!                                                 '(invisible t front-sticky nil rear-nonsticky t)))))
!                 )
! ;; 	      (when other-tag
! ;; 		(save-excursion
! ;; 		  (goto-char (match-beginning 1))
! ;; 		  (insert other-tag)))
! 	      (when (and Info-refill-paragraphs Info-hide-note-references)
  		(push (set-marker (make-marker) start)
  		      paragraph-markers)))))
  
***************
*** 2997,3009 ****
  				     'font-lock-face 'info-menu-5))
  	      (add-text-properties
  	       (match-beginning 1) (match-end 1)
! 	       (cons 'help-echo
! 		     (cons
! 		      (if (match-end 3)
! 			  (concat "mouse-2: go to " (match-string 3))
! 			"mouse-2: go to this node")
! 		      '(font-lock-face info-xref
! 			mouse-face highlight))))
  	      (when (eq Info-hide-note-references t)
  		(put-text-property (match-beginning 2) (1- (match-end 6))
  				   'invisible t)
--- 3137,3161 ----
  				     'font-lock-face 'info-menu-5))
  	      (add-text-properties
  	       (match-beginning 1) (match-end 1)
!                (list
!                 'help-echo (if (match-end 3)
!                                (concat "mouse-2: go to " (match-string 3))
!                              "mouse-2: go to this node")
!                 'font-lock-face
!                 ;; Display visited nodes in a different face
!                 (if (and Info-visited-nodes
!                          (let ((node (if (equal (match-string 3) "")
!                                          (match-string 1)
!                                        (match-string 3)))
!                                (l Info-history-tree)
!                                res)
!                            (while l
!                              (if (and (equal (cadr (car l)) node)
!                                       (equal Info-current-file (caar l)))
!                                  (setq res (car l) l nil))
!                              (setq l (cdr l)))
!                            res)) 'info-xref-visited 'info-xref)
!                 'mouse-face 'highlight))
  	      (when (eq Info-hide-note-references t)
  		(put-text-property (match-beginning 2) (1- (match-end 6))
  				   'invisible t)
***************
*** 3026,3031 ****
--- 3178,3190 ----
  				       '(space :align-to 24)))
  		  (setq cont t))))))
  
+ 	(goto-char (point-min))
+ 	(while (re-search-forward "http://[-~/[:alnum:]_.${}#%,:?=&]+" nil t)
+           (add-text-properties (match-beginning 0) (match-end 0)
+                                '(font-lock-face info-xref
+                                  mouse-face highlight
+                                  help-echo "mouse-2: go to this URL")))
+ 
  	(Info-fontify-menu-headers)
  	(set-buffer-modified-p nil)))))
  \f
===================================================================

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Luc Teirlinck]

I have not yet had the time to look at your patch in detail.  I just
looked at one feature:

   - use reference names to move point to the place within the current
     node where reference name is defined.  For example, by following the
     reference "*Note file-coding-system-alist: Default Coding Systems,"
     Info finds a node with the name "Default Coding Systems" and moves
     point to the line where reference name "file-coding-system-alist" is
     defined.

I applied your patch.  I replaced the @xref{Default Coding Systems}
in nonascii.texi you are referring to by 
@xref{Default Coding Systems, file-coding-system-alist}.

Then I launch info, go to (elisp)Default Coding Systems and click on
that reference.  It indeed carries me to the intended place.  But the
header-line goes blank.  `u' sometimes, but not always makes the
header-line go blank: C-h i m elisp RET m non- RET m text re RET u
Blank header line.  In general, it seems pretty easy to get a blank
header line.  This happens regardless of the value of
Info-hide-note-references.

As an other remark on the feature, it needs help from the .texi source
file.  So either other Info readers will have to adapt to the feature,
or the references in the .texi files will have to be written in such a
way that they look reasonable even in Info readers that do not have your
feature.  (These Info readers behave like the Emacs Info reader with
Info-hide-note-references  set to nil.)  Maybe the latter is no
problem, because "*Note file-coding-system-alist: Default Coding Systems."
makes sense to me, even without your feature.

Sincerely,

Luc.

Re: Info enhancements

[Juri Linkov]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:
> I have not yet had the time to look at your patch in detail.  I just
> looked at one feature:
>
>    - use reference names to move point to the place within the current
>      node where reference name is defined.  For example, by following the
>      reference "*Note file-coding-system-alist: Default Coding Systems,"
>      Info finds a node with the name "Default Coding Systems" and moves
>      point to the line where reference name "file-coding-system-alist" is
>      defined.
>
> I applied your patch.  I replaced the @xref{Default Coding Systems}
> in nonascii.texi you are referring to by 
> @xref{Default Coding Systems, file-coding-system-alist}.
>
> Then I launch info, go to (elisp)Default Coding Systems and click on
> that reference.  It indeed carries me to the intended place.  But the
> header-line goes blank.  `u' sometimes, but not always makes the
> header-line go blank: C-h i m elisp RET m non- RET m text re RET u
> Blank header line.  In general, it seems pretty easy to get a blank
> header line.  This happens regardless of the value of
> Info-hide-note-references.

Yes, this is because `Info-fontify-node' was called twice on the same
node where header was already made invisible, so it was copied again
with invisibility property to a header line.  I will fix it by calling
code that re-fontifies only node references.

BTW, I just noticed that `Info-fontify-node' uses the function
`Info-escape-percent' which have very limited applicability.
It doubles all occurrences of only one particular character %.
Seems this function is a copy of `replace-regexp-in-string'
with a little modification.  I think it's too bad to have such
a limited function: it should be removed with making modifications
in the `replace-regexp-in-string'.  What do you think?

> As an other remark on the feature, it needs help from the .texi source
> file.  So either other Info readers will have to adapt to the feature,
> or the references in the .texi files will have to be written in such a
> way that they look reasonable even in Info readers that do not have your
> feature.  (These Info readers behave like the Emacs Info reader with
> Info-hide-note-references  set to nil.)  Maybe the latter is no
> problem, because "*Note file-coding-system-alist: Default Coding Systems."
> makes sense to me, even without your feature.

I just discovered that the stand-alone Info reader already provides
exactly the same feature.  It uses a reference name to move to correct
position within the selected Info node.  It's too surprising to see
a feature the stand-alone Info reader has, but Emacs Info reader hasn't!

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Luc Teirlinck]

Juri Linkov wrote:

   I would like to submit a patch that fixes some problems in the Emacs
   Info reader and adds features most web browsers already have.
   This patch don't change the existing Info file format.  It improves
   usability of the Emacs Info reader with the current Info file format.
   Any comments are welcome.

I now took a look at your other features.  I have not yet looked at
them carefully enough, but at first sight, it looks like all your new
features are useful and real improvements.

You have to do something about that header line going blank problem I
mentioned in my previous message, however.

Sincerely,

Luc.

Re: Info enhancements (was: Re: HTML as info format)

[Juri Linkov]

Eli Zaretskii <eliz@elta.co.il> writes:
> [I have no idea why mailman sent me this message from 2 weeks ago.]
>> From: Juri Linkov <juri@jurta.org>
>> Date: Mon, 17 Nov 2003 15:29:54 +0200
>> 
>> Current Info format can't make a link to another part of the same
>> Info node.
>
> I think you miss the @anchor directive, introduced in Texinfo 4.x.
>
>> The same problem appears in the Glossary node of the Emacs manual,
>> where links to the same node are marked by the "(q.v.)".
>
> Arguably, we could modify the Glossary by using anchors in the online
> formats.

Yes, using anchors might be a more clean solution, but it has one
drawback: it will generate too many excessive references in the tag
table for its Info file.  And these references will be mixed up with
node names, e.g. in the completion list of `Info-goto-node'.  Maybe
this is not too bad to jump directly to the glossary term definition
by `Info-goto-node', but seems that its disadvantages outweigh a
little convenience it provides.

I solved this problem by using reference names for finding correct
position within an Info node by calling the function `Info-find-index-name'
with reference name after selecting an Info node.  For example,
instead of the text "is shared by an indirect buffer (q.v.@:)" the text
"is shared by an @ref{Glossary,indirect buffer}" could be used.

But I just noticed one problem with using it in the Glossary node.
If some glossary term coincides with the node name then Info jumps to
this node instead of finding a term in the some Glossary node.  It's
because the function `Info-follow-reference' always selects the first
occurrence of the "*Note:" text within one Info node.  For example, if
Glossary node has two following references:

     *Note Input Methods::.
     *Note input method: Glossary.

it will always jump to the first reference even if point was on second
before calling the `Info-follow-reference' function.  I hope this
should be fixed somehow in this function.

>> There are other problems with the current Info format.  For example,
>> currently there is no way to hide the address part of the link without
>> corrupting the paragraph formatting.
>
> IMHO, the current way to hide the address of the link is still
> experimental and needs further work.

I already fixed some its deficiencies, so now it looks quite good.
It don't cause too long lines, but still don't fix too short lines.
But I think too short lines is not a big problem.  Long lines were
much worse, because they became partially invisible when truncated.

>> After hiding the address part of
>> the link lines become either too short or too long.  For example, lines:
>> 
>>    See *Note Customizing Indentation: (ccmode)Customizing Indentation, for
>> more information on customizing indentation for C and related modes,
>> 
>> in Info the first line becomes too short:
>> 
>>    See Customizing Indentation for
>> more information on customizing indentation for C and related modes,
>
> Doing this in some other way, like physically erasing the text we now
> hide and then re-filling the paragraph, would solve this.  In any
> case, this problem is not relevant to Info format per se, it is due to
> the way the Emacs Info reader renders an Info document.

The proper refilling in the Emacs Info reader is impossible because
Info file format loses some information about formatting presented in
a source Texinfo file, like @*, @w{...}, etc.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements (was: Re: HTML as info format)

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Date: Tue, 02 Dec 2003 12:18:09 +0200
> 
> Yes, using anchors might be a more clean solution, but it has one
> drawback: it will generate too many excessive references in the tag
> table for its Info file.  And these references will be mixed up with
> node names, e.g. in the completion list of `Info-goto-node'.

Perhaps there should be a way to tell Info-goto-node to complete on
node names only, or maybe we should have two distinct commands, one
which considers only nodes, the other which considers all entries in
the tag tables.

Re: Info enhancements (was: Re: HTML as info format)

[Karl Berry]

    > From: Juri Linkov <juri@jurta.org>
    > Date: Tue, 02 Dec 2003 12:18:09 +0200
    > 
    > Yes, using anchors might be a more clean solution, but it has one
    > drawback: it will generate too many excessive references in the tag
    > table for its Info file.  And these references will be mixed up with
    > node names, e.g. in the completion list of `Info-goto-node'.

    Perhaps there should be a way to tell Info-goto-node to complete on
    node names only, or maybe we should have two distinct commands, one
    which considers only nodes, the other which considers all entries in
    the tag tables.

Once again I've been removed from the thread.  What is under discussion now?

I doubt having two different completion commands would make users happy.

Re: Info enhancements

[Juri Linkov]

karl@freefriends.org (Karl Berry) writes:
>     > From: Juri Linkov <juri@jurta.org>
>     > Date: Tue, 02 Dec 2003 12:18:09 +0200
>     > 
>     > Yes, using anchors might be a more clean solution, but it has one
>     > drawback: it will generate too many excessive references in the tag
>     > table for its Info file.  And these references will be mixed up with
>     > node names, e.g. in the completion list of `Info-goto-node'.
>
>     Perhaps there should be a way to tell Info-goto-node to complete on
>     node names only, or maybe we should have two distinct commands, one
>     which considers only nodes, the other which considers all entries in
>     the tag tables.
>
> Once again I've been removed from the thread.  What is under discussion now?

There is a problem of more accurate addressing of a position within a
given Info node.  For example, currently the Glossary node of the
Emacs Manual has non-functional references that merely has a form of a
simple text "(q.v.)" or "See `default.'".  There are many other
places in Info documentation where more exact referencing is needed.
This discussion currently goes about two solutions to this problem:

- use anchors

for example:

@item Argument
@xref{Numeric Argument}.
...
@item Numeric Argument
@anchor{Numeric Argument}
A numeric argument is a number, specified before a command, to change

- or use reference names

@item Argument
@xref{Glossary,Numeric Argument}.

This works by selecting an Info node ("Glossary") and then by
using some heuristics to find a needed position in this Info node.
The stand-alone Info reader searches for the first occurrence of the
reference name ("Numeric Argument") and moves point here. The Emacs
Info reader now uses the function `Info-find-index-name' to move point
to the place within the current node where reference name ("Numeric
Argument") is defined (but still sometimes it misses the correct place).

If the solution will be to use anchors, then I can suggest to develop
it further and generate anchors (i.e. Ref: tags in tag tables of
Info files) from all indexing commands (@findex, @vindex, etc.).
Currently their positions are not available in Info files, but it
might be useful to jump unambiguously to positions in Info files where
these index entries were defined in Texinfo source files.

-- 
http://www.jurta.org/emacs/

_______________________________________________
Texinfo home page: http://www.gnu.org/software/texinfo/
texinfo-pretest@texinfo.org
http://ff0.org/mailman/listinfo/texinfo-pretest

Re: Info enhancements

[Karl Berry]

    For example, currently the Glossary node of the
    Emacs Manual has non-functional references that merely has a form of a
    simple text "(q.v.)" or "See `default.'".  

I see.  Yes, this is more or less what anchors were invented for.  As
far as glossary entries go, I think that would work ok.

The reference name solution seems too heuristic.

However, I certainly agree with the comment that if we make an anchor
for every index entry, that's too many anchors (it would make the i cmd
a subset of g :).  Instead, I think indexes are important enough that
they deserve special treatment.

In fact, we've had this discussion before, in the context of allowing
arbitrary index names (specifically, ones with a :).  One message from
that thread is from rms, on 26 Jun 2003 01:30:50 -0400, Message-Id:
<E19VPLO-0004C2-6Q@fencepost.gnu.org>.

If we mark index menus with a special tag, then we can also easily the
exact character or line position within the node for the index entry.  I
believe Dave Gillespie (that's my memory, might have been someone else)
implemented a hack for this at one point, but it never made it back
into info.el.
_______________________________________________
Texinfo home page: http://www.gnu.org/software/texinfo/
texinfo-pretest@texinfo.org
http://ff0.org/mailman/listinfo/texinfo-pretest

Re: Info enhancements

[Robert J. Chassell]

karl@freefriends.org (Karl Berry) wrote

    .... If we mark index menus with a special tag, then we can also
    easily the exact character or line position within the node for
    the index entry.  I believe Dave Gillespie (that's my memory,
    might have been someone else) implemented a hack for this at one
    point, but it never made it back into info.el.

Here is an example from the `Index of Key Sequences' in calc-2.02f

    * quick-calc:                   Quick Calculator.       6.

which comes from node Quick Calculator in the Texinfo file:

    @pindex quick-calc

Unfortunately, I could not find the source for the hack, just its output.

As far as I can see, a better format would have the line number before
the description rather than after it, with the description indented 6
spaces from the column number to which the description would otherwise
have been indented.

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

Re: Info enhancements

[Juri Linkov]

karl@freefriends.org (Karl Berry) writes:
>     For example, currently the Glossary node of the
>     Emacs Manual has non-functional references that merely has a form of a
>     simple text "(q.v.)" or "See `default.'".  
>
> I see.  Yes, this is more or less what anchors were invented for.
> As far as glossary entries go, I think that would work ok.  The
> reference name solution seems too heuristic.

Anchors wouldn't work in this case because many glossary entries have
the same names as Info nodes (e.g. "Filling", "Global Mark Ring" and
many others).  Making anchors for them is not possible because anchors
and nodes can't have the same names.  So, using the reference name
solution seems inevitable here.

> However, I certainly agree with the comment that if we make an anchor
> for every index entry, that's too many anchors (it would make the i cmd
> a subset of g :).  Instead, I think indexes are important enough that
> they deserve special treatment.
>
> In fact, we've had this discussion before, in the context of allowing
> arbitrary index names (specifically, ones with a :).  One message from
> that thread is from rms, on 26 Jun 2003 01:30:50 -0400, Message-Id:
> <E19VPLO-0004C2-6Q@fencepost.gnu.org>.

I found this message, but I have one question to administrators of the
emacs-devel mailing list: does the emacs-devel archive exist in mbox
format available for download?  Often there is a need to read old
discussions, but web interface to archives is too inconvenient.  Much
better is to browse mail archives in a local mbox file by one of the
Emacs mail readers.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Karl Berry]

    does the emacs-devel archive exist in mbox
    format available for download?

ftp://mail.gnu.org/emacs-devel/  (by month).

All the GNU lists are available there, as far as I know.

HTH,
k

Re: Info enhancements (was: Re: HTML as info format)

[Richard Stallman]

	Perhaps there should be a way to tell Info-goto-node to complete on
	node names only,

Perhaps Info-goto-node should go to node names only,
and the basic function to go to any locator should have another name.

Re: Info enhancements

[Reiner Steib]

On Mon, Dec 01 2003, Juri Linkov wrote:

> - rebind `M-s' key to a new function `Info-search-next' that searches
>   for another occurrence of regular expression from a previous
>   `Info-search' command (key `s').  Pressing only one key to repeat
>   a search is more convenient than pressing two keys (`s RET').

ACK.  I would even suggest to use an easily accessible single-key [1],
because `Info-search-next' is used often and repeatedly.  Like `,' for
`Info-index-next'.

[1] I'm using (define-key Info-mode-map "/" "s") for this which made
using info much more convenient for me.

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

`s' (regex) search [was Re: Info enhancements]

[Harry Putnam]

Reiner Steib <4.uce.03.r.s@nurfuerspam.de> writes:

> On Mon, Dec 01 2003, Juri Linkov wrote:
>
>> - rebind `M-s' key to a new function `Info-search-next' that searches
>>   for another occurrence of regular expression from a previous
>>   `Info-search' command (key `s').  Pressing only one key to repeat
>>   a search is more convenient than pressing two keys (`s RET').

This comment must be about reading info inside emacs ... right?

I think it needs to be said somewhere in this discussion that a regex
search needs to be added to the standalone info reader.  A regex
search is much more usefull in my opinion, than a string match search.

Of course the index search is the first line of attack but after that
I rely on emacs  info reader's `s' (regex) search.

I wondered why this is not part of standalone info reader.  Is it
difficult to add?  If its possible, can it also be added to the new
formats now under discussion?

Re: `s' (regex) search [was Re: Info enhancements]

[Eli Zaretskii]

> From: Harry Putnam <reader@newsguy.com>
> Date: Tue, 02 Dec 2003 21:54:40 -0600
> 
> Of course the index search is the first line of attack but after that
> I rely on emacs  info reader's `s' (regex) search.

The Emacs manual suggests quite a few ways of searching the docs
using additional commands, before you even get to `s'.

> I wondered why this is not part of standalone info reader.

FWIW, I never needed that in Info.

Re: `s' (regex) search [was Re: Info enhancements]

[Harry Putnam]

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

>> From: Harry Putnam <reader@newsguy.com>
>> Date: Tue, 02 Dec 2003 21:54:40 -0600
>> 
>> Of course the index search is the first line of attack but after that
>> I rely on emacs  info reader's `s' (regex) search.
>
> The Emacs manual suggests quite a few ways of searching the docs
> using additional commands, before you even get to `s'.
>
>> I wondered why this is not part of standalone info reader.
>
> FWIW, I never needed that in Info.

Being an experienced programmer and developer may have left you with
a much better idea of what to look for and how to do it.  But I have
found consistently over the last several years that the `s' search
requires less knowledge on my part to find what I need.  Right down
to the patterns that are found in a snippet of code or the like.

If only one search method were allowed I'd opt for `s'.

Re: `s' (regex) search [was Re: Info enhancements]

[Eli Zaretskii]

> From: Harry Putnam <reader@newsguy.com>
> Date: Wed, 03 Dec 2003 03:42:50 -0600
> 
> Being an experienced programmer and developer may have left you with
> a much better idea of what to look for and how to do it.

Not really, especially when I work with a manual for a tool that I
don't use too regularly.

> But I have found consistently over the last several years that the
> `s' search requires less knowledge on my part to find what I need.

Good indexing should require even less knowledge.  All you need is to
think about related words or phrases.

> If only one search method were allowed I'd opt for `s'.

Ah, but it's not the only method, so this is not the issue at point.

Re: `s' (regex) search [was Re: Info enhancements]

[Harry Putnam]

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

>> If only one search method were allowed I'd opt for `s'.
>
> Ah, but it's not the only method, so this is not the issue at point.

It does point up the fact that `s' search is a very usefull kind of
search, so my question still stands:  Is it difficult to add to
standalone reader.  And could it be also included in the new formats
under discussion?

Re: `s' (regex) search [was Re: Info enhancements]

[Eli Zaretskii]

> From: Harry Putnam <reader@newsguy.com>
> Date: Wed, 03 Dec 2003 05:56:41 -0600
> 
> so my question still stands: Is it difficult to add to standalone
> reader.

You should suggest that to the appropriate Texinfo forum, I think.

> And could it be also included in the new formats under discussion?

Sorry, I don't understand the question: what does search have to do
with a change in format?

Re: `s' (regex) search [was Re: Info enhancements]

[Harry Putnam]

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

>> From: Harry Putnam <reader@newsguy.com>
>> Date: Wed, 03 Dec 2003 05:56:41 -0600
>> 
>> so my question still stands: Is it difficult to add to standalone
>> reader.
>
> You should suggest that to the appropriate Texinfo forum, I think.

Well I appreciate the comment and will do so, but it doesn't seem
inappropriate here either.  There has been a major discussion here
that overlaps texi lists but no one has suggested to remove it to
texi lists.  This serveral thread discussion about reworking info and
texi output for online reading etc.
>
>> And could it be also included in the new formats under discussion?
>
> Sorry, I don't understand the question: what does search have to do
> with a change in format?

There has been a fair bit of discussion here about redoing info and
texi to generate a new format for online reading of info in html+
javascritp/xtml etc.  One point in that discussion has been where the
searching would take place, on server or client.

See MID Message-ID: <87r800dr09.fsf@kanga.tapsellferrier.co.uk> 
for a small example.

A regex search could be pretty intensive over a remote connection I
guess so I'm asking if a regex search is feasable to be built into the
new formats under discussion.  As I understand it, a regex search
engine under javascript or whatever would work differently than the
current one inside emacs (`s' search)

Re: `s' (regex) search [was Re: Info enhancements]

[Eli Zaretskii]

> From: Harry Putnam <reader@newsguy.com>
> Date: Wed, 03 Dec 2003 13:13:06 -0600
> >
> > You should suggest that to the appropriate Texinfo forum, I think.
> 
> Well I appreciate the comment and will do so, but it doesn't seem
> inappropriate here either.  There has been a major discussion here
> that overlaps texi lists but no one has suggested to remove it to
> texi lists.  This serveral thread discussion about reworking info and
> texi output for online reading etc.

I've suggested elsewhere to move those threads as well.

Re: Info enhancements

[Juri Linkov]

Reiner Steib <4.uce.03.r.s@nurfuerspam.de> writes:
> On Mon, Dec 01 2003, Juri Linkov wrote:
>> - rebind `M-s' key to a new function `Info-search-next' that searches
>>   for another occurrence of regular expression from a previous
>>   `Info-search' command (key `s').  Pressing only one key to repeat
>>   a search is more convenient than pressing two keys (`s RET').
>
> ACK.  I would even suggest to use an easily accessible single-key [1],
> because `Info-search-next' is used often and repeatedly.  Like `,' for
> `Info-index-next'.
>
> [1] I'm using (define-key Info-mode-map "/" "s") for this which made
> using info much more convenient for me.

On German and Scandinavian keyboards "/" is placed above the "7" key,
so still two key presses are needed to use it (shift and "7").
But M-s is not a bad choice because <META> key can be held down while
repeating pressing "s" for the next search.  Anyhow, "/" might be
bound to `Info-search-next' as well.

BTW, you didn't use the function `Info-search-next' in your key
binding.  But seems this function could be useful to add it
to the menu and describe it in the `Info-mode' docstring.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Reiner Steib]

On Wed, Dec 03 2003, Juri Linkov wrote:

> Reiner Steib <4.uce.03.r.s@nurfuerspam.de> writes:
>> On Mon, Dec 01 2003, Juri Linkov wrote:
>>> - rebind `M-s' key to a new function `Info-search-next' that searches
>>>   for another occurrence of regular expression from a previous
>>>   `Info-search' command (key `s').  Pressing only one key to repeat
>>>   a search is more convenient than pressing two keys (`s RET').
>>
>> ACK.  I would even suggest to use an easily accessible single-key [1],
>> because `Info-search-next' is used often and repeatedly.  Like `,' for
>> `Info-index-next'.
>>
>> [1] I'm using (define-key Info-mode-map "/" "s") for this which made
>> using info much more convenient for me.
>
> On German and Scandinavian keyboards "/" is placed above the "7" key,
> so still two key presses are needed to use it (shift and "7").
> But M-s is not a bad choice because <META> key can be held down while
> repeating pressing "s" for the next search.  Anyhow, "/" might be
> bound to `Info-search-next' as well.
>
> BTW, you didn't use the function `Info-search-next' in your key
> binding.  But seems this function could be useful to add it
> to the menu and describe it in the `Info-mode' docstring.

I used Emacs 21.3 at that time where `Info-search-next' wasn't
available, IIRC.

Now I use the CVS version, but apparently there still is no key
binding for `Info-search-next' (it in the menu, though).  Was there
any objection against binding `Info-search-next' to `M-s' (or `/')?

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

Re: Info enhancements

[Juri Linkov]

Reiner Steib <4.uce.03.r.s@nurfuerspam.de> writes:
> I used Emacs 21.3 at that time where `Info-search-next' wasn't
> available, IIRC.
>
> Now I use the CVS version, but apparently there still is no key
> binding for `Info-search-next' (it in the menu, though).  Was there
> any objection against binding `Info-search-next' to `M-s' (or `/')?

I remember Richard objected against binding `Info-search-next'
to `M-s' and `/'.

But fortunately, now `Info-search-next' (with possible `M-s' and `/'
bindings) as well as `Info-search' with `s' binding are basically
obsoleted by the ability to use C-M-s and C-M-r to isearch for a regexp
across Info nodes.

-- 
Juri Linkov
http://www.jurta.org/emacs/

Re: Info enhancements

[Richard Stallman]

    But fortunately, now `Info-search-next' (with possible `M-s' and `/'
    bindings) as well as `Info-search' with `s' binding are basically
    obsoleted by the ability to use C-M-s and C-M-r to isearch for a regexp
    across Info nodes.

Could you write an update for info.texi?  If you make the text
basically correct, I can polish up the English.

Re: Info enhancements

[Kim F. Storm]

Juri Linkov <juri@jurta.org> writes:

> - don't hide the newline (with following whitespace) in references when
>   Info-hide-note-references is t.  This fixes the problem where hidden
>   newlines cause too long (and truncated) lines.

I think that change is ok.

> 
> - don't hide the name of external Info file in references in case
>   when Info-hide-note-references is t and references lead outside
>   the current Info file.  It's important for user to know about
>   such situation.

That is a sensible change.

> 
> - don't insert the text "See" instead of "Note" because inserting a
>   new text in Info buffer breaks the stored point positions. This bug
>   can be observed by calling `Info-last', `Info-search' where point is
>   moved with some offset to its correct position (the offset is the sum
>   of lengths of strings "See" inserted in the buffer above the point).

I don't see how this is "fixing a bug"...

Isn't there a way to generate the correct positions some other way?

Or you could add a suitable number of invisible space after each "see".

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

Re: Info enhancements

[Juri Linkov]

storm@cua.dk (Kim F. Storm) writes:
> Juri Linkov <juri@jurta.org> writes:
>> - don't insert the text "See" instead of "Note" because inserting a
>>   new text in Info buffer breaks the stored point positions. This bug
>>   can be observed by calling `Info-last', `Info-search' where point is
>>   moved with some offset to its correct position (the offset is the sum
>>   of lengths of strings "See" inserted in the buffer above the point).
>
> I don't see how this is "fixing a bug"...
> Isn't there a way to generate the correct positions some other way?
> Or you could add a suitable number of invisible space after each "see".

Fixing all the problems caused by inserting new text into Info
buffers will require too much work.  Moreover, this will vastly
complicate a simple thing while I see no sense in replacing text
"Note" with "See" at all.  People that want to see some leading word
before references will be happy by setting the variable
`Info-hide-note-references' to nil.

If you still think this is needed then adding "See" could be
placed under condition `Info-refill-paragraphs' because of their
similar fragile behavior or under some new separate value of the
`Info-hide-note-references'.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Juri Linkov]

I'd like to submit the new version of a patch that fixes problems
in the Emacs Info reader and adds new features.  Actually, this is a
patch to the previous patch because below I describe the changes made
after previous changes.  I can send a full patch when needed.
Thanks for all the responses to the previous patch.

* Implemented a new `S' command suggested by Eli.  This command is
  bound to a new function `Info-search-case-sensitively' that searches
  for a regexp case-sensitively.  The `Info-search-next' uses the case
  of a previous `Info-search' or `Info-search-case-sensitively' command.

* Added a new keybinding "/" for `Info-search-next' (suggested by Reiner).

* Added a new variable `Info-search-whitespace-regexp' used to match a
  sequence of whitespace chars in Info search.  I borrowed this idea
  from `search-whitespace-regexp' from isearch.el.

* Removed the history tree feature from the previous patch because
  I found that history tree is less useful than a history list.  There
  are many different variants of tree creation so I couldn't decide
  which is the better one.  But I think that a plain history list
  sorted by node visiting order is good enough.  The history list
  items are represented now by menu instead of references because menu
  is more useful for selecting history nodes (keys 1-9 can be used to
  quickly select a history item in node's menu).

* Unhide a file name in menu items if it has no period after parentheses,
  (i.e. it don't refer to the "Top" node).  This is needed mostly
  for the history list menu where Info file names should be shown.

* Node Tree: this new feature generates a separate buffer with a tree
  of all Info node names collected from an Info file.  The node-subnode
  relationships are extracted from node menus.  The generated buffer
  with a node tree contains the references to Info nodes.  I "stole"
  two functions for this feature from ee-info.el file that builds
  different tree views of Info nodes.  I think that node tree feature
  will be useful even for users not installed the Ee package.  The
  keybinding for this feature is "*".

* A new value 'hide ("Hide tag and reference") of user variable
  `Info-hide-note-references' is added for users that don't want
  to see "see" (no pun intended almost) instead of "*note".  This
  option is also needed for the node tree feature because inserting
  "see" before every node in a node tree is too ugly.

* The function `Info-follow-reference' gives the preference to the
  reference at or closest to point (suggested by Eli to make it
  similar to the standalone Info reader).  However, currently it
  don't handle a situation with off-screen references, because it's
  too impractical to write code for such extremely rare situations.

* The functions `Info-next-reference' and `Info-prev-reference' now
  skip the "*note" tag and move cursor to the position on reference
  immediately after this tag.  This is especially useful when "*note"
  is replaced with "see" by a `display' property as suggested by Kim
  because it's better when point is placed directly on the reference
  instead of the "see" text.

* The command `u' (`Info-up') now relocates point to the menu item
  with the name of a previously visited node.  Very useful to keep
  track of node navigation from menu.

* All anchors are filtered out from a node completion list.  I'm not
  sure whether a separate command with anchor list to select and go to
  a selected anchor by its name is needed or not?  Seems anchors are
  useful only for making references to them, not for selecting them
  from completion list.

* Fixed a bug reported by Luc for the previous patch where anchors
  were disabled by the reference names feature.  I still think this
  feature is very useful especially for moving from indexes directly
  to lines where index items are described.  This feature can be
  replaced later gradually by anchors as suggested by Luc.  However,
  now this feature needs more testing to collect more evidences for
  its usefulness/uselessness/harmfulness.

* Fixed a bug reported by Luc where header-line's gone blank.
  It's fixed by calling fontification only once, but calling
  refontification of visited links every time.

* The function `Info-fontify-menu-headers' is removed and its content
  moved to `Info-fontify-node' where is was called before.

===================================================================
diff -cwB emacs/lisp/info.el~ emacs/lisp/info.el
*** emacs/lisp/info.el~	Tue Dec 02 00:25:29 2003
--- emacs/lisp/info.el	Fri Dec 12 02:45:12 2003
***************
*** 45,59 ****
  
  
  (defvar Info-history nil
!   "List of info nodes user has visited.
  Each element of list is a list (FILENAME NODENAME BUFFERPOS).")
  
! (defvar Info-history-tree nil
!   "Tree of info nodes user has visited.
! Each element of list is a list (FILENAME NODENAME PARENT-INDEX).")
! 
! (defvar Info-history-node -1
!   "Position of the current node on the info nodes tree user has visited.")
  
  (defcustom Info-enable-edit nil
    "*Non-nil means the \\<Info-mode-map>\\[Info-edit] command in Info can edit the current node.
--- 45,56 ----
  
  
  (defvar Info-history nil
!   "Stack of info nodes user has visited.
  Each element of list is a list (FILENAME NODENAME BUFFERPOS).")
  
! (defvar Info-history-list nil
!   "Full list of all info nodes user has ever visited.
! Each element of list is a list (FILENAME NODENAME).")
  
  (defcustom Info-enable-edit nil
    "*Non-nil means the \\<Info-mode-map>\\[Info-edit] command in Info can edit the current node.
***************
*** 175,185 ****
  
  (defcustom Info-hide-note-references t
    "*If non-nil, hide the tag and section reference in *note and * menu items.
  If value is non-nil but not t, the reference section is still shown."
    :version "21.4"
!   :type '(choice (const :tag "No reformatting" nil)
  		 (const :tag "Replace tag and hide reference" t)
! 		 (other :tag "Replace only tag" tag))
    :group 'info)
  
  (defcustom Info-refill-paragraphs nil
--- 172,184 ----
  
  (defcustom Info-hide-note-references t
    "*If non-nil, hide the tag and section reference in *note and * menu items.
+ Also replaces the \"*note\" text with \"see\".
  If value is non-nil but not t, the reference section is still shown."
    :version "21.4"
!   :type '(choice (const :tag "No hiding" nil)
  		 (const :tag "Replace tag and hide reference" t)
! 		 (other :tag "Hide tag and reference" hide)
! 		 (other :tag "Only replace tag" tag))
    :group 'info)
  
  (defcustom Info-refill-paragraphs nil
***************
*** 190,195 ****
--- 189,203 ----
    :type 'boolean
    :group 'info)
  
+ (defcustom Info-search-whitespace-regexp "\\\\(?:\\\\s-+\\\\)"
+   "*If non-nil, regular expression to match a sequence of whitespace chars.
+ This applies to regular expression Info search.
+ You might want to use something like \"[ \\t\\r\\n]+\" instead.
+ In the Customization buffer, that is `[' followed by a space,
+ a tab, a carriage return (control-M), a newline, and `]+'."
+   :type 'regexp
+   :group 'info)
+ 
  (defcustom Info-mode-hook
    ;; Try to obey obsolete Info-fontify settings.
    (unless (and (boundp 'Info-fontify) (null Info-fontify))
***************
*** 225,231 ****
    "List of possible matches for last `Info-index' command.")
  
  (defvar Info-reference-name nil
!   "Name of the current reference.")
  
  (defvar Info-standalone nil
    "Non-nil if Emacs was started solely as an Info browser.")
--- 233,241 ----
    "List of possible matches for last `Info-index' command.")
  
  (defvar Info-reference-name nil
!   "Name of the selected cross-reference.
! Point is moved to the proper occurrence of this name within a node
! after selecting it.")
  
  (defvar Info-standalone nil
    "Non-nil if Emacs was started solely as an Info browser.")
***************
*** 809,820 ****
  		       nodename)))
  
  	    (Info-select-node)
! 	    (goto-char (or anchorpos (point-min)))
! 
!             ;; Move point to the place where the referer name points to
!             (when Info-reference-name
                (Info-find-index-name Info-reference-name)
!               (setq Info-reference-name nil)))))
      ;; If we did not finish finding the specified node,
      ;; go back to the previous one.
      (or Info-current-node no-going-back (null Info-history)
--- 819,829 ----
  		       nodename)))
  
  	    (Info-select-node)
! 	    (goto-char (point-min))
! 	    (cond (anchorpos (goto-char anchorpos))
! 		  (Info-reference-name
  		   (Info-find-index-name Info-reference-name)
! 		   (setq Info-reference-name nil))))))
      ;; If we did not finish finding the specified node,
      ;; go back to the previous one.
      (or Info-current-node no-going-back (null Info-history)
***************
*** 1201,1225 ****
  					    (read (current-buffer))))))
  			    (point-max)))
  	(if Info-enable-active-nodes (eval active-expression))
  	(Info-fontify-node)
  	(Info-display-images-node)
- 
-         ;; Add a new history node or use old node from the history tree
-         (let ((tree Info-history-tree)
-               (i 0) res)
-           (while tree
-             (if (and (equal (nth 0 (car tree)) Info-current-file)
-                      (equal (nth 1 (car tree)) Info-current-node))
-                 (setq res i tree nil))
-             (setq tree (cdr tree) i (1+ i)))
-           (if res
-               (setq Info-history-node res)
-             (setq Info-history-tree
-                   (nconc Info-history-tree
-                          (list (list Info-current-file Info-current-node
-                                      Info-history-node)))
-                   Info-history-node (1- (length Info-history-tree)))))
- 
  	(run-hooks 'Info-selection-hook)))))
  
  (defun Info-set-mode-line ()
--- 1210,1221 ----
  					    (read (current-buffer))))))
  			    (point-max)))
  	(if Info-enable-active-nodes (eval active-expression))
+ 	;; Add a new unique history item to full history list
+ 	(let ((new-history (list Info-current-file Info-current-node)))
+ 	  (setq Info-history-list
+ 		(cons new-history (delete new-history Info-history-list))))
  	(Info-fontify-node)
  	(Info-display-images-node)
  	(run-hooks 'Info-selection-hook)))))
  
  (defun Info-set-mode-line ()
***************
*** 1251,1257 ****
    (if fork
        (set-buffer
         (clone-buffer (concat "*info-" (if (stringp fork) fork nodename) "*") t)))
!   (if (equal (buffer-name) "*info-history*")
        (switch-to-buffer "*info*"))
    (let (filename)
      (string-match "\\s *\\((\\s *\\([^\t)]*\\)\\s *)\\s *\\|\\)\\(.*\\)"
--- 1247,1253 ----
    (if fork
        (set-buffer
         (clone-buffer (concat "*info-" (if (stringp fork) fork nodename) "*") t)))
!   (if (member (buffer-name) '("*info-history*" "*info-tree*"))
        (switch-to-buffer "*info*"))
    (let (filename)
      (string-match "\\s *\\((\\s *\\([^\t)]*\\)\\s *)\\s *\\|\\)\\(.*\\)"
***************
*** 1327,1335 ****
  		  (widen)
  		  (goto-char marker)
  		  (while (re-search-forward "\n\\(Node\\|Ref\\): \\(.*\\)\177" nil t)
  		    (setq compl
  			  (cons (list (match-string-no-properties 2))
! 				compl))))
  	      (widen)
  	      (goto-char (point-min))
  	      ;; If the buffer begins with a node header, process that first.
--- 1323,1332 ----
  		  (widen)
  		  (goto-char marker)
  		  (while (re-search-forward "\n\\(Node\\|Ref\\): \\(.*\\)\177" nil t)
+ 		    (or (string-equal "Ref" (match-string 1))
  			(setq compl
  			      (cons (list (match-string-no-properties 2))
! 				    compl)))))
  	      (widen)
  	      (goto-char (point-min))
  	      ;; If the buffer begins with a node header, process that first.
***************
*** 1361,1366 ****
--- 1358,1366 ----
  (defvar Info-search-history nil
    "The history list for `Info-search'.")
  
+ (defvar Info-search-case-fold nil
+   "The value of `case-fold-search' from previous `Info-search' command.")
+ 
  (defun Info-search (regexp)
    "Search for REGEXP, starting from point, and select node it's found in."
    (interactive (list (read-string
***************
*** 1380,1385 ****
--- 1380,1389 ----
  	  (opoint (point))
  	  (ostart (window-start))
  	  (osubfile Info-current-subfile))
+       (when Info-search-whitespace-regexp
+         (setq regexp (replace-regexp-in-string
+                       "[ \t\n]+" Info-search-whitespace-regexp regexp)))
+       (setq Info-search-case-fold case-fold-search)
        (save-excursion
  	(save-restriction
  	  (widen)
***************
*** 1456,1468 ****
  	  (setq Info-history (cons (list ofile onode opoint)
  				   Info-history))))))
  
  (defun Info-search-next ()
    "Search for next regexp from a previous `Info-search' command."
    (interactive)
    (if Info-search-history
        (Info-search (car Info-search-history))
!     ;; If no history then read search string in Info-search
!     (call-interactively 'Info-search)))
  \f
  (defun Info-extract-pointer (name &optional errorname)
    "Extract the value of the node-pointer named NAME.
--- 1460,1478 ----
  	  (setq Info-history (cons (list ofile onode opoint)
  				   Info-history))))))
  
+ (defun Info-search-case-sensitively ()
+   "Search for a regexp case-sensitively."
+   (interactive)
+   (let ((case-fold-search nil))
+     (call-interactively 'Info-search)))
+ 
  (defun Info-search-next ()
    "Search for next regexp from a previous `Info-search' command."
    (interactive)
+   (let ((case-fold-search Info-search-case-fold))
      (if Info-search-history
          (Info-search (car Info-search-history))
!       (call-interactively 'Info-search))))
  \f
  (defun Info-extract-pointer (name &optional errorname)
    "Extract the value of the node-pointer named NAME.
***************
*** 1514,1525 ****
    "Go to the superior node of this node.
  If SAME-FILE is non-nil, do not move to a different Info file."
    (interactive)
!   (let ((node (Info-extract-pointer "up")))
      (and (or same-file (not (stringp Info-current-file)))
  	 (string-match "^(" node)
  	 (error "Up node is in another Info file"))
!     (Info-goto-node node))
!   (Info-restore-point Info-history))
  
  (defun Info-last ()
    "Go back to the last node visited."
--- 1524,1547 ----
    "Go to the superior node of this node.
  If SAME-FILE is non-nil, do not move to a different Info file."
    (interactive)
!   (let ((old-node Info-current-node)
!         (old-file Info-current-file)
!         (node (Info-extract-pointer "up")) p)
      (and (or same-file (not (stringp Info-current-file)))
  	 (string-match "^(" node)
  	 (error "Up node is in another Info file"))
!     (Info-goto-node node)
!     (setq p (point))
!     (goto-char (point-min))
!     (if (and (search-forward "\n* Menu:" nil t)
!              (re-search-forward
!               (if (string-equal old-node "Top")
!                   (concat "\n\\*.+: (" (file-name-nondirectory old-file) ")")
!                 (concat "\n\\* +" old-node ":"))
!               nil t))
!         (beginning-of-line)
!       (goto-char p)
!       (Info-restore-point Info-history))))
  
  (defun Info-last ()
    "Go back to the last node visited."
***************
*** 1535,1587 ****
      (setq Info-history (cdr Info-history))
      (goto-char opoint)))
  
  ;;;###autoload (add-hook 'same-window-buffer-names "*info-history*")
  
! (defun Info-history-buffer (&optional tree-p)
!   "Create the buffer *info-history* with references to visited nodes.
! Optional argument TREE-P creates a tree of nodes; the default
! creates the plain list of nodes."
!   (interactive "P")
!   (let ((curr-node Info-history-node)
          p)
      (pop-to-buffer
       (with-current-buffer (get-buffer-create "*info-history*")
!        (let ((Info-hide-note-references t)
!              (Info-visited-nodes t)
!              (inhibit-read-only t))
           (erase-buffer)
           (goto-char (point-min))
!          (setq p (Info-insert-history-tree -1 0 (or curr-node 0) tree-p))
!          (if (not (bobp)) (Info-fontify-node))
           (or (eq major-mode 'Info-mode) (Info-mode))
!          (let ((Info-current-file "history")
!                (Info-current-node "History"))
!            (Info-set-mode-line))
           (current-buffer))))
      (goto-char (or p (point-min)))))
  
! (defun Info-insert-history-tree (index indent curr-node tree-p)
!   "Insert the tree or list of references to visited nodes.
! Return the position of the current node on the generated tree."
!   (let ((tree Info-history-tree)
!         (i 0) p)
!     (while tree
!       (when (or (null tree-p) (eq (nth 2 (car tree)) index))
!         (if tree-p (insert (make-string indent ?\040)))
!         (if (eq i curr-node) (setq p (point)))
!         (insert  "*Note " (nth 1 (car tree)) ": ("
!                  (file-name-nondirectory (nth 0 (car tree)))
!                  ")" (nth 1 (car tree)) ".\n")
!         (if tree-p (setq p (or (Info-insert-history-tree
!                                 i (1+ indent) curr-node tree-p) p))))
!       (setq tree (cdr tree) i (1+ i)))
!     p))
  
! ;;;###autoload
! (defun Info-directory ()
!   "Go to the Info directory node."
    (interactive)
!   (Info-find-node "dir" "top"))
  \f
  (defun Info-follow-reference (footnotename &optional fork)
    "Follow cross reference named FOOTNOTENAME to the node it refers to.
--- 1557,1758 ----
      (setq Info-history (cdr Info-history))
      (goto-char opoint)))
  
+ 
+ ;;;###autoload
+ (defun Info-directory ()
+   "Go to the Info directory node."
+   (interactive)
+   (Info-find-node "dir" "top"))
+ \f
  ;;;###autoload (add-hook 'same-window-buffer-names "*info-history*")
  
! (defun Info-history-buffer ()
!   "Create the buffer *info-history* with references to visited nodes."
!   (interactive)
!   (let ((curr-file Info-current-file)
!         (curr-node Info-current-node)
          p)
      (pop-to-buffer
       (with-current-buffer (get-buffer-create "*info-history*")
!        (let ((inhibit-read-only t))
           (erase-buffer)
           (goto-char (point-min))
!          (insert "Node: History\n\n* Menu:\n\n")
!          (let ((hl Info-history-list))
!            (while hl
!              (let ((file (nth 0 (car hl)))
!                    (node (nth 1 (car hl))))
!                (if (and (equal file curr-file)
!                         (string-equal node curr-node))
!                    (setq p (point)))
!                (insert "* " node ": (" (file-name-nondirectory file)
!                        ")" node ".\n"))
!              (setq hl (cdr hl))))
           (or (eq major-mode 'Info-mode) (Info-mode))
!          (setq Info-current-file "info-history")
!          (setq Info-current-node "Info History")
!          (Info-set-mode-line)
!          (if (not (bobp)) (Info-fontify-node))
           (current-buffer))))
      (goto-char (or p (point-min)))))
  
! ;;;###autoload (add-hook 'same-window-buffer-names "*info-tree*")
  
! (defun Info-node-tree-buffer ()
!   "Create the buffer *info-tree* with Info node tree."
    (interactive)
!   (let ((curr-file Info-current-file)
!         (curr-node Info-current-node)
!         p)
!     (pop-to-buffer
!      (with-current-buffer (get-buffer-create "*info-tree*")
!        (if (not (equal Info-current-file curr-file))
!            (let ((inhibit-read-only t)
!                  (node-list (Info-node-tree-collect-menus curr-file)))
!              (erase-buffer)
!              (goto-char (point-min))
!              (insert "Node: Node Tree\n\n")
!              (Info-node-tree-insert
!               (delq nil (mapcar (lambda (node)
!                                   (if (nth 1 node)
!                                       (nth 0 node))) node-list))
!               node-list 0)
!              (set (make-local-variable 'Info-current-file) curr-file)
!              (or (eq major-mode 'Info-mode) (Info-mode))
!              (setq Info-current-node "Info Node Tree")
!              (Info-set-mode-line)))
!        (if (not (bobp))
!            (let ((Info-hide-note-references 'hide))
!              (Info-fontify-node)))
!        (goto-char (point-min))
!        (if (setq p (search-forward (concat "*Note " curr-node "::") nil t))
!            (setq p (- p (length curr-node) 8)))       (current-buffer)))
!     (goto-char (or p (point-min)))))
! 
! (defun Info-node-tree-insert (nodes node-list level)
!   "Insert the node tree of references to nodes."
!   (while nodes
!     (insert (make-string (* level 4) ?\040))
!     (insert "*Note " (car nodes) "::\n")
!     (Info-node-tree-insert (nth 2 (assoc (car nodes) node-list))
!                            node-list
!                            (1+ level))
!     (setq nodes (cdr nodes))))
! 
! (defvar Info-node-tree-section-names nil
!   "Global variable to hold association list during data collection.
! The elements of list are (\"section name\" . \"node name\").")
! 
! (defun Info-node-tree-collect-menus (filename)
!   "Collect all node names and subnodes from current Info file."
!   (save-excursion
!     (let ((res))
!       (set-buffer (get-buffer-create " *info-node-tree*"))
!       (or (eq major-mode 'Info-mode) (Info-mode))
!       (Info-find-node filename "Top")
!       (setq Info-node-tree-section-names '(("Top" "Top")))
!       ;; Read menus from info file of Top node
!       ;; (setq res (Info-node-tree-collect-menus-current))
!       ;; Read menus from info subfiles
!       (let ((list ())
!             (osubfile ))
!         ;; Get list of subfiles (code borrowed from `Info-search')
!         (save-excursion
!           (set-buffer (marker-buffer Info-tag-table-marker))
!           (goto-char (point-min))
!           (if (search-forward "\n\^_\nIndirect:" nil t)
!               (save-restriction
!                 (narrow-to-region (point)
!                                   (progn (search-forward "\n\^_")
!                                          (1- (point))))
!                 (goto-char (point-min))
!                 (beginning-of-line)
!                 (while (not (eobp))
!                   (re-search-forward "\\(^.*\\): [0-9]+$")
!                   (goto-char (+ (match-end 1) 2))
!                   (setq list (cons (cons (read (current-buffer))
!                                          (buffer-substring-no-properties
!                                           (match-beginning 1) (match-end 1)))
!                                    list))
!                   (goto-char (1+ (match-end 0))))
!                 (setq list (nreverse list)
!                       list (cdr list)))))
!         (while list
!           (message "Searching subfile %s..." (cdr (car list)))
!           (Info-read-subfile (car (car list)))
!           (setq res (append (Info-node-tree-collect-menus-current) res))
!           (setq list (cdr list)))
!         (nreverse res)))))
! 
! (defun Info-node-tree-collect-menus-current ()
!   "Return list of menus extracted from current Info file.
! Return all nodes, even those that are not accessible from menus.
! Output: ((\"nodename1\",\"sectname1\",(\"subnode2\",\"subnode3\")))."
!   (let ((res))
!     (save-excursion
!       (save-restriction
!         (widen)
!         (goto-char (point-min))
!         (while (and (search-forward "\n\^_\nFile:" nil 'move)
!                     (search-forward "Node: " nil 'move))
!           (let (nodename section-name menu-items index-items ref-items beg bound)
!             (setq nodename (substring-no-properties (Info-following-node-name)))
!             (forward-line 1)
!             (setq beg (point))
!             (search-forward "\n\^_" nil 'move)
!             (beginning-of-line)
!             (forward-line -1)
!             (setq bound (point))
!             (goto-char beg)
!             (when (re-search-forward "^\\* Menu:" bound t)
!               (forward-line 1)
!               (beginning-of-line)
!               (cond
!                ((equal nodename "Top")
!                 (while (and (< (point) bound)
!                             (not (looking-at "^[ \t]*-+ The Detailed Node Listing")))
!                   (cond
!                    ;; Menu line
!                    ((looking-at "^\\* +\\([^:\t\n]*\\):")
!                     (beginning-of-line)
!                     (forward-char 2)
!                     (let ((menu-node-name (substring-no-properties (Info-extract-menu-node-name))))
!                       (setq menu-items
!                             (cons menu-node-name ;; (list menu-node-name section-name)
!                                   ;; (match-string-no-properties 1)
!                                   menu-items))
!                       (setq Info-node-tree-section-names
!                             (cons (list menu-node-name (or section-name "Top"))
!                                    Info-node-tree-section-names))))
!                    ;; Other non-empty strings in the dir buffer are section names
!                    ((looking-at "^\\([^ \t\n][^:\n]*\\)")
!                     (setq section-name (match-string-no-properties 1))))
!                   (forward-line 1)
!                   (beginning-of-line)))
!                ((string-match "Index" nodename)
!                 ;; Accept index menu items, e.g.:
!                 ;; * forward-list:                          List Motion.
!                 (while (re-search-forward "\n\\* +\\([^:\t\n]*\\):" bound t)
!                   (beginning-of-line)
!                   (forward-char 2)
!                   (setq index-items (cons (substring-no-properties (Info-extract-menu-node-name))
!                                           ;; (match-string-no-properties 1)
!                                           index-items))))
!                (t
!                 (while (re-search-forward "\n\\* +\\([^:\t\n]*\\):" bound t)
!                   (beginning-of-line)
!                   (forward-char 2)
!                   (setq menu-items (cons (substring-no-properties (Info-extract-menu-node-name))
!                                          ;; (match-string-no-properties 1)
!                                          menu-items))))))
!             (setq res (cons (list nodename
!                                   (cadr (assoc nodename Info-node-tree-section-names))
!                                   (if (not (equal nodename "Top")) ; hack
!                                       (nreverse menu-items))
!                                   (nreverse index-items))
!                             res))
!             (goto-char bound)))))
!     res))
  \f
  (defun Info-follow-reference (footnotename &optional fork)
    "Follow cross reference named FOOTNOTENAME to the node it refers to.
***************
*** 1650,1661 ****
        (setq str (concat (substring str 0 i) "[ \t\n]+" (substring str (1+ i))))
        (setq i (+ i 6)))
      (save-excursion
!       (goto-char (point-min))
!       (or (re-search-forward str nil t)
! 	  (error "No cross-reference named %s" footnotename))
!       (goto-char (+ (match-beginning 0) 5))
!       (setq target
! 	    (Info-extract-menu-node-name t)))
      (while (setq i (string-match "[ \t\n]+" target i))
        (setq target (concat (substring target 0 i) " "
  			   (substring target (match-end 0))))
--- 1821,1848 ----
        (setq str (concat (substring str 0 i) "[ \t\n]+" (substring str (1+ i))))
        (setq i (+ i 6)))
      (save-excursion
!       ;; Move point to the beginning of reference if point is on reference
!       (or (looking-at "\\*note[ \n\t]*")
!           (and (looking-back "\\*note[ \n\t]*")
!                (goto-char (match-beginning 0)))
!           (if (and (save-excursion
!                      (goto-char (+ (point) 5)) ; skip a possible *note
!                      (search-backward "\*note " nil t)
!                      (looking-at (concat "\\*note " (Info-following-node-name-re))))
!                    (<= (point) (match-end 0)))
!               (goto-char (match-beginning 0))))
!       ;; Go to the reference closest to point
!       (let ((next-ref (save-excursion (and (re-search-forward str nil t)
!                                            (+ (match-beginning 0) 5))))
!             (prev-ref (save-excursion (and (re-search-backward str nil t)
!                                            (+ (match-beginning 0) 5)))))
!         (goto-char (cond ((and next-ref prev-ref)
!                           (if (< (abs (- next-ref (point)))
!                                  (abs (- prev-ref (point))))
!                               next-ref prev-ref))
!                          ((or next-ref prev-ref))
!                          ((error "No cross-reference named %s" footnotename))))
!         (setq target (Info-extract-menu-node-name t))))
      (while (setq i (string-match "[ \t\n]+" target i))
        (setq target (concat (substring target 0 i) " "
  			   (substring target (match-end 0))))
***************
*** 2067,2073 ****
  (defun Info-next-reference (&optional recur)
    "Move cursor to the next cross-reference or menu item in the node."
    (interactive)
!   (let ((pat "\\*note[ \n\t]*\\([^:]*\\):\\|^\\* .*:\\|http://")
  	(old-pt (point))
  	(case-fold-search t))
      (or (eobp) (forward-char 1))
--- 2254,2260 ----
  (defun Info-next-reference (&optional recur)
    "Move cursor to the next cross-reference or menu item in the node."
    (interactive)
!   (let ((pat "\\*note[ \n\t]*\\([^:]*\\):\\|^\\* .*:\\|[hf]t?tp://")
  	(old-pt (point))
  	(case-fold-search t))
      (or (eobp) (forward-char 1))
***************
*** 2079,2084 ****
--- 2266,2273 ----
  		(goto-char old-pt)
  		(error "No cross references in this node")))))
      (goto-char (match-beginning 0))
+     (if (looking-at "\\*note[ \n\t]*")
+         (forward-char (- (match-end 0) (match-beginning 0))))
      (if (looking-at "\\* Menu:")
  	(if recur
  	    (error "No cross references in this node")
***************
*** 2087,2093 ****
  (defun Info-prev-reference (&optional recur)
    "Move cursor to the previous cross-reference or menu item in the node."
    (interactive)
!   (let ((pat "\\*note[ \n\t]*\\([^:]*\\):\\|^\\* .*:\\|http://")
  	(old-pt (point))
  	(case-fold-search t))
      (or (re-search-backward pat nil t)
--- 2276,2282 ----
  (defun Info-prev-reference (&optional recur)
    "Move cursor to the previous cross-reference or menu item in the node."
    (interactive)
!   (let ((pat "\\*note[ \n\t]*\\([^:]*\\):\\|^\\* .*:\\|[hf]t?tp://")
  	(old-pt (point))
  	(case-fold-search t))
      (or (re-search-backward pat nil t)
***************
*** 2098,2103 ****
--- 2287,2294 ----
  		(goto-char old-pt)
  		(error "No cross references in this node")))))
      (goto-char (match-beginning 0))
+     (if (looking-at "\\*note[ \n\t]*")
+         (forward-char (- (match-end 0) (match-beginning 0))))
      (if (looking-at "\\* Menu:")
  	(if recur
  	    (error "No cross references in this node")
***************
*** 2331,2337 ****
    "Follow a node reference near point.  Return non-nil if successful."
    (let (node)
      (cond
!      ((and (Info-get-token (point) "http://" "\\(http://\\)")
             (or (featurep 'browse-url) (require 'browse-url nil t)))
        (setq node t)
        (browse-url (browse-url-url-at-point)))
--- 2522,2528 ----
    "Follow a node reference near point.  Return non-nil if successful."
    (let (node)
      (cond
!      ((and (Info-get-token (point) "[hf]t?tp://" "[hf]t?tp://\\([^ \t\n\"`({<>})']+\\)")
             (or (featurep 'browse-url) (require 'browse-url nil t)))
        (setq node t)
        (browse-url (browse-url-url-at-point)))
***************
*** 2345,2351 ****
        (Info-goto-node node fork))
       ;; menu item: index entry
       ((Info-get-token (point) "\\* +" "\\* +\\(.*\\): ")
!       (setq Info-reference-name (match-string-no-properties 1))
        (beginning-of-line)
        (forward-char 2)
        (setq node (Info-extract-menu-node-name))
--- 2536,2543 ----
        (Info-goto-node node fork))
       ;; menu item: index entry
       ((Info-get-token (point) "\\* +" "\\* +\\(.*\\): ")
!       (or (member Info-current-file '("dir" "info-history"))
!           (setq Info-reference-name (match-string-no-properties 1)))
        (beginning-of-line)
        (forward-char 2)
        (setq node (Info-extract-menu-node-name))
***************
*** 2401,2412 ****
--- 2593,2607 ----
    (define-key Info-mode-map "p" 'Info-prev)
    (define-key Info-mode-map "q" 'Info-exit)
    (define-key Info-mode-map "s" 'Info-search)
+   (define-key Info-mode-map "S" 'Info-search-case-sensitively)
+   (define-key Info-mode-map "/" 'Info-search-next)
    (define-key Info-mode-map "\M-s" 'Info-search-next)
    (define-key Info-mode-map "\M-n" 'clone-buffer)
    (define-key Info-mode-map "t" 'Info-top-node)
    (define-key Info-mode-map "u" 'Info-up)
    (define-key Info-mode-map "," 'Info-index-next)
    (define-key Info-mode-map "\\" 'Info-history-buffer)
+   (define-key Info-mode-map "*" 'Info-node-tree-buffer)
    (define-key Info-mode-map "\177" 'Info-scroll-down)
    (define-key Info-mode-map [mouse-2] 'Info-mouse-follow-nearest-node)
    )
***************
*** 2441,2454 ****
     ("Reference" ["You should never see this" report-emacs-bug t])
     ["Search..." Info-search
      :help "Search for regular expression in this Info file"]
     ["Search Next" Info-search-next
      :help "Search for another occurrence of regular expression"]
     ["Go to Node..." Info-goto-node
      :help "Go to a named node"]
     ["Last (Back)" Info-last :active Info-history
      :help "Go to the last node you were at"]
!    ["History" Info-history-buffer :active Info-history-tree
      :help "Go to the history buffer"]
     ("Index..."
      ["Lookup a String" Info-index
       :help "Look for a string in the index items"]
--- 2636,2653 ----
     ("Reference" ["You should never see this" report-emacs-bug t])
     ["Search..." Info-search
      :help "Search for regular expression in this Info file"]
+    ["Search Case-Sensitively..." Info-search-case-sensitively
+     :help "Search for regular expression case sensitively"]
     ["Search Next" Info-search-next
      :help "Search for another occurrence of regular expression"]
     ["Go to Node..." Info-goto-node
      :help "Go to a named node"]
     ["Last (Back)" Info-last :active Info-history
      :help "Go to the last node you were at"]
!    ["History" Info-history-buffer :active Info-history-list
      :help "Go to the history buffer"]
+    ["Node Tree" Info-node-tree-buffer
+     :help "Go to the node tree buffer"]
     ("Index..."
      ["Lookup a String" Info-index
       :help "Look for a string in the index items"]
***************
*** 2587,2592 ****
--- 2786,2792 ----
  \\[Info-follow-reference]	Follow a cross reference.  Reads name of reference.
  \\[Info-last]	Move to the last node you were at.
  \\[Info-history-buffer]	Go to the history buffer.
+ \\[Info-node-tree-buffer]	Go to the node tree buffer.
  \\[Info-index]	Look up a topic in this file's Index and move to that node.
  \\[Info-index-next]	(comma) Move to the next match from a previous `i' command.
  \\[Info-top-node]	Go to the Top node of this file.
***************
*** 2615,2620 ****
--- 2815,2822 ----
  \\[universal-argument] \\[info]	Move to new Info file with completion.
  \\[Info-search]	Search through this Info file for specified regexp,
  	  and select the node in which the next occurrence is found.
+ \\[Info-search-case-sensitively]	Search through this Info file
+ 	  for specified regexp case-sensitively.
  \\[Info-search-next]	Search for another occurrence of regexp
  	  from a previous `Info-search' command.
  \\[Info-next-reference]	Move cursor to next cross-reference or menu item.
***************
*** 2637,2643 ****
    (make-local-variable 'Info-tag-table-buffer)
    (setq Info-tag-table-buffer nil)
    (make-local-variable 'Info-history)
-   (make-local-variable 'Info-history-node)
    (make-local-variable 'Info-index-alternatives)
    (setq header-line-format
  	(if Info-use-header-line
--- 2839,2844 ----
***************
*** 2907,2923 ****
        (push (substring string start end) matches)
        (apply #'concat (nreverse matches)))))
  
- (defun Info-fontify-menu-headers ()
-   "Add the face `info-menu-header' to any header before a menu entry."
-   (save-excursion
-     (goto-char (point-min))
-     (when (re-search-forward "^\\* Menu:" nil t)
-       (put-text-property (match-beginning 0) (match-end 0)
- 			 'font-lock-face 'info-menu-header)
-       (while (re-search-forward "\n\n\\([^*\n ].*\\)\n\n?[*]" nil t)
- 	(put-text-property (match-beginning 1) (match-end 1)
- 			   'font-lock-face 'info-menu-header)))))
- 
  (defvar Info-next-link-keymap
    (let ((keymap (make-sparse-keymap)))
      (define-key keymap [header-line mouse-1] 'Info-next)
--- 3108,3113 ----
***************
*** 2947,2963 ****
    "Keymap to put on the Up link in the text or the header line.")
  
  (defun Info-fontify-node ()
!   ;; Only fontify the node if it hasn't already been done
!   ;; or always fontify visited nodes (because of their dynamic nature).
!   (when (or Info-visited-nodes
!             (not (let ((where (next-property-change (point-min))))
!                    (and where (not (= where (point-max)))))))
      (save-excursion
!       (let ((inhibit-read-only t)
  	    (case-fold-search t)
! 	    paragraph-markers)
  	(goto-char (point-min))
! 	(when (looking-at "^\\(File: [^,: \t]+,?[ \t]+\\)?")
  	  (goto-char (match-end 0))
  	  (while (looking-at "[ \t]*\\([^:, \t\n]+\\):[ \t]+\\([^:,\t\n]+\\),?")
  	    (goto-char (match-end 0))
--- 3137,3158 ----
    "Keymap to put on the Up link in the text or the header line.")
  
  (defun Info-fontify-node ()
!   "Fontify the node."
    (save-excursion
!     (let* ((inhibit-read-only t)
             (case-fold-search t)
!            paragraph-markers
!            (not-fontified-p ; the node hasn't already been fontified
!             (not (let ((where (next-property-change (point-min))))
!                    (and where (not (= where (point-max)))))))
!            (fontify-visited-p ; visited nodes need to be re-fontified
!             (and Info-visited-nodes
!                  ;; Don't take time to refontify visited nodes in huge nodes
!                  (< (- (point-max) (point-min)) Info-fontify-maximum-menu-size))))
! 
!       ;; Fontify header line
        (goto-char (point-min))
!       (when (and not-fontified-p (looking-at "^\\(File: [^,: \t]+,?[ \t]+\\)?"))
          (goto-char (match-end 0))
          (while (looking-at "[ \t]*\\([^:, \t\n]+\\):[ \t]+\\([^:,\t\n]+\\),?")
            (goto-char (match-end 0))
***************
*** 3009,3015 ****
--- 3203,3212 ----
                ;; Hide the punctuation at the end, too.
                (skip-chars-backward " \t,")
                (put-text-property (point) header-end 'invisible t)))))
+ 
+       ;; Fontify titles
        (goto-char (point-min))
+       (when not-fontified-p
          (while (re-search-forward "\n\\([^ \t\n].+\\)\n\\(\\*+\\|=+\\|-+\\|\\.+\\)$"
                                    nil t)
            (let* ((c (preceding-char))
***************
*** 3025,3105 ****
  	  ;; on frames that can display the font above.
  	  (when (memq (framep (selected-frame)) '(x pc w32 mac))
  	    (add-text-properties (1- (match-beginning 2)) (match-end 2)
! 				 '(invisible t front-sticky nil rear-nonsticky t))))
  	(goto-char (point-min))
! 	(while (re-search-forward "\\(\\*Note[ \t]*\\)\n?[ \t]*\\([^:]*\\)\\(:[^.,:(]*\\((\\([^)]*\\))\\([^.,:]*\\)\\)?[,:]?\n?\\)" nil t)
  	  (unless (memq (char-after (1- (match-beginning 0))) '(?\" ?\`)) ; hack
  	    (let ((start (match-beginning 0))
! ;; 		  (next (point))
! ;; 		  other-tag
!                   )
  	      (when Info-hide-note-references
! ;; 		;; *Note is often used where *note should have been
! ;; 		(goto-char start)
! ;; 		(skip-syntax-backward " ")
! ;; 		(setq other-tag
! ;;                       (cond ((memq (char-before) '(nil ?\. ?! ??))
! ;;                              "See ")
! ;;                             ((memq (char-before) '(?\, ?\; ?\: ?-))
! ;;                              "see ")
! ;;                             ((memq (char-before) '(?\( ?\[ ?\{))
! ;;                              ;; Check whether the paren is preceded by
! ;;                              ;; an end of sentence
! ;;                              (skip-syntax-backward " (")
! ;;                              (if (memq (char-before) '(nil ?\. ?! ??))
! ;;                                  "See "
! ;;                                "see "))
! ;;                             ((save-match-data (looking-at "\n\n"))
! ;;                              "See ")))
! ;; 		(goto-char next)
!                 (add-text-properties (match-beginning 1) (match-end 1)
!                                      '(invisible t front-sticky nil rear-nonsticky t)))
  	      (add-text-properties
  	       (match-beginning 2) (match-end 2)
                 (list
!                 'help-echo (if (match-end 4)
!                                (concat "mouse-2: go to " (match-string 4))
                               "mouse-2: go to this node")
                  'font-lock-face
                  ;; Display visited nodes in a different face
!                 (if (and Info-visited-nodes
!                          (save-match-data
!                            (let* ((file (concat (or (match-string 5) Info-current-file) "$"))
                                    (node (replace-regexp-in-string
                                           "[ \t\n]+" " "
!                                          (or (match-string 6) (match-string 2))))
!                                   (l Info-history-tree)
                                    res)
!                              (while l
!                                (if (and (equal (cadr (car l)) node)
!                                         (string-match file (caar l)))
!                                    (setq res (car l) l nil))
!                                (setq l (cdr l)))
!                              res))) 'info-xref-visited 'info-xref)
!                 'mouse-face 'highlight))
! 	      (when (eq Info-hide-note-references t)
  		(add-text-properties (match-beginning 3) (match-end 3)
  				     '(invisible t front-sticky nil rear-nonsticky t))
                  ;; Unhide the file name of the reference in parens
!                 (if (match-string 5)
!                     (remove-text-properties (1- (match-beginning 5)) (1+ (match-end 5))
                                              '(invisible t front-sticky nil rear-nonsticky t)))
                  ;; Unhide newline because hidden newlines cause too long lines
                  (save-match-data
                    (let ((start3 (match-beginning 3)))
                      (if (string-match "\n[ \t]*" (match-string 3))
                          (remove-text-properties (+ start3 (match-beginning 0)) (+ start3 (match-end 0))
!                                                 '(invisible t front-sticky nil rear-nonsticky t)))))
!                 )
! ;; 	      (when other-tag
! ;; 		(save-excursion
! ;; 		  (goto-char (match-beginning 1))
! ;; 		  (insert other-tag)))
  	      (when (and Info-refill-paragraphs Info-hide-note-references)
  		(push (set-marker (make-marker) start)
! 		      paragraph-markers)))))
  
! 	(when (and Info-refill-paragraphs
  		   paragraph-markers)
  	  (let ((fill-nobreak-invisible t)
  		(fill-individual-varying-indent nil)
--- 3222,3313 ----
            ;; on frames that can display the font above.
            (when (memq (framep (selected-frame)) '(x pc w32 mac))
              (add-text-properties (1- (match-beginning 2)) (match-end 2)
!                                  '(invisible t front-sticky nil rear-nonsticky t)))))
! 
!       ;; Fontify cross references
        (goto-char (point-min))
!       (when (or not-fontified-p fontify-visited-p)
!         (while (re-search-forward "\\(\\*Note[ \t]*\\)\n?[ \t]*\\([^:]*\\)\\(:[ \t]*\\([^.,:(]*\\)\\((\\([^)]*\\))\\([^.,:]*\\)\\)?[,:]?\n?\\)" nil t)
            (unless (memq (char-after (1- (match-beginning 0))) '(?\" ?\`)) ; hack
              (let ((start (match-beginning 0))
!                   (next (point))
!                   other-tag)
!               (when not-fontified-p
                  (when Info-hide-note-references
!                   ;; *Note is often used where *note should have been
!                   (goto-char start)
!                   (skip-syntax-backward " ")
!                   (setq other-tag
!                         (cond ((memq (char-before) '(nil ?\. ?! ??))
!                                "See ")
!                               ((memq (char-before) '(?\, ?\; ?\: ?-))
!                                "see ")
!                               ((memq (char-before) '(?\( ?\[ ?\{))
!                                ;; Check whether the paren is preceded by
!                                ;; an end of sentence
!                                (skip-syntax-backward " (")
!                                (if (memq (char-before) '(nil ?\. ?! ??))
!                                    "See "
!                                  "see "))
!                               ((save-match-data (looking-at "\n\n"))
!                                "See ")))
!                   (goto-char next)
!                   (add-text-properties
!                    (match-beginning 1) (match-end 1)
!                    (if (and other-tag (not (eq Info-hide-note-references 'hide)))
!                        `(display ,other-tag front-sticky nil rear-nonsticky t)
!                      '(invisible t front-sticky nil rear-nonsticky t))))
                  (add-text-properties
                   (match-beginning 2) (match-end 2)
                   (list
!                   'help-echo (if (or (match-end 5) (not (equal (match-string 4) "")))
!                                  (concat "mouse-2: go to " (or (match-string 5) (match-string 4)))
                                 "mouse-2: go to this node")
+                   'mouse-face 'highlight)))
+               (when (or not-fontified-p fontify-visited-p)
+                 (add-text-properties
+                  (match-beginning 2) (match-end 2)
+                  (list
                    'font-lock-face
                    ;; Display visited nodes in a different face
!                   (if (save-match-data
!                         (let* ((file (concat (or (match-string 6)
!                                                  Info-current-file) "$"))
                                 (node (replace-regexp-in-string
                                        "[ \t\n]+" " "
!                                       (or (match-string 7)
!                                           (and (not (equal (match-string 4) ""))
!                                                (match-string 4))
!                                           (match-string 2))))
!                                (hl Info-history-list)
                                 res)
!                           (while hl
!                             (if (and (string-equal node (nth 1 (car hl)))
!                                      (string-match file (nth 0 (car hl))))
!                                 (setq res (car hl) hl nil))
!                             (setq hl (cdr hl)))
!                           res)) 'info-xref-visited 'info-xref))))
!               (when not-fontified-p
!                 (when (memq Info-hide-note-references '(t hide))
                    (add-text-properties (match-beginning 3) (match-end 3)
                                         '(invisible t front-sticky nil rear-nonsticky t))
                    ;; Unhide the file name of the reference in parens
!                   (if (match-string 6)
!                       (remove-text-properties (1- (match-beginning 6)) (1+ (match-end 6))
                                                '(invisible t front-sticky nil rear-nonsticky t)))
                    ;; Unhide newline because hidden newlines cause too long lines
                    (save-match-data
                      (let ((start3 (match-beginning 3)))
                        (if (string-match "\n[ \t]*" (match-string 3))
                            (remove-text-properties (+ start3 (match-beginning 0)) (+ start3 (match-end 0))
!                                                   '(invisible t front-sticky nil rear-nonsticky t))))))
                  (when (and Info-refill-paragraphs Info-hide-note-references)
                    (push (set-marker (make-marker) start)
!                         paragraph-markers)))))))
  
!       ;; Refill paragraphs (experimental feature)
!       (when (and not-fontified-p
!                  Info-refill-paragraphs
                   paragraph-markers)
          (let ((fill-nobreak-invisible t)
                (fill-individual-varying-indent nil)
***************
*** 3119,3126 ****
  		      (goto-char beg))))
  		(set-marker m nil)))))
  
  	(goto-char (point-min))
! 	(when (and (search-forward "\n* Menu:" nil t)
  		   (not (string-match "\\<Index\\>" Info-current-node))
  		   ;; Don't take time to annotate huge menus
  		   (< (- (point-max) (point)) Info-fontify-maximum-menu-size))
--- 3327,3336 ----
                      (goto-char beg))))
                (set-marker m nil)))))
  
+       ;; Fontify menu items
        (goto-char (point-min))
!       (when (and (or not-fontified-p fontify-visited-p)
!                  (search-forward "\n* Menu:" nil t)
                   (not (string-match "\\<Index\\>" Info-current-node))
                   ;; Don't take time to annotate huge menus
                   (< (- (point-max) (point)) Info-fontify-maximum-menu-size))
***************
*** 3130,3164 ****
  		    (concat "^\\* +\\(" Info-menu-entry-name-re "\\)\\(:"
  			    Info-node-spec-re "\\([ \t]*\\)\\)")
  		    nil t)
  	      (setq n (1+ n))
  	      (if (and (<= n 9) (zerop (% n 3))) ; visual aids to help with 1-9 keys
  		  (put-text-property (match-beginning 0)
  				     (1+ (match-beginning 0))
! 				     'font-lock-face 'info-menu-5))
  	      (add-text-properties
  	       (match-beginning 1) (match-end 1)
                 (list
                  'help-echo (if (match-end 3)
                                 (concat "mouse-2: go to " (match-string 3))
                               "mouse-2: go to this node")
                  'font-lock-face
!                 ;; Display visited nodes in a different face
!                 (if (and Info-visited-nodes
                           (let ((node (if (equal (match-string 3) "")
                                           (match-string 1)
                                         (match-string 3)))
!                                (l Info-history-tree)
                                 res)
!                            (while l
!                              (if (and (equal (cadr (car l)) node)
!                                       (equal Info-current-file (caar l)))
!                                  (setq res (car l) l nil))
!                              (setq l (cdr l)))
!                            res)) 'info-xref-visited 'info-xref)
!                 'mouse-face 'highlight))
! 	      (when (eq Info-hide-note-references t)
  		(put-text-property (match-beginning 2) (1- (match-end 6))
  				   'invisible t)
  		;; We need a stretchable space like :align-to but with
  		;; a minimum value.
  		(put-text-property (1- (match-end 6)) (match-end 6) 'display
--- 3340,3388 ----
                    (concat "^\\* +\\(" Info-menu-entry-name-re "\\)\\(:"
                            Info-node-spec-re "\\([ \t]*\\)\\)")
                    nil t)
+             (when not-fontified-p
                (setq n (1+ n))
                (if (and (<= n 9) (zerop (% n 3))) ; visual aids to help with 1-9 keys
                    (put-text-property (match-beginning 0)
                                       (1+ (match-beginning 0))
!                                      'font-lock-face 'info-menu-5)))
!             (when not-fontified-p
                (add-text-properties
                 (match-beginning 1) (match-end 1)
                 (list
                  'help-echo (if (match-end 3)
                                 (concat "mouse-2: go to " (match-string 3))
                               "mouse-2: go to this node")
+                 'mouse-face 'highlight)))
+             (when (or not-fontified-p fontify-visited-p)
+               (add-text-properties
+                (match-beginning 1) (match-end 1)
+                (list
                  'font-lock-face
!                 ;; Display visited menu items in a different face
!                 (if (save-match-data
                        (let ((node (if (equal (match-string 3) "")
                                        (match-string 1)
                                      (match-string 3)))
!                             (file (concat Info-current-file "$"))
!                             (hl Info-history-list)
                              res)
!                         (if (string-match "(\\([^)]+\\))" node)
!                             (setq file (concat (match-string 1 node) "$")
!                                   node "Top"))
!                         (while hl
!                           (if (and (string-equal node (nth 1 (car hl)))
!                                    (string-match file (nth 0 (car hl))))
!                               (setq res (car hl) hl nil))
!                           (setq hl (cdr hl)))
!                         res)) 'info-xref-visited 'info-xref))))
!             (when (and not-fontified-p (memq Info-hide-note-references '(t hide)))
                (put-text-property (match-beginning 2) (1- (match-end 6))
                                   'invisible t)
+               ;; Unhide the file name in parens
+               (if (and (match-end 4) (not (eq (char-after (match-end 4)) ?.)))
+                   (remove-text-properties (match-beginning 4) (match-end 4)
+                                           '(invisible t)))
                ;; We need a stretchable space like :align-to but with
                ;; a minimum value.
                (put-text-property (1- (match-end 6)) (match-end 6) 'display
***************
*** 3178,3192 ****
  				       '(space :align-to 24)))
  		  (setq cont t))))))
  
  	(goto-char (point-min))
! 	(while (re-search-forward "http://[-~/[:alnum:]_.${}#%,:?=&]+" nil t)
            (add-text-properties (match-beginning 0) (match-end 0)
                                 '(font-lock-face info-xref
                                   mouse-face highlight
!                                  help-echo "mouse-2: go to this URL")))
  
! 	(Info-fontify-menu-headers)
! 	(set-buffer-modified-p nil)))))
  \f
  
  ;; When an Info buffer is killed, make sure the associated tags buffer
--- 3402,3426 ----
                                       '(space :align-to 24)))
                  (setq cont t))))))
  
+       ;; Add the face `info-xref' to http links
        (goto-char (point-min))
!       (when not-fontified-p
!         (while (re-search-forward "[hf]t?tp://[^ \t\n\"`({<>})']+" nil t)
            (add-text-properties (match-beginning 0) (match-end 0)
                                 '(font-lock-face info-xref
                                                  mouse-face highlight
!                                                 help-echo "mouse-2: go to this URL"))))
! 
!       ;; Add the face `info-menu-header' to any header before a menu entry
!       (goto-char (point-min))
!       (when (and not-fontified-p (re-search-forward "^\\* Menu:" nil t))
!         (put-text-property (match-beginning 0) (match-end 0)
!                            'font-lock-face 'info-menu-header)
!         (while (re-search-forward "\n\n\\([^*\n ].*\\)\n\n?[*]" nil t)
!           (put-text-property (match-beginning 1) (match-end 1)
!                              'font-lock-face 'info-menu-header)))
  
!       (set-buffer-modified-p nil))))
  \f
  
  ;; When an Info buffer is killed, make sure the associated tags buffer
===================================================================

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Karl Berry]

    Seems anchors are useful only for making references to them, not for
    selecting them from completion list.

I don't see any a priori reason to suppose it's not useful to "g"o to an
anchor.  One document's anchor is another document's node.  (I mean, the
division into nodes vs. subnode positioning via anchors is a judgement
call, not an absolute fact.)

That said, I don't feel terribly strongly about whether "g" includes
anchor names in possible completions or not.  Standalone Info does.

      ... the reference names feature.  I still think this feature is
      very useful especially for moving from indexes directly to lines
      where index items are described.  This feature can be replaced
      later gradually by anchors as suggested by Luc.

I don't understand.  I thought that this required index entries to be
used as the second or third arg of xrefs, and I am not aware of any
manuals which make xrefs like that.  Nor is that how @xref is intended
to be used.  Am I confused?  Are you somehow implicitly inserting
references to index definitions?

The other changes seem good, as far as I understand them.  (Discounting
my aversion to Info-hide-note-references.)

Thanks,
karl

Re: Info enhancements

[Eli Zaretskii]

> Date: Fri, 12 Dec 2003 09:24:06 -0500
> From: karl@freefriends.org (Karl Berry)
> 
> That said, I don't feel terribly strongly about whether "g" includes
> anchor names in possible completions or not.  Standalone Info does.

Perhaps an Emacs option is in order.

Re: Info enhancements

[Stefan Monnier]

>> That said, I don't feel terribly strongly about whether "g" includes
>> anchor names in possible completions or not.  Standalone Info does.
> Perhaps an Emacs option is in order.

How do you spell overkill again?


        Stefan

Re: Info enhancements

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: 12 Dec 2003 14:23:04 -0500
> 
> >> That said, I don't feel terribly strongly about whether "g" includes
> >> anchor names in possible completions or not.  Standalone Info does.
> > Perhaps an Emacs option is in order.
> 
> How do you spell overkill again?

It is spelled "whenever we are not sure which behavior to make the
default, have an option so that users can decide."

Re: Info enhancements

[Richard Stallman]

    It is spelled "whenever we are not sure which behavior to make the
    default, have an option so that users can decide."

Our principle is to add an option only if it seems important.  Many
issues are not important enough to justify one.  If a few users really
care, they can change the code.  An option is useful when each
alternative is preferred by many users.

Re: Info enhancements

[Juri Linkov]

karl@freefriends.org (Karl Berry) writes:
>     Seems anchors are useful only for making references to them, not for
>     selecting them from completion list.
>
> I don't see any a priori reason to suppose it's not useful to "g"o to an
> anchor.  One document's anchor is another document's node.  (I mean, the
> division into nodes vs. subnode positioning via anchors is a judgement
> call, not an absolute fact.)
>
> That said, I don't feel terribly strongly about whether "g" includes
> anchor names in possible completions or not.  Standalone Info does.

Since the name of the function bound to "g" is `Info-goto-node'
and its documentation says that this function works only with nodes,
so I thought that it's more correct to omit anchors from a list
of node completions.  I see no harm in removing anchors from a node
list because all nodes still can be reached by the "g" command.
Anchors only provide additional locations within one Info node.
When Info file has many anchors it would be undesirable to overfill
a node list with names that lead to the same Info node.  I think
anchors are only useful in references, for instance, as demonstrated
recently by Luc: @xref{doc-hyperlinks, , Tips for Documentation Strings}.
However, if there is need to go to anchors by selecting their names
from a completion list, then possible solution is either to implement
an additional command with an anchor completion list or to add anchor
names to a completion list of the `Info-index' command because
in fact anchors are more like index items than node names.

>       ... the reference names feature.  I still think this feature is
>       very useful especially for moving from indexes directly to lines
>       where index items are described.  This feature can be replaced
>       later gradually by anchors as suggested by Luc.
>
> I don't understand.  I thought that this required index entries to be
> used as the second or third arg of xrefs, and I am not aware of any
> manuals which make xrefs like that.  Nor is that how @xref is intended
> to be used.  Am I confused?  Are you somehow implicitly inserting
> references to index definitions?

Actually I meant not xrefs but menu entries of Info index nodes,
for instance, like this:

* auto-fill-mode:                        Auto Fill.

Currently, the `Info-index' command (`i') moves point to the place
within a node where an index name is defined, but its functional
equivalent - selecting an index from index menu still don't move point
to the place where an index name is defined.  This patch tries to
improve this (but now it works only if index entries are selected
by the `Info-follow-nearest-node', not by the `Info-menu', this can
be implemented later).

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Richard Stallman]

    Since the name of the function bound to "g" is `Info-goto-node'
    and its documentation says that this function works only with nodes,
    so I thought that it's more correct to omit anchors from a list
    of node completions.

I see no harm in letting it include anchors in completion, given that
it does handle anchor names.  We could rename it "Info-goto"
to avoid the conflict between the name (which comes from a time
before there were anchors) and the functionality (which reflects
the existence of anchors).

Re: Info enhancements

[Juri Linkov]

Richard Stallman <rms@gnu.org> writes:
> I see no harm in letting it include anchors in completion, given that
> it does handle anchor names.  We could rename it "Info-goto"
> to avoid the conflict between the name (which comes from a time
> before there were anchors) and the functionality (which reflects
> the existence of anchors).

Yes, I remember that you already suggested two weeks ago to create
a new function to go to any locator.  This is the function that you
suggest to name Info-goto.  At the same time, Info-goto-node could
be changed to go to node names only, and it makes sense to create also
a new function Info-goto-anchor to go to anchors only.

So, what do you think about this patch?  It provides three functions
Info-goto, Info-goto-node and Info-goto-anchor that differ only by
their completion lists.  I'm still unsure about keybindings to these
functions.  Maybe, "g" - for Info-goto-node, "G" - for Info-goto
and no keybindings for Info-goto-anchor because Info-goto-anchor will
be rarely used (actually, I added Info-goto-anchor because it was too
easy to add it when a completion list creation function was changed
to handle anchor and node names separately).

===================================================================
*** emacs/lisp/info.el	Fri Dec 12 03:29:35 2003
--- emacs/lisp/info.el	Tue Dec 16 03:31:18 2003
***************
*** 227,233 ****
    "Buffer used for indirect tag tables.")
  
  (defvar Info-current-file-completions nil
!   "Cached completion list for current Info file.")
  
  (defvar Info-index-alternatives nil
    "List of possible matches for last `Info-index' command.")
--- 227,236 ----
    "Buffer used for indirect tag tables.")
  
  (defvar Info-current-file-completions nil
!   "Cached node completion list for current Info file.")
! 
! (defvar Info-current-file-anchor-completions nil
!   "Cached anchor completion list for current Info file.")
  
  (defvar Info-index-alternatives nil
    "List of possible matches for last `Info-index' command.")
***************
*** 715,720 ****
--- 718,724 ----
                (setq Info-current-file nil
                      Info-current-subfile nil
                      Info-current-file-completions nil
+                     Info-current-file-anchor-completions nil
                      buffer-file-name nil)
                (erase-buffer)
                (if (eq filename t)
***************
*** 1234,1248 ****
  ;; of the sort that is found in pointers in nodes.
  
  (defun Info-goto-node (nodename &optional fork)
!   "Go to info node named NODENAME.  Give just NODENAME or (FILENAME)NODENAME.
! If NODENAME is of the form (FILENAME)NODENAME, the node is in the Info file
! FILENAME; otherwise, NODENAME should be in the current Info file (or one of
  its sub-files).
  Completion is available, but only for node names in the current Info file.
  If FORK is non-nil (interactively with a prefix arg), show the node in
  a new info buffer.
  If FORK is a string, it is the name to use for the new buffer."
!   (interactive (list (Info-read-node-name "Go to node: ") current-prefix-arg))
    (info-initialize)
    (if fork
        (set-buffer
--- 1238,1266 ----
  ;; of the sort that is found in pointers in nodes.
  
  (defun Info-goto-node (nodename &optional fork)
!   "Go to info node named NODENAME."
!   (interactive (list (Info-read-node-name "Go to node: ")
!                      current-prefix-arg))
!   (Info-goto nodename fork))
! 
! (defun Info-goto-anchor (anchorname &optional fork)
!   "Go to info anchor named ANCHORNAME."
!   (interactive (list (Info-read-node-name "Go to anchor: " nil 'anchor)
!                      current-prefix-arg))
!   (Info-goto anchorname fork))
! 
! (defun Info-goto (nodename &optional fork)
!   "Go to info node or anchor named NODENAME.
! Give just NODENAME or (FILENAME)NODENAME.  If NODENAME is of the
! form (FILENAME)NODENAME, the node is in the Info file FILENAME;
! otherwise, NODENAME should be in the current Info file (or one of
  its sub-files).
  Completion is available, but only for node names in the current Info file.
  If FORK is non-nil (interactively with a prefix arg), show the node in
  a new info buffer.
  If FORK is a string, it is the name to use for the new buffer."
!   (interactive (list (Info-read-node-name "Go to node or anchor: " nil t)
!                      current-prefix-arg))
    (info-initialize)
    (if fork
        (set-buffer
***************
*** 1300,1317 ****
     (t
      (test-completion string Info-read-node-completion-table predicate))))
  
! (defun Info-read-node-name (prompt &optional default)
    (let* ((completion-ignore-case t)
! 	 (Info-read-node-completion-table (Info-build-node-completions))
  	 (nodename (completing-read prompt 'Info-read-node-name-1 nil t)))
      (if (equal nodename "")
  	(or default
! 	    (Info-read-node-name prompt))
        nodename)))
  
  (defun Info-build-node-completions ()
    (or Info-current-file-completions
        (let ((compl nil)
  	    ;; Bind this in case the user sets it to nil.
  	    (case-fold-search t)
  	    (node-regexp "Node: *\\([^,\n]*\\) *[,\n\t]"))
--- 1318,1345 ----
     (t
      (test-completion string Info-read-node-completion-table predicate))))
  
! (defun Info-read-node-name (prompt &optional default anchor)
    (let* ((completion-ignore-case t)
!          (node-completions (Info-build-node-completions))
!          ;; On the first call of `Info-build-node-completions'
!          ;; it should set `Info-current-file-anchor-completions'
!          (anchor-completions Info-current-file-anchor-completions)
! 	 (Info-read-node-completion-table
!           (append
!            ;; Include node names if anchor is nil or t
!            (if (not (eq anchor 'anchor)) node-completions)
!            ;; Include anchor names if anchor is 'anchor or t
!            (if anchor anchor-completions)))
  	 (nodename (completing-read prompt 'Info-read-node-name-1 nil t)))
      (if (equal nodename "")
  	(or default
! 	    (Info-read-node-name prompt anchor))
        nodename)))
  
  (defun Info-build-node-completions ()
    (or Info-current-file-completions
        (let ((compl nil)
+             (compl-anchors nil)
  	    ;; Bind this in case the user sets it to nil.
  	    (case-fold-search t)
  	    (node-regexp "Node: *\\([^,\n]*\\) *[,\n\t]"))
***************
*** 1323,1332 ****
  		  (widen)
  		  (goto-char marker)
  		  (while (re-search-forward "\n\\(Node\\|Ref\\): \\(.*\\)\177" nil t)
! 		    (or (string-equal "Ref" (match-string 1))
! 			(setq compl
  			      (cons (list (match-string-no-properties 2))
! 				    compl)))))
  	      (widen)
  	      (goto-char (point-min))
  	      ;; If the buffer begins with a node header, process that first.
--- 1351,1363 ----
  		  (widen)
  		  (goto-char marker)
  		  (while (re-search-forward "\n\\(Node\\|Ref\\): \\(.*\\)\177" nil t)
! 		    (if (string-equal "Ref" (match-string 1))
! 			(setq compl-anchors
  			      (cons (list (match-string-no-properties 2))
! 				    compl-anchors))
! 			(setq compl
! 			    (cons (list (match-string-no-properties 2))
! 				  compl)))))
  	      (widen)
  	      (goto-char (point-min))
  	      ;; If the buffer begins with a node header, process that first.
***************
*** 1342,1347 ****
--- 1373,1379 ----
  			    (cons (list (match-string-no-properties 1))
  				  compl))))))))
  	(setq compl (cons '("*") compl))
+ 	(set (make-local-variable 'Info-current-file-anchor-completions) compl-anchors)
  	(set (make-local-variable 'Info-current-file-completions) compl))))
  \f
  (defun Info-restore-point (hl)
===================================================================

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Richard Stallman]

    So, what do you think about this patch?  It provides three functions
    Info-goto, Info-goto-node and Info-goto-anchor that differ only by
    their completion lists.  I'm still unsure about keybindings to these
    functions.  Maybe, "g" - for Info-goto-node, "G" - for Info-goto

Do we really need Info-goto-anchor?
Do we really need Info-goto-node, except as an alias
for compatibility?  I don't see a need for them.

Re: Info enhancements

[Juri Linkov]

Richard Stallman <rms@gnu.org> writes:
>     So, what do you think about this patch?  It provides three functions
>     Info-goto, Info-goto-node and Info-goto-anchor that differ only by
>     their completion lists.  I'm still unsure about keybindings to these
>     functions.  Maybe, "g" - for Info-goto-node, "G" - for Info-goto
>
> Do we really need Info-goto-anchor?

We don't need Info-goto-anchor.

> Do we really need Info-goto-node, except as an alias
> for compatibility?  I don't see a need for them.

I think Info-goto-node with a completion list without anchors might be
useful for users that want to see only node names.  For instance,
currently Info-goto-node called on the Emacs manual adds anchors
useless for users:

Coding Systems-Footnote-1          Debugger Operation-Footnote-1
Dissociated Press-Footnote-1       Expressions-Footnote-1
File Names with $                  Fontsets-Footnote-1
General Variables-Footnote-1       Language Environments-Footnote-1
Language Environments-Footnote-2   MS-DOS Printing-Footnote-1
MS-DOS and MULE-Footnote-1         MS-DOS and MULE-Footnote-2
Mail Amusements-Footnote-1         Man Page-Footnote-1
Man Page-Footnote-2                Manifesto-Footnote-1
Manifesto-Footnote-2               Manifesto-Footnote-3
Manifesto-Footnote-4               Manifesto-Footnote-5
Menu Mouse Clicks-Footnote-1       Non-ASCII Rebinding-Footnote-1
Scroll Bars-Footnote-1             Several Buffers-Footnote-1
Shell Mode-Footnote-1              TeX Mode-Footnote-1

But since now anchors are very infrequent in Info files they don't
cause a problem yet.  However, with more widespread use of anchors
completion lists of node names will grow significantly.  So, I think
this discussion should be postponed until Info files have more anchors
and thus it will be clear how many real problems anchors cause.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Richard Stallman]

    I think Info-goto-node with a completion list without anchors might be
    useful for users that want to see only node names.  For instance,
    currently Info-goto-node called on the Emacs manual adds anchors
    useless for users:

Maybe we should make a convention to distinguish between anchors that
users might find interesting and anchors users would never want to
visit.  For instance, maybe we could put spaces into the anchor names
that users should not see, and exclude them from completion.

    But since now anchors are very infrequent in Info files they don't
    cause a problem yet.  However, with more widespread use of anchors
    completion lists of node names will grow significantly.  So, I think
    this discussion should be postponed until Info files have more anchors
    and thus it will be clear how many real problems anchors cause.

That is ok.

Re: Info enhancements

[Luc Teirlinck]

The following is an apparent bug in your proposed patch to info.el.

Do C-h i g (texinfo)example

If you click on the ` of the `@verbatim': reference you indeed go
there, but clicking elsewhere on the reference produces an error.
Same thing for the other two references in that node:

Info-follow-reference: No cross-reference named      `@verbatim'
Info-follow-reference: No cross-reference named `@noindent'
Info-follow-reference: No cross-reference named `@code'

Your patch still seems to try to guess places in the node when one
follows cross-references.  I believe that it would be better to
give up on that, since it would use the second or third argument to
@xref and friends in a way that was not intended.  I believe it is OK
in index menus.

Sincerely,

Luc.

Re: Info enhancements

[Juri Linkov]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:
> If you click on the ` of the `@verbatim': reference you indeed go
> there, but clicking elsewhere on the reference produces an error.

It was caused by an incomplete regexp for references.  I will post
a fix in the next version of the full patch to info.el.

> Your patch still seems to try to guess places in the node when one
> follows cross-references.

No, this is not related to guessing places in the node.

> I believe that it would be better to give up on that, since it would
> use the second or third argument to @xref and friends in a way that
> was not intended.

I still think this is a useful feature.  And currently it works
exactly as the standalone Info reader does.  But we could add an
option for users willing to disable this feature.

> I believe it is OK in index menus.

But even going from index menus it sometimes misses the right place.
After adding information about positions of index entries to Info
files it would work better than guessing.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Date: Fri, 12 Dec 2003 23:38:56 +0200
> 
> However, if there is need to go to anchors by selecting their names
> from a completion list, then possible solution is either to implement
> an additional command with an anchor completion list or to add anchor
> names to a completion list of the `Info-index' command because
> in fact anchors are more like index items than node names.

I disagree with the latter suggestion.  Info-index should provide
completion for index entries; adding anchor names would not add any
useful possible completions, since anchor names are just tags, not
meaningful phrases.

Re: Info enhancements

[Richard Stallman]

Most of the features are good ones, but I think these two
should have different interfaces.

    * Implemented a new `S' command suggested by Eli.  This command is
      bound to a new function `Info-search-case-sensitively' that searches
      for a regexp case-sensitively.  The `Info-search-next' uses the case
      of a previous `Info-search' or `Info-search-case-sensitively' command.

It would be more consistent with the rest of Emacs to make the user
interface be to specify this with a capital letter in the regexp.

    * Added a new keybinding "/" for `Info-search-next' (suggested by Reiner).

I think that `s RET' would be a good way to specify this,
also more consistent with other search commands in Emacs.

Re: Info enhancements

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Sun, 14 Dec 2003 21:35:35 -0500
> 
>     * Implemented a new `S' command suggested by Eli.  This command is
>       bound to a new function `Info-search-case-sensitively' that searches
>       for a regexp case-sensitively.  The `Info-search-next' uses the case
>       of a previous `Info-search' or `Info-search-case-sensitively' command.
> 
> It would be more consistent with the rest of Emacs to make the user
> interface be to specify this with a capital letter in the regexp.

I think these are two independent features.  (The stand-alone reader
supports both.)  The problem is that sometimes you may wish to find an
all-lowercase string in a case-sensitive fashion; starting the regexp
with a capital letter doesn't help in that case.

>     * Added a new keybinding "/" for `Info-search-next' (suggested by Reiner).
> 
> I think that `s RET' would be a good way to specify this,
> also more consistent with other search commands in Emacs.

I think `/' should be simply another binding for `Info-search', for
compatibility with the stand-alone reader.  Then, `s RET' and `/ RET'
will find the next occurrence (the former of these already works in
Emacs, and both work in the stand-alone reader).

Re: Info enhancements

[Richard Stallman]

    >     * Added a new keybinding "/" for `Info-search-next' (suggested by Reiner).
    > 
    > I think that `s RET' would be a good way to specify this,
    > also more consistent with other search commands in Emacs.

    I think `/' should be simply another binding for `Info-search', for
    compatibility with the stand-alone reader.

That sounds ok to me.

Re: Info enhancements

[Juri Linkov]

Eli Zaretskii <eliz@elta.co.il> writes:
>>     * Added a new keybinding "/" for `Info-search-next' (suggested by Reiner).
>> 
>> I think that `s RET' would be a good way to specify this,
>> also more consistent with other search commands in Emacs.
>
> I think `/' should be simply another binding for `Info-search', for
> compatibility with the stand-alone reader.  Then, `s RET' and `/ RET'
> will find the next occurrence (the former of these already works in
> Emacs, and both work in the stand-alone reader).

If `/' will be another binding for `Info-search', then perhaps its
counterpart character `\' would be bound to `Info-search-next'.
However, I already used `\' for `Info-history' buffer.  So, if someone
suggests a better keybinding for `Info-history', then `\' could be used
for `Info-search-next'.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Kim F. Storm]

Juri Linkov <juri@jurta.org> writes:

> Eli Zaretskii <eliz@elta.co.il> writes:
> >>     * Added a new keybinding "/" for `Info-search-next' (suggested by Reiner).
> >> 
> >> I think that `s RET' would be a good way to specify this,
> >> also more consistent with other search commands in Emacs.
> >
> > I think `/' should be simply another binding for `Info-search', for
> > compatibility with the stand-alone reader.  Then, `s RET' and `/ RET'
> > will find the next occurrence (the former of these already works in
> > Emacs, and both work in the stand-alone reader).
> 
> If `/' will be another binding for `Info-search', then perhaps its
> counterpart character `\' would be bound to `Info-search-next'.
> However, I already used `\' for `Info-history' buffer.  So, if someone
> suggests a better keybinding for `Info-history', then `\' could be used
> for `Info-search-next'.

What if / would run Info-search-next if previous command 
was Info-search or Info-search-next.

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

Re: Info enhancements

[Richard Stallman]

    What if / would run Info-search-next if previous command 
    was Info-search or Info-search-next.

That is very inconsistent with other Emacs interfaces, so I would
rather not do that.  I'd rather tell people to use s RET or / RET.

Re: Info enhancements

[Richard Stallman]

    If `/' will be another binding for `Info-search', then perhaps its
    counterpart character `\' would be bound to `Info-search-next'.

That seems too inconsistent with the rest of Emacs.

non-blocking socket io: data limit on read?

[Nic Ferrier]

I have the beginnings of an nbio imap client. It sets up the socket
like this:

      (open-network-stream-nowait
	    "nbimap"
	    con-buffer
	    server 143
	    'nbimap-sentinel
	    'nbimap-filter)

The sentinel doesn't do anything special, it just sets states based
on the connection status.

The filter parses the data passed into it, and then inserts it into
the buffer.

But I am getting some read problems. Large data sets don't arrive in
full. I get a truncated form of the data. The bit I'm recieving is the
last part, so it's not that my filter is being called twice.

As an example I'm issuing an IMAP list command:
 
  0x LIST "" "*"

which returns all my folders, here's what goes over the socket
(sniffed):

T 127.0.0.1:143 -> 127.0.0.1:48929 [AP]
* LIST (\HasNoChildren) "." "INBOX.clients.earthport"..* LIST (\HasNoChildren) "." "INBOX.gnu.gdb"..* LIS
T (\HasNoChildren) "." "INBOX.Spam.test"..* LIST (\HasNoChildren) "." "INBOX.exim"..* LIST (\HasNoChildre
n) "." "INBOX.Spam.clever"..* LIST (\HasNoChildren) "." "INBOX.servlets.jcp"..* LIST (\HasNoChildren) "."
 "INBOX.gnu.libxmlxsl"..* LIST (\HasNoChildren) "." "INBOX.gnu.scheme"..* LIST (\HasNoChildren) "." "INBO
X.lispweb"..* LIST (\HasNoChildren) "." "INBOX.linux"..* LIST (\HasNoChildren) "." "INBOX.nic.policematte
r"..* LIST (\HasNoChildren) "." "INBOX.clients.sweetandmaxwell.java-tips"..* LIST (\HasNoChildren) "." "I
NBOX.gnu.emacs.nics-tip-of-the-day"..* LIST (\HasNoChildren) "." "INBOX.schemeunderground"..* LIST (\HasN
oChildren) "." "INBOX.debian.laptop"..* LIST (\HasNoChildren) "." "INBOX.tf.net"..* LIST (\HasNoChildren)
 "." "INBOX.gnu.servletapi"..* LIST (\HasNoChildren) "." "INBOX.gnu.gcj"..* LIST (\HasNoChildren) "." "IN
BOX.imapua-broken"..* LIST (\HasNoChildren) "." "INBOX.xsl"..* LIST (\HasNoChildren) "." "INBOX.wikipedia
"..* LIST (\HasChildren) "." "INBOX.tf"..* LIST (\HasChildren) "." "INBOX.servlets"..* LIST (\HasNoChildr
en) "." "INBOX.nic.jobs"..* LIST (\HasNoChildren) "." "INBOX.rest"..* LIST (\HasNoChildren) "." "INBOX.po
stgresql"..* LIST (\HasNoChildren) "." "INBOX.oracle"..* LIST (\HasNoChildren) "." "INBOX.nic.egg"..* LIS
T (\HasChildren) "." "INBOX.nic"..* LIST (\HasChildren) "." "INBOX.Spam"..* LIST (\HasNoChildren) "." "IN
BOX.java"..* LIST (\HasNoChildren) "." "INBOX.gnu.paperclips"..* LIST (\HasNoChildren) "." "INBOX.gnu.mai
lutils"..* LIST (\HasNoChildren) "." "INBOX.gnu.jaxp"..* LIST (\HasNoChildren) "." "INBOX.gnu.javamail"..
* LIST (\HasNoChildren) "." "INBOX.gnu.java"..* LIST (\HasNoChildren) "." "INBOX.gnu.gjdoc"..* LIST (\Has
Children) "." "INBOX.gnu.emacs"..* LIST (\HasNoChildren) "." "INBOX.gnu.cvs"..* LIST (\HasNoChildren) "."
 "INBOX.gnu.classpathx-administrivia"..* LIST (\HasChildren) "." "INBOX.gnu"..* LIST (\HasNoChildren) "."
 "INBOX.ferrier_me_uk"..* LIST (\HasChildren) "." "INBOX.debian"..* LIST (\HasNoChildren) "." "INBOX.clie
nts.withyham"..* LIST (\HasChildren) "." "INBOX.clients.sweetandmaxwell"..* LIST (\HasChildren) "." "INBO
X.clients"..* LIST (\HasNoChildren) "." "INBOX.articles"..* LIST (\HasNoChildren) "." "INBOX.affs"..* LIS
T (\HasNoChildren) "." "INBOX.Trash"..* LIST (\HasNoChildren) "." "INBOX.Sent"..* LIST (\Marked \HasChild
ren) "." "INBOX"..02 OK LIST completed...                                                                

But what I get in the data argument to the filter function is this:

  "BOX.debian\"\n* LIST (\\HasNoChildren) \".\" \"INBOX.clients.withyham\"\n* LIST (\\HasChildren) \".\" \"INBOX.clients.sweetandmaxwell\"\n* LIST (\\HasChildren) \".\" \"INBOX.clients\"\n* LIST (\\HasNoChildren) \".\" \"INBOX.articles\"\n* LIST (\\HasNoChildren) \".\" \"INBOX.affs\"\n* LIST (\\HasNoChildren) \".\" \"INBOX.Trash\"\n* LIST (\\HasNoChildren) \".\" \"INBOX.Sent\"\n* LIST (\\Marked \\HasChildren) \".\" \"INBOX\"\n02 OK LIST completed.\n"

Clearly truncated.

My Emacs version is:

   GNU Emacs 21.3.50.2 (i686-pc-linux-gnu, X toolkit)


It's pretty complicated code (process.c) so I don't want to have to
get into it unless I need to   /8->

Has anyone got any ideas?


-- 
Nic Ferrier
http://www.tapsellferrier.co.uk

Re: terminal escapes in Info files?

[Stefan Monnier]

>> How about using what Enriched-Text mode uses in Emacs?  See
>> etc/enriched.doc in the Emacs distro.

Why not HTML ?  There's already an HTML backend in makeinfo, so no
change is needed there.  Also it has the advantage of providing much
more markup so that text-reflowing is possible.

Maybe the current HTML output is not appropriate for an Info-like
reader, so maybe some touch up will be needed, but I think it's
not a bad direction to go.  At least, it's no worse than the idea
of introducing yet-another-markup.

Of course, a direction I'd even prefer is some way to make it possible to
use the TeXinfo file(s) directly (probably with some form of caching for
things like the indices that would be generated on the fly).


        Stefan

Re: terminal escapes in Info files?

[Richard Stallman]

Is HTML adequate for the job of replacing info format?  Yes, it does
something vaguely similar, but that does not mean the answer is yes.
Does the HTML output produced by makeinfo give just as good results in
a browser as info files do in the info readers?  Can we support *all*
the features of info just as well as we do now?

One other obstacle to using HTML instead of info format is that emacs
does not contain a browser at present.  We have considered for years
the idea of installing the W3 package into Emacs, but (from what I
recall) it does not work as well as ordinary browsers.  So I hesitate
to replace info.el with W3.

Re: terminal escapes in Info files?

[David Kastrup]

Richard Stallman <rms@gnu.org> writes:

> Is HTML adequate for the job of replacing info format?  Yes, it does
> something vaguely similar, but that does not mean the answer is yes.
> Does the HTML output produced by makeinfo give just as good results
> in a browser as info files do in the info readers?  Can we support
> *all* the features of info just as well as we do now?

I don't think that the main idea was to replace the various info
readers by browsers, but to change the info format to a strict subset
of HTML, and then make the info readers recognize this subset as an
external format.

The info readers would not need to be able to understand arbitrary
HTML, just the specific HTML subset output by whatever tool was used
for generating it, and native HTML browsers would not necessarily
support everything the info readers could.

I think the first sensible step would be to augment the HTML
generating scripts in the texinfo distribution so as to include the
_complete_ information available in info file format, probably as
some tags usually ignored by typical HTML browsers.

Once the complete information is available in the HTML files, one can
write a reader for it.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: terminal escapes in Info files?

[Eli Zaretskii]

> From: David Kastrup <dak@gnu.org>
> Date: 29 Oct 2003 20:47:46 +0100
> 
> I think the first sensible step would be to augment the HTML
> generating scripts in the texinfo distribution so as to include the
> _complete_ information available in info file format, probably as
> some tags usually ignored by typical HTML browsers.

HTML browsers don't ignore anything, they just don't have commands to
look up menus generated for indices, and don't have search commands
that look up entire documents, not only single pages.

I may be forgetting something, but in general I don't think there's
some Texinfo markup we don't put into HTML as we do into Info format.

Re: terminal escapes in Info files?

[David Kastrup]

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

> > From: David Kastrup <dak@gnu.org>
> > Date: 29 Oct 2003 20:47:46 +0100
> > 
> > I think the first sensible step would be to augment the HTML
> > generating scripts in the texinfo distribution so as to include the
> > _complete_ information available in info file format, probably as
> > some tags usually ignored by typical HTML browsers.
> 
> HTML browsers don't ignore anything,

Not even comments?

> I may be forgetting something, but in general I don't think there's
> some Texinfo markup we don't put into HTML as we do into Info
> format.

So then it should be conceivable to use this HTML as a different info
file format.

-- 
David Kastrup, Kriemhildstr. 15, 44793 Bochum

Re: terminal escapes in Info files?

[Eli Zaretskii]

> From: David Kastrup <dak@gnu.org>
> Date: 29 Oct 2003 23:39:00 +0100
> 
> "Eli Zaretskii" <eliz@elta.co.il> writes:
> 
> > > From: David Kastrup <dak@gnu.org>
> > > Date: 29 Oct 2003 20:47:46 +0100
> > > 
> > > I think the first sensible step would be to augment the HTML
> > > generating scripts in the texinfo distribution so as to include the
> > > _complete_ information available in info file format, probably as
> > > some tags usually ignored by typical HTML browsers.
> > 
> > HTML browsers don't ignore anything,
> 
> Not even comments?

Sorry, it seems I completely misunderstood what you were saying in the
sentence to which I responded.  I thought you were saying that HTML
browsers ignore some parts of the HTML output produced by makeinfo,
and that is why they are less efficient for reading a manual.

Thus, this paragraph:

> > I may be forgetting something, but in general I don't think there's
> > some Texinfo markup we don't put into HTML as we do into Info
> > format.
> 
> So then it should be conceivable to use this HTML as a different info
> file format.

Sure, it's conceivable, it just requires a thorough rewrite of the
standalone reader.

Re: terminal escapes in Info files?

[Richard Stallman]

    I don't think that the main idea was to replace the various info
    readers by browsers, but to change the info format to a strict subset
    of HTML, and then make the info readers recognize this subset as an
    external format.

this might be an ok idea, if people work out the details.
it would be a totally incompatible change, though.

Re: terminal escapes in Info files?

[Richard Stallman]

      1) Older versions friendly,
      2) Future versions friendly.

    (1) is using ANSI escapes directly in Info files.  The benefit is,
    these files will still be displayed correctly by older versions of
    info when -R option is given (though I'm not sure about emacs.) 

it wont work in emacs.

    The downside is, Info becomes an intermediate format rather than
    a final one, always asking for an additional step in the browsers.
    Display will be totally screwed in older versions[1].

this is true for both #1 and #2.  both would need conversion
for emacs to display them.  both would need conversion to
display them properly in stand-alone info, on a non-ansi terminal.

Re: terminal escapes in Info files?

[Alper Ersoy]

Richard Stallman:
>     The downside is, Info becomes an intermediate format rather than
>     a final one, always asking for an additional step in the browsers.
>     Display will be totally screwed in older versions[1].

> this is true for both #1 and #2.  both would need conversion
> for emacs to display them.  both would need conversion to
> display them properly in stand-alone info, on a non-ansi terminal.

Speaking for stand-alone info, there already is stripping
functionality that kicks in when viewing man pages without the -R
option.  Likewise if emacs' browser is capable of viewing man pages,
it too should have such functionality already.

-- 
Alper Ersoy

Re: terminal escapes in Info files?

[Eli Zaretskii]

> Date: Wed, 29 Oct 2003 21:45:44 +0200
> From: Alper Ersoy <dirt@gtk.org>
> 
> Speaking for stand-alone info, there already is stripping
> functionality that kicks in when viewing man pages without the -R
> option.  Likewise if emacs' browser is capable of viewing man pages,
> it too should have such functionality already.

It does (by means of an awk script it runs as a subprocess when it
prepares the man page for display).

Re: terminal escapes in Info files?

[Richard Stallman]

      Likewise if emacs' browser is capable of viewing man pages,
    it too should have such functionality already.

yes, people say that Emacs Lisp code to display those escape sequences
exists.  that would reduce the amount of work for implementing this
change, but wouldn't alter the fact that Info won't handle these
sequences without a change.

I will say yes to something like this only if it uses a cleaner design.
not with terminal escape sequences.

That is my final decision.

Re: terminal escapes in Info files?

[Richard Stallman]

    Since Info is inherently limited to what can be displayed on a terminal,
    it seems like ANSI escape sequences are as reasonable specification of
    the capabilities as anything else?

Info files can be displayed under X and we need not assume they are
limited to a narrow range of display features forever.  But even if we
never support anything beyond what terminal escape sequences can do,
we still should not use them.  There is nothing particularly easy
about converting terminal escape sequences into text properties for
emacs to display.

Re: Info enhancements

[Karl Berry]

    As far as I can see, a better format would have the line number before
    the description rather than after it, with the description indented 6

But then it would not follow the standard format for menus, i.e.,
<term>:<node name>.

Re: Info enhancements

[Robert J. Chassell]

       As far as I can see, a better format would have the line number before
       the description rather than after it, with the description indented 6

   But then it would not follow the standard format for menus, i.e.,
   <term>:<node name>.

I must not have been clear.  The format I meant is:

     * MENU-ENTRY-NAME: NODE-NAME.   LINE_NUMBER. DESCRIPTION

instead of Dave Gillespie's

     * MENU-ENTRY-NAME: NODE-NAME.   DESCRIPTION. LINE_NUMBER. 

or the current

     * MENU-ENTRY-NAME: NODE-NAME.   DESCRIPTION

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

Re: Info enhancements

[Juri Linkov]

"Robert J. Chassell" <bob@rattlesnake.com> writes:
>        As far as I can see, a better format would have the line number before
>        the description rather than after it, with the description indented 6
>
>    But then it would not follow the standard format for menus, i.e.,
>    <term>:<node name>.
>
> I must not have been clear.  The format I meant is:
>
>      * MENU-ENTRY-NAME: NODE-NAME.   LINE_NUMBER. DESCRIPTION
>
> instead of Dave Gillespie's
>
>      * MENU-ENTRY-NAME: NODE-NAME.   DESCRIPTION. LINE_NUMBER. 
>
> or the current
>
>      * MENU-ENTRY-NAME: NODE-NAME.   DESCRIPTION

I think that line numbers in index menus can distract users.
Even if newer versions of Info readers could hide them, they still
will be shown by older versions.

But what do you think about recording the locations of index entries
in the tag table?  For example:

^_
Tag Table:
Node: Top^?123
Ref: menu-entry-name^?12345

Then menu entries would have the following format:

     * menu-entry-name::               Description.

Another variant is to generate a separate tag name for every index type,
e.g.:

^_
Tag Table:
Node: Top^?123
findex: menu-entry-name^?12345
vindex: menu-entry-name^?23456
pindex: menu-entry-name^?34567
cindex: menu-entry-name^?45678

I hope this will not break older Info readers, but newer Info readers
might use this advantage and with index menus marked by a special tag
(e.g. the title "* Variable Index:", etc.) they can read corresponding
locations from the tag table.

The information about locations of index entries could be used by the
`i' command as well.  Note also than in the first variant where index
entries are treated as they were anchors (i.e. by generating a "Ref:"
tag in the tag table) the `g' command can replace the `i' command.

-- 
http://www.jurta.org/emacs/

_______________________________________________
Texinfo home page: http://www.gnu.org/software/texinfo/
texinfo-pretest@texinfo.org
http://ff0.org/mailman/listinfo/texinfo-pretest

Re: Info enhancements

[Robert J. Chassell]

   > I must not have been clear.  The format I meant is:
   >
   >      * MENU-ENTRY-NAME: NODE-NAME.   LINE_NUMBER. DESCRIPTION

and Juri Linkov <juri@jurta.org>:

   I think that line numbers in index menus can distract users.

Yes, they do.  I found them very distracting when they followed the
description and figured I would be much less bothered by seeing them
in front of the description, like this:

* abs:                          147.  Basic Arithmetic.       
* abs (vectors):                18.   Vector and Matrix Arithmetic.  
* abssqr:                       157.  Basic Arithmetic.       
* accum:                        20.   Reducing.               
* acute:                        55.   TeX Language Mode.      
* add:                          90.   Specifying Operators.   
* afixp:                        21.   Nesting and Fixed Points.  

(Adapted from calc-2.02f-patch-1/calc.info-26 -- those are actual line
numbers.  Basicially, the descriptions are lined up, and I can ignore
the line numbers easily.  In Dave Gillespie's format the line numbers
come after the description.  With short descriptions they, too, are
lined up.  That is fine, except that many descriptions are not short,
so the method breaks down.)

You go on to say

   Even if newer versions of Info readers could hide them, they still
   will be shown by older versions.

Yes.

   But what do you think about recording the locations of index entries
   in the tag table?  

The problem is, I think your fear:

   I hope this will not break older Info readers, ...

If the suggestion does not break older Info readers, then I am all
for it.  But I think it will break them.  Karl, what do you think?

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

Re: Info enhancements

[Eli Zaretskii]

> Date: Thu, 4 Dec 2003 13:12:17 +0000 (UTC)
> From: "Robert J. Chassell" <bob@rattlesnake.com>
> 
>    But what do you think about recording the locations of index entries
>    in the tag table?  
> 
> The problem is, I think your fear:
> 
>    I hope this will not break older Info readers, ...
> 
> If the suggestion does not break older Info readers, then I am all
> for it.  But I think it will break them.  Karl, what do you think?

AFAICS, it will break them: the first time Info sees a line in the
tag table that is neither a "Node:" nor a "Ref:" line, it decides
that it's outside the tag table and stops looking for further tags.
So all the nodes and anchors after the first unrecognized line will
be absent from the internal data structure created by the reader from
the tag table, and the corresponding nodes and anchors will not be
found.

Or so it seemed to me when I glanced over the code (of the stand-alone
Info reader).  But you don't need to take my word for it: it is very
easy to edit an Info file, add a line in the tag table that doesn't
match "Node:" and "Ref:" lines, and then see if you can still reach
every node and anchor in that file.

Re: Info enhancements

[Karl Berry]

       I hope this will not break older Info readers, ...

    If the suggestion does not break older Info readers, then I am all
    for it.  But I think it will break them.  Karl, what do you think?

As Eli said, looking at the code in info/nodes.c, it looks like it will.

When we added @anchor, we broke older Info readers.  The saving grace
there was that only Texinfo documents using @anchor were affected (and
of course there were none of those at the time, and are still relatively
few).  The proposed change would affect all Info documents.

We have to do something compatible.

In this case, I like Stefan's idea of explicitly stating "line".  So my
proposal is to change makeinfo to append "(line NNN)" or the equivalent
to the index lines.  Then the info readers can read it and do the right
thing.  For instance:

* Writing index entries:                 Indexing Commands.  (line 1)
* xdvi:                                  Output Formats.  (line 99)

It is not especially beautiful, but it is 100% compatible, and gets the
job done.  If there is a strong consensus that "Line 1." is preferable
to "(line 1)", I don't mind.

Bob, I don't believe we can put the line numbers in front of the node
names.  That would break existing readers.  (I'm also not entirely
convinced that's more readable, to me having the numbers in front of the
node names is more distracting than the reverse, but that's a moot point.)

I don't see the line indications have to align, but if they do, they
could be right justified to column 79 with maybe four spaces for the
number or something.  Personally I'd just as soon not even try to align
them, as in the example above.

Unless there are vehement objections, I will do this for the next
makeinfo release.  It should be straightforward.

Thanks,
k

Re: Info enhancements

[Robert J. Chassell]

   In this case, I like Stefan's idea of explicitly stating "line".  

Yes, this helps a great deal.

   Bob, I don't believe we can put the line numbers in front of the
   node names.  That would break existing readers.  ....

If you use `(line 999)' or `Line 999.' then the menu looks better when
the line numbers go after the node names.  The parenthetical format
looks better to me.

Will it look better if `(line 999)' is always on one line, rather than
broken over two lines?

Thus we might see

* electric-future-map:                   A Sample Variable Description. (line 
                                           999)

unless we make sure that the formatting produces:

* electric-future-map:                   A Sample Variable Description. 
                                           (line 999)

As far as I can see, using parenthetical line numbers, the node name
must end on column 65 (66 being the period), or else the line
expression should all go to the next line.  This puts the closing
parenthesis on column 78.

   I don't see the line indications have to align, ....

I think they will look better if aligned.  Many manuals, such as the
Calc manual, have lots of short node names.  The line numbers will
look better if also in a nice column -- maybe even with the numbers
themselves padded (invisibly) to four columns, so the right hand
parentheses line up.  Menu entries with longer node names push the
line numbers to the right, and that is that.

Thus a menu might look like this (which I indented to make the filling
more obvious):

    * histogram:                    Manipulating Vectors.   (line   78)
    * hms:                          Conversions.            (line   63)
    * holiday:                      Business Days.          (line  114)
    * hour:                         Date Functions.         (line   27)
    * hypot:                        Basic Arithmetic.       (line  174)
    * idiv:                         Basic Arithmetic.       (line  121)
    * idn:                          Building Vectors.       (line   44)
    * ierf:                         Other Features of Rewrite Rules.  
                                      (line   246)
    * if:                           Logical Operations.     (line   89)
    * ilog:                         Logarithmic Functions.  (line   27)

rather than:

    * histogram:                    Manipulating Vectors. (line   78)
    * hms:                          Conversions. (line   63)
    * holiday:                      Business Days. (line  114)
    * hour:                         Date Functions. (line   27)
    * hypot:                        Basic Arithmetic. (line  174)
    * idiv:                         Basic Arithmetic. (line  121)
    * idn:                          Building Vectors. (line   44)
    * ierf:                         Other Features of Rewrite Rules.  
                                      (line   246)
    * if:                           Logical Operations. (line   89)
    * ilog:                         Logarithmic Functions. (line   27)

With an alternative format a menu looks like this:

    * histogram:                    Manipulating Vectors.   Line   78.
    * hms:                          Conversions.            Line   63.
    * holiday:                      Business Days.          Line  114.
    * hour:                         Date Functions.         Line   27.
    * hypot:                        Basic Arithmetic.       Line  174.
    * idiv:                         Basic Arithmetic.       Line  121.
    * idn:                          Building Vectors.       Line   44.
    * ierf:                         Other Features of Rewrite Rules.  
                                      Line   246.
    * if:                           Logical Operations.     Line   89.
    * ilog:                         Logarithmic Functions.  Line   27.

or even

    * histogram:                    Manipulating Vectors.   Line   78
    * hms:                          Conversions.            Line   63
    * holiday:                      Business Days.          Line  114
    * hour:                         Date Functions.         Line   27
    * hypot:                        Basic Arithmetic.       Line  174
    * idiv:                         Basic Arithmetic.       Line  121
    * idn:                          Building Vectors.       Line   44
    * ierf:                         Other Features of Rewrite Rules. 
                                      Line   246
    * if:                           Logical Operations.     Line   89
    * ilog:                         Logarithmic Functions.  Line   27

rather than

    * histogram:                    Manipulating Vectors. Line   78.
    * hms:                          Conversions. Line   63.
    * holiday:                      Business Days. Line  114.
    * hour:                         Date Functions. Line   27.
    * hypot:                        Basic Arithmetic. Line  174.
    * idiv:                         Basic Arithmetic. Line  121.
    * idn:                          Building Vectors. Line   44.
    * ierf:                         Other Features of Rewrite Rules.  
                                      Line   246.
    * if:                           Logical Operations. Line   89.
    * ilog:                         Logarithmic Functions. Line   27.

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

Re: Info enhancements

[Kai Grossjohann]

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

> * electric-future-map:                   A Sample Variable Description. 
>                                            (line 999)

Actually, I found find it nice if the "(line 999)" part would align
with all the other line numbers that aren't on extra lines.  What do
people think?

Kai

Re: Info enhancements

[Eli Zaretskii]

> From: Kai Grossjohann <kai@emptydomain.de>
> Date: Sat, 06 Dec 2003 21:01:11 +0000
> 
> > * electric-future-map:                   A Sample Variable Description. 
> >                                            (line 999)
> 
> Actually, I found find it nice if the "(line 999)" part would align
> with all the other line numbers that aren't on extra lines.  What do
> people think?

I tend to agree.  The question is, as always, is it feasible to force
makeinfo to do that?

Re: Info enhancements

[Kai Grossjohann]

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

>> From: Kai Grossjohann <kai@emptydomain.de>
>> Date: Sat, 06 Dec 2003 21:01:11 +0000
>> 
>> > * electric-future-map:                   A Sample Variable Description. 
>> >                                            (line 999)
>> 
>> Actually, I found find it nice if the "(line 999)" part would align
>> with all the other line numbers that aren't on extra lines.  What do
>> people think?
>
> I tend to agree.  The question is, as always, is it feasible to force
> makeinfo to do that?

Oh, I think I misunderstood.  I thought the original suggestion was to
have makeinfo automatically put "(line 999)" on a new line.  In that
case, I didn't expect that the number of leading spaces (or tabs?) on
that line would make a lot of difference.  (And computing the right
number of spaces to make sure that the ")" is in column 78 doesn't
seem difficult.)

I guess there is some other issue that I'm not seeing.

Kai

Re: Info enhancements

[Eli Zaretskii]

> From: Kai Grossjohann <kai@emptydomain.de>
> Date: Sun, 07 Dec 2003 14:49:52 +0000
> >> 
> >> > * electric-future-map:                   A Sample Variable Description. 
> >> >                                            (line 999)
> >> 
> >> Actually, I found find it nice if the "(line 999)" part would align
> >> with all the other line numbers that aren't on extra lines.  What do
> >> people think?
> >
> > I tend to agree.  The question is, as always, is it feasible to force
> > makeinfo to do that?
> 
> Oh, I think I misunderstood.  I thought the original suggestion was to
> have makeinfo automatically put "(line 999)" on a new line.  In that
> case, I didn't expect that the number of leading spaces (or tabs?) on
> that line would make a lot of difference.  (And computing the right
> number of spaces to make sure that the ")" is in column 78 doesn't
> seem difficult.)
> 
> I guess there is some other issue that I'm not seeing.

What I think you are missing is that the alignment of the text "A
Sample Variable Description" is determined by the Texinfo source.  So
when makeinfo outputs the "(line 999)" thingy, it needs to somehow
``recall' the column number where that text begins (since it is not
known apriori, so cannot be simply a constant in the code).  This
requires that makeinfo ``remembers'' that column when it outputs the
line before the line number.  As makeinfo is essentially a one-pass
translator, I'm not sure it is easy to get it to remember such things.

But I might be mistaken: it's been a while since I last hacked
makeinfo.

Re: Info enhancements

[Kai Grossjohann]

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

> What I think you are missing is that the alignment of the text "A
> Sample Variable Description" is determined by the Texinfo source.  So
> when makeinfo outputs the "(line 999)" thingy, it needs to somehow
> ``recall' the column number where that text begins (since it is not
> known apriori, so cannot be simply a constant in the code).  This
> requires that makeinfo ``remembers'' that column when it outputs the
> line before the line number.  As makeinfo is essentially a one-pass
> translator, I'm not sure it is easy to get it to remember such things.

The original post showed something like this:

* foo::         Short description                       (line   42)
* bar::         A very long description causing the line number to wrap
                  (line 999)

I suggested to produce this output:

* foo::         Short description                       (line   42)
* bar::         A very long description causing the line number to wrap
                                                        (line  999)

The "(line  999)" part can be positioned without knowing the column
where "A very long description..." starts.  Instead, you can just go
to column fill-column minus 11 (the width of "(line XXXX)").

Right?

Kai

Re: Info enhancements

[Eli Zaretskii]

> From: Kai Grossjohann <kai@emptydomain.de>
> Date: Sun, 07 Dec 2003 16:42:23 +0000
> 
> I suggested to produce this output:
> 
> * foo::         Short description                       (line   42)
> * bar::         A very long description causing the line number to wrap
>                                                         (line  999)
> 
> The "(line  999)" part can be positioned without knowing the column
> where "A very long description..." starts.  Instead, you can just go
> to column fill-column minus 11 (the width of "(line XXXX)").

If you always want to go to a certain column, it should be easy.  I
thought you wanted to align "line 999" on the column with the first
non-blank character of the previous line.

Re: Info enhancements

[Richard Stallman]

Nobody seems to be considering a format line

  * foo: Node (line 42).       A short description.

which I and at least one other person thought would be
more natural and clear.

Re: Info enhancements

[Stefan Monnier]

> Nobody seems to be considering a format line
>   * foo: Node (line 42).       A short description.

> which I and at least one other person thought would be
> more natural and clear.

But indices are a funny kind of menu where there's a lot of space between
`foo' and `Node' and where there is typically no `a short description'.
I.e. it looks like:

  * foo:                               Node.

so your proposal is to use

  * foo:                               Node (line 42).

which is not aesthetically very different from

  * foo:                               Node. (line 42)

or

  * foo:                               Node.  Line 42.

It does have the difference that it puts the line info in the
"location" part of the reference, which is probably a good thing.


        Stefan

Re: Info enhancements

[Juri Linkov]

karl@freefriends.org (Karl Berry) writes:
> For instance:
>
> * Writing index entries:                 Indexing Commands.  (line 1)
> * xdvi:                                  Output Formats.  (line 99)
>
> It is not especially beautiful, but it is 100% compatible, and gets the
> job done.

Yes, it is not beautiful.  It is ugly.  The information about line
numbers is useless for users.  Certainly we shouldn't overburden users
with purely technical information.  Moreover, it don't solve the
problem of using index entries in cross-references.  For instance:

     This function looks up the target in *Note
     file-coding-system-alist: Default Coding Systems, *Note
     process-coding-system-alist: Default Coding Systems, or
     *Note network-coding-system-alist: Default Coding Systems,
     depending on OPERATION.

These cross-references refer to variables indexed by the @vindex
command, but there is no place for line numbers here.  So, I urge you
to find a better solution.  If placing this information in the tag
table will break older version (though this should be verified yet),
then we should try to find another safe place in Info files (e.g. some
unreachable Info node).  Do you know such a place?

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Karl Berry]

         This function looks up the target in *Note
         file-coding-system-alist: Default Coding Systems, *Note
         process-coding-system-alist: Default Coding Systems, or
         *Note network-coding-system-alist: Default Coding Systems,
         depending on OPERATION.

    These cross-references refer to variables indexed by the @vindex
    command, but there is no place for line numbers here.  

What is the Texinfo source that is generating this?  Texinfo does not
have a way to make an xref to index entries, as far as I know.

Re: Info enhancements

[Juri Linkov]

karl@freefriends.org (Karl Berry) writes:
>          This function looks up the target in *Note
>          file-coding-system-alist: Default Coding Systems, *Note
>          process-coding-system-alist: Default Coding Systems, or
>          *Note network-coding-system-alist: Default Coding Systems,
>          depending on OPERATION.
>
>     These cross-references refer to variables indexed by the @vindex
>     command, but there is no place for line numbers here.  
>
> What is the Texinfo source that is generating this?  Texinfo does not
> have a way to make an xref to index entries, as far as I know.

This is generated by the `@ref' with two arguments:

     @ref{Default Coding Systems, file-coding-system-alist}

True, the `file-coding-system-alist' is the cross reference name here.
But  it can  be  used to  find  the correct  position  of index  entry
definition.   The  standalone  Info  reader  already  uses  the  cross
reference name  to move point to  its first occurrence  within an Info
node, but this could be improved to search the cross reference name in
the  tag table  of index  entries with  their positions  and  use this
information  for more  accurate navigation  by cross  references.

Another variant is to generate Ref: tags in the tag table for every
index entry and use them as anchors, for instance:

     @ref{file-coding-system-alist}

would move directly to the position where the `@vindex' command was
defined in the Texinfo source.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Date: Fri, 05 Dec 2003 17:57:31 +0200
> >
> > What is the Texinfo source that is generating this?  Texinfo does not
> > have a way to make an xref to index entries, as far as I know.
> 
> This is generated by the `@ref' with two arguments:
> 
>      @ref{Default Coding Systems, file-coding-system-alist}

A digression: My personal view is that this is bad usage of Texinfo.
Instead of saying

   This function looks up the target in @ref{Default Coding Systems,
   file-coding-system-alist}

which looks awkward in Info and downright incomprehensible in the
printed copy, it is much better to say

   This function looks up the target in
   @code{file-coding-system-alist} (@pxref{Default Coding Systems,
   file-coding-system-alist})

Re: Info enhancements

[Juri Linkov]

"Eli Zaretskii" <eliz@elta.co.il> writes:
>> From: Juri Linkov <juri@jurta.org>
>> Date: Fri, 05 Dec 2003 17:57:31 +0200
>> >
>> > What is the Texinfo source that is generating this?  Texinfo does not
>> > have a way to make an xref to index entries, as far as I know.
>> 
>> This is generated by the `@ref' with two arguments:
>> 
>>      @ref{Default Coding Systems, file-coding-system-alist}
>
> A digression: My personal view is that this is bad usage of Texinfo.
> Instead of saying
>
>    This function looks up the target in @ref{Default Coding Systems,
>    file-coding-system-alist}
>
> which looks awkward in Info and downright incomprehensible in the
> printed copy, it is much better to say
>
>    This function looks up the target in
>    @code{file-coding-system-alist} (@pxref{Default Coding Systems,
>    file-coding-system-alist})

But this looks awkward in Info with Info-hide-note-references equal t:

   This function looks up the target in file-coding-system-alist
   (see file-coding-system-alist).

whereas the first variant is better:

   This function looks up the target in file-coding-system-alist.

So the variant that will look equally good in Info with
Info-hide-note-references equal to t or nil and in the printed copy
has yet to be found.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Date: Sat, 06 Dec 2003 02:15:43 +0200
> 
> > it is much better to say
> >
> >    This function looks up the target in
> >    @code{file-coding-system-alist} (@pxref{Default Coding Systems,
> >    file-coding-system-alist})
> 
> But this looks awkward in Info with Info-hide-note-references equal t:

Yet another sign that Info-hide-note-references is not such a good
idea, if you ask me.

> So the variant that will look equally good in Info with
> Info-hide-note-references equal to t or nil and in the printed copy
> has yet to be found.

That might be so, but my point was that the example you've shown is
not something people should follow.  Try to TeX it, and you will
understand what I mean.

Re: Info enhancements

[Luc Teirlinck]

Juri Linkov wrote:

	This function looks up the target in *Note
	file-coding-system-alist: Default Coding Systems, *Note
	process-coding-system-alist: Default Coding Systems, or
	*Note network-coding-system-alist: Default Coding Systems,
	depending on OPERATION.

I will soon commit several changes to (elisp)Non-ASCII Characters.  I
personally believe the xref you are referring to got into
`(elisp)Default Coding Systems' by mistake.  I originally just erased
it.  I am reluctant to do that now since it is used as the prime
example in this thread and with your feature, it might make sense in
Info.  As Eli pointed out, the above is the result of non-standard
Texinfo usage and looks weird.  The xref still makes no sense in the
printed version, since it refers to the beginning of the same section.

I currently have:

===File ~/refs1=============================================
This function looks up the target in @code{file-coding-system-alist},
@code{process-coding-system-alist}, or
@code{network-coding-system-alist}, depending on @var{operation}.
@ifinfo
@ifnotplaintext
@xref{Default Coding Systems, file-coding-system-alist}.
@end ifnotplaintext
@end ifinfo

============================================================

Do you really need those _three_ xrefs?  The three alists are
described in succession starting with `file-coding-system-alist'.  I
am even still not completely sure that we really need any xref here,
since the descriptions are right above, but it certainly makes more
sense with your feature than without it.  It is, of course, trivial to
add the other two xrefs, should this be considered desirable.

Sincerely,

Luc.

Re: Info enhancements

[Luc Teirlinck]

There seems to be a bug in the Info history buffer machinery of your
patch.

Do C-h i m elisp RET \ and press return on the `Top: (elisp)Top.'
line.  We somehow go to `Top: (dir)Top.'.  In fact, any `Top: 'line
seems to go to `Top: (dir)Top.'

Sincerely,

Luc.

Re: Info enhancements

[Luc Teirlinck]

My previous message was, of course addressed to Juri.  I inadvertently
sent it to myself.

Sincerely,

Luc.

Re: Info enhancements

[Juri Linkov]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:
> There seems to be a bug in the Info history buffer machinery of your
> patch.
>
> Do C-h i m elisp RET \ and press return on the `Top: (elisp)Top.'
> line.  We somehow go to `Top: (dir)Top.'.  In fact, any `Top: 'line
> seems to go to `Top: (dir)Top.'

This is due to the limitation of the function `Info-follow-reference'.
It don't follow a reference under point, but instead it searches the
first occurrence of reference name from the buffer beginning.  The
Info history buffer has many references with the name `Top', but
`Info-follow-reference' always follows only the first one.  I already
noticed the same problem in Glossary node where no term name and
node name are allowed with the same name in references.

So currently no references with the same name are allowed in the same
Info node.  I suppose the purpose of such limitation was to make
possible to select a reference from the completion list of all references
where names should be unique.  But we can remove such limitation by
adding a new argument `nodename' to the `Info-follow-reference'.  This
argument can be transfered from the `Info-try-follow-nearest-node'
to explicitly specify a reference under point.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Date: Sat, 06 Dec 2003 01:52:01 +0200
> 
> This is due to the limitation of the function `Info-follow-reference'.
> It don't follow a reference under point, but instead it searches the
> first occurrence of reference name from the buffer beginning.

IIRC, the stand-alone Info reader was fixed to prefer the reference
at point, if there is one, and otherwise try the reference that is
closest to point.

> So currently no references with the same name are allowed in the same
> Info node.

If that is so (I'm surprised that it is, btw), it's IMHO a grave bug
in the Emacs Info reader: there are quite a few manuals out there
which do have several references to the same node.  The stand-alone
reader doesn't have this limitation.

> But we can remove such limitation by
> adding a new argument `nodename' to the `Info-follow-reference'.

Please don't.  Let's not introduce yet another haphazard change into
the Info format.  As the case of the stand-alone reader shows, this
limitation can be lifted without any changes to the Info format per
se.

Re: Info enhancements

[Luc Teirlinck]

Eli Zaretskii wrote:

   IIRC, the stand-alone Info reader was fixed to prefer the reference
   at point, if there is one, and otherwise try the reference that is
   closest to point.

In my bug report to Juri I was not talking about references (@ref and
the like), but about _menu entries_.  Juri talked about "references".
Juri, is this really what you meant?  I actually made myself a mini
.texi file to check whether there was a similar problem with
references, but everything seemed to work OK.

Menu entries with the same name would give trouble for the `m'
(Info-menu) command.  But we have no control over what winds up in the
user's (dir)Top.  It believe that it is a problem that needs to be
fixed.

   > But we can remove such limitation by
   > adding a new argument `nodename' to the `Info-follow-reference'.

   Please don't.  Let's not introduce yet another haphazard change into
   the Info format.  As the case of the stand-alone reader shows, this
   limitation can be lifted without any changes to the Info format per
   se.

Either I misunderstand you, or you misunderstood Juri or I
misunderstood Juri.  `Info-follow-reference' is a function in info.el.
It has nothing to do with the Info format or formatting, it is a
navigational function.

Sincerely,

Luc.

Re: Info enhancements

[Eli Zaretskii]

> Date: Sat, 6 Dec 2003 10:45:49 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
>    IIRC, the stand-alone Info reader was fixed to prefer the reference
>    at point, if there is one, and otherwise try the reference that is
>    closest to point.
> 
> In my bug report to Juri I was not talking about references (@ref and
> the like), but about _menu entries_.  Juri talked about "references".
> Juri, is this really what you meant?  I actually made myself a mini
> .texi file to check whether there was a similar problem with
> references, but everything seemed to work OK.
> 
> Menu entries with the same name would give trouble for the `m'
> (Info-menu) command.

IIRC, the stand-alone reader handles this problems as well (by
preferring the menu entry that is closest to point).

>    > But we can remove such limitation by
>    > adding a new argument `nodename' to the `Info-follow-reference'.
> 
>    Please don't.  Let's not introduce yet another haphazard change into
>    the Info format.  As the case of the stand-alone reader shows, this
>    limitation can be lifted without any changes to the Info format per
>    se.
> 
> Either I misunderstand you, or you misunderstood Juri or I
> misunderstood Juri.  `Info-follow-reference' is a function in info.el.
> It has nothing to do with the Info format or formatting, it is a
> navigational function.

Same difference.  There's no need to do that, IMHO, so let's not.

Really, the only positive outcome of this longish thread is the
more-or-less widespread consensus that we should develop an XML-based
reader.  Could we please drop the (IMHO futile) attempts to ``fix''
the current Info readers by making them slicker than they were
designed to be?

Re: Info enhancements

[Luc Teirlinck]

Eli Zaretskii wrote:

   Same difference.  There's no need to do that, IMHO, so let's not.

   Really, the only positive outcome of this longish thread is the
   more-or-less widespread consensus that we should develop an XML-based
   reader.  Could we please drop the (IMHO futile) attempts to ``fix''
   the current Info readers by making them slicker than they were
   designed to be?

This thread concerns ten changes proposed by Juri in a patch (which I
personally applied, so I know more or less what it does).  This has
nothing to do with the move to XML, discussed in a variety of threads
unrelated to this one.  In this one we are discussing the ten changes
in Juri's patch.

Of these ten there is _one_ (the playing around with the arguments to
xref and with `Info-find-index-name', to determine where a reference
leads to) to which your last sentence indeed might apply.

The "subthread" you responded to is concerned with the "Info history
buffer" feature in Juri's patch, unrelated to the above feature.

Right now, we are trying to deal with an apparent problem that the
Elisp info reader has with similarly named references (it were really
references, not menu entries, I just got confused for a moment).  I do
not understand in what way your last sentence, quoted above, relates
to this problem, or to the way Juri was proposing to solve it.  There
would be other ways to solve the problem, if Juri's way were
objectionable.  But, your last sentence seems to imply that you
consider _all_ attempts to solve the problem futile and that they
should be dropped immediately.  Is this really what you mean?

Sincerely,

Luc.

Re: Info enhancements

[Richard Stallman]

I think it would be best if we end the discussion here
of the idea of generating a new XML form from Texinfo.
Those who would like to implement this are welcome to do so,
but discussing it on emacs-devel is not very useful.

Re: Info enhancements

[Luc Teirlinck]

>From my previous message:

   In my bug report to Juri I was not talking about references (@ref and
   the like), but about _menu entries_.

No I was not.  I got confused.  We _were_ talking about actual
references. I will try to figure out why I did _not_ see the same bug
in the file I constructed.

Sincerely,

Luc.

Re: Info enhancements

[Luc Teirlinck]

Eli Zaretskii wrote:

   IIRC, the stand-alone Info reader was fixed to prefer the reference
   at point, if there is one, and otherwise try the reference that is
   closest to point.

Let us first decide whether there is a bug in info.el or not.  If not,
I believe that it would be easy for Juri to fix what would, in that
case, be a bug in his patch.  The problem(?) is that a node can not
have two references to two different nodes with exactly the same name.
Maybe this is a reasonable restriction and no bug?  If it is a bug,
here is a test case.

Source file:

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

@node Top
@top Top

@menu
* name:entry.           description.
@end menu

@node entry
@chapter Entry

This node is called @samp{entry}
@xref{Top}.  @xref{(dir)Top}.  @xref{(elisp)Top}. @xref{(elisp)Top, Top}.

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

The .info file is attached below.

Clicking return on the reference produced by `@xref{(elisp)Top}.'
leads to (elisp)top, but the reference produced by `@xref{(elisp)Top,
Top}.' leads to (experiment)Top in Emacs Info.  Is this a bug?

The stand-alone Info goes to (elisp)top.

@unrelated 
But to a strange place there:

* Related Topics::          Cross-references to specific Lisp primitives

I am afraid to mix two issues up more than they already are.  At the
risk of doing that, note that *on a completely unrelated note*, the
strange place the stand-alone info goes to, once again seems to say:
do not try to guess positions if you are not completely sure.
@end unrelated

.info file:

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

\x1f
File: experiment.info,  Node: Top,  Next: entry,  Up: (dir)

Top
***

* Menu:

* name:entry.           description.

\x1f
File: experiment.info,  Node: entry,  Prev: Top,  Up: Top

Entry
*****

This node is called `entry' *Note Top::.  *Note (dir)Top::.  *Note
(elisp)Top::. *Note Top: (elisp)Top.


\x1f
Tag Table:
Node: Top\x7f81
Node: entry\x7f200
\x1f
End Tag Table
============================================================

Re: Info enhancements

[Luc Teirlinck]

Juri Linkov wrote:

   So currently no references with the same name are allowed in the same
   Info node.  I suppose the purpose of such limitation was to make
   possible to select a reference from the completion list of all references
   where names should be unique.  But we can remove such limitation by
   adding a new argument `nodename' to the `Info-follow-reference'.  This
   argument can be transfered from the `Info-try-follow-nearest-node'
   to explicitly specify a reference under point.

Why do you need an extra argument to Info-follow-reference?  It seems
to me that Info-follow-reference has access to the value of `(point)'
and should be able to get things right from that value.

Sincerely,

Luc.

Re: Info enhancements

[Luc Teirlinck]

>From my previous message:

   Why do you need an extra argument to Info-follow-reference?

Or do you plan to ask the user for more information if the user enters
`f top', `f variables' or whatever and that could refer to nodes in
several different manuals?  In which situations would you use that
extra argument and how?

Sincerely,

Luc.

Re: Info enhancements

[Juri Linkov]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:
>    Why do you need an extra argument to Info-follow-reference?  It seems
>    to me that Info-follow-reference has access to the value of `(point)'
>    and should be able to get things right from that value.

I thought that since `Info-try-follow-nearest-node' already matches a
reference name regexp, this regexp could be extended to match a node
name too, and its value could be transfered to Info-follow-reference
by extra argument.  However, this can be done in Info-follow-reference
as well given than point is still located on a position with reference.

> Or do you plan to ask the user for more information if the user enters
> `f top', `f variables' or whatever and that could refer to nodes in
> several different manuals?

Yes, there is another problem with similarly named references: how to
select a reference unambiguously from a completion list.  I thought
that node name could be concatenated with a reference name to form one
item string in a completion list to disambiguate them, for instance:

Top::
Top: (elisp)Top

and after an item is selected from the minibuffer to split it to two
values: reference name and node name and use them as function
arguments.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Luc Teirlinck]

I just checked that the feature in your patch that we have been mostly
discussing (the alternative to @anchor) actually _breaks_ @anchor.
After applying your patch, @anchor does not work anymore.  So, I
definitely believe that this particular feature should be removed from
your patch.

Sincerely,

Luc.

Re: Info enhancements

[Luc Teirlinck]

Juri Linkov wrote:

   I thought that since `Info-try-follow-nearest-node' already matches a
   reference name regexp, this regexp could be extended to match a node
   name too, and its value could be transfered to Info-follow-reference
   by extra argument.  However, this can be done in Info-follow-reference
   as well given than point is still located on a position with reference.

If you are going to fix the bug, then you are probably best placed to
decide what the best way to do so is.

   Yes, there is another problem with similarly named references: how to
   select a reference unambiguously from a completion list.  I thought
   that node name could be concatenated with a reference name to form one
   item string in a completion list to disambiguate them, for instance:

   Top::
   Top: (elisp)Top

   and after an item is selected from the minibuffer to split it to two
   values: reference name and node name and use them as function
   arguments.

I personally believe that we should indeed tell the user that the
completion does not specify a unique alternative and allow him to make
it unique.

Sincerely,

Luc.

Re: Info enhancements

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Date: Sun, 07 Dec 2003 19:31:41 +0200
> 
> Yes, there is another problem with similarly named references: how to
> select a reference unambiguously from a completion list.

Doesn't the stand-alone reader handle this correctly?  (I don't
remember.)  If it does, we could do something similar in Emacs.

Re: Info enhancements

[Luc Teirlinck]

Eli Zaretskii wrote:

   > From: Juri Linkov <juri@jurta.org>
   > Date: Sun, 07 Dec 2003 19:31:41 +0200
   > 
   > Yes, there is another problem with similarly named references: how to
   > select a reference unambiguously from a completion list.

   Doesn't the stand-alone reader handle this correctly?  (I don't
   remember.)  If it does, we could do something similar in Emacs.

The user invokes `f' and starts typing in the minibuffer.

If the node is not unique because the _file_ is not unique, the
stand-alone reader chooses a node based on the value of point in the
*info* buffer.

But the user is entering input in the minibuffer.  Hence I believe it
would make more sense to ask for extra characters, as `f' does in all
other situations where the node can not be uniquely determined by the
minibuffer contents.

Sincerely,

Luc.

Re: Info enhancements

[Juri Linkov]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:
> Eli Zaretskii wrote:
>    > From: Juri Linkov <juri@jurta.org>
>    > Date: Sun, 07 Dec 2003 19:31:41 +0200
>    > 
>    > Yes, there is another problem with similarly named references: how to
>    > select a reference unambiguously from a completion list.
>
>    Doesn't the stand-alone reader handle this correctly?  (I don't
>    remember.)  If it does, we could do something similar in Emacs.
>
> The user invokes `f' and starts typing in the minibuffer.
>
> If the node is not unique because the _file_ is not unique, the
> stand-alone reader chooses a node based on the value of point in the
> *info* buffer.

Yes, the stand-alone reader handles this somehow interestingly.
A completion list always has only one unique name, but if point is
somewhere above the first reference with this name in Info node then
after selecting a reference name from a completion list it goes to the
node from the first reference.  If point is somewhere below the second
reference with the same name then it goes to the second node.  If
point is between first and second reference with the same name then it
goes to the closest node.  We could do similar in Emacs if
disambiguating reference names in a completion list by adding node
names to them is undesirable.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Date: Sun, 07 Dec 2003 21:27:05 +0200
> 
> Yes, the stand-alone reader handles this somehow interestingly.
> A completion list always has only one unique name, but if point is
> somewhere above the first reference with this name in Info node then
> after selecting a reference name from a completion list it goes to the
> node from the first reference.  If point is somewhere below the second
> reference with the same name then it goes to the second node.  If
> point is between first and second reference with the same name then it
> goes to the closest node.

IIRC, it simply chooses the reference that is closest to point, for
some definition of ``closest''.  (Since a reference spans more than a
single character, the precise definition of ``closest'' is somewhat
vague; I needed some simple heuristics to get reasonable results.)

Re: Info enhancements

[Eli Zaretskii]

> Date: Sun, 7 Dec 2003 12:57:46 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
>    Doesn't the stand-alone reader handle this correctly?  (I don't
>    remember.)  If it does, we could do something similar in Emacs.
> 
> The user invokes `f' and starts typing in the minibuffer.
> 
> If the node is not unique because the _file_ is not unique, the
> stand-alone reader chooses a node based on the value of point in the
> *info* buffer.
> 
> But the user is entering input in the minibuffer.  Hence I believe it
> would make more sense to ask for extra characters

You can still type more characters if you want, don't you?

The preference given to the reference at or closest to point does
sound like a reasonable feature, doesn't it?

If you agree to those two points, why force the user to type more when
in most cases the alternative suggested by the reader is good?

(I usually press TAB before hitting RET, just to be sure I'm going to
wind up at the right spot.  But even if I didn't, typing `l' will
bring me back to where I was, and then I can type the right node name
explicitly.)

In any case, unless you think the behavior of the stand-alone reader
is undesirable, I think we should for starters make Emacs behave
similarly.

Re: Info enhancements

[Juri Linkov]

Eli Zaretskii <eliz@elta.co.il> writes:
> The preference given to the reference at or closest to point does
> sound like a reasonable feature, doesn't it?

I agree that using the reference closest to point is a reasonable
feature.  Firstly, the cases with two references with the same name
in one Info node are very rare.  Secondly, mostly users put point on
the reference before following it.  So this feature will work in the
most cases.  So I agree that Emacs should behave similarly.  I'll look
over the source code of the stand-alone reader.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Luc Teirlinck]

Eli Zaretskii wrote:

   You can still type more characters if you want, don't you?

No (at least not currently), because `f' is based on the reference
name (not the node name, as we may have abusively said sometimes).
Hence, if two references have the same name you currently can not type
more characters, because the reference name has no file name
component.  I believe Juri wanted to make it possible to append a file
name to the reference name to distinguish. (If I understood
correctly.)

   The preference given to the reference at or closest to point does
   sound like a reasonable feature, doesn't it?

Can give some bad surprises, like typing `f' followed by a reference
one is seeing on the screen and the reader going to a "closer"
off-screen reference of the same name.

Anyway, in practice the situation only occurs in very special buffers
like Juri's history buffer, so it is not worth an endless discussion.

If you and Juri both believe that it is better to go with the
stand-alone reader's behavior, then that is fine with me.

Sincerely,

Luc.

Re: Info enhancements

[Eli Zaretskii]

> Date: Mon, 8 Dec 2003 21:34:15 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
>    The preference given to the reference at or closest to point does
>    sound like a reasonable feature, doesn't it?
> 
> Can give some bad surprises, like typing `f' followed by a reference
> one is seeing on the screen and the reader going to a "closer"
> off-screen reference of the same name.

Does this really happen in practice?  That is, can you really create a
situation where an off-screen reference wins?  I'd think the
stand-alone reader should avoid that pitfall, but I might be mistaken.

Re: Info enhancements

[Luc Teirlinck]

Eli Zaretskii wrote:

   > Can give some bad surprises, like typing `f' followed by a reference
   > one is seeing on the screen and the reader going to a "closer"
   > off-screen reference of the same name.

   Does this really happen in practice?  That is, can you really create a
   situation where an off-screen reference wins?

Yes.  In the `Entry' node of the following file, put point at the
start of the line containing the first of the series of a's.  Do:
M-0 C-l.

The `@xref{Top, , , dir}.' is now out of view. We do `f' and see:

Follow xref (Top): 

If we accept the default (or type Top), we go to (dir)Top, an
off-screen reference, whereas `@xref{Top, Top, , elisp}.' is visible.

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

@node Top
@top Top

@menu
* name: entry.           description.
@end menu

@node entry
@chapter Entry

This node is called @samp{entry}
@xref{Top}.  @xref{Top, , , dir}.

a

a

a

a

a

@xref{Top, Top, , elisp}.

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

Resulting .info file:

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

\x1f
File: experiment.info,  Node: Top,  Next: entry,  Up: (dir)

Top
***

* Menu:

* name: entry.           description.

\x1f
File: experiment.info,  Node: entry,  Prev: Top,  Up: Top

Entry
*****

This node is called `entry' *Note Top::.  *Note Top: (dir)Top.

   a

   a

   a

   a

   a

   *Note Top: (elisp)Top.


\x1f
Tag Table:
Node: Top\x7f81
Node: entry\x7f201
\x1f
End Tag Table
============================================================

Re: Info enhancements

[Eli Zaretskii]

> Date: Tue, 9 Dec 2003 20:56:44 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
>    > Can give some bad surprises, like typing `f' followed by a reference
>    > one is seeing on the screen and the reader going to a "closer"
>    > off-screen reference of the same name.
> 
>    Does this really happen in practice?  That is, can you really create a
>    situation where an off-screen reference wins?
> 
> Yes.  In the `Entry' node of the following file, put point at the
> start of the line containing the first of the series of a's.  Do:
> M-0 C-l.
> 
> The `@xref{Top, , , dir}.' is now out of view. We do `f' and see:
> 
> Follow xref (Top): 
> 
> If we accept the default (or type Top), we go to (dir)Top, an
> off-screen reference, whereas `@xref{Top, Top, , elisp}.' is visible.

Sounds like a bug in the stand-alone reader: it should have filtered
out off-screen references, unless they are the only ones in the node.
I probably failed to consider this possibility (or perhaps there's no
easy way to know what's off screen in the stand-alone reader).

Re: Info enhancements

[Luc Teirlinck]

I forgot to point out that my previous message applied to the
_stand-alone_ info reader.  (I believe this is obvious to Eli, but
not to people who have not followed prior postings.)  Emacs Info goes
to (experiment)Top, which appears to be definitely wrong, as we
discussed before.  The stand-alone behavior _is_ relevant to Emacs,
because we are discussing whether or not Emacs should adopt the
present stand-alone behavior.

Sincerely,

Luc.

Re: Info enhancements

[Juri Linkov]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:
> Juri Linkov wrote:
> 	This function looks up the target in *Note
> 	file-coding-system-alist: Default Coding Systems, *Note
> 	process-coding-system-alist: Default Coding Systems, or
> 	*Note network-coding-system-alist: Default Coding Systems,
> 	depending on OPERATION.
>
> The xref still makes no sense in the printed version, since it
> refers to the beginning of the same section.

What do you think about writing a variable name in a third argument
of @xref with the empty second argument?

============================================================
This function looks up the target in
@ref{Default Coding Systems, , file-coding-system-alist},
@ref{Default Coding Systems, , process-coding-system-alist}, or
@ref{Default Coding Systems, , network-coding-system-alist},
depending on @var{operation}.
============================================================

This would look good in the printed version as well as in Info.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Richard Stallman]

    What do you think about writing a variable name in a third argument
    of @xref with the empty second argument?

    ============================================================
    This function looks up the target in
    @ref{Default Coding Systems, , file-coding-system-alist},
    @ref{Default Coding Systems, , process-coding-system-alist}, or
    @ref{Default Coding Systems, , network-coding-system-alist},
    depending on @var{operation}.

Doesn't the variable name come out in the wrong font?
It ought to be in @code, but it won't be if.

Re: Info enhancements

[Juri Linkov]

Richard Stallman <rms@gnu.org> writes:
>     What do you think about writing a variable name in a third argument
>     of @xref with the empty second argument?
>
>     ============================================================
>     This function looks up the target in
>     @ref{Default Coding Systems, , file-coding-system-alist},
>     @ref{Default Coding Systems, , process-coding-system-alist}, or
>     @ref{Default Coding Systems, , network-coding-system-alist},
>     depending on @var{operation}.
>
> Doesn't the variable name come out in the wrong font?
> It ought to be in @code, but it won't be if.

Yes, one disadvantage of this is that it comes out in the wrong font.
So I tend to agree with Eli that it is better to write

   This function looks up the target in
   @code{file-coding-system-alist} (@pxref{Default Coding Systems,
   file-coding-system-alist})

which produces in the printed copy

   This function looks up the target in file-coding-system-alist
   (see Section 33.10.5 [Default Coding Systems], page 686).

and in Info

     This function looks up the target in `file-coding-system-alist'
     (*note file-coding-system-alist: Default Coding Systems.)

Although with Info-hide-note-references=t it looks awkward

   This function looks up the target in file-coding-system-alist
   (file-coding-system-alist.)

but it's desired awkwardness for users that want to hide the note tag.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Date: Sun, 07 Dec 2003 23:21:45 +0200
> 
> Although with Info-hide-note-references=t it looks awkward
> 
>    This function looks up the target in file-coding-system-alist
>    (file-coding-system-alist.)

I think that, under Info-hide-note-references=t, a reference inside
parens should have a "see " before the reference name.

Re: Info enhancements

[Juri Linkov]

Eli Zaretskii <eliz@elta.co.il> writes:
>> From: Juri Linkov <juri@jurta.org>
>> Date: Sun, 07 Dec 2003 23:21:45 +0200
>> 
>> Although with Info-hide-note-references=t it looks awkward
>> 
>>    This function looks up the target in file-coding-system-alist
>>    (file-coding-system-alist.)
>
> I think that, under Info-hide-note-references=t, a reference inside
> parens should have a "see " before the reference name.

I still think that replacing a "note" with "see" has no sense because
if the user prefers to set the Info-hide-note-references to t this
means that he don't want to see any tags before the reference name.
Since references are fontified in a different color the user can
already recognize a reference without an additional hint that
encourages him to follow this reference.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Miles Bader]

Juri Linkov <juri@jurta.org> writes:
> I still think that replacing a "note" with "see" has no sense because
> if the user prefers to set the Info-hide-note-references to t this
> means that he don't want to see any tags before the reference name.

`See' makes perfect sense -- it makes the reference into (usually)
correct english without drawing undue attention to itself, which is in
keeping with the style of the documentation, whereas the *Note crap is
just ugly obfuscation.

> Since references are fontified in a different color the user can
> already recognize a reference without an additional hint that
> encourages him to follow this reference.

[Doesn't work too well on non-color displays, and yes those exist.]

-Miles
-- 
Ich bin ein Virus. Mach' mit und kopiere mich in Deine .signature.

Re: Info enhancements

[Juri Linkov]

Miles Bader <miles@lsi.nec.co.jp> writes:
> Juri Linkov <juri@jurta.org> writes:
>> I still think that replacing a "note" with "see" has no sense because
>> if the user prefers to set the Info-hide-note-references to t this
>> means that he don't want to see any tags before the reference name.
>
> `See' makes perfect sense -- it makes the reference into (usually)
> correct english without drawing undue attention to itself, which is in
> keeping with the style of the documentation, whereas the *Note crap is
> just ugly obfuscation.

These attempts to fix the *Note to produce correct English cause
too much trouble: inserting the text "See" into Info buffers breaks
some Info functions (e.g. `Info-last', `Info-search').

>> Since references are fontified in a different color the user can
>> already recognize a reference without an additional hint that
>> encourages him to follow this reference.
>
> [Doesn't work too well on non-color displays, and yes those exist.]

It works on non-color displays very well because in this case it
underlines the references (just like web browsers do).

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Date: Mon, 08 Dec 2003 12:46:00 +0200
> 
> inserting the text "See" into Info buffers breaks
> some Info functions (e.g. `Info-last', `Info-search').

You don't need to actually insert "see" into the buffer, you could
define an overlay instead.

Re: Info enhancements

[Juri Linkov]

Eli Zaretskii <eliz@elta.co.il> writes:
>> From: Juri Linkov <juri@jurta.org>
>> Date: Mon, 08 Dec 2003 12:46:00 +0200
>> 
>> inserting the text "See" into Info buffers breaks
>> some Info functions (e.g. `Info-last', `Info-search').
>
> You don't need to actually insert "see" into the buffer, you could
> define an overlay instead.

Seems overlays don't interact well with the `invisible' property.
For instance, move point to the beginning of the reference
with Info-hide-note-references=t and evaluate this code:
M-: (overlay-put (make-overlay (point) (point)) 'before-string "See ")
and the reference loses its fontification.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Kim F. Storm]

Juri Linkov <juri@jurta.org> writes:

> Eli Zaretskii <eliz@elta.co.il> writes:
> >> From: Juri Linkov <juri@jurta.org>
> >> Date: Mon, 08 Dec 2003 12:46:00 +0200
> >> 
> >> inserting the text "See" into Info buffers breaks
> >> some Info functions (e.g. `Info-last', `Info-search').
> >
> > You don't need to actually insert "see" into the buffer, you could
> > define an overlay instead.
> 
> Seems overlays don't interact well with the `invisible' property.
> For instance, move point to the beginning of the reference
> with Info-hide-note-references=t and evaluate this code:
> M-: (overlay-put (make-overlay (point) (point)) 'before-string "See ")
> and the reference loses its fontification.

I still think Info-hide-note-references=t is a good default choice
if we can make it work better.  And I think we can.

The following patch seems to work well for me (no lost fontification
of the reference), and it doesn't alter the buffer as before, which
should make references by buffer positions work again.

And copy/paste works at least as well (or equally bad) as before.


*** info.el.~1.374.~	2003-10-06 09:14:21.000000000 +0200
--- info.el	2003-12-09 12:48:04.000000000 +0100
***************
*** 2938,2944 ****
  		(goto-char next))
  	      (if hide-tag
  		  (add-text-properties (match-beginning 1) (match-end 1)
! 				       '(invisible t front-sticky nil rear-nonsticky t)))
  	      (add-text-properties
  	       (match-beginning 2) (match-end 2)
  	       (cons 'help-echo
--- 2938,2946 ----
  		(goto-char next))
  	      (if hide-tag
  		  (add-text-properties (match-beginning 1) (match-end 1)
! 				       (if other-tag
! 					   `(display ,other-tag front-sticky nil rear-nonsticky t)
! 					 '(invisible t front-sticky nil rear-nonsticky t))))
  	      (add-text-properties
  	       (match-beginning 2) (match-end 2)
  	       (cons 'help-echo
***************
*** 2950,2959 ****
  	      (when (eq Info-hide-note-references t)
  		(add-text-properties (match-beginning 3) (match-end 3)
  				     '(invisible t front-sticky nil rear-nonsticky t)))
- 	      (when other-tag
- 		(save-excursion
- 		  (goto-char (match-beginning 1))
- 		  (insert other-tag)))
  	      (when (and Info-refill-paragraphs
  			 (or hide-tag (eq Info-hide-note-references t)))
  		(push (set-marker (make-marker) start)
--- 2952,2957 ----

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

Re: Info enhancements

[Luc Teirlinck]

Eli Zaretskii wrote:

   You don't need to actually insert "see" into the buffer, you could
   define an overlay instead.

Please do not use overlays to insert things that look like regular
text.  It is extremely confusing to users who want to cut and paste,
save things to file, print out hardcopy and do all kind of other
everyday stuff.  We already got rid of similar uses (in info with
Info-hide-note-references set to t) for these reasons and made things
such that only the amount of whitespace was controlled by an overlay
(which is still somewhat bad, but much less bad than regular
non-whitespace text).

Sincerely,

Luc.

Re: Info enhancements

[Eli Zaretskii]

> Date: Mon, 8 Dec 2003 11:05:44 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
>    You don't need to actually insert "see" into the buffer, you could
>    define an overlay instead.
> 
> Please do not use overlays to insert things that look like regular
> text.  It is extremely confusing to users who want to cut and paste,
> save things to file, print out hardcopy and do all kind of other
> everyday stuff.

Don't we already see similar adverse effects under
Info-hide-note-references set to t?  If we do, then using overlays
when that same option is in effect will not make things worse than
they already are.

Re: Info enhancements

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Date: Mon, 08 Dec 2003 12:12:22 +0200
> >
> > I think that, under Info-hide-note-references=t, a reference inside
> > parens should have a "see " before the reference name.
> 
> I still think that replacing a "note" with "see" has no sense because
> if the user prefers to set the Info-hide-note-references to t this
> means that he don't want to see any tags before the reference name.

"See" is not a tag, it's a word that, if added, makes the text in
parens be comprehensible by humans.

> Since references are fontified in a different color the user can
> already recognize a reference without an additional hint that
> encourages him to follow this reference.

Let's imagine that this text is in some HTML page: would you argue
even then that it is a well-written reference?  I think you'd expect
"see" or some such; at least I would.

Re: Info enhancements

[Karl Berry]

    Certainly we shouldn't overburden users
    with purely technical information.

Well, in Emacs under X, the reader can erase the "(line NNN)" so users
don't have to see it.


As for the xref stuff, I am not at all sure the second arg to xref
should be treated in a special way; that was not its original intent and
nothing has ever been documented about it.  I didn't know standalone
info did any searching based on it.  I'll have to think about that.

I can see that making index entries automatically be xrefable points
could be useful, in a few circumstances.  But that is a separate feature
from handling entries in the indexes themselves, so that the menu
entries there go to the right place.


Luc, my own personal opinion is that the conditional
file-coding-system-alist xref should be deleted as you were going to
do.  If it's in the same section, users shouldn't need an xref (or else
the section should be split, but the section in question seems a
reasonable length to me).

Re: Info enhancements

[Luc Teirlinck]

Karl Berry wrote:

   As for the xref stuff, I am not at all sure the second arg to xref
   should be treated in a special way; that was not its original intent and
   nothing has ever been documented about it.  I didn't know standalone
   info did any searching based on it.  I'll have to think about that.

The standalone info goes to the wrong place in the example we have
been looking at.  Instead of going to the intended place:

 - Variable: file-coding-system-alist

It goes to:

     files and the contents of `file-coding-system-alist' (see below).

in the description of `auto-coding-regexp-alist'.

While it is very useful to go to the intended place, it is a lot
better to just go to the top of the node than to attempt to guess.
Going to the wrong place misleads the user.

Sincerely,

Luc.

Re: Info enhancements

[Luc Teirlinck]

>From my earlier message:

   The standalone info goes to the wrong place in the example we have
   been looking at.

As I now realize, Juri already pointed that out.  Sorry for the redundancy.

Sincerely,

Luc.

Re: Info enhancements

[Eli Zaretskii]

> Date: Fri, 5 Dec 2003 14:44:12 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
> The standalone info goes to the wrong place in the example we have
> been looking at.

That's the best that could be done using the available information
without any chanegs to the Info format.

Re: Info enhancements

[Juri Linkov]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:
> Karl Berry wrote:
>    As for the xref stuff, I am not at all sure the second arg to xref
>    should be treated in a special way; that was not its original intent and
>    nothing has ever been documented about it.  I didn't know standalone
>    info did any searching based on it.  I'll have to think about that.
>
> The standalone info goes to the wrong place in the example we have
> been looking at.  Instead of going to the intended place:
>
>  - Variable: file-coding-system-alist
>
> It goes to:
>
>      files and the contents of `file-coding-system-alist' (see below).
>
> in the description of `auto-coding-regexp-alist'.
>
> While it is very useful to go to the intended place, it is a lot
> better to just go to the top of the node than to attempt to guess.
> Going to the wrong place misleads the user.

Going to the wrong place will not mislead the user more than going to
the top of the node because when user starts to scan visually the node
by reading it from the top he soon encounters the first and wrong
occurrence of the searched string.  Now the user is exactly in the same
situation as if point was placed here automatically by the Info
reader.  So it is the task of authors of Info manuals to warn the user
that the right place is somewhere below.  And as you can notice this
is already done in the mentioned node.  You can see that authors
already added the warning "(see below)" exactly for this purpose!

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Juri Linkov]

karl@freefriends.org (Karl Berry) writes:
> As for the xref stuff, I am not at all sure the second arg to xref
> should be treated in a special way; that was not its original intent and
> nothing has ever been documented about it.  I didn't know standalone
> info did any searching based on it.  I'll have to think about that.
>
> I can see that making index entries automatically be xrefable points
> could be useful, in a few circumstances.  But that is a separate feature
> from handling entries in the indexes themselves, so that the menu
> entries there go to the right place.
>
> Luc, my own personal opinion is that the conditional
> file-coding-system-alist xref should be deleted as you were going to
> do.  If it's in the same section, users shouldn't need an xref (or else
> the section should be split, but the section in question seems a
> reasonable length to me).

I agree that references to another part of the same small Info node is
useless.  I used this particular section as an example of enhancements.
But there are many other places in Info documentation where better
references to index entries are needed.  For instance, let's consider the
following excerpt from the Emacs Lisp Manual:

     See also `append' in *Note Building Lists::, `concat' in *Note
     Creating Strings::, and `vconcat' in *Note Vectors::, for other
     ways to copy sequences.

Such kind of references has at least two big drawbacks:

1. Users see too much unimportant information such as node names.
With using function names in reference names users will see only
function names, i.e. only what they need.  Nodes names will be hidden:

     See also append, concat, and vconcat for other ways to copy
     sequences.

2. When a reference contains only a node name, then after going to
   this node user should manually locate a place where needed
   function is described.  Note that nodes `Building Lists' and
   `Creating Strings' are very large, so user must spend a significant
   amount of time to locate this place.  With using index entries
   as reference names, this tedious task will be performed automatically.

   There are two variants of writing index names in references:

     See also *Note append: Building Lists, *Note concat: Creating
     Strings, and *Note vconcat: Vectors, for other ways to copy
     sequences.

   or references to anchors:

     See also *Note append::, *Note concat::, and *Note vconcat::, for
     other ways to copy sequences.

I believe this enhancement can easily be done with the existing Info
format.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Date: Sat, 06 Dec 2003 03:27:37 +0200
> 
>      See also `append' in *Note Building Lists::, `concat' in *Note
>      Creating Strings::, and `vconcat' in *Note Vectors::, for other
>      ways to copy sequences.
> 
> Such kind of references has at least two big drawbacks:

I think these drawbacks stem from the basic limitations of the Info
format.  People nowadays are more accustomed to HTML and similar
hyper-text formats, where the actual pointer is hidden, that's why the
somewhat naive Info format looks bad to them.

> I believe this enhancement can easily be done with the existing Info
> format.

And having spent many hours hacking makeinfo and the stand-alone Info
reader, I believe, like Karl does, that doing that is a complete waste
of time and effort.  I think we basically have reached the point where
no significant improvements could be done to Info without breaking
something somewhere else.  Evene the relatively simple change such as
Info-hide-node-references caused a series of unintended consequences
that we haven't fixed yet to the full extent.  Isn't the experience
drawn from that experiment enough for us to understand the simple
truth that

   THOU SHALT NOT CHANGE INFO ANYMORE

?

I say, if we want a better reader of the docs, let's invest our energy
in an XML-based reader.

Re: Info enhancements

[Juri Linkov]

"Eli Zaretskii" <eliz@elta.co.il> writes:
>> From: Juri Linkov <juri@jurta.org>
>> Date: Sat, 06 Dec 2003 03:27:37 +0200
>> 
>> I believe this enhancement can easily be done with the existing Info
>> format.
>
> And having spent many hours hacking makeinfo and the stand-alone Info
> reader, I believe, like Karl does, that doing that is a complete waste
> of time and effort.

I appreciate your efforts and time you spent on hacking Info readers.
But I think more improvements are possible without changing the
current Info format.

> I think we basically have reached the point where
> no significant improvements could be done to Info without breaking
> something somewhere else.  Evene the relatively simple change such as
> Info-hide-node-references caused a series of unintended consequences
> that we haven't fixed yet to the full extent.

I think the main question with improvements is whether they are good
for most users or not.  Improvements that cause some troubles
(e.g. Info-hide-node-references) could be turned off by default.  And
users that want to use them should be ready to have some problems.

> Isn't the experience drawn from that experiment enough for us to
> understand the simple truth that
>
>    THOU SHALT NOT CHANGE INFO ANYMORE

But I'd rather say that

   THERE'S PLENTY OF ROOM FOR INFO IMPROVEMENT

And I mean improvement of Info readers, not improvement of the Info
format that might break something.  I think that even in its current
form the Info format is very useful.

> I say, if we want a better reader of the docs, let's invest our energy
> in an XML-based reader.

I see there is an opinion that XML format will solve all problems of
Info format.  But I must warn that

   XML IS NOT A PANACEA

It solves some problems but introduces other problems.  Just to name
one of its problems: even such a trivial operation as text search on
a whole Info document (key `s' in Info readers) in XML will cause
several problems: to search a continuous text split by XML tags
(e.g. the text "abc" in the "a<b>b</b>c") a whole XML document should
be rendered to its textual representation before search, or some
complex rules should be used to collect text squashed between many
XML elements.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Karl Berry]

    Note that nodes `Building Lists' and
       `Creating Strings' are very large

Perhaps they should be split up, then.  But obviously that's a different
issue.


As for the general question of making index entries xrefable, as I said
before, I am not sure.  Although it would be useful in the cases you
cite, I am not sure if it would be useful enough in general to
automatically do it for every index entry.  Most index entries (in most
manuals) are long strings of human-readable text that it is not useful
to xref.

Also, the question of conflicts would arise.  If there is both an index
entry and a node with the same name, what to do?  Or two index entries
with the same name?  The xref commands are not set up to handle this.
Making them take a sixth argument or something does not sound all that
appealing, although maybe it is the cleanest thing.

So I don't think it is "easy".  The easy thing to do is accept the
feaure Texinfo already provides for subnode positioning: anchors.  It is
more work for the authors in one way, but on the other hand it actually
works.

Re: Info enhancements

[Eli Zaretskii]

> Date: Sat, 6 Dec 2003 09:49:36 -0500
> From: karl@freefriends.org (Karl Berry)
> 
> Most index entries (in most manuals) are long strings of
> human-readable text that it is not useful to xref.

Yes, it's typical for @cindex entries to be like that.  Entries that
are just symbol names are mostly produced by @vindex and @findex.

> So I don't think it is "easy".  The easy thing to do is accept the
> feaure Texinfo already provides for subnode positioning: anchors.  It is
> more work for the authors in one way, but on the other hand it actually
> works.

I tend to agree that the decision whether to xref an index entry is a
human one, so @anchor is the solution.

Re: Info enhancements

[Luc Teirlinck]

Again, sorry for assuming the wrong author in my previous message,
falsely attributing quotes to Eli and misspelling Juri's name
repeatedly (again).  Let us see how many blunders I manage to commit
in the present post.

This concerns the problem with the place references lead to in info.

As already mentioned, I believe that just going to the top of the node
is better than guessing at the risk of misleading the user.

The ideal would be to have a _reliable_ way to go to the correct place
without requiring any changes in existing .texi files.  Since a
solution of this type is probably impossible, we should, in my
opinion, stick with the @anchor solution.

Juri's change requires rewriting references in .texi files in a way
that departs from the present standard style and I believe that Juri
mentioned himself in a previous post that his method is not 100%
reliable.  Hence I would personally _not_ lean toward making this
particular change.  This is, as I already pointed out before,
independent of the question of whether we adopt the other changes in
the patch.

But what do we want to do with @anchor?  I have always actually
_avoided_ using it, because I saw it barely ever used in any major
manual.  For instance, it is _only_ used in texinfo.txi to illustrate
the @anchor command itself and _never_ used in info.texi.  I deduced
from this an implicit stylistic guideline "by example" that one should
use @anchor very sparingly, that is, only if *really* called for, and
that it would not be appropriate to write five or so @anchors per
node.  If anchors are actually preferred over node names, unless the
top of the node is the _real_ target, that should be clearly pointed
out in texinfo.txi.  Or one might give some guidelines on _when_ to use
@anchor.

If we started using @anchor systematically, the apparent inconsistency
with older Texinfo source might be confusing to the user.  A reference
would lead in a random way either to the top of the node or to the
"correct place".  At the very least, something should be said about it
in (info)Help-Xref.

Sincerely,

Luc.

Re: Info enhancements

[Luc Teirlinck]

>From my previous message:

   If we started using @anchor systematically, the apparent inconsistency
   with older Texinfo source might be confusing to the user.  A reference
   would lead in a random way either to the top of the node or to the
   "correct place".  At the very least, something should be said about it
   in (info)Help-Xref.

I retract that.  You can, of course, make it clear from the name.

Sincerely,

Luc.

Re: Info enhancements

[Eli Zaretskii]

> Date: Sat, 6 Dec 2003 15:40:51 -0600 (CST)
> From: Luc Teirlinck <teirllm@dms.auburn.edu>
> 
> But what do we want to do with @anchor?  I have always actually
> _avoided_ using it, because I saw it barely ever used in any major
> manual.  For instance, it is _only_ used in texinfo.txi to illustrate
> the @anchor command itself and _never_ used in info.texi.

This is simply a consequence of the decision made by manual
maintainers (in many packages, not just in Emacs) to not use features
that break old Info readers until @anchor support gets widespread
enough to justify that.  IIRC, Emacs switched to using @anchor only
after v21.1 went into press.

Re: Info enhancements

[Juri Linkov]

karl@freefriends.org (Karl Berry) writes:
> Also, the question of conflicts would arise.  If there is both an index
> entry and a node with the same name, what to do?  Or two index entries
> with the same name?

There is exactly the same problem with anchors: no anchors with the
same name are allowed within one Info file.  So we can't make anchors
for two index entries with the same name.

The problem with anchors is even worse: both a node and an anchor with
the same name are not allowed in one Info file.  If there are a node
and an anchor with the same name then after following a reference with
their name the stand-alone reader always prefers a node, whereas Emacs
reader prefers an anchor.

There is the same problem with a completion list of all node names and
anchor names (called by the command `g').  Even if we make a separate
command to select an anchor this will break older Info readers that
don't allow to separately select nodes and anchors.  So older readers
will fail on Info files with anchors and nodes with the same name.

> Making them take a sixth argument or something does not sound all that
> appealing, although maybe it is the cleanest thing.

Making a sixth argument is a good idea and deserves to be elaborated
further.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Eli Zaretskii]

> From: Juri Linkov <juri@jurta.org>
> Date: Sun, 07 Dec 2003 22:00:53 +0200
> 
> karl@freefriends.org (Karl Berry) writes:
> > Also, the question of conflicts would arise.  If there is both an index
> > entry and a node with the same name, what to do?  Or two index entries
> > with the same name?
> 
> There is exactly the same problem with anchors: no anchors with the
> same name are allowed within one Info file.  So we can't make anchors
> for two index entries with the same name.
> 
> The problem with anchors is even worse: both a node and an anchor with
> the same name are not allowed in one Info file.

I think that's precisely the problem that Karl was talking about.

(IMHO, having several index entries with the same name is not a good
idea, anyway.  It is much better to disambiguate them by adding a bit
of context information to each entry.  For example, instead of having
two entries that say "@cindex foo", do this:

  @cindex foo, used together with @code{bar}
  @cindex foo, when before @code{baz}

Not only does this help to find the required info faster when looking
at the index of a printed copy, it also allows the user to decide
which completion to select when she types "i foo TAB", whereas given
the two completions "foo<1>" and "foo<2>" such a decision is
impossible.  But I digress...)

Re: Info enhancements

[Richard Stallman]

    (IMHO, having several index entries with the same name is not a good
    idea, anyway.  It is much better to disambiguate them by adding a bit
    of context information to each entry.  For example, instead of having
    two entries that say "@cindex foo", do this:

Our policy is to avoid such duplicates, and disambiguate instead.

Re: Info enhancements

[Richard Stallman]

      Note that nodes `Building Lists' and
       `Creating Strings' are very large, so user must spend a significant
       amount of time to locate this place.

When a node is so large that it is a pain to find something in it,
we should try to split it up.  Would someone like to try to split these?

Re: Info enhancements

[Luc Teirlinck]

Richard Stallman wrote:

	 Note that nodes `Building Lists' and
	  `Creating Strings' are very large, so user must spend a significant
	  amount of time to locate this place.

   When a node is so large that it is a pain to find something in it,
   we should try to split it up.  Would someone like to try to split these?

I will take a look at those two.  However these two are not even the
largest nodes in the Elisp manual.  `Creating Strings' has 204 lines,
`Building Lists' 252 lines.  Many sections have more than 204 and a
few have more than 252.  For instance, `Window frame parameters' has
338 lines, `Coding Conventions' has 347.

Probably everything above 100 lines, certainly above 150, can be
inconvenient to search if only one single paragraph in the middle or
the end is referenced.  I believe we can not get all sections below
150 lines.  So there definitely seems to be some need for using
@anchor.

Sincerely,

Luc.

Re: Info enhancements

[Luc Teirlinck]

All occurrences of `section' in my message about node lenghts were
meant to say `node'.

Sincerely,

Luc.

Re: Info enhancements

[Juri Linkov]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:
> Richard Stallman wrote:
>
> 	 Note that nodes `Building Lists' and
> 	  `Creating Strings' are very large, so user must spend a significant
> 	  amount of time to locate this place.
>
>    When a node is so large that it is a pain to find something in it,
>    we should try to split it up.  Would someone like to try to split these?
>
> I will take a look at those two.  However these two are not even the
> largest nodes in the Elisp manual.  `Creating Strings' has 204 lines,
> `Building Lists' 252 lines.  Many sections have more than 204 and a
> few have more than 252.  For instance, `Window frame parameters' has
> 338 lines, `Coding Conventions' has 347.

It's much more useful for users if Info nodes are split not by size
but grouped by logically related topics.  This helps to look over all
related information at once.  But it's not the case in some places.
For instance, look at the Emacs Lisp Reference Manual:

Node: Sets And Lists
 - Function: memq object list
 - Function: member-ignore-case object list
 - Function: delq object list
 - Function: member object list
 - Function: delete object sequence
 - Function: remove object sequence

Node: Building Lists
 - ...
 - Function: remq object list
 - ...

The function `remq' is placed in the wrong node and
`member-ignore-case' in the wrong place of the same node.  A better
variant is the following:

Node: Sets And Lists
 - Function: memq object list
 - Function: remq object list
 - Function: delq object list
 - Function: member object list
 - Function: member-ignore-case object list
 - Function: delete object sequence
 - Function: remove object sequence

There are other possible inconsistencies, for instance, functions
`assoc-ignore-case' and `assoc-ignore-representation' are described
in the "Text Comparison" node, but better place would be the
"Association Lists" node.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Luc Teirlinck]

I guess you can not update your CVS right now, but at least one of the
things you mentioned has been fixed on November 29:

       (Sets And Lists): Describe `member-ignore-case' after `member'.

Sincerely,

Luc.

Re: Info enhancements

[Richard Stallman]

I will move remq, thanks.  I think that assoc-ignore-* belong where they are.

Re: Info enhancements

[Richard Stallman]

      For instance, `Window frame parameters' has
    338 lines, `Coding Conventions' has 347.

There may be difficulties in splitting Window frame parameters.
Splitting Coding Conventions is possible if someone can think
of a good subtopic that a large fraction fit into.

    Probably everything above 100 lines, certainly above 150, can be
    inconvenient to search if only one single paragraph in the middle or
    the end is referenced.  I believe we can not get all sections below
    150 lines.

I agree.

Re: Info enhancements

[Luc Teirlinck]

Richard Stallman wrote:

   There may be difficulties in splitting Window frame parameters.
   Splitting Coding Conventions is possible if someone can think
   of a good subtopic that a large fraction fit into.

I agreed to start splitting nodes.  However, I actually started trying
to do so and very soon I started doubting whether this was, right now,
the best thing to do.  Even though there is no specific deadline, we
are preparing to release a new printed version of the Elisp manual.

Splitting nodes or even moving many items between nodes requires a lot
of work.  Splitting the node itself is not the worst part, the real
work is looking up all references to the old node in all manuals
included with the Emacs distribution and deciding to which of the two
new nodes they should refer.  Often, we will need to reference both
new nodes.  (Moving remq is OK, because there appears to be little
danger with that one.)

We need to do this anew each time we split a node and if we decide
that even `Creating Strings' with its 204 lines is too big, then there
are _many_ nodes to split.  On the other hand, we already decided that
splitting the second largest node in the manual, `Window frame
parameters', 338 lines, is undesirable.

If the only reason to split nodes is so that the reader will have no
difficulties following references, then I believe that it is
substantially less work to systematically go through all references in
the elisp manual and check which ones could use @anchor's.  I did this
for `Non-ASCII Characters' and it is less work than one might expect.

The @anchor solution works well for both info and for the printed
manual.  Since Juri's proposed feature only works for info and does
not adjust page numbers in the printed manual, it is not a real
alternative.

I propose, at least for this edition of the manual, since there
appears to be still so much work to do, to just try to put in
@anchor's in all places where needed and not to split nodes based
solely on their length.

Sincerely,

Luc.

Re: Info enhancements

[Richard Stallman]

      Even though there is no specific deadline, we
    are preparing to release a new printed version of the Elisp manual.

I see your point.  It can wait.

    I propose, at least for this edition of the manual, since there
    appears to be still so much work to do, to just try to put in
    @anchor's in all places where needed and not to split nodes based
    solely on their length.

Please add anchors wherever you think they will be useful.

Re: Info enhancements

[Luc Teirlinck]

It might be useful to split up some nodes and, as I already said, I am
willing to help do so.  However, I believe that we might also have to
increase the number of @anchor's in the elisp manual from the current
four.  The two efforts could complement each other.

I believe that, for instance, a node like `(elisp)Documentation Tips'
(216 lines) is best kept together and, at the same time, large enough
to be a nuisance to wade through to find the correct item.

I CC the following proposed change to Emacs devel because I believe
that it is relevant to the discussion we are having.  The somewhat
strange name of the anchor is deliberate, to avoid interfering with
present or, especially, future, anchor or node names, and to avoid
problems with `g' completion.  It is overridden by the third argument
to @xref anyway.  It could, of course be changed.  (The [Tips] refers
to tips.texi.)

I propose to systematically rely on @anchor rather than on Juri's
feature, because it is more reliable, more flexible and because it is
an existing Texinfo feature, that does not require a departure from
current Texinfo style and conventions.

I believe that the @anchor in the diffs below could save the user
quite a bit of searching and confusion.  To me, it seems very helpful
to the user in both Info and the printed manual.  

If desired, I could commit when Savannah starts working again.  We
could start making more of these @anchor's, in similar situations.

===File ~/tips-diff=========================================
*** tips.texi.~1.53.~	Mon Oct 20 14:37:21 2003
--- tips.texi	Sun Dec  7 19:28:58 2003
***************
*** 647,652 ****
--- 647,653 ----
  This prevents the open-parenthesis from being treated as the start of a
  defun (@pxref{Defuns,, Defuns, emacs, The GNU Emacs Manual}).
  
+ @anchor{doc-hyperlinks [Tips]}
  @item
  @iftex
  When a documentation string refers to a Lisp symbol, write it as it
============================================================


===File ~/displaydiff=======================================
*** display.texi.~1.106.~	Sun Nov  2 12:23:12 2003
--- display.texi	Sun Dec  7 20:03:32 2003
***************
*** 805,812 ****
  so that it is still Help mode at the end of their execution, then
  @code{with-output-to-temp-buffer} makes this buffer read-only at the
  end, and also scans it for function and variable names to make them
! into clickable cross-references.  @xref{Documentation Tips, , Tips for
! Documentation Strings}.
  
  The string @var{buffer-name} specifies the temporary buffer, which
  need not already exist.  The argument must be a string, not a buffer.
--- 805,813 ----
  so that it is still Help mode at the end of their execution, then
  @code{with-output-to-temp-buffer} makes this buffer read-only at the
  end, and also scans it for function and variable names to make them
! into clickable cross-references.  @xref{doc-hyperlinks [Tips], , Tips
! for Documentation Strings}, more particularly the item on hyperlinks
! in documentation strings, for more details.
  
  The string @var{buffer-name} specifies the temporary buffer, which
  need not already exist.  The argument must be a string, not a buffer.
============================================================

Appendix: Exhaustive list (grep) of all current @anchor's in the Elisp
manual (four total):

@anchor{modifier bits} in (elisp)Character Type, 165 lines.

@anchor{Display Face Attribute Testing} in (elisp)Display Feature
Testing, 133 lines.

@anchor{Text help-echo} and @anchor{Help display}, both in
(elisp)Special Properties, 224 lines.

Re: Info enhancements

[Luc Teirlinck]

I intend to replace the `@anchor{doc-hyperlinks [Tips]} in my original
patch with `@anchor{docstring-hyperlinks}'.  Karl Berry thought that
the risk of duplication was not big enough to add the `[Tips]' (whose
intent was to make the name more `unique').

Sincerely,

Luc.

Re: Info enhancements

[Richard Stallman]

    It might be useful to split up some nodes and, as I already said, I am
    willing to help do so.  However, I believe that we might also have to
    increase the number of @anchor's in the elisp manual from the current
    four.  The two efforts could complement each other.

By all means install anchors wherever you find them useful.

Re: Info enhancements

[Stefan Monnier]

> I think that line numbers in index menus can distract users.

I think they only distract me if they say

  * Index entry:                          Node name.    54.

but not if they say

  * Index entry:                          Node name.    Line 54.


-- Stefan

Re: Info enhancements

[Richard Stallman]

    > I must not have been clear.  The format I meant is:
    >
    >      * MENU-ENTRY-NAME: NODE-NAME.   LINE_NUMBER. DESCRIPTION
    >
    > instead of Dave Gillespie's
    >
    >      * MENU-ENTRY-NAME: NODE-NAME.   DESCRIPTION. LINE_NUMBER. 


Of those two, I think the latter is better because the line number
will be less intrusive.

However,

     * MENU-ENTRY-NAME: NODE-NAME (LINE_NUMBER).     DESCRIPTION

or something along those lines would be even better.  This makes
it visible that the line number goes with the node name and that
the two together spec the location.

I chose parens for this example but that was arbitrary.  I'm not
attached to that particular detail.

    But what do you think about recording the locations of index entries
    in the tag table?  For example:

Something like this might be ok, depending on details, but it might
be a bigger change.

Re: Info enhancements

[Karl Berry]

My preference is either (a) maximal alignment:

    * histogram:                    Manipulating Vectors.   (line   78)
    * hms:                          Conversions.            (line   63)

Or my original proposal (b), with no attempt at any alignment:

    * histogram:                    Manipulating Vectors.  (line 78)
    * hms:                          Conversions.  (line 63)

I prefer the parenthetical forms to the "Line N" forms, with or without
period.


Ok, since you prefer alignment, and I guess I rather agree, it will be
nicer in the common case of relatively short node names, I will do (a)
for the next release, barring objections.

Thanks,
k

Re: Info enhancements

[Karl Berry]

    What do you think about writing a variable name in a third argument

No.  The third arg to xref is for the printed manual.

All the existing args to xref have a meaning (obviously).  It doesn't
make sense to replace one of them willy-nilly with index entries.

Re: Info enhancements

[Karl Berry]

    Right now, we are trying to deal with an apparent problem that the
    Elisp info reader has with similarly named references

Exactly what is the bug and what is the proposed solution?  Sample files?

I had no idea there was an actual patch being applied.
What other changes are being made?  While savannah is down, it's
impossible to know what is being done.

As we know, the standalone Info reader searches for the second arg to
xref in the node.  This is not perfect, as you yourself noted, but I
guess it only hurts occasionally.  So if you want to implement that in
the Emacs reader, fine.  Consistency is nice, anyway.

Other than that, the only practical solution to subnode positioning is
anchors, as far as I can see.

Re: Info enhancements

[Luc Teirlinck]

Eli Zaretskii wrote:

   Exactly what is the bug and what is the proposed solution?  Sample
   files?

I filed a bug report with Yuri, which only makes sense if you apply
Yuri's patch, and which was posted on emacs-devel.  Yuri said that it
was due to a pre-existing bug in Emacs Info.  It is all in the
messages you responded to (and which, hence, I assume you have read).
I am still confused about some of this myself, but Yuri gave the
impression of knowing what is going on.  I do not know anything more
about Yuri's solution than the short line you mentioned and criticized
(maybe because you misunderstood it).

   I had no idea there was an actual patch being applied.
   What other changes are being made?  While savannah is down, it's
   impossible to know what is being done.

I applied the patch to my owm _personal_ Emacs, for testing, _not_ to
the Emacs CVS.

The second part of your message is an unrelated problem.  I may send
my opinion on that one somewhat later.

The ten features in Juri's patch are mostly unrelated.  We can install
some and reject others.  Maybe we should not even be discussing them
all in a single thread.

Sincerely,

Luc.

Re: Info enhancements

[Luc Teirlinck]

>From my earlier message:

   Eli Zaretskii wrote:

      Exactly what is the bug and what is the proposed solution?  Sample
      files?

Sorry for misattributing this and following quotes to Eli.  (It was
quoted from Karl Berry)

Sincerely,

Luc.

Re: Info enhancements

[Luc Teirlinck]

>From my previous message:

   It is all in the messages you responded to (and which, hence, I
   assume you have read).

Sorry, I do not know why I assumed the message I responded was sent by
Eli.  It is in the messages Eli responded too.  Sorry, I should pay
attention to the "author" field.  I am in an absent-minded mood, I
guess.

Sincerely,

Luc.

Re: Info enhancements

[Karl Berry]

Luc, thank you for the clear mail with examples.

    @xref{(elisp)Top}. @xref{(elisp)Top, Top}.

Hmm.  The documentation is not explicit about any assigned meaning for the
second arg to an xref, beyond being the "name of the Info reference",
which is to say, the thing before the first colon.
http://www.gnu.org/software/texinfo/manual/texinfo/html_node/Two-Arguments.html
(and preceding and following nodes).

I had always thought of it as an arbitrary string.

    the reference produced by `@xref{(elisp)Top, Top}.' leads to
    (experiment)Top in Emacs Info.  Is this a bug?

My opinion is yes, it is a bug.  This very example shows it is a
reasonable thing to do -- have references to Top nodes of different
manuals within one node.  In fact, I myself have written nodes that do that.

Thanks,
k

Re: Info enhancements

[Eli Zaretskii]

> Date: Sat, 6 Dec 2003 19:53:22 -0500
> From: karl@freefriends.org (Karl Berry)
> 
>     the reference produced by `@xref{(elisp)Top, Top}.' leads to
>     (experiment)Top in Emacs Info.  Is this a bug?
> 
> My opinion is yes, it is a bug.

It is at least a misfeature that we should try to fix.

Re: Info enhancements

[Karl Berry]

    *on a completely unrelated note*, the
    strange place the stand-alone info goes to, once again seems to say:
    do not try to guess positions if you are not completely sure.
    @end unrelated

It is a judgement call.  In the case you cited, it goes to the wrong
position.  In most cases, Eli tells me, "amazingly" it goes to the right
place.

If I had written the code (Brian Fox did, it's been part of standalone
Info since early days), I probably would not have done this magic
searching, since, as we all know by now, it is a band-aid on the real
problem of subnode positioning.

If Emacs Info and standalone Info differ in this regard, I think that's
ok.  I'm not sure if I want to remove the code from sa-Info, since it's
been there so long.

Re: Info enhancements

[Karl Berry]

Responding now to Juri's original email, which I did not see before.
(Thanks for forwarding, Luc.)

All the changes look fine to me, except for the one we've been discussing:
    - - use reference names to move point to the place within the current
      node where reference name is defined.  


My only other comment is that the spate of changes around
Info-hide-note-references makes me question whether that is truly a
desirable new feature or not.  It seems like it has potential to cause
endless trouble for relatively little gain.  I hope at least that
Info-hide-note-references=t will not be the default for its first release.

Re: Info enhancements

[Eli Zaretskii]

> Date: Sat, 6 Dec 2003 19:59:41 -0500
> From: karl@freefriends.org (Karl Berry)
> 
> My only other comment is that the spate of changes around
> Info-hide-note-references makes me question whether that is truly a
> desirable new feature or not.  It seems like it has potential to cause
> endless trouble for relatively little gain.  I hope at least that
> Info-hide-note-references=t will not be the default for its first release.

Given our experience from its introduction, I tend to agree.

Re: Info enhancements

[Luc Teirlinck]

Eli Zaretskii wrote:

   > Date: Sat, 6 Dec 2003 19:59:41 -0500
   > From: karl@freefriends.org (Karl Berry)
   > 
   > My only other comment is that the spate of changes around
   > Info-hide-note-references makes me question whether that is truly a
   > desirable new feature or not.  It seems like it has potential to cause
   > endless trouble for relatively little gain.  I hope at least that
   > Info-hide-note-references=t will not be the default for its first release.

   Given our experience from its introduction, I tend to agree.

Me too.

Sincerely,

Luc.

Re: Info enhancements

[Kim F. Storm]

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

> Eli Zaretskii wrote:
> 
>    > Date: Sat, 6 Dec 2003 19:59:41 -0500
>    > From: karl@freefriends.org (Karl Berry)
>    > 
>    > My only other comment is that the spate of changes around
>    > Info-hide-note-references makes me question whether that is truly a
>    > desirable new feature or not.  It seems like it has potential to cause
>    > endless trouble for relatively little gain.  I hope at least that
>    > Info-hide-note-references=t will not be the default for its first release.
> 
>    Given our experience from its introduction, I tend to agree.
> 
> Me too.
> 

I can see there are some problems, but IMO, still minor.  But given those
problems, let's change the default setting to nil.

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

Re: Info enhancements

[Juri Linkov]

storm@cua.dk (Kim F. Storm) writes:
> Luc Teirlinck <teirllm@dms.auburn.edu> writes:
>> Eli Zaretskii wrote:
>>    > Date: Sat, 6 Dec 2003 19:59:41 -0500
>>    > From: karl@freefriends.org (Karl Berry)
>>    > 
>>    > My only other comment is that the spate of changes around
>>    > Info-hide-note-references makes me question whether that is truly a
>>    > desirable new feature or not.  It seems like it has potential to cause
>>    > endless trouble for relatively little gain.  I hope at least that
>>    > Info-hide-note-references=t will not be the default for its first release.
>> 
>>    Given our experience from its introduction, I tend to agree.
>> 
>> Me too.
>
> I can see there are some problems, but IMO, still minor.  But given those
> problems, let's change the default setting to nil.

I like the Info-hide-note-references feature very much but I agree
that it might be a bit confusing for unaware users.  So if it will
be changed to nil by default, this feature should be suggested in the
Info manual with an explanation of all its consequences.

-- 
http://www.jurta.org/emacs/

Re: Info enhancements

[Richard Stallman]

    I like the Info-hide-note-references feature very much but I agree
    that it might be a bit confusing for unaware users.

The feature will not be much use if it is off by default.
If we conclude that we must leave it off by default, in effect
we are concluding it is a failure.  Perhaps we must reach that
conclusion, but we should not mislead ourselves about what
the conclusion means.

Re: Info enhancements

[Eli Zaretskii]

> From: Richard Stallman <rms@gnu.org>
> Date: Tue, 09 Dec 2003 16:48:31 -0500
> 
> If we conclude that we must leave it off by default, in effect
> we are concluding it is a failure.

I'm not sure this is always so.  Some newly introduced options are
deliberately left off by default to avoid drastic changes in the
default behavior (that would surprise users) or if we are uncertain
whether users will like them.  So I don't think every option that's
off by default means a failure.

Re: Info enhancements

[Richard Stallman]

    I'm not sure this is always so.  Some newly introduced options are
    deliberately left off by default to avoid drastic changes in the
    default behavior (that would surprise users) or if we are uncertain
    whether users will like them.

It is true we could leave it off by default temporarily, then ask
people to try it and do a poll.  But if it isn't ultimately enabled by
default, it will be mostly a failure.

Re: Info enhancements

[Karl Berry]

Responding now to Luc's mail about @anchor in general.

    If anchors are actually preferred over node names, 

I would not say that anchors are "preferred" over names.  Ultimately,
there is a bias in Texinfo toward reasonably short nodes.  When the
nodes are short, subnode positioning does not matter.  Thus, @anchor was
not available in Texinfo for many years -- and thus was not used in most
existing manuals, which predate the feature.

On the other hand, anchors are there to be used, there's no reason to
hesitate about it at this point.

    Or one might give some guidelines on _when_ to use @anchor.

I agree.  From this discussion, the answer forming in my mind is "when
you have a long node, and want to go to an exact location within it".

And I would also say "consider splitting such a long node into several
subnodes" -- but I realize there are cases where that is not desirable.

    A reference would lead in a random way either to the top of the node
    or to the "correct place".

If there were more anchors, users would simply get to the "correct"
place more often.  That's all to the good.

You're right that naming conventions could distinguish, but I'm not sure
that's completely the way to go either.  An xref label like
"file-coding-system-alist" seems perfectly reasonable to me; it is
not apparent whether it is a node or an anchor, but as long as the user
ends up at the description of file-coding-system-alist when they follow
a reference, I don't think it matters.

A couple of sentences in Help-Xref couldn't hurt.

Thanks,
k

Re: Info enhancements

[Eli Zaretskii]

> Date: Sat, 6 Dec 2003 20:20:17 -0500
> From: karl@freefriends.org (Karl Berry)
> 
> I agree.  From this discussion, the answer forming in my mind is "when
> you have a long node, and want to go to an exact location within it".
> 
> And I would also say "consider splitting such a long node into several
> subnodes" -- but I realize there are cases where that is not desirable.

A typical situation is in nodes that describe command-line arguments
accepted by a program.  These nodes are quite long and essentially
present a large group of almost-unrelated short descriptions.
Splitting such a node is not very desirable, since that would harm
"info --usage".

Perhaps we should specifically recommend use of anchors in such usage
nodes.