[ELPA] New package: inform

[ELPA] New package: inform

[H. Dieter Wilhelm]

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

Hello Emacs

Please consider the following package for future inclusion.  (Some years
ago I signed the GNU paperwork.)

This library provides links of symbols (functions, variables, faces)
within Emacs' Info viewer to their help documentation.  This linking is
done, when the symbol names in the texinfo document are:

1. Quoted symbol names like `quoted-symbol' or:

2. Function names are prefixed by M-x, for example "M-x
function-name" or are quoted and prefixed like "`M-x
function-name'".

3. Function names are behind the following forms in the Elisp manual:

  -- Special Form:
  -- Command:
  -- Function:
  -- Macro:

4. Variables names are behind the following text:

  -- User Option:
  -- Variable:

In any case all symbol names must be known to Emacs, i.e. their names
are found in the variable `obarray'.

You can follow the additional links with the usual Info keybindings.
The customisation variable `mouse-1-click-follows-link' is influencing
the clicking behavior (and the tooltips) of the links, the variable's
default is 450 (milli seconds) setting it to nil means only clicking
with mouse-2 is following the link (hint: Drew Adams).

The code uses mostly mechanisms from GNU-Emacs' lisp/help-mode.el file.


[-- Attachment #2: inform.el --]
[-- Type: application/emacs-lisp, Size: 13413 bytes --]

[-- Attachment #3: Type: text/plain, Size: 82 bytes --]


Thank you

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

Re: [ELPA] New package: inform

[Stefan Monnier]

> Please consider the following package for future inclusion.  (Some years
> ago I signed the GNU paperwork.)

I think it would make sense to integrate it directly into `info.el`.

It looks fine to me, except that the extra links should only be added to
those manuals we know are related to Emacs/Elisp (e.g. it doesn't make
sense to add them to the Coreutils or Ada manuals).


        Stefan


PS: I mentioned the Ada manual specifically because it can be added as
    a GNU ELPA package, so this manual may be found under
    ~/.emacs.d/elpa and yet doesn't talk about Elisp functions and variables

Re: [ELPA] New package: inform

[T.V Raman]

As also SICP (Structure And Interpretation Of Computer Programs). Should
we create an elpa/info directory to hold these?
-- 

Re: [ELPA] New package: inform

[H. Dieter Wilhelm]

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

>> Please consider the following package for future inclusion.  (Some years
>> ago I signed the GNU paperwork.)
>
> I think it would make sense to integrate it directly into `info.el`.

Yes indeed! :-)

> It looks fine to me, except that the extra links should only be added to
> those manuals we know are related to Emacs/Elisp (e.g. it doesn't make
> sense to add them to the Coreutils or Ada manuals).

I agree, there's a danger of "false positives" and suggest looping over
something in the line of

   when (string= (file-name-nondirectory Info-current-file) "emacs").

I assume it would be easier to create a collection of all (important?)
Elisp related documents than the opposite.  Is it possible to ask Emacs
package archives programmatically which texinfo docs are included?

Thanks

        Dieter

PS: The inform.el source: https://github.com/dieter-wilhelm/inform

-- 
Best wishes
H. Dieter Wilhelm
Zwingenberg, Germany

Re: [ELPA] New package: inform

[H. Dieter Wilhelm]

And on most GNU-Linux systems there's, at least, the GNU core utils
documentation.

"T.V Raman" <raman@google.com> writes:

> As also SICP (Structure And Interpretation Of Computer Programs). Should
> we create an elpa/info directory to hold these?

Good to know that books exist on Melpa...

Thanks
        Dieter

-- 
Best wishes
H. Dieter Wilhelm
Zwingenberg, Germany

Re: [ELPA] New package: inform

[Eli Zaretskii]

> From: dieter@duenenhof-wilhelm.de (H. Dieter Wilhelm)
> Date: Fri, 08 May 2020 10:18:15 +0200
> Cc: emacs-devel@gnu.org
> 
> > It looks fine to me, except that the extra links should only be added to
> > those manuals we know are related to Emacs/Elisp (e.g. it doesn't make
> > sense to add them to the Coreutils or Ada manuals).
> 
> I agree, there's a danger of "false positives" and suggest looping over
> something in the line of
> 
>    when (string= (file-name-nondirectory Info-current-file) "emacs").

I think there are several more manuals to be added to the list.
Basically, any manual that describes some Emacs facility should be
there.  Examples include elisp, eintr, ebrowse, eieio, cl, tramp, and
many others.

Re: [ELPA] New package: inform

[H. Dieter Wilhelm]

>>    when (string= (file-name-nondirectory Info-current-file) "emacs").
>
> I think there are several more manuals to be added to the list.
> Basically, any manual that describes some Emacs facility should be
> there.  Examples include elisp, eintr, ebrowse, eieio, cl, tramp, and
> many others.

Absolutely.

I'll collect the "standard" documentation which will be more or less
eternal.  Thank you for the first pointer.  

And my hope is that a package repository maintainer is coming up with a
way to update programatically the growing?, ephemeral? Elpa, Melpa
texinfo documentation.

       Dieter

PS: Wasn't it decided on this list to change the name "eintr" for the
Elisp Introduction?

-- 
Best wishes
H. Dieter Wilhelm
Zwingenberg, Germany

Re: [ELPA] New package: inform

[Eli Zaretskii]

> From: dieter@duenenhof-wilhelm.de (H. Dieter Wilhelm)
> Cc: monnier@iro.umontreal.ca,  emacs-devel@gnu.org
> Date: Fri, 08 May 2020 13:06:17 +0200
> 
> PS: Wasn't it decided on this list to change the name "eintr" for the
> Elisp Introduction?

We talked about that, yes.

Re: [ELPA] New package: inform

[Maurizio Boriani]

Eli Zaretskii writes:

>> > It looks fine to me, except that the extra links should only be added to
>> > those manuals we know are related to Emacs/Elisp (e.g. it doesn't make
>> > sense to add them to the Coreutils or Ada manuals).

> I think there are several more manuals to be added to the list.
> Basically, any manual that describes some Emacs facility should be
> there.  Examples include elisp, eintr, ebrowse, eieio, cl, tramp, and
> many others.

agree, may be an "Emacs canon" :-)


-- 
Maurizio Boriani 
GPG key: 0xCC0FBF8F

Re: [ELPA] New package: inform

[H. Dieter Wilhelm]

dieter@duenenhof-wilhelm.de (H. Dieter Wilhelm) writes:

> I'll collect the "standard" documentation which will be more or less
> eternal.  Thank you for the first pointer.  

Aren't these "standards" all the files in Emacs' info/ folder?  (Except
the dir file.)

> And my hope is that a package repository maintainer is coming up with a
> way to update programatically the growing?, ephemeral? Elpa, Melpa
> texinfo documentation.

After a second thought, it might be more practical to check if a
document is coming from the `package-user-dir' or info/ and collect over
time a - hopefully - small list of none-Elisp/Emacs related documents to
filter them out.

(defcustom info(rm)-none-emacs-or-elisp-documents
           '("aarm2012" ; Stefan: Ada manual
             "arm2012"  ; Stefan: Ada manual
             "sicp"  ; T.V: Structure and Interpretation of Computer Programs)
 "List of all none GNU-Emacs or Elisp documentation.
  Not to be checked for linking."
 type: list
 group: info)?

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

Re: [ELPA] New package: inform

[Eli Zaretskii]

> From: dieter@duenenhof-wilhelm.de (H. Dieter Wilhelm)
> Date: Fri, 08 May 2020 15:45:02 +0200
> Cc: monnier@iro.umontreal.ca, emacs-devel@gnu.org
> 
> dieter@duenenhof-wilhelm.de (H. Dieter Wilhelm) writes:
> 
> > I'll collect the "standard" documentation which will be more or less
> > eternal.  Thank you for the first pointer.  
> 
> Aren't these "standards" all the files in Emacs' info/ folder?

Quite possibly.

Re: [ELPA] New package: inform

[Stefan Monnier]

> After a second thought, it might be more practical to check if a
> document is coming from the `package-user-dir' or info/ and collect over
> time a - hopefully - small list of none-Elisp/Emacs related documents to
> filter them out.

Indeed, I suspect a test like

- if it's in the blacklist => don't activate
- if it comes from Emacs's own directory => activate
- if it comes from an ELPA package => activate
- else => don't activate

will be a good enough start.  The blacklist should likely use regexps
and will presumably start with the Ada manual and SICP.


        Stefan

RE: [ELPA] New package: inform

[Drew Adams]

> > It looks fine to me, except that the extra links should only be added
> > to those manuals we know are related to Emacs/Elisp (e.g. it doesn't
> > make sense to add them to the Coreutils or Ada manuals).
> 
> I agree, there's a danger of "false positives" and suggest looping over
> something in the line of
>    when (string= (file-name-nondirectory Info-current-file) "emacs").
> 
> I assume it would be easier to create a collection of all (important?)
> Elisp related documents than the opposite.  Is it possible to ask Emacs
> package archives programmatically which texinfo docs are included?

In `help-fns+.el' I do something similar: providing links
to manual sections in `*Help*' output.  I handle the
question of which manuals to treat with this user option:
___

help-cross-reference-manuals is a variable defined in `help-fns+.el'.
Its value is (("emacs" "elisp"))

Documentation:
Manuals to search, for a `*Help*' buffer link to the manuals.
A cons.

 The car is a list of manuals to search, or the symbol `all', to
  search all.  If nil, then do not create a cross-reference link.

 The cdr is a boolean:

  Non-`nil' means search the manuals, then create a cross-ref link:
        create it only if some search hits are found.

  `nil' means create a cross-ref link without searching manuals
        first (but only if there are some manuals to search).
___

IOW, the car of the value is a whitelist of manuals to
handle in this regard.

The default value corresponds to what Stefan suggested
for inform.el's links in Info: the manuals known to
always be appropriate for such handling: Emacs, Elisp.

Different users have different sets of Info manuals.
It's quite possible that some will have manuals that
are similar to the Emacs and Elisp manuals in this
regard.  They can just add them to the list of manuals
to handle.  (And they can remove manuals from the list,
of course.)

You might want to have a user option for what you're
considering wrt Info links: a whitelist of the manuals
to treat.

RE: [ELPA] New package: inform

[Drew Adams]

I wrote:

> a whitelist of manuals to handle in this regard.
> The default value corresponds to what Stefan suggested
> for inform.el's links in Info: the manuals known to
> always be appropriate for such handling: Emacs, Elisp.

It's been pointed out that there are more manuals
than that which generally deal with Elisp functions
etc.

The particular use I make of that whitelist for
*Help* output is a bit different, so I kept the
default list very short.  For links in Info, I
agree that the default whitelist would normally
be longer, and could, e.g., be taken from what's
in .../share/info/.

My real point was that you might want to make
the list customizable by users, as they might
want things handled differently from what's
available in .../share/info/.

Re: [ELPA] New package: inform

[H. Dieter Wilhelm]

Drew Adams <drew.adams@oracle.com> writes:

>> I assume it would be easier to create a collection of all
>> (important?)  Elisp related documents than the opposite.  Is it
>> possible to ask Emacs package archives programmatically which texinfo
>> docs are included?
>
> In `help-fns+.el' I do something similar: providing links to manual
> sections in `*Help*' output.  I handle the question of which manuals
> to treat with this user option:

I downloaded help-fns+.el and it provides, among other things, the
inverse functionality of inform: It is putting Info links in *Help*
buffers. :-) Which is a georgeous idea because herewith the
documentation loop between Help and Info documentation seems to be
closed, at least for many, many symbols! :-)

> ___
>
> help-cross-reference-manuals is a variable defined in `help-fns+.el'.
> Its value is (("emacs" "elisp"))

Oh, that means (("emacs" "elisp") nil), OK further

> Documentation: Manuals to search, for a `*Help*' buffer link to the
> manuals.  A cons.
>
>  The car is a list of manuals to search, or the symbol `all', to
>   search all.  If nil, then do not create a cross-reference link.
>
>  The cdr is a boolean:
>
>   Non-`nil' means search the manuals, then create a cross-ref link:
>         create it only if some search hits are found.
>
>   `nil' means create a cross-ref link without searching manuals
>         first (but only if there are some manuals to search).
    :set #'(lambda (sym defs) (custom-set-default sym defs) (setq Info-indexed-nodes ()))

Hmm, a setter function, why, that's over my horizon...

    :type '(cons
            (choice :tag "Which Manuals"
             (repeat :tag "Specific Manuals (files)" string) (const :tag
             "All Manuals" all))
            (boolean :tag "Search Before Creating Button?"))

Aha, I learned how to influence `customize' in a non trivial way, thank
you Drew.

> IOW, the car of the value is a whitelist of manuals to handle in this
> regard.
>
> The default value corresponds to what Stefan suggested for inform.el's
> links in Info: the manuals known to always be appropriate for such
> handling: Emacs, Elisp.
>
> Different users have different sets of Info manuals.  It's quite
> possible that some will have manuals that are similar to the Emacs and
> Elisp manuals in this regard.  They can just add them to the list of
> manuals to handle.  (And they can remove manuals from the list, of
> course.)

I agree that white- or blacklists should be customisable.

> You might want to have a user option for what you're considering wrt
> Info links: a whitelist of the manuals to treat.

Are you telling me that I can use, in these situtations, one variable
for two purposes?  1) For specifying and changing the list and 2)
switching a linking for lists off and on?

  '((list members) t) ; only these
  '((other members) nil) ; none of these
  '('all nil) ; no links
  '('all t) ; link everything?

Thanks
        Dieter

-- 
Best wishes
H. Dieter Wilhelm
Zwingenberg, Germany

RE: [ELPA] New package: inform

[Drew Adams]

> > You might want to have a user option for what
> > you're considering wrt Info links: a whitelist
> > of the manuals to treat.
> 
> Are you telling me that I can use, in these situtations, one variable
> for two purposes?  1) For specifying and changing the list and 2)
> switching a linking for lists off and on?
> 
>   '((list members) t) ; only these
>   '((other members) nil) ; none of these
>   '('all nil) ; no links
>   '('all t) ; link everything?

Not sure what you're asking.  I think you're
asking whether you can about doing something
like what I did in help-fns+.el: let a single
option value specify both:

1. Either a list of manuals or a value that means
   use all manuals present.

and

2. Whether to do <something>.

In my case, #2 is whether to search the manuals
specified by #1 before creating the button, so
the button either (a) takes you directly to an
Info Index buffer (menu) of the relevant links
or (b) searches the manuals and produces such
an Info Index buffer of links when you click it.

(a) Takes the time to compute the menu before
showing *Help*, which is a waste of time if you
never click the button.

(b) Saves that time before creating *Help*, but
spends it when you click the button.

TBH, the approach in help-fns+.el is not very
satisfactory, because of the time to compute
the links (either way).  But that's what that
particular defcustom is about.

In Customize, there are two things to customize:

1. "Which Manuals:" which has a `Value Menu' that
   lets you choose between "Specific Manuals (files)"
   and "All Manuals".
   For the former, the type is a repetition (`repeat')
   of type `string'.  For the latter, the value is the
   symbol `all'.

2. A toggle button, "Search Before Creating Button?"
   The type is `boolean'.

RE: [ELPA] New package: inform

[Drew Adams]

> Not sure what you're asking.  I think you're
> asking whether you can about doing something
                         ^^^^^^^^^^^
                              do

Re: [ELPA] New package: inform

[Richard Stallman]

[[[ To any NSA and FBI agents reading my email: please consider    ]]]
[[[ whether defending the US Constitution against all enemies,     ]]]
[[[ foreign or domestic, requires you to follow Snowden's example. ]]]

  > This library provides links of symbols (functions, variables, faces)
  > within Emacs' Info viewer to their help documentation.

It sounds good in principle, but what does a "link" look like
concretely?  Does it look like Info cross references, or is it different?
How do you follow one of these links?

-- 
Dr Richard Stallman
Chief GNUisance of the GNU Project (https://gnu.org)
Founder, Free Software Foundation (https://fsf.org)
Internet Hall-of-Famer (https://internethalloffame.org)

Re: [ELPA] New package: inform

[H. Dieter Wilhelm]

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

Richard Stallman <rms@gnu.org> writes:
>   > This library provides links of symbols (functions, variables, faces)
>   > within Emacs' Info viewer to their help documentation.
>
> It sounds good in principle, but what does a "link" look like

Thanks, attached a PNG visualisation of the current state in reversed
colour.


[-- Attachment #2: inform.png --]
[-- Type: image/png, Size: 964950 bytes --]

[-- Attachment #3: Type: text/plain, Size: 629 bytes --]


> concretely?  Does it look like Info cross references, or is it different?

I think it is helpful (and possibly less confusing) to distinguish these
links from the regular "Info links".

> How do you follow one of these links?

Currently you can use the same keys and mouse clicks to follow and open
them as for the Info links.  I feel this is intuitively and is working
well in practice.

(I'm considering the idea of Drew Adams to close the appearing *Help*
window with a second click or <RET> press, though I've no idea how to
achieve this at the moment.)

    Dieter

-- 
Best wishes
H. Dieter Wilhelm
Zwingenberg, Germany

Re: [ELPA] New package: inform

[Jean-Christophe Helary]

> On May 9, 2020, at 1:23, Drew Adams <drew.adams@oracle.com> wrote:
> 
>>> It looks fine to me, except that the extra links should only be added
>>> to those manuals we know are related to Emacs/Elisp (e.g. it doesn't
>>> make sense to add them to the Coreutils or Ada manuals).
>> 
>> I agree, there's a danger of "false positives" and suggest looping over
>> something in the line of
>>   when (string= (file-name-nondirectory Info-current-file) "emacs").
>> 
>> I assume it would be easier to create a collection of all (important?)
>> Elisp related documents than the opposite.  Is it possible to ask Emacs
>> package archives programmatically which texinfo docs are included?
> 
> In `help-fns+.el' I do something similar: providing links
> to manual sections in `*Help*' output.  I handle the
> question of which manuals to treat with this user option:

Why is help-fns+ not in emacs/elpa/melpa ?

(yet ?)

https://www.reddit.com/r/emacs/comments/8z2jd0/why_isnt_the_code_from_helpfns_in_emacs/

That was 1 year ago.


Jean-Christophe Helary
-----------------------------------------------
http://mac4translators.blogspot.com @brandelune

Re: [ELPA] New package: inform

[Eli Zaretskii]

> From: dieter@duenenhof-wilhelm.de (H. Dieter Wilhelm)
> Date: Sat, 09 May 2020 11:38:58 +0200
> Cc: emacs-devel@gnu.org
> 
> Richard Stallman <rms@gnu.org> writes:
> >   > This library provides links of symbols (functions, variables, faces)
> >   > within Emacs' Info viewer to their help documentation.
> >
> > It sounds good in principle, but what does a "link" look like
> 
> Thanks, attached a PNG visualisation of the current state in reversed
> colour.

I think it's easier to say that these "links" are just normal Emacs
buttons, like we have in *Help* buffers.  Isn't that so?

Re: help-fns+ (WAS: [ELPA] New package: inform)

[Noam Postavsky]

On Sat, 9 May 2020 at 05:46, Jean-Christophe Helary
<jean.christophe.helary@traduction-libre.org> wrote:

> Why is help-fns+ not in emacs/elpa/melpa ?
>
> (yet ?)
>
> https://www.reddit.com/r/emacs/comments/8z2jd0/why_isnt_the_code_from_helpfns_in_emacs/
>
> That was 1 year ago.

Probably because Drew doesn't want to use git, and nobody else feels
like periodically inspecting and transferring the code from the wiki.

https://www.reddit.com/r/emacs/comments/7vocqa/update_on_melpa_removing_emacswiki_packages_they/dtuhzmt/

Re: help-fns+ (WAS: [ELPA] New package: inform)

[Jean-Christophe Helary]

> On May 9, 2020, at 22:06, Noam Postavsky <npostavs@gmail.com> wrote:
> 
> On Sat, 9 May 2020 at 05:46, Jean-Christophe Helary
> <jean.christophe.helary@traduction-libre.org> wrote:
> 
>> Why is help-fns+ not in emacs/elpa/melpa ?
>> 
>> (yet ?)
>> 
>> https://www.reddit.com/r/emacs/comments/8z2jd0/why_isnt_the_code_from_helpfns_in_emacs/
>> 
>> That was 1 year ago.
> 
> Probably because Drew doesn't want to use git, and nobody else feels
> like periodically inspecting and transferring the code from the wiki.
> 
> https://www.reddit.com/r/emacs/comments/7vocqa/update_on_melpa_removing_emacswiki_packages_they/dtuhzmt/

Thank you Noam. That makes sense.


Jean-Christophe Helary
-----------------------------------------------
http://mac4translators.blogspot.com @brandelune

Re: [ELPA] New package: inform

[H. Dieter Wilhelm]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: dieter@duenenhof-wilhelm.de (H. Dieter Wilhelm)
>> Date: Sat, 09 May 2020 11:38:58 +0200
>> Cc: emacs-devel@gnu.org
>> 
>> Richard Stallman <rms@gnu.org> writes:
>> >   > This library provides links of symbols (functions, variables, faces)
>> >   > within Emacs' Info viewer to their help documentation.
>> >
>> > It sounds good in principle, but what does a "link" look like
>> 
>> Thanks, attached a PNG visualisation of the current state in reversed
>> colour.
>
> I think it's easier to say that these "links" are just normal Emacs
> buttons, like we have in *Help* buffers.  Isn't that so?

It is so.  Technically that are "buttons" (realised with text overlays,
as in the *Help* buffers) which provide hyperlinks to other
documents.

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

Re: [ELPA] New package: inform

[H. Dieter Wilhelm]

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

>> Please consider the following package for future inclusion.  (Some years
>> ago I signed the GNU paperwork.)
>
> I think it would make sense to integrate it directly into `info.el`.

May I suggest to put the code in lisp/info-xref.el?  It has the right
name and is much smaller than info.el.  (The code is practically
independent of info.el.)

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

RE: [ELPA] New package: inform

[Drew Adams]

> Why is help-fns+ not in emacs/elpa/melpa? (yet ?)
> 
> https://www.reddit.com/r/emacs/comments/8z2
> jd0/why_isnt_the_code_from_helpfns_in_emacs/
> 
> That was 1 year ago.

The thread you cite has nothing to do with MELPA.
The question addressed there was this: "Why isn't
the code from help-fns+.el in Emacs?"
___

The answer to why it is not in MELPA is here:

https://www.reddit.com/r/emacs/comments/7vocqa/update_on_melpa_removing_emacswiki_packages_they/dtuhzmt/
___

It's not hard to obtain help-fns+.el:

https://www.emacswiki.org/emacs/download/help-fns%2b.el

And it's not hard to (require 'help-fns+)

Re: [ELPA] New package: inform

[Jean-Christophe Helary]

> On May 10, 2020, at 2:27, Drew Adams <drew.adams@oracle.com> wrote:
> 
>> Why is help-fns+ not in emacs/elpa/melpa? (yet ?)
>> 
>> https://www.reddit.com/r/emacs/comments/8z2
>> jd0/why_isnt_the_code_from_helpfns_in_emacs/
>> 
>> That was 1 year ago.
> 
> The thread you cite has nothing to do with MELPA.
> The question addressed there was this: "Why isn't
> the code from help-fns+.el in Emacs?"

What I wrote → "Why is help-fns+ not in emacs/elpa/melpa? (yet ?)"

> ___
> 
> The answer to why it is not in MELPA is here:
> 
> https://www.reddit.com/r/emacs/comments/7vocqa/update_on_melpa_removing_emacswiki_packages_they/dtuhzmt/
> ___

Thank you. That link was sent by Noam before I receive your mail, to whom I replied, "Thank you, that makes sense".

> It's not hard to obtain help-fns+.el:
> 
> https://www.emacswiki.org/emacs/download/help-fns%2b.el
> 
> And it's not hard to (require 'help-fns+)

Indeed, but since I always use package.el I had forgotten about how to simply install code, and I checked the manual which had no clear information about that and I created a new thread with the title '"Emacs Lisp Packages" chapter in the Emacs manual' where I'm proposing a patch to clarify/improve the documentation on this fundamental subject.


Jean-Christophe Helary
-----------------------------------------------
http://mac4translators.blogspot.com @brandelune

Re: [ELPA] New package: inform

[H. Dieter Wilhelm]

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

>> After a second thought, it might be more practical to check if a
>> document is coming from the `package-user-dir' or info/ and collect over
>> time a - hopefully - small list of none-Elisp/Emacs related documents to
>> filter them out.
>
> Indeed, I suspect a test like
>
> - if it's in the blacklist => don't activate
> - if it comes from Emacs's own directory => activate
> - if it comes from an ELPA package => activate
> - else => don't activate
>
> will be a good enough start.  The blacklist should likely use regexps
> and will presumably start with the Ada manual and SICP.

Here's a first prototype along this line, I'm looking forward to your
advice, I'm not sure how to activate this linking, hope the autoloading
below will do...

modified   lisp/info-xref.el
@@ -1,4 +1,4 @@
-;;; info-xref.el --- check external references in an Info document -*- lexical-binding: t -*-
+;;; info-xref.el --- Cross references in an Info document -*- lexical-binding: t -*-
 
 ;; Copyright (C) 2003-2020 Free Software Foundation, Inc.
 
@@ -38,6 +38,119 @@
 ;; `M-x info-xref-docstrings' checks docstring "Info node ..." hyperlinks in
 ;; source files (and other files).
 
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+
+;; This library provides links of symbols (functions, variables,
+;; faces) within Emacs' Info viewer to their builtin help
+;; documentation.  This linking is done, when the symbol names in
+;; texinfo documentations (like the Emacs- and Elisp manual) are
+
+;; 1. Quoted symbol names like `quoted-symbol' or:
+
+;; 2. Function names are prefixed by M-x, for example M-x
+;; function-name or are quoted and prefixed like `M-x function-name'.
+
+;; 3. Function names appearing behind the following forms, which
+;; occur, for example, in the Elisp manual:
+
+;;   -- Special Form: function-name
+;;   -- Command:
+;;   -- Function:
+;;   -- Macro:
+
+;; 4. And variables names behind the following text:
+
+;;   -- User Option: variable-name
+;;   -- Variable:
+
+;;  In any case all symbol names must be known to Emacs, i.e. their
+;; names are found in the variable `obarray'.
+
+;; You can follow the additional links with the usual Info
+;; keybindings.  The customisation variable
+;; `mouse-1-click-follows-link' is influencing the clicking behavior
+;; (and the tooltips) of the links, the variable's default is 450
+;; (milli seconds) setting it to nil means only clicking with mouse-2
+;; is following the link (hint: Drew Adams).
+
+;; The link color of symbols - referencing their builtin documentation
+;; - is distinct from links which are referencing further Info
+;;  documentation.
+
+;; Inform is checking if the Info documents are relevant Elisp and
+;; Emacs related files to avoid false positives.  Please see the
+;; customization variable `inform-none-emacs-or-elisp-documents'.
+
+;; The code uses mostly mechanisms from Emacs' lisp/help-mode.el file.
+
+;;; Change Log:
+
+;; 1.3:
+
+;; Inform is checking if the Info documents are relevant Elisp and
+;; Emacs related files to avoid false positives.
+
+;; 1.2:
+
+;; Link Elisp descriptions of symbols to their help documentation,
+;; like the following function example: -- Function: eval form
+
+;; Distinguish color of texinfo links (`link' type) and Help links
+;; (`font-lock-function-name-face')
+
+;;; TODO:
+
+;; Currently inconsistent link colors to help buffers: In *info*
+;; different as in *Help* buffers!
+
+;; Check the application `inform-xref-symbol-regexp' for additional
+;; symbol prefixes without quoting of symbol-names
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+;; Does the following belong to customize.el?
+
+;; Generalise linking to "customization buffers" for the "easy
+;; customization" info documentation see also the customization
+;; section in the elisp manual
+
+;; - distinguish the Customization-links from Help- and Info-links
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+
+;;; Ideas:
+
+;; Link the help buffers back to higher level info manual subjects,
+;; similar to help-fns+.el from Drew Adams.
+
+;; Twice clicking or RETurning removes *Help* buffer (idea: Drew
+;; Adams)
+
+;; Different colors for different symbol types (idea: Drew Adams) see
+;; package helpful and info+ / info-colors on Melpa and see
+;; font-lock.el for common faces.
+
+;; - Do we need to indicate an already visited Help link with a
+;;   different color?
+
+;; - Would it be be good to overtake all colors of package
+;;   "info-colors"?
+
+;; - Do we need to distinguish the link FONTS? No, difficult to read!
+
+;; Back / Forward button in help buffer - back to info buffer or
+;; remain in help mode?
+
+;; Linking of standard symbol properties?
+
+;; - (info "(elisp) Standard Properties")
+
+;;  Elisp manual examples:
+;;       (symbol-name 'car) ... ?
+
+;; Shortening the verbose texinfo URLs?  But how to handle the changed
+;; indentation?
+
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+
 ;;; History:
 
 ;; Version 3 - new M-x info-xref-docstrings, use compilation-mode
@@ -556,6 +669,301 @@ info-xref-docstrings
 
                (info-xref-check-node node)))))))))
 
+;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;
+
+(require 'button)
+(require 'cl-lib)
+(require 'help-mode)			;redundant?
+
+;; activate inform without manually loading it. Is there a better way?
+;; ;;;###autoload (require 'info-xref)
+
+;; this is spawning lisp/info-xref.el's definition to 'info! This
+;; group is sorted now in 'docs and 'info! -FIXME-
+(defgroup info-xref nil
+  "Customisation 'info-xref' subgroup of info.
+Check external cross-references in Info documents and provide
+hyperlinks from symbols to their help documentation."
+  :group 'info)
+
+;;;###autoload
+(defcustom info-xref-make-xref-flag t
+  "Non-nil means create symbol links in info buffers."
+  :type '(choice (const :tag "Create links" t)
+		 (const :tag "Do not link" nil))
+  :group 'info-xref)
+
+(require 'cl-seq)
+;; Info-director-list must be initialised
+(info-initialize)
+(defvar Info-xref-emacs-info-dir-content
+  (mapcar 'file-name-nondirectory ;'file-name-sans-extension
+	  (directory-files
+	   (car
+	    ;; search for the main Emacs' info/ directory
+	    (cl-member "[^.]emacs" Info-directory-list :test 'string-match-p))
+	   ;; don't list "." and ".."
+	   t  "[^.]$"))
+  "List of file names in Emacs' own info/ directory.")
+
+;; Turn into regexp list necessary? Stefan
+;; Switch to alist with explanation of file name?
+(defcustom info-xref-none-emacs-or-elisp-documents
+  '("aarm2012" ; Stefan: Ada manual, Elpa archive
+    "arm2012"  ; Stefan: Ada manual
+    "sicp"   ; T.V: Structure and Interpretation of Computer Programs,
+					; Melpa archive
+    )
+  "List of all none GNU-Emacs or Elisp documentation.
+Or other documents not to be checked for linking to their help
+documentation.  The list must contains only the base name of the
+files (without their file name extension \".info\")."
+  :type '(repeat string)
+  :group 'info-xref)
+
+(defun Info-xref-check-docu-p ()
+  "Check if the current info file is relevant to Emacs.
+That means `Info-current-file' is either found in Emacs' info/
+directory or in `package-user-dir' and is not included in the
+`info-xref-none-emacs-or-elisp-documents' list."
+  (let* ((ifile Info-current-file)
+	 (ifi (when ifile
+		(file-name-sans-extension
+		 (file-name-nondirectory ifile))))
+	 (pdir (when (boundp 'package-user-dir)
+		 (expand-file-name
+		  package-user-dir)))
+	 (ifiles Info-xref-emacs-info-dir-content)
+	 (ndocu info-xref-none-emacs-or-elisp-documents))
+    (and ifile
+	 (or (assoc-string (concat ifi ".info") ifiles)
+	     ;; info files might be archived!
+	     (assoc-string (concat ifi ".info.gz") ifiles)
+	     (when pdir (string-match pdir ifile)))
+	 (not (assoc-string ifi ndocu)))))
+
+(defvar describe-symbol-backends) 	;from help-mode.el
+(defvar help-xref-following)		;dito
+
+;; this toggles the complete linking process
+;;;###autoload
+(when info-xref-make-xref-flag
+  (add-hook 'Info-selection-hook 'Info-xref-make-xrefs))
+
+(defface Info-xref-color
+  '((t (:inherit font-lock-doc-face
+		 ;; font-lock-preprocessor-face ; similar to link face (default)
+		 ;; font-lock-builtin-face ; similar (default Emacs)
+		 ;; font-lock-function-name-face ; similar (default)
+		 ;; Info-xref-face
+		 )))
+  "Face for the `symbol' reference items in `info' nodes."
+  :group 'info-colors)
+
+;; Button types
+
+(define-button-type 'Info-xref
+  'link t			   ;for Info-next-reference-or-link
+  'follow-link t
+  'face 'Info-xref-color
+  'action #'Info-xref-button-action)
+
+(define-button-type 'Info-xref-function
+  :supertype 'Info-xref
+  'Info-xref-function 'describe-function
+  'Info-xref-echo (purecopy "mouse-2, RET: describe this function"))
+
+(define-button-type 'Info-xref-variable
+  :supertype 'Info-xref
+  'Info-xref-function 'describe-variable
+  'Info-xref-echo (purecopy "mouse-2, RET: describe this variable"))
+
+(define-button-type 'Info-xref-face
+  :supertype 'Info-xref
+  'Info-xref-function 'describe-face
+  'Info-xref-echo (purecopy "mouse-2, RET: describe this face"))
+
+(define-button-type 'Info-xref-symbol
+  :supertype 'Info-xref
+  'Info-xref-function #'describe-symbol
+  'Info-xref-echo (purecopy "mouse-2, RET: describe this symbol"))
+
+(define-button-type 'Info-xref-function-def
+  :supertype 'Info-xref
+  'Info-xref-function (lambda (fun &optional file type)
+		     (or file
+			 (setq file (find-lisp-object-file-name fun type)))
+		     (if (not file)
+			 (message "Unable to find defining file")
+		       (require 'find-func)
+		       (when (eq file 'C-source)
+			 (setq file
+			       (help-C-file-name (indirect-function fun) 'fun)))
+		       ;; Don't use find-function-noselect because it follows
+		       ;; aliases (which fails for built-in functions).
+		       (let ((location
+			      (find-function-search-for-symbol fun type file)))
+			 (pop-to-buffer (car location))
+			 (run-hooks 'find-function-after-hook)
+			 (if (cdr location)
+			     (goto-char (cdr location))
+			   (message "Unable to find location in file")))))
+  'Info-xref-echo (purecopy "mouse-2, RET: find function's definition"))
+
+;; Functions
+
+(defun Info-xref-button-action (button)
+  "Call BUTTON's help function."
+  (Info-xref-do-xref nil
+		  (button-get button 'Info-xref-function)
+		  (button-get button 'Info-xref-args)))
+
+(defun Info-xref-do-xref (_pos function args)
+  "Call the help cross-reference function FUNCTION with args ARGS.
+Things are set up properly so that the resulting `help-buffer' has
+a proper [back] button."
+  ;; There is a reference at point.  Follow it.
+  (let ((help-xref-following nil))
+    (apply
+     function (if (eq function 'info)
+		  (append args (list (generate-new-buffer-name "*info*")))args))))
+
+(defun Info-xref-button (match-number type &rest args)
+  "Make a hyperlink for cross-reference text previously matched.
+MATCH-NUMBER is the subexpression of interest in the last matched
+regexp.  TYPE is the type of button to use.  Any remaining arguments are
+passed to the button's Info-xref-function when it is invoked.
+See `Info-xref-make-xrefs' Don't forget ARGS." ; -TODO-
+  ;; Don't mung properties we've added specially in some instances.
+  (unless (button-at (match-beginning match-number))
+    ;; (message "Creating button: %s." args)
+    (make-text-button (match-beginning match-number)
+                      (match-end match-number)
+                      'type type 'Info-xref-args args)))
+
+(defconst Info-xref-symbol-regexp
+  (purecopy (concat "\\(\\<\\(\\(variable\\|option\\)\\|"  ; Link to var
+                    "\\(function\\|command\\|call\\)\\|"   ; Link to function
+                    "\\(face\\)\\|"			   ; Link to face
+                    "\\(symbol\\|program\\|property\\)\\|" ; Don't link
+                    "\\(source \\(?:code \\)?\\(?:of\\|for\\)\\)\\)"
+                    "[ \t\n]+\\)?"
+                    ;; Note starting with word-syntax character:
+                    "['`‘]\\(\\sw\\(\\sw\\|\\s_\\)+\\|`\\)['’]"))
+  "Regexp matching doc string references to symbols.
+
+The words preceding the quoted symbol can be used in doc strings to
+distinguish references to variables, functions and symbols.")
+
+;;;###autoload
+(defun Info-xref-make-xrefs (&optional buffer)
+  "Parse and hyperlink documentation cross-references in the given BUFFER.
+
+Find cross-reference information in a buffer and activate such cross
+references for selection with `help-follow'.  Cross-references have
+the canonical form `...'  and the type of reference may be
+disambiguated by the preceding word(s) used in
+`Info-xref-symbol-regexp'.
+
+Function names are also prefixed by \"M-x\", for example \"M-x
+function-name\" or are quoted and prefixed like `M-x
+function-name'.
+
+Also Function names appearing behind the following forms, which
+occur, for example, in the Elisp manual:
+
+ -- Special Form: function-name
+ -- Command:
+ -- Function:
+ -- Macro:
+
+And variables names behind the following text:
+
+ -- User Option: variable-name
+ -- Variable:
+
+Faces only get cross-referenced if preceded or followed by the
+word `face'.  Variables without variable documentation do not get
+cross-referenced, unless preceded by the word `variable' or
+`option'."
+  (interactive "b")
+  (when (Info-xref-check-docu-p)
+    (with-current-buffer (or buffer (current-buffer))
+      (save-excursion
+	(goto-char (point-min))
+	;; Skip the header-type info, though it might be useful to parse
+	;; it at some stage (e.g. "function in `library'").
+	;;      (forward-paragraph)
+	(with-silent-modifications	;from Stefan
+	  (let (;(stab (syntax-table))
+		(case-fold-search t)
+		(inhibit-read-only t))
+	    (with-syntax-table emacs-lisp-mode-syntax-table
+	      ;; Quoted symbols
+	      (save-excursion
+		(while (re-search-forward Info-xref-symbol-regexp nil t)
+		  (let* ((data (match-string 8))
+			 (sym (intern-soft data)))
+		    (if sym
+			(cond
+			 ((match-string 3) ; `variable' &c
+			  (and (or (boundp sym) ; `variable' doesn't ensure
+                                        ; it's actually bound
+				   (get sym 'variable-documentation))
+			       (Info-xref-button 8 'Info-xref-variable sym)))
+			 ((match-string 4) ; `function' &c
+			  (and (fboundp sym) ; similarly
+			       (Info-xref-button 8 'Info-xref-function sym)))
+			 ((match-string 5) ; `face'
+			  (and (facep sym)
+			       (Info-xref-button 8 'Info-xref-face sym)))
+			 ((match-string 6)) ; nothing for `symbol'
+			 ((match-string 7)
+			  (Info-xref-button 8 'Info-xref-function-def sym))
+			 ((cl-some (lambda (x) (funcall (nth 1 x) sym))
+				   describe-symbol-backends)
+			  (Info-xref-button 8 'Info-xref-symbol sym)))))))
+
+	    ;; (info "(elisp) Eval")
+	    ;; Elisp manual      -- Special Form:
+	    ;;                   -- Command:
+	    ;;                   -- Function: function-name function
+	    ;;                   -- Macro:
+	    (save-excursion
+	      (while (re-search-forward
+		      "-- \\(Special Form:\\|Command:\\|Function:\\|Macro:\\) "
+		      nil t)
+		(looking-at "\\(\\sw\\|\\s_\\)+")
+		(let ((sym (intern-soft (match-string 0))))
+		  (if (fboundp sym)
+		      (Info-xref-button 0 'Info-xref-function sym)))))
+
+	    ;;              -- User Option:
+	    ;;              -- Variable: variable-name
+	    (save-excursion
+	      (while (re-search-forward
+		      "-- \\(User Option:\\|Variable:\\) "
+		      nil t)
+		(looking-at "\\(\\sw\\|\\s_\\)+")
+		(let ((sym (intern-soft (match-string 0))))
+		  (if (boundp sym)
+		      (Info-xref-button 0 'Info-xref-variable sym)))))
+
+	    ;; M-x prefixed functions
+	    (save-excursion
+	      (while (re-search-forward
+		      ;; Assume command name is only word and symbol
+		      ;; characters to get things like `use M-x foo->bar'.
+		      ;; Command required to end with word constituent
+		      ;; to avoid `.' at end of a sentence.
+		      ;; "\\<M-x\\s-+\\(\\sw\\(\\sw\\|\\s_\\)*\\sw\\)" nil t)
+		      ;; include M-x and quotes
+		      "['`‘]?M-x\\s-*\n?\\(\\sw\\(\\sw\\|\\s_\\)*\\sw\\)['’]?" nil t)
+		(let ((sym (intern-soft (match-string 1))))
+		  ;; (message "found %s" sym)
+		  (if (fboundp sym)
+		      (Info-xref-button 1 'Info-xref-function sym))))))))))))
+
 
 (provide 'info-xref)


-- 
Best wishes
H. Dieter Wilhelm
Zwingenberg, Germany

Re: [ELPA] New package: inform

[Ihor Radchenko]

dieter@duenenhof-wilhelm.de (H. Dieter Wilhelm) writes:

>> Indeed, I suspect a test like
>>
>> - if it's in the blacklist => don't activate
>> - if it comes from Emacs's own directory => activate
>> - if it comes from an ELPA package => activate
>> - else => don't activate
>>
>> will be a good enough start.  The blacklist should likely use regexps
>> and will presumably start with the Ada manual and SICP.
>
> Here's a first prototype along this line, I'm looking forward to your
> advice, I'm not sure how to activate this linking, hope the autoloading
> below will do...

May I know if this has been merged?
Or should anything be done to move the merge forward?

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: [ELPA] New package: inform

[Stefan Monnier]

> May I know if this has been merged?

AFAIK it hasn't.

> Or should anything be done to move the merge forward?

I think the last code I saw was sill a prototype, but I can't remember
reviewing it, really :-(

It would be good to get a bug-nb for it and send the latest version of
he suggested patch to it.


        Stefan

Re: [ELPA] New package: inform

[H. Dieter Wilhelm]

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

>> May I know if this has been merged?
> AFAIK it hasn't.

I also think it hasn't merged.

>> Or should anything be done to move the merge forward?
>
> I think the last code I saw was sill a prototype, but I can't remember
> reviewing it, really :-(

I think I suggested putting it on Melpa to see if there's a real
interest in it (up to now there were 432 downloads, please see
https://melpa.org/#/?q=inform).  My idea of getting some feedback, hints
or even bug reports were in vain, though.

> It would be good to get a bug-nb for it and send the latest version of
> he suggested patch to it.

Sorry, what do you mean by bug-nb?

Thanks

        Dieter

-- 
Best wishes
H. Dieter Wilhelm
Zwingenberg, Germany

Re: [ELPA] New package: inform

[Ihor Radchenko]

"H. Dieter Wilhelm" <dieter@duenenhof-wilhelm.de> writes:

>> I think the last code I saw was sill a prototype, but I can't remember
>> reviewing it, really :-(
>
> I think I suggested putting it on Melpa to see if there's a real
> interest in it (up to now there were 432 downloads, please see
> https://melpa.org/#/?q=inform).  My idea of getting some feedback, hints
> or even bug reports were in vain, though.

There is real interest to make it part of info.el :)
Right from Emacs devs.

" I think it would make sense to integrate it directly into `info.el`."
                 Stefan Monnier <monnier@iro.umontreal.ca> (2020-05-07)

You don't need to publish this as separate package to fix bugs. You will
not fix all of them anyway, and you have more chances to get bug reports
for a core code.

>> It would be good to get a bug-nb for it and send the latest version of
>> he suggested patch to it.
>
> Sorry, what do you mean by bug-nb?

Bug number. Basically: "send it via M-x report-emacs-bug attaching a
patch against Emacs master branch".

Then, we can discuss the implementation and not loose it in emacs-devel
archives. A "bug" will be tracked.

-- 
Ihor Radchenko // yantar92,
Org mode contributor,
Learn more about Org mode at <https://orgmode.org/>.
Support Org development at <https://liberapay.com/org-mode>,
or support my work at <https://liberapay.com/yantar92>

Re: [ELPA] New package: inform

[H. Dieter Wilhelm]

Ihor Radchenko <yantar92@posteo.net> writes:

> There is real interest to make it part of info.el :)
> Right from Emacs devs.
>
> " I think it would make sense to integrate it directly into `info.el`."
>                  Stefan Monnier <monnier@iro.umontreal.ca> (2020-05-07)

Obviously missed that. Thanks for the reminder!

> Bug number. Basically: "send it via M-x report-emacs-bug attaching a
> patch against Emacs master branch".

I'll do.  Please be patient, grew a bit Elisp rusty..

> Then, we can discuss the implementation and not loose it in emacs-devel
> archives. A "bug" will be tracked.

I'm looking forward to it.

        Dieter

-- 
Best wishes
H. Dieter Wilhelm
Zwingenberg, Germany

Re: [ELPA] New package: inform

[H. Dieter Wilhelm]

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

> It looks fine to me, except that the extra links should only be added
> to those manuals we know are related to Emacs/Elisp (e.g. it doesn't
> make sense to add them to the Coreutils or Ada manuals).

I think 2 years ago were "arm2012" and "aarm2012" on Elpa but now it
seems they're gone.  I assume they are succeeded by the package
"ada-ref-man" (from 2020) but'll leave the old notations in the
"blacklist" in case somebody might be using the old manual packages..

-- 
     Dieter

Best wishes
H. Dieter Wilhelm
Zwingenberg, Germany

Re: [ELPA] New package: inform

[H. Dieter Wilhelm]

"H. Dieter Wilhelm" <dieter@duenenhof-wilhelm.de> writes:

> Stefan Monnier <monnier@iro.umontreal.ca> writes:
>
>> It looks fine to me, except that the extra links should only be added
>> to those manuals we know are related to Emacs/Elisp (e.g. it doesn't
>> make sense to add them to the Coreutils or Ada manuals).
>
> I think 2 years ago were "arm2012" and "aarm2012" on Elpa but now it
> seems they're gone.  I assume they are succeeded by the package
> "ada-ref-man" (from 2020) but'll leave the old notations in the
> "blacklist" in case somebody might be using the old manual packages..

Just installed "ada-ref-man" and found these Info files in its folder!

I'm sorry for the noise.

-- 
Best wishes
H. Dieter Wilhelm
Zwingenberg, Germany