texinfo question about `...' and links - possible enhancement?

texinfo question about `...' and links - possible enhancement?

[Drew Adams]

There are lots of places in the Emacs manuals (esp. Elisp) where we mention a
function, macro, variable, etc. `...', which is documented elsewhere in the
manual, and we follow the `...' with a cross reference to that doc.

See, for instance, `(elisp) Type Predicates', which looks like this:

   Here is a table of predefined type predicates, in
 alphabetical order, with references to further information.

 `atom'
      see atom.

 `arrayp'
      see arrayp.

 `bool-vector-p'
      see bool-vector-p.

 `bufferp'
      see bufferp.

 `byte-code-function-p'
      see byte-code-function-p.

 `case-table-p'
      see case-table-p.

 `char-or-string-p'
      see char-or-string-p.

and so on.

It would be less noisy and easier to read if the `...' were themselves simply
links, so that instead of "`foo' see foo." you would see just "`foo'", with
"foo" highlighted as a link:

 `atom'
 `arrayp'
 `bool-vector-p'
 `bufferp'
 `byte-code-function-p'
 `case-table-p'
 `char-or-string-p'

etc.  Would such an enhancement be feasible?

I assume this would mean somehow stating, in texinfo, that you wanted the thingy
occurrence to be both between `...' and a link (in Emacs).  I.e., you would ask
for this treatment explicitly whenever you wanted it, providing the link target
node, just as you do now for the "see...".

Another possibility might be to provide such linking automatically, based on the
presence of such a term in the index.  In that case, whenever foo is indexed, a
mention of `foo' in the manual would link to the same target location as the foo
index entry does.  If automatic, there should probably be a way to override that
(turn it off for one or for all occurrences).

Re: texinfo question about `...' and links - possible enhancement?

[Eli Zaretskii]

> From: "Drew Adams" <drew.adams@oracle.com>
> Date: Thu, 20 Sep 2012 13:24:49 -0700
> 
>  `atom'
>       see atom.
> 
>  `arrayp'
>       see arrayp.
> 
>  `bool-vector-p'
>       see bool-vector-p.
> 
>  `bufferp'
>       see bufferp.
> 
>  `byte-code-function-p'
>       see byte-code-function-p.
> 
>  `case-table-p'
>       see case-table-p.
> 
>  `char-or-string-p'
>       see char-or-string-p.
> 
> and so on.
> 
> It would be less noisy and easier to read if the `...' were themselves simply
> links, so that instead of "`foo' see foo." you would see just "`foo'", with
> "foo" highlighted as a link:
> 
>  `atom'
>  `arrayp'
>  `bool-vector-p'
>  `bufferp'
>  `byte-code-function-p'
>  `case-table-p'
>  `char-or-string-p'
> 
> etc.  Would such an enhancement be feasible?

We could use @ref in Texinfo to get a bare link without the "see", but
AFAIK it's impossible to decorate links with the typeface of a program
symbol using Texinfo features.

> Another possibility might be to provide such linking automatically, based on the
> presence of such a term in the index.  In that case, whenever foo is indexed, a
> mention of `foo' in the manual would link to the same target location as the foo
> index entry does.  If automatic, there should probably be a way to override that
> (turn it off for one or for all occurrences).

This should be possible in Emacs, assuming it could be fast enough
(indices could be quite long).

RE: texinfo question about `...' and links - possible enhancement?

[Drew Adams]

> > Another possibility might be to provide such linking 
> > automatically, based on the presence of such a term in
> > the index.  In that case, whenever foo is indexed, a
> > mention of `foo' in the manual would link to the same 
> > target location as the foo index entry does.  If automatic,
> > there should probably be a way to override that
> > (turn it off for one or for all occurrences).
> 
> This should be possible in Emacs, assuming it could be fast enough
> (indices could be quite long).

Juri will come up with a patch within the hour! ;-)

Re: texinfo question about `...' and links - possible enhancement?

[Juri Linkov]

>> > Another possibility might be to provide such linking
>> > automatically, based on the presence of such a term in
>> > the index.  In that case, whenever foo is indexed, a
>> > mention of `foo' in the manual would link to the same
>> > target location as the foo index entry does.  If automatic,
>> > there should probably be a way to override that
>> > (turn it off for one or for all occurrences).
>>
>> This should be possible in Emacs, assuming it could be fast enough
>> (indices could be quite long).
>
> Juri will come up with a patch within the hour! ;-)

Not for 24.3, sorry.  There is only one week until feature freeze,
but more related enhancements are necessary in Info rendering.

RE: texinfo question about `...' and links - possible enhancement?

[Drew Adams]

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

> > > Another possibility might be to provide such linking 
> > > automatically, based on the presence of such a term in
> > > the index.  In that case, whenever foo is indexed, a
> > > mention of `foo' in the manual would link to the same 
> > > target location as the foo index entry does.  If automatic,
> > > there should probably be a way to override that
> > > (turn it off for one or for all occurrences).
> > 
> > This should be possible in Emacs, assuming it could be fast enough
> > (indices could be quite long).
> 
> Juri will come up with a patch within the hour! ;-)

Actually, I did that locally today, to see what it might be like.  I didn't try
any special optimizations, and I didn't try to remove any existing cross refs
that might thus become redundant.

I tried a couple of alternative approaches:

1. Doing it automatically whenever you visit a node (based on a Boolean user
option).

2. Doing it only on demand (a key) for the current node.

It is helpful to have the links (including distinguishing which ones have
already been visited), IMO.

However, it is very slow, as might be expected.  Hence the turn from approach #1
to #2.  But it is still too slow to be useful, IMO.

For #2 I didn't bother to follow up with any attempt to keep or reinstate such
links once they have been added to a given node, i.e., when you revisit it
later.

So unless someone has a good idea about optimizing this, I withdraw the
suggestion.  The effect is helpful, but it is just too slow today.


Instead, two other things can still be helpful in this regard, IMO.

1. A simple patch to provide the symbol at point as the default for `i'.  This
should have been done long ago, IMO.  It makes little sense to offer no default.

2. Highlighting for `...' (and "..."), so you can more easily recognize such
terms.

The (trivial) patch (#1) is attached.  I mention #2 because it is a helpful
complement to #1.

---

FWIW -

#2 makes Elisp symbols etc. stand out, which is one of the benefits of the above
links.  Without highlighting, they just disappear into the noise, IMO, in spite
of the fact that we set them off with `...'.

I would not use Info without #2, personally.  I am only mentioning it, not
proposing it - I've done that more than once in the past.  For those who might
be interested, this is what it looks like:
http://www.emacswiki.org/cgi-bin/wiki/InfoPlus.

[-- Attachment #2: info-2012-09-21.patch --]
[-- Type: application/octet-stream, Size: 2343 bytes --]

diff -cw info.el info-patched-2012-09-21.el
*** info.el	Fri Sep 21 15:41:54 2012
--- info-patched-2012-09-21.el	Fri Sep 21 15:47:12 2012
***************
*** 3168,3186 ****
  If there are no exact matches to the specified topic, this chooses
  the first match which is a case-insensitive substring of a topic.
  Use the \\<Info-mode-map>\\[Info-index-next] command to see the other matches.
! Give an empty topic name to go to the Index node itself."
    (interactive
     (list
      (let ((completion-ignore-case t)
  	  (Info-complete-menu-buffer (clone-buffer))
  	  (Info-complete-nodes (Info-index-nodes))
! 	  (Info-history-list nil))
        (if (equal Info-current-file "dir")
  	  (error "The Info directory node has no index; use m to select a manual"))
        (unwind-protect
  	  (with-current-buffer Info-complete-menu-buffer
  	    (Info-goto-index)
! 	    (completing-read "Index topic: " 'Info-complete-menu-item))
  	(kill-buffer Info-complete-menu-buffer)))))
    (if (equal Info-current-file "dir")
        (error "The Info directory node has no index; use m to select a manual"))
--- 3168,3189 ----
  If there are no exact matches to the specified topic, this chooses
  the first match which is a case-insensitive substring of a topic.
  Use the \\<Info-mode-map>\\[Info-index-next] command to see the other matches.
! Give an empty topic name to go to the Index node itself.
! The default topic (`M-n') is the name of the symbol at point."
    (interactive
     (list
      (let ((completion-ignore-case t)
  	  (Info-complete-menu-buffer (clone-buffer))
  	  (Info-complete-nodes (Info-index-nodes))
! 	  (Info-history-list nil)
!           (default-topic (thing-at-point 'symbol)))
        (if (equal Info-current-file "dir")
  	  (error "The Info directory node has no index; use m to select a manual"))
        (unwind-protect
             (with-current-buffer Info-complete-menu-buffer
               (Info-goto-index)
!              (completing-read "Index topic: " 'Info-complete-menu-item
!                               nil nil nil nil default-topic))
  	(kill-buffer Info-complete-menu-buffer)))))
    (if (equal Info-current-file "dir")
        (error "The Info directory node has no index; use m to select a manual"))

Diff finished.  Fri Sep 21 15:48:34 2012

Re: texinfo question about `...' and links - possible enhancement?

[Stefan Monnier]

> I tried a couple of alternative approaches:
> 1. Doing it automatically whenever you visit a node (based on a Boolean user
> option).
> 2. Doing it only on demand (a key) for the current node.

3. Do it with a font-lock rule (so jit-lock only does it for the
   viewable part of the node).

> It is helpful to have the links (including distinguishing which ones have
> already been visited), IMO.

Maybe you can speed it up by doing as little work at font-lock time
(e.g. not try to distinguish seen-vs-notseen, maybe not even try to
figure out the target of the link) and delay it to the time the link is
actually used.


        Stefan