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.