all messages for Emacs-related lists mirrored at yhetil.org
 help / color / mirror / code / Atom feed
* Info viewer: Links to symbol documentation
@ 2020-04-21 20:38 H. Dieter Wilhelm
  2020-04-25 10:16 ` Eli Zaretskii
  2020-04-25 12:03 ` Stefan Monnier
  0 siblings, 2 replies; 14+ messages in thread
From: H. Dieter Wilhelm @ 2020-04-21 20:38 UTC (permalink / raw)
  To: emacs-devel

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




^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: Info viewer: Links to symbol documentation
  2020-04-21 20:38 Info viewer: Links to symbol documentation H. Dieter Wilhelm
@ 2020-04-25 10:16 ` Eli Zaretskii
  2020-04-25 10:53   ` H. Dieter Wilhelm
  2020-04-25 11:15   ` Basil L. Contovounesios
  2020-04-25 12:03 ` Stefan Monnier
  1 sibling, 2 replies; 14+ messages in thread
From: Eli Zaretskii @ 2020-04-25 10:16 UTC (permalink / raw)
  To: H. Dieter Wilhelm; +Cc: emacs-devel

> 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?



^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: Info viewer: Links to symbol documentation
  2020-04-25 10:16 ` Eli Zaretskii
@ 2020-04-25 10:53   ` H. Dieter Wilhelm
  2020-04-25 11:15   ` Basil L. Contovounesios
  1 sibling, 0 replies; 14+ messages in thread
From: H. Dieter Wilhelm @ 2020-04-25 10:53 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: emacs-devel

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



^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: Info viewer: Links to symbol documentation
  2020-04-25 10:16 ` Eli Zaretskii
  2020-04-25 10:53   ` H. Dieter Wilhelm
@ 2020-04-25 11:15   ` Basil L. Contovounesios
  2020-04-25 16:04     ` Drew Adams
  1 sibling, 1 reply; 14+ messages in thread
From: Basil L. Contovounesios @ 2020-04-25 11:15 UTC (permalink / raw)
  To: Eli Zaretskii; +Cc: H. Dieter Wilhelm, emacs-devel

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



^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: Info viewer: Links to symbol documentation
  2020-04-21 20:38 Info viewer: Links to symbol documentation H. Dieter Wilhelm
  2020-04-25 10:16 ` Eli Zaretskii
@ 2020-04-25 12:03 ` Stefan Monnier
  2020-04-25 12:22   ` Stefan Kangas
  1 sibling, 1 reply; 14+ messages in thread
From: Stefan Monnier @ 2020-04-25 12:03 UTC (permalink / raw)
  To: H. Dieter Wilhelm; +Cc: emacs-devel

> 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`.




^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: Info viewer: Links to symbol documentation
  2020-04-25 12:03 ` Stefan Monnier
@ 2020-04-25 12:22   ` Stefan Kangas
  2020-04-25 13:02     ` Stefan Monnier
  2020-04-25 13:21     ` H. Dieter Wilhelm
  0 siblings, 2 replies; 14+ messages in thread
From: Stefan Kangas @ 2020-04-25 12:22 UTC (permalink / raw)
  To: Stefan Monnier; +Cc: H. Dieter Wilhelm, Emacs developers

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



^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: Info viewer: Links to symbol documentation
  2020-04-25 12:22   ` Stefan Kangas
@ 2020-04-25 13:02     ` Stefan Monnier
  2020-05-03 10:51       ` H. Dieter Wilhelm
  2020-04-25 13:21     ` H. Dieter Wilhelm
  1 sibling, 1 reply; 14+ messages in thread
From: Stefan Monnier @ 2020-04-25 13:02 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: H. Dieter Wilhelm, Emacs developers

> 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




^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: Info viewer: Links to symbol documentation
  2020-04-25 12:22   ` Stefan Kangas
  2020-04-25 13:02     ` Stefan Monnier
@ 2020-04-25 13:21     ` H. Dieter Wilhelm
  1 sibling, 0 replies; 14+ messages in thread
From: H. Dieter Wilhelm @ 2020-04-25 13:21 UTC (permalink / raw)
  To: Stefan Kangas; +Cc: Stefan Monnier, Emacs developers

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



^ permalink raw reply	[flat|nested] 14+ messages in thread

* RE: Info viewer: Links to symbol documentation
  2020-04-25 11:15   ` Basil L. Contovounesios
@ 2020-04-25 16:04     ` Drew Adams
  2020-04-25 17:22       ` H. Dieter Wilhelm
  0 siblings, 1 reply; 14+ messages in thread
From: Drew Adams @ 2020-04-25 16:04 UTC (permalink / raw)
  To: Basil L. Contovounesios, Eli Zaretskii; +Cc: H. Dieter Wilhelm, emacs-devel

> +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.



^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: Info viewer: Links to symbol documentation
  2020-04-25 16:04     ` Drew Adams
@ 2020-04-25 17:22       ` H. Dieter Wilhelm
  2020-04-25 17:34         ` Drew Adams
  0 siblings, 1 reply; 14+ messages in thread
From: H. Dieter Wilhelm @ 2020-04-25 17:22 UTC (permalink / raw)
  To: Drew Adams; +Cc: Basil L. Contovounesios, Eli Zaretskii, emacs-devel

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



^ permalink raw reply	[flat|nested] 14+ messages in thread

* RE: Info viewer: Links to symbol documentation
  2020-04-25 17:22       ` H. Dieter Wilhelm
@ 2020-04-25 17:34         ` Drew Adams
  0 siblings, 0 replies; 14+ messages in thread
From: Drew Adams @ 2020-04-25 17:34 UTC (permalink / raw)
  To: dieter; +Cc: Basil L. Contovounesios, Eli Zaretskii, emacs-devel

> >    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.



^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: Info viewer: Links to symbol documentation
  2020-04-25 13:02     ` Stefan Monnier
@ 2020-05-03 10:51       ` H. Dieter Wilhelm
  2020-05-03 14:46         ` Stefan Monnier
  0 siblings, 1 reply; 14+ messages in thread
From: H. Dieter Wilhelm @ 2020-05-03 10:51 UTC (permalink / raw)
  To: Stefan Monnier; +Cc: Stefan Kangas, Emacs developers

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



^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: Info viewer: Links to symbol documentation
  2020-05-03 10:51       ` H. Dieter Wilhelm
@ 2020-05-03 14:46         ` Stefan Monnier
  2020-05-03 16:02           ` H. Dieter Wilhelm
  0 siblings, 1 reply; 14+ messages in thread
From: Stefan Monnier @ 2020-05-03 14:46 UTC (permalink / raw)
  To: H. Dieter Wilhelm; +Cc: Stefan Kangas, Emacs developers

> 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?"




^ permalink raw reply	[flat|nested] 14+ messages in thread

* Re: Info viewer: Links to symbol documentation
  2020-05-03 14:46         ` Stefan Monnier
@ 2020-05-03 16:02           ` H. Dieter Wilhelm
  0 siblings, 0 replies; 14+ messages in thread
From: H. Dieter Wilhelm @ 2020-05-03 16:02 UTC (permalink / raw)
  To: Stefan Monnier; +Cc: Stefan Kangas, Emacs developers

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



^ permalink raw reply	[flat|nested] 14+ messages in thread

end of thread, other threads:[~2020-05-03 16:02 UTC | newest]

Thread overview: 14+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2020-04-21 20:38 Info viewer: Links to symbol documentation H. Dieter Wilhelm
2020-04-25 10:16 ` Eli Zaretskii
2020-04-25 10:53   ` H. Dieter Wilhelm
2020-04-25 11:15   ` Basil L. Contovounesios
2020-04-25 16:04     ` Drew Adams
2020-04-25 17:22       ` H. Dieter Wilhelm
2020-04-25 17:34         ` Drew Adams
2020-04-25 12:03 ` Stefan Monnier
2020-04-25 12:22   ` Stefan Kangas
2020-04-25 13:02     ` Stefan Monnier
2020-05-03 10:51       ` H. Dieter Wilhelm
2020-05-03 14:46         ` Stefan Monnier
2020-05-03 16:02           ` H. Dieter Wilhelm
2020-04-25 13:21     ` H. Dieter Wilhelm

Code repositories for project(s) associated with this external index

	https://git.savannah.gnu.org/cgit/emacs.git
	https://git.savannah.gnu.org/cgit/emacs/org-mode.git

This is an external index of several public inboxes,
see mirroring instructions on how to clone and mirror
all data and code used by this external index.