Info viewer: Links to symbol documentation

Info viewer: Links to symbol documentation

[H. Dieter Wilhelm]

Hello Emacs

I think that info documentation would be even better if there were links
to the function and variable documentation along the line of
help-mode.el.  As a proof of concept I extended info.el so that Emacs'
Info viewer exhibits links to most symbol definitions (when they are
`quoted' in the documentation).

When looking at a few Elisp and Emacs pages the verbosity and redundancy
of these automatic links seems not to be disturbing or too distracting.

Maybe this draft can be extended so that references to customisation
buffers are working as well (as is asked for in the TODO file)...

What are your ideas?

     Dieter                  
-- 
Best wishes
H. Dieter Wilhelm
Zwingenberg, Germany

Re: Info viewer: Links to symbol documentation

[Eli Zaretskii]

> From: dieter@duenenhof-wilhelm.de (H. Dieter Wilhelm)
> Date: Tue, 21 Apr 2020 22:38:53 +0200
> 
> I think that info documentation would be even better if there were links
> to the function and variable documentation along the line of
> help-mode.el.  As a proof of concept I extended info.el so that Emacs'
> Info viewer exhibits links to most symbol definitions (when they are
> `quoted' in the documentation).
> 
> When looking at a few Elisp and Emacs pages the verbosity and redundancy
> of these automatic links seems not to be disturbing or too distracting.
> 
> Maybe this draft can be extended so that references to customisation
> buffers are working as well (as is asked for in the TODO file)...
> 
> What are your ideas?

I think this could be a useful feature, thanks1.

What do others think?

Re: Info viewer: Links to symbol documentation

[H. Dieter Wilhelm]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: dieter@duenenhof-wilhelm.de (H. Dieter Wilhelm)
>> Date: Tue, 21 Apr 2020 22:38:53 +0200
>> 
>> I think that info documentation would be even better if there were links
>> to the function and variable documentation along the line of
>> help-mode.el.  As a proof of concept I extended info.el so that Emacs'
>> Info viewer exhibits links to most symbol definitions (when they are
>> `quoted' in the documentation).
>> 
>> When looking at a few Elisp and Emacs pages the verbosity and redundancy
>> of these automatic links seems not to be disturbing or too distracting.
>> 
>> Maybe this draft can be extended so that references to customisation
>> buffers are working as well (as is asked for in the TODO file)...
>> 
>> What are your ideas?
>
> I think this could be a useful feature, thanks1.
>
> What do others think?

For the starting code please have a look here:

https://github.com/dieter-wilhelm/inform

-- 
Best wishes
H. Dieter Wilhelm
Zwingenberg, Germany

Re: Info viewer: Links to symbol documentation

[Basil L. Contovounesios]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: dieter@duenenhof-wilhelm.de (H. Dieter Wilhelm)
>> Date: Tue, 21 Apr 2020 22:38:53 +0200
>> 
>> I think that info documentation would be even better if there were links
>> to the function and variable documentation along the line of
>> help-mode.el.  As a proof of concept I extended info.el so that Emacs'
>> Info viewer exhibits links to most symbol definitions (when they are
>> `quoted' in the documentation).
>> 
>> When looking at a few Elisp and Emacs pages the verbosity and redundancy
>> of these automatic links seems not to be disturbing or too distracting.
>> 
>> Maybe this draft can be extended so that references to customisation
>> buffers are working as well (as is asked for in the TODO file)...
>> 
>> What are your ideas?
>
> I think this could be a useful feature, thanks1.
>
> What do others think?

+1 from me.  Perhaps some users will want a toggle.

-- 
Basil

Re: Info viewer: Links to symbol documentation

[Stefan Monnier]

> What are your ideas?

AFAIK your code adds links to `describe-<foo>` commands, basically.
This is great for Emacs documentation, but not for all the Info pages
that document non-Emacs packages (Make, glibc, LaTeX, you name it).

Not sure how to distinguish those two different cases.


        Stefan


PS: You should use `with-syntax-table` and `with-silent-modifications`,
    and you should NOT copy the definition of `describe-symbol-backends`.

Re: Info viewer: Links to symbol documentation

[Stefan Kangas]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

> AFAIK your code adds links to `describe-<foo>` commands, basically.
> This is great for Emacs documentation, but not for all the Info pages
> that document non-Emacs packages (Make, glibc, LaTeX, you name it).
>
> Not sure how to distinguish those two different cases.

One could perhaps create a new defvar with a list of manuals for which
to enable this, and disable it in all other cases.  Perhaps more
elegantly, one could add links only when there is a corresponding
symbol in the obarray.  Just two ideas.

Best regards,
Stefan Kangas

Re: Info viewer: Links to symbol documentation

[Stefan Monnier]

> One could perhaps create a new defvar with a list of manuals for which
> to enable this, and disable it in all other cases.

Short of finding it out automatically, that's probably what we'd need to
do, yes.

> Perhaps more elegantly, one could add links only when there is
> a corresponding symbol in the obarray.

That will suffer from false positives.
Also for non-Emacs documentation, we could also add links but to the
relevant part of the manual.


        Stefan

Re: Info viewer: Links to symbol documentation

[H. Dieter Wilhelm]

Stefan Kangas <stefan@marxist.se> writes:

> Stefan Monnier <monnier@iro.umontreal.ca> writes:
>
>> AFAIK your code adds links to `describe-<foo>` commands, basically.
>> This is great for Emacs documentation, but not for all the Info pages
>> that document non-Emacs packages (Make, glibc, LaTeX, you name it).
>>
>> Not sure how to distinguish those two different cases.
>
> One could perhaps create a new defvar with a list of manuals for which
> to enable this, and disable it in all other cases.  Perhaps more
> elegantly, one could add links only when there is a corresponding
> symbol in the obarray.  Just two ideas.

The latter seems to me how help-mode.el implemented linking.  And since
I - more or less literally - copied the relevant code, only defined
symbols are linked in an info buffer.

       Dieter
-- 
Best wishes
H. Dieter Wilhelm
Zwingenberg, Germany

RE: Info viewer: Links to symbol documentation

[Drew Adams]

> +1 from me.  Perhaps some users will want a toggle.

+1, in general.

1. Needs an option or a minor mode, for on/off.
   IOW, this should not happen in a hard-coded way:

   (add-hook 'Info-selection-hook 'Inform-make-xrefs)

2. At least in Emacs 26.3, I don't see the `Inform-echo'
   text (and I don't see where property `Inform-echo' is
   actually used in the code).  Instead, I see, for each
   link ("button"), this tooltip: "mouse-1, RET: Push
   this button".

3. It could help to (at least optionally be able to)
   have different link faces for the different types of
   objects (options, other variables, commands, other
   functions, etc.).

4. Using `mouse-1' or `RET' a second time could remove
   the *Help* display.  IOW, let it be a toggle for
   showing *Help* about the given object.

Re: Info viewer: Links to symbol documentation

[H. Dieter Wilhelm]

Drew Adams <drew.adams@oracle.com> writes:
> +1, in general.
>
> 1. Needs an option or a minor mode, for on/off.
>    IOW, this should not happen in a hard-coded way:
>
>    (add-hook 'Info-selection-hook 'Inform-make-xrefs)

Definitely, there must be an option, if this functionality will be
integrated. :-)

> 2. At least in Emacs 26.3, I don't see the `Inform-echo'
>    text (and I don't see where property `Inform-echo' is

Right, this is annoying, I'll remove it.  (Had the messages for
"debugging" purposes...)

>    actually used in the code).  Instead, I see, for each
>    link ("button"), this tooltip: "mouse-1, RET: Push
>    this button".

Mouse-1 instead of mouse-2?  Maybe this is different for the Windows OS?
OK, I'll check this.

> 3. It could help to (at least optionally be able to)
>    have different link faces for the different types of
>    objects (options, other variables, commands, other
>    functions, etc.).

This is a good idea!  I think the Melpa package "helpful" is
implementing this for *Help* buffers.

> 4. Using `mouse-1' or `RET' a second time could remove
>    the *Help* display.  IOW, let it be a toggle for
>    showing *Help* about the given object.

This is also a good idea, I don't know yet how to implement this but
will take a note!


Thank for your valuable hints.

      Dieter
-- 
Best wishes
H. Dieter Wilhelm
Zwingenberg, Germany

RE: Info viewer: Links to symbol documentation

[Drew Adams]

> >    actually used in the code).  Instead, I see, for each
> >    link ("button"), this tooltip: "mouse-1, RET: Push
> >    this button".
> 
> Mouse-1 instead of mouse-2?  Maybe this is different
> for the Windows OS? OK, I'll check this.

Actually, in my own use it's `mouse-2'.  But in vanilla
`emacs -Q' it's `mouse-1'.

It depends on your value of ` mouse-1-click-follows-link'.
My value is `nil`', but the default value is 450.

> Thank for your valuable hints.

De nada.  Thank you for the general idea and code.

Re: Info viewer: Links to symbol documentation

[H. Dieter Wilhelm]

Hello Emacs

FYI: 5 people reacted to the idea of furthering the self-documenting
capabilities - admittedly only a tiny step - for Emacs, but, at least
the feedback was positive.  So I thought it might be a good idea to
bring this package to Melpa, ripen the code and judge the interest
before it could be integrated into GNU-ELPA.

  https://melpa.org/#/inform

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> Perhaps more elegantly, one could add links only when there is a
>> corresponding symbol in the obarray.
>
> That will suffer from false positives.

At the moment the linking is only done when variable -, function - and
font names are `quoted' or there is a prefix M-x for function names and
additionally, if all these symbols are in `obarray'.  I guess the
chances of false positives are therefore minuscule.

> Also for non-Emacs documentation, we could also add links but to the
> relevant part of the manual.

I had a look for the `automake' manual. I'm not sure what you have in
mind for this kind of documentation and therefore how to implement it..

Could you please give me a concrete example?

    Dieter

-- 
Best wishes
H. Dieter Wilhelm
Zwingenberg, Germany

Re: Info viewer: Links to symbol documentation

[Stefan Monnier]

> FYI: 5 people reacted to the idea of furthering the self-documenting
> capabilities - admittedly only a tiny step - for Emacs, but, at least
> the feedback was positive.  So I thought it might be a good idea to
> bring this package to Melpa, ripen the code and judge the interest
> before it could be integrated into GNU-ELPA.

Why not add it directly to GNU ELPA?


        Stefan "Why o why do people assume GNU ELPA is only for
                old/mature/retired packages?"

Re: Info viewer: Links to symbol documentation

[H. Dieter Wilhelm]

Stefan Monnier <monnier@iro.umontreal.ca> writes:

>> FYI: 5 people reacted to the idea of furthering the self-documenting
>> capabilities - admittedly only a tiny step - for Emacs, but, at least
>> the feedback was positive.  So I thought it might be a good idea to
>> bring this package to Melpa, ripen the code and judge the interest
>> before it could be integrated into GNU-ELPA.
>
> Why not add it directly to GNU ELPA?

Oooooohkay, I'll give it a try...

>         Stefan "Why o why do people assume GNU ELPA is only for
>                 old/mature/retired packages?"

Out of pusillanimous respect?

Thanks

        Dieter
-- 
Best wishes
H. Dieter Wilhelm
Zwingenberg, Germany