Info viewer: Links to function documentations?

Info viewer: Links to function documentations?

[H. Dieter Wilhelm]

Hello Emacs

The self-documenting capapilities of GNU-Emacs are so nice that I'm
wondering, a bit, why they are not available for the info viewer in
Emacs?

For example: When I'm writing `command-name' in a mode documentation
Emacs creates automatically a link to the function documentation.  When
I'm writing the same in an info documentation it is shown as
´command-name', a dead string under Emacs' info viewer.  And the user
has to know that typing "C-h f" is accesses this documention.

Is such an implementation so much work and not worth doing it?  Is the
usage of info style documentation lessening overall?

And while I'm at it, Texinfo allows to include images.  It would be
helpful if they were available for the info viewer - under Emacs - as
well.. :-)

Thank you for your opinion

-- 
Best wishes
H. Dieter Wilhelm
Zwingenberg, Germany

Re: Info viewer: Links to function documentations?

[Stefan Monnier]

> For example: When I'm writing `command-name' in a mode documentation
> Emacs creates automatically a link to the function documentation.  When
> I'm writing the same in an info documentation it is shown as
> ´command-name', a dead string under Emacs' info viewer.  And the user
> has to know that typing "C-h f" is accesses this documention.

Info would indeed benefit from better use of hyperlinks (and images).
This will require using a different format, tho, since the Info format
is barely more than plain text.


        Stefan

Re: Info viewer: Links to function documentations?

[Eli Zaretskii]

> From: Stefan Monnier <monnier@iro.umontreal.ca>
> Date: Wed, 25 Mar 2020 10:15:07 -0400
> 
> > For example: When I'm writing `command-name' in a mode documentation
> > Emacs creates automatically a link to the function documentation.  When
> > I'm writing the same in an info documentation it is shown as
> > ´command-name', a dead string under Emacs' info viewer.  And the user
> > has to know that typing "C-h f" is accesses this documention.
> 
> Info would indeed benefit from better use of hyperlinks (and images).
> This will require using a different format, tho, since the Info format
> is barely more than plain text.

Info does support images (and the Emacs Info reader can display them).
So at least this part really just waits volunteers to add images to
our manuals.

As for hyperlinks to Emacs documentation: if the intent is to link to
the doc strings, then this is just a question of someone coming up
with the code to do that.

Re: Info viewer: Links to function documentations?

[H. Dieter Wilhelm]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: Stefan Monnier <monnier@iro.umontreal.ca>
>> Date: Wed, 25 Mar 2020 10:15:07 -0400

...
>> > ´command-name', a dead string under Emacs' info viewer.  And the user
>> > has to know that typing "C-h f" is accesses this documention.
>> 
>> Info would indeed benefit from better use of hyperlinks (and images).
>> This will require using a different format, tho, since the Info format
>> is barely more than plain text.
>
> Info does support images (and the Emacs Info reader can display them).

OK, then I have to try harder in my example. :-/
Thank you Eli

> So at least this part really just waits volunteers to add images to
> our manuals.  As for hyperlinks to Emacs documentation: if the intent
> is to link to the doc strings,

Yes

> then this is just a question of someone coming up with the code to do
> that.

I assume this would mean coding in C, wouldn't it? :D

-- 
Best wishes
H. Dieter Wilhelm
Zwingenberg, Germany

Re: Info viewer: Links to function documentations?

[Robert Pluim]

>>>>> On Wed, 25 Mar 2020 17:27:06 +0100, dieter@duenenhof-wilhelm.de (H. Dieter Wilhelm) said:
    >> then this is just a question of someone coming up with the code to do
    >> that.

    H> I assume this would mean coding in C, wouldn't it? :D

Emacs' info support is written in elisp.

Robert

Re: Info viewer: Links to function documentations?

[Eli Zaretskii]

> From: dieter@duenenhof-wilhelm.de (H. Dieter Wilhelm)
> Cc: help-gnu-emacs@gnu.org
> Date: Wed, 25 Mar 2020 17:27:06 +0100
> 
> > Info does support images (and the Emacs Info reader can display them).
> 
> OK, then I have to try harder in my example. :-/
> Thank you Eli

TIA

> > As for hyperlinks to Emacs documentation: if the intent
> > is to link to the doc strings,
> 
> Yes
> 
> > then this is just a question of someone coming up with the code to do
> > that.
> 
> I assume this would mean coding in C, wouldn't it? :D

No.  The Emacs Info reader is implemented entirely in Emacs Lisp.

Re: Info viewer: Links to function documentations?

[Stefan Monnier]

>> Info would indeed benefit from better use of hyperlinks (and images).
>> This will require using a different format, tho, since the Info format
>> is barely more than plain text.
>
> As for hyperlinks to Emacs documentation: if the intent is to link to
> the doc strings, then this is just a question of someone coming up
> with the code to do that.

I was thinking more of the "redundant" hyperlinks you can see e.g. in
Wikipedia, where lots of words are hyperlinked "just in case".

Texinfo doesn't encourage this practice because it was designed for
paper and (mostly) plain text, where references can be annoying in the
text, unlike the relatively inconspicuous "blue with underline" used for
web hyperlinks.  And AFAIK the Info format also doesn't support such
lightweight hyperlinks really (IIRC info-mode may try to make some links
lighter weight by eliding some surrounding text (which plays the role of
markup), but it's a bit brittle and negatively affects the paragraph
filling of the surrounding text).


        Stefan

Re: Info viewer: Links to function documentations?

[H. Dieter Wilhelm]

Eli Zaretskii <eliz@gnu.org> writes:

>> From: dieter@duenenhof-wilhelm.de (H. Dieter Wilhelm)
>> Cc: help-gnu-emacs@gnu.org
>> Date: Wed, 25 Mar 2020 17:27:06 +0100
>> 
>> > Info does support images (and the Emacs Info reader can display them).
>> 
>> OK, then I have to try harder in my example. :-/
>> Thank you Eli
>
> TIA

Previously I tried a PDF image which isn't working for me but a PNG
image is doing very nicely in Info viewer! :-)

By the way, I'm exporting the info files from an org file..

Thank you again for your hint

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

Re: Info viewer: Links to function documentations?

[H. Dieter Wilhelm]

Eli Zaretskii <eliz@gnu.org> writes:

> As for hyperlinks to Emacs documentation: if the intent is to link to
> the doc strings, then this is just a question of someone coming up
> with the code to do that.

It seems that most of the work is already being done with the `helpful'
package on Melpa!  Here's the source code:
https://github.com/wilfred/helpful

Thank you Bruno for the pointer

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

Re: Info viewer: Links to function documentations?

[H. Dieter Wilhelm]

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

> Eli Zaretskii <eliz@gnu.org> writes:
>
>> As for hyperlinks to Emacs documentation: if the intent is to link to
>> the doc strings, then this is just a question of someone coming up
>> with the code to do that.
>
> It seems that most of the work is already being done with the `helpful'

Sorry for above remark, it is completely off the mark.  `helpful' is
about help buffers and NOT info buffers.

The way to go is to inoculate the machinery from help-mode.el (based on
button.el) into info.el.  This I managed for functions, variables and
symbols (based on quotations with `' ) in info files.

At the moment I'm stuck with extending info keybindings so that, for
example, <TAB> is skipping to the buttons and to the texinfo links.

I've seen that help is building a sparse map and using a parent map

  (defvar help-mode-map
    (let ((map (make-sparse-keymap)))
      (set-keymap-parent map (make-composed-keymap button-buffer-map
                                                   special-mode-map))

I'd like to do something similar for info as well but info is not using
a sparse map and I'm not sure if I can use set-keymap-parent.

 (defvar Info-mode-map
   (let ((map (make-keymap)))
     (suppress-keymap map)

Thank you for your feedback

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