What's the flow for adding info: links in Org documents?

What's the flow for adding info: links in Org documents?

[Kaushal Modi]

Hello all,

I believe I am missing out something basic with inserting info: links
in Org documents.

The info links look like:

    [[info:org#External links]]

But if I am on that Info node and I hit `w' to copy the node
reference, this gets copied: "(org) External Links"

So when I insert a link in Org, it goes like this:

1. Type "[[info:"
2. Paste the Info node ref, so that I get "[[info:(org) External Links"
3. Refactor that to make it parseable by ol-info: "[[info:org#External Links]]"

I can locally advice the `org-info-export' so that "[[info:(org)
External Links]]" would work as well. But I think I am missing out on
some flow that would make the above manually editing in step 3
unnecessary.

How do you insert info: links efficiently?

--
Kaushal Modi

Re: What's the flow for adding info: links in Org documents?

[Kaushal Modi]

On Mon, Apr 11, 2022 at 8:35 AM Kaushal Modi <kaushal.modi@gmail.com> wrote:

> I believe I am missing out something basic with inserting info: links
> in Org documents.

Yes, I was missing out on something :)

To my future self:

1. When in Info buffer, do M-x org-store-link (typically a user binds
this to C-c l: https://orgmode.org/manual/Activation.html ). The link
gets copied in the [[info:MANUAL#NODE]] format.
2. In Org buffer, do C-c C-l to insert that last stored link.

Re: What's the flow for adding info: links in Org documents?

[Max Nikulin]

On 11/04/2022 19:47, Kaushal Modi wrote:
> On Mon, Apr 11, 2022 at 8:35 AM Kaushal Modi wrote:
> 
>> I believe I am missing out something basic with inserting info: links
>> in Org documents.
> 
> Yes, I was missing out on something :)
> 
> To my future self:
> 
> 1. When in Info buffer, do M-x org-store-link (typically a user binds
> this to C-c l: https://orgmode.org/manual/Activation.html ). The link
> gets copied in the [[info:MANUAL#NODE]] format.
> 2. In Org buffer, do C-c C-l to insert that last stored link.

There are a some problems with info links outside of Emacs:
- Export to PDF
- Links to single page manuals as the result of export to HTML. E.g. 
Emacs manual is really huge
- info: is a registered scheme, but not for texinfo.
   https://www.rfc-editor.org/rfc/rfc4452.html
   RFC 4452 - The "info" URI Scheme for Information Assets

Re: What's the flow for adding info: links in Org documents?

[Kaushal Modi]

On Mon, Apr 11, 2022 at 10:57 AM Max Nikulin <manikulin@gmail.com> wrote:

> There are a some problems with info links outside of Emacs:
> - Export to PDF

Yeah, I recently realized that I will need to add custom support for
exporting info: links using ox-hugo. I made a small blog post out of
this learning: https://scripter.co/linking-and-exporting-org-info-links/.

> - Links to single page manuals as the result of export to HTML. E.g.
> Emacs manual is really huge

I did not understand this. The HTML exports convert an Info node to a
hyperlink of the same manual page online.

> - info: is a registered scheme, but not for texinfo.
>    https://www.rfc-editor.org/rfc/rfc4452.html
>    RFC 4452 - The "info" URI Scheme for Information Assets

Re: What's the flow for adding info: links in Org documents?

[Max Nikulin]

On 13/04/2022 01:26, Kaushal Modi wrote:
> On Mon, Apr 11, 2022 at 10:57 AM Max Nikulin wrote:
> 
>> There are a some problems with info links outside of Emacs:
>> - Export to PDF
> 
> Yeah, I recently realized that I will need to add custom support for
> exporting info: links using ox-hugo. I made a small blog post out of
> this learning: https://scripter.co/linking-and-exporting-org-info-links/.

I would prefer
     info "(org) Top"
to
     Org Info: Top
since the former may be pasted to M-x : or to shell command prompt. And 
the link target ideally should be https://orgmode.org/manual/index.html
Unfortunately there is no way to customize mapping of documents.

>> - Links to single page manuals as the result of export to HTML. E.g.
>> Emacs manual is really huge
> 
> I did not understand this. The HTML exports convert an Info node to a
> hyperlink of the same manual page online.

For <info:emacs#Browse-URL> export to html produces the following link:
https://www.gnu.org/software/emacs/manual/html_mono/emacs.html#Browse_002dURL
I think, a better variant is
https://www.gnu.org/software/emacs/manual/html_node/emacs/Browse_002dURL.html
even though for the Org manual I often prefer single-page HTML version.

Maybe several months ago there was a thread or at least message 
concerning some problems with info links export (PDF?), but I can not 
find it. The word "info" is too general and "ol-info" is present in 
almost every bug reports. Too much noise.

Re: What's the flow for adding info: links in Org documents?

[Kaushal Modi]

On Wed, Apr 13, 2022 at 7:38 AM Max Nikulin <manikulin@gmail.com> wrote:
>
> On 13/04/2022 01:26, Kaushal Modi wrote:
> > On Mon, Apr 11, 2022 at 10:57 AM Max Nikulin wrote:
> >
> >> There are a some problems with info links outside of Emacs:
> >> - Export to PDF
> >
> > Yeah, I recently realized that I will need to add custom support for
> > exporting info: links using ox-hugo. I made a small blog post out of
> > this learning: https://scripter.co/linking-and-exporting-org-info-links/.
>
> I would prefer
>      info "(org) Top"
> to
>      Org Info: Top
> since the former may be pasted to M-x : or to shell command prompt. And
> the link target ideally should be https://orgmode.org/manual/index.html
> Unfortunately there is no way to customize mapping of documents.
>
> >> - Links to single page manuals as the result of export to HTML. E.g.
> >> Emacs manual is really huge
> >
> > I did not understand this. The HTML exports convert an Info node to a
> > hyperlink of the same manual page online.
>
> For <info:emacs#Browse-URL> export to html produces the following link:
> https://www.gnu.org/software/emacs/manual/html_mono/emacs.html#Browse_002dURL
> I think, a better variant is
> https://www.gnu.org/software/emacs/manual/html_node/emacs/Browse_002dURL.html
> even though for the Org manual I often prefer single-page HTML version.

Thanks for your feedback! I absorbed almost all of it into ox-hugo and
wrote about it in a followup blog post:
https://scripter.co/improving-ox-hugo-exported-org-info-links/.

You'll see the update info: link examples on that post.

Re: What's the flow for adding info: links in Org documents?

[Max Nikulin]

On 16/04/2022 10:07, Kaushal Modi wrote:
> On Wed, Apr 13, 2022 at 7:38 AM Max Nikulin <manikulin@gmail.com> wrote:
>>
>> For <info:emacs#Browse-URL> export to html produces the following link:
>> https://www.gnu.org/software/emacs/manual/html_mono/emacs.html#Browse_002dURL
>> I think, a better variant is
>> https://www.gnu.org/software/emacs/manual/html_node/emacs/Browse_002dURL.html
>> even though for the Org manual I often prefer single-page HTML version.
> 
> Thanks for your feedback! I absorbed almost all of it into ox-hugo and
> wrote about it in a followup blog post:
> https://scripter.co/improving-ox-hugo-exported-org-info-links/.

I hope to see similar changes in ol-info.el as well. I appreciate your 
activity since it allows to test such feature and to choose better 
variant of its implementation.

> I wanted the link descriptions in the exported markdown to be
> more“English” and understandable to people not familiar with the
> Emacs Info interface. So I decided to keep this mostly unchanged ..
 From my point of view, references like (info "(org) Top") resembles 
scholar citations and does not harm. Citations are used for a lot of 
time with established language constructs. The only thing I do not like 
is the nested parenthesis. Traditions hypertext formatting is different 
though. I believe, your variant is acceptable since it allows to realize 
whether linked document is known to the reader. It is much better than 
"here" links or series of links hidden behind of words of some 
statement. What I am looking for is something like man(1) that became 
standard way to mention man pages.

https://blog.tecosaur.com/tmio/2021-07-31-citations.html

> I did not change the link description, but I did add a new HTML title
> attribute to the link. This attribute contains the Emacs Lisp code
> needed to access the Info manual from Emacs. … Of course, the user will
> still not be able to copy that text and paste in Emacs. But it will
> still provide them enough hint on how to access Info nodes in Emacs.

Your decision is certainly better than a multistep recipe from "emacs 
--help": "Run M-x info RET m emacs RET m emacs invocation RET inside 
Emacs to read the main documentation for these command-line arguments."

At some moment I got tired of aggressive kindness of sites using 
relative timestamps in text and put full timestamps to titles. I created 
a browser extension that tries to extract text from title, alt and some 
other attributes:
https://addons.mozilla.org/firefox/addon/altcopy/
I was disappointed when I discovered that e.g. bugzilla has some 
countermeasures and may temporary remove title in response to right click...

Back to info links. I am curious if it is possible to implement handlers 
for particular URLs to allow users to choose whether they would like to 
open a web page or a local application. It is doable on Android, but I 
am unsure concerning regular desktop environments since I never tried to 
do it. Mozilla promised to not remove intercepting network request 
handlers from manifest v3 add-ons, but I would prefer declarative 
approach. Certainly it will require either desktop-wide scheme handler 
of info links or a native messaging helper.

For a while I spent some time experimenting with per-link switch to 
choose its representation.
- It should work with disabled JavaScript.
- It should allow keyboard navigation.
I learned a trick from Timothy when he was redesigning Org site. 
Unfortunately the approach adds some noise for text-only browsers 
ignoring CSS (eww, etc.). I am unsure concerning accessibility and 
convenience to screen reader users and proper aria attributes. Even 
appearance in regular browsers should be tuned, e.g. to use some icons 
instead of text and to make the element recognizable as a switch:

   <span class="link-alternate">
     <input type="checkbox" class="link-switch-nojs"
       title="Switch link type">
     <a href="https://orgmode.org/manual/Working-with-Source-Code.html"
       >info "(org) Working with Source Code"</a>
     <input readonly
       title="Paste text to shell prompt or to GNU Emacs M-:"
       value="info &quot;(org) Working with Source Code&quot;"
   ></span>.

   .link-alternate > input.link-switch-nojs {
     appearance: none;
     width: 6em;
     font-size: 1ex;
     border-color: blue;
     border-width: 2px;
     border-radius: 20%;
   }
   .link-alternate > input.link-switch-nojs::after,
   .link-alternate > input.link-switch-nojs::before {
     padding: 2px;
   }

   /* ::before can not be styled for :checked state */
   .link-alternate > input.link-switch-nojs::before {
     content: "Web";
     vertical-align: super;
   }
   .link-alternate > input.link-switch-nojs::after {
     content: "Info";
     vertical-align: sub;
   }
   .link-alternate > input.link-switch-nojs:not(:checked) {
     border-top-style: solid;
     border-left-style: solid;
   }
   .link-alternate > input.link-switch-nojs:checked {
     border-bottom-style: solid;
     border-right-style: solid;
   }

I have tried "<label>" but it does not allow to hide checkbox input 
element using "display: none" otherwise it works with mouse only. 
Moreover, styling through content CSS property, the text is skipped 
during selection. It seems, radio inputs have no advantages in this case.