info URL « open at point » patch

info URL « open at point » patch

[Vincent Belaïche]

[-- Attachment #1.1: Type: text/plain, Size: 1555 bytes --]

Bonjour tout l'monde !
I am writing to both Emacs-devel and org-mode list because this concerns
browsing URL, and Org-mode already has quite some stuff on this.
Recently I came across this that in an Info file a « file: » protocol
URL is not opened at point. Please find attached a patch to make it
known to the Emacs info browser.
My point was that I have some manual that are only in HTML or PDF, like
the SVN manual, In have a local copy, and I want to find it through a
manual index that I written in Texinfo to get an info node with this
index.
I suspect that some other people than me may have the same need, and as
such the patch is useful. If everybody agrees with the attached patch I
can commit/push it on the master branch.

Now, maybe it is the time to reconsider how the info browser consider
URL's, maybe there is some code factorization to do with org-mode, in
order to accept a wider range of variety of URL's. Org-mode is good at
that, and that is why I am having its forum in the loop of this
discussion.
For instance, I remember that at some point of time at my job I was
handling some requirements with IBM-Doors (it was a long time ago, and
that SW was named Telelogic-Doors at that time). I had a few org-mode
files with custom URL's pointing at Doors objects, and that was quite
useful to me to be able to keep in my TODO lists, and other Org-mode
stuff direct links to these objects. I suspect that some people may have
the same need with Texinfo documents when they want to use custom URL's…
  Vincent.

[-- Attachment #1.2: Type: text/html, Size: 2104 bytes --]

[-- Attachment #2: info-patch.diff --]
[-- Type: application/octet-stream, Size: 629 bytes --]

diff --git a/lisp/info.el b/lisp/info.el
index c45b7f9cb3..ab2c51d84b 100644
--- a/lisp/info.el
+++ b/lisp/info.el
@@ -3938,8 +3938,8 @@ Info-try-follow-nearest-node
 If FORK is non-nil, it is passed to `Info-goto-node'."
   (let (node)
     (cond
-     ((setq node (Info-get-token (point) "[hf]t?tps?://"
-				 "\\([hf]t?tps?://[^ \t\n\"`‘({<>})’']+\\)"))
+     ((setq node (Info-get-token (point) "\\(?:f\\(?:ile\\|tp\\)\\|https?\\)://"
+				 "\\(\\(?:f\\(?:ile\\|tp\\)\\|https?\\)://[^ \t\n\"`‘({<>})’']+\\)"))
       (browse-url node)
       (setq node t))
      ((setq node (Info-get-token (point) "\\*note[ \n\t]+"

Re: info URL « open at point » patch

[Eli Zaretskii]

> From: Vincent Belaïche <vincent.b.1@hotmail.fr>
> Date: Sun, 24 Jun 2018 06:57:53 +0000
> 
> I am writing to both Emacs-devel and org-mode list because this concerns
> browsing URL, and Org-mode already has quite some stuff on this.
> Recently I came across this that in an Info file a « file: » protocol
> URL is not opened at point. Please find attached a patch to make it
> known to the Emacs info browser.
> My point was that I have some manual that are only in HTML or PDF, like
> the SVN manual, In have a local copy, and I want to find it through a
> manual index that I written in Texinfo to get an info node with this
> index.

Maybe I'm missing something, but I don't understand why support for
file:// protocol is needed in Info.  Info already supports its own
protocol of referencing to an external file, via the @xref command and
its varieties, with 4 or more arguments.  So why cannot you simply use
one of those cross-referencing commands, if you want a reference to
another manual?

Thanks.

Re: info URL « open at point » patch

[Jean-Christophe Helary]

> On Jun 24, 2018, at 15:57, Vincent Belaïche <vincent.b.1@hotmail.fr> wrote:
> 
> Bonjour tout l'monde !
> I am writing to both Emacs-devel and org-mode list because this concerns
> browsing URL, and Org-mode already has quite some stuff on this.
> Recently I came across this that in an Info file a « file: » protocol
> URL is not opened at point. Please find attached a patch to make it
> known to the Emacs info browser.
> My point was that I have some manual that are only in HTML or PDF, like
> the SVN manual, In have a local copy, and I want to find it through a
> manual index that I written in Texinfo to get an info node with this
> index.

> <info-patch.diff>

Wouldn't it be shorter and easier to understand/maintain to explicitly describe the protocols:

+     ((setq node (Info-get-token (point) "\\(?:f\\(?:ile\\|tp\\)\\|https?\\)://"

???

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

RE: info URL « open at point » patch

[Vincent Belaïche]

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

Hello Eli,

To my understanding @xref works only for info links (node names or anchors, or qualified thereof where the qualificator is the info document name) --- maybe I am wrong, tell me if so ---  but I want to refer to an HTML or PDF document.

  Vincent.


________________________________
De : Eli Zaretskii <eliz@gnu.org>
Envoyé : dimanche 24 juin 2018 16:31
À : Vincent Belaïche
Cc : emacs-devel@gnu.org; emacs-orgmode@gnu.org
Objet : Re: info URL « open at point » patch

> From: Vincent Belaïche <vincent.b.1@hotmail.fr>
> Date: Sun, 24 Jun 2018 06:57:53 +0000
>
> I am writing to both Emacs-devel and org-mode list because this concerns
> browsing URL, and Org-mode already has quite some stuff on this.
> Recently I came across this that in an Info file a « file: » protocol
> URL is not opened at point. Please find attached a patch to make it
> known to the Emacs info browser.
> My point was that I have some manual that are only in HTML or PDF, like
> the SVN manual, In have a local copy, and I want to find it through a
> manual index that I written in Texinfo to get an info node with this
> index.

Maybe I'm missing something, but I don't understand why support for
file:// protocol is needed in Info.  Info already supports its own
protocol of referencing to an external file, via the @xref command and
its varieties, with 4 or more arguments.  So why cannot you simply use
one of those cross-referencing commands, if you want a reference to
another manual?

Thanks.

[-- Attachment #2: Type: text/html, Size: 2565 bytes --]

RE: info URL « open at point » patch

[Vincent Belaïche]

See (info "(texinfo) Reference Syntax")…




De : Vincent Belaïche <vincent.b.1@hotmail.fr>
Envoyé : dimanche 24 juin 2018 18:48
À : Eli Zaretskii
Cc : emacs-devel@gnu.org; emacs-orgmode@gnu.org
Objet : RE: info URL « open at point » patch
   

Hello Eli,
To my understanding @xref works only for info links (node names or anchors, or qualified thereof where the qualificator is the info document name) --- maybe I am wrong, tell me if so ---  but I want to refer to an HTML  or PDF document.
  Vincent.




De : Eli Zaretskii <eliz@gnu.org>
Envoyé : dimanche 24 juin 2018 16:31
À : Vincent Belaïche
Cc : emacs-devel@gnu.org; emacs-orgmode@gnu.org
Objet : Re: info URL « open at point » patch
  

> From: Vincent Belaïche <vincent.b.1@hotmail.fr>
> Date: Sun, 24 Jun 2018 06:57:53 +0000
> 
> I am writing to both Emacs-devel and org-mode list because this concerns
> browsing URL, and Org-mode already has quite some stuff on this.
> Recently I came across this that in an Info file a « file: » protocol
> URL is not opened at point. Please find attached a patch to make it
> known to the Emacs info browser.
> My point was that I have some manual that are only in HTML or PDF, like
> the SVN manual, In have a local copy, and I want to find it through a
> manual index that I written in Texinfo to get an info node with this
> index.

Maybe I'm missing something, but I don't understand why support for
file:// protocol is needed in Info.  Info already supports its own
protocol of referencing to an external file, via the @xref command and
its varieties, with 4 or more arguments.  So why cannot you simply use
one of those cross-referencing commands, if you want a reference to
another manual?

Thanks.
       

Re: info URL « open at point » patch

[Eli Zaretskii]

> From: Vincent Belaïche <vincent.b.1@hotmail.fr>
> CC: "emacs-devel@gnu.org" <emacs-devel@gnu.org>, "emacs-orgmode@gnu.org"
> 	<emacs-orgmode@gnu.org>
> Date: Sun, 24 Jun 2018 16:48:30 +0000
> 
> To my understanding @xref works only for info links (node names or anchors, or qualified thereof where the
> qualificator is the info document name) --- maybe I am wrong, tell me if so ---  but I want to refer to an HTML
> or PDF document.

No, Texinfo cross-references work in any format supported by Texinfo.
If your link should only appear in the HTML version, you could use the
@ifhtml..@end ifhtml conditional, and similarly with links that should
only appear in PDF (i.e. printed version) of the manual.  There's also
@ifnotinfo etc.

So once again I don't think I understand the problem.  Could you
perhaps elaborate, or show an actual example?

RE: info URL « open at point » patch

[Vincent Belaïche]

What I want to do is to refer an HTML or PDF document from an Info document. So
I want the info browser to launch the web browser for it to open a
« file: »  protocol document.

Here is the Texinfo source which I would like to use:

--8<----8<----8<----8<----8<-- begin -->8---->8---->8---->8---->8----
\input texinfo   @c -*-texinfo-*-
@c %**start of header
@setfilename svnbook.info
@settitle Manuel Subversion 1.8
@c %**end of header


@dircategory Archiving
@direntry
* SVN book: (svnbook). Gestion de versions avec Subversion
@end direntry



@node Top
@top SVN Book

@url{file:///c%3A/Program%20Files/CollabNet/Subversion%20Client/doc/svn-book-html-chunk/index.html,SVN book}


@bye

@c Lo
cal Variables:
@c compile-command: "makeinfo svnbook.texi && copy svnbook.info c:\\Nos_Programmes\\MinGW\\msys\\info\\"
@c End:
--8<----8<----8<----8<----8<--  end  -->8---->8---->8---->8---->8----

  Vincent.





De : Eli Zaretskii <eliz@gnu.org>
Envoyé : dimanche 24 juin 2018 19:03
À : Vincent Belaïche
Cc : emacs-devel@gnu.org; emacs-orgmode@gnu.org
Objet : Re: info URL « open at point » patch
  

> From: Vincent Belaïche <vincent.b.1@hotmail.fr>
> CC: "emacs-devel@gnu.org" <emacs-devel@gnu.org>, "emacs-orgmode@gnu.org"
>        <emacs-orgmode@gnu.org>
> Date: Sun, 24 Jun 2018 16:48:30 +0000
> 
> To my understanding @xref works only for info links (node names or anchors, or qualified thereof where the
> qualificator is the info document name) --- maybe I am wrong, tell me if so ---  but I want to refer to an HTML
> or PDF document.

No, Texinfo cross-references work in any format supported by Texinfo.
If your link should only appear in the HTML version, you could use the
@ifhtml..@end ifhtml conditional, and similarly with links that should
only appear in PDF (i.e. printed version) of the manual.  There's also
@ifnotinfo etc.

So once again I don't think I understand the problem.  Could you
perhaps elaborate, or show an actual example?
    

Re: info URL « open at point » patch

[Eli Zaretskii]

> From: Vincent Belaïche <vincent.b.1@hotmail.fr>
> CC: "emacs-devel@gnu.org" <emacs-devel@gnu.org>, "emacs-orgmode@gnu.org"
> 	<emacs-orgmode@gnu.org>
> Date: Sun, 24 Jun 2018 18:21:20 +0000
> 
> What I want to do is to refer an HTML or PDF document from an Info document. So
> I want the info browser to launch the web browser for it to open a
> « file: »  protocol document.

Got it.  Strange use case, but whatever.

RE: info URL « open at point » patch

[Vincent Belaïche]

I generated the regexp with (regexp-opt '("ftp" "http" "https"
"file")). I admit that the list of protocols is not clear from the
regexp, but it was already done this way before my change, and I tried
to minimize the change.
More concerning in my opinion is how the Info-get-token is written. As
some point of the code one can read the following statement:
      ;; First look for a match for START that goes across POS.
      (while (and (not (bobp)) (> (point) (- pos (length start)))
    (not (looking-at start)))
 (forward-char -1))


Here start is a regexp, so (length start) is just the length of the
string holding the regexp, not the max length over which the regexp
match can span. For instance assume that aaaaaaaaaa is a new new
protocol which you want Info-get-token to catch. This is 10 character
long, but the typical regexp to catch it would be « a\{10\} » which is
only 7 character long.
It would propably be cleaner to provide the value to be used instead of
(length start) as a separate optional argument that would be set to
(length start) if omitted.
Another way would be to have some standard function max-matchable-length
that given some regexp would compute the maximum length of its match (or
output some special value like t if the maximum length is infinite),
thus (length start) could be replaced by (max-matchable-length start)
--- maybe this is already somthing existing. In the same vein there
could be some standard function that given regexp re and some position
pos-in would function position pos-out such that the following
expression would be true:
(save-excursion
  (goto-char pos-out)
  (and (<= pos-out pos-in)
       (looking-at re)
       (>= (match-end 0) pos-in)))
I think that such standard function is already existing, but I can't
remember the package name which provides it…
  V.

RE: info URL « open at point » patch

[Vincent Belaïche]

I agree it is a bit strange, but the reason for it is simple : I would
like a single entry point for all the manuals installed on my PC, so
that my old and tired brain does not have to remember where the manual
is located, and what format is it written in. So it would be nice if all
the manuals were just listed in the info top level menu.
So, for manuals that are not written in Texinfo and which I have only a
PDF, HTML, or whatever, I would like just to create a direntry with an
url to the concerned manual.
  V.




De : Eli Zaretskii <eliz@gnu.org>
Envoyé : dimanche 24 juin 2018 20:45
À : Vincent Belaïche
Cc : emacs-devel@gnu.org; emacs-orgmode@gnu.org
Objet : Re: info URL « open at point » patch
  

> From: Vincent Belaïche <vincent.b.1@hotmail.fr>
> CC: "emacs-devel@gnu.org" <emacs-devel@gnu.org>, "emacs-orgmode@gnu.org"
>        <emacs-orgmode@gnu.org>
> Date: Sun, 24 Jun 2018 18:21:20 +0000
> 
> What I want to do is to refer an HTML or PDF document from an Info document. So
> I want the info browser to launch the web browser for it to open a
> « file: »  protocol document.

Got it.  Strange use case, but whatever.
    

Re: info URL « open at point » patch

[Eli Zaretskii]

> From: Vincent Belaïche <vincent.b.1@hotmail.fr>
> CC: "emacs-devel@gnu.org" <emacs-devel@gnu.org>, "emacs-orgmode@gnu.org"
> 	<emacs-orgmode@gnu.org>
> Date: Sun, 24 Jun 2018 20:34:26 +0000
> 
> I agree it is a bit strange, but the reason for it is simple : I would
> like a single entry point for all the manuals installed on my PC, so
> that my old and tired brain does not have to remember where the manual
> is located, and what format is it written in. So it would be nice if all
> the manuals were just listed in the info top level menu.

That's not the strange part.  The strange part is to reference an HTML
document from a Texinfo document.

RE: info URL « open at point » patch

[Vincent Belaïche]

Just to be factual:
1) Does anybody objects the patch as it is --- if not I would push it to the repo ?
2) Does anybody agrees that the coding of Info-get-token is not futureproof (length of regexp string used for max length of matchable string).

  Vincent.



De : Eli Zaretskii <eliz@gnu.org>
Envoyé : lundi 25 juin 2018 04:30
À : Vincent Belaïche
Cc : emacs-devel@gnu.org; emacs-orgmode@gnu.org
Objet : Re: info URL « open at point » patch
  

> From: Vincent Belaïche <vincent.b.1@hotmail.fr>
> CC: "emacs-devel@gnu.org" <emacs-devel@gnu.org>, "emacs-orgmode@gnu.org"
>        <emacs-orgmode@gnu.org>
> Date: Sun, 24 Jun 2018 20:34:26 +0000
> 
> I agree it is a bit strange, but the reason for it is simple : I would
> like a single entry point for all the manuals installed on my PC, so
> that my old and tired brain does not have to remember where the manual
> is located, and what format is it written in. So it would be nice if all
> the manuals were just listed in the info top level menu.

That's not the strange part.  The strange part is to reference an HTML
document from a Texinfo document.
    

RE: info URL « open at point » patch

[Vincent Belaïche]

One more point : do org-mode experts have an idea about whether there
are any better way to match a URL that can be browsed with the
browse-url function.

My point is that for a modular design, the same package that provides
the browse-url function, should also provide some match-url-at-point-p
predicate, e.g.

- 1st optional argument would give a point in the current buffer, (point) if
  omitted
  
- 2nd optional argument would be an include/exclude list of protocols which you
  want/don't want to browse with browse-url. All browsable protocols
  would be assumed if omitted. For instance the info browser would
  exclude info protocol, so that it can directly browse it.


This way the package calling browse-url would be independant/futureproof
w.r.t. to URL format/evolultion.

  V.

Re: info URL « open at point » patch

[Eli Zaretskii]

> From: Vincent Belaïche <vincent.b.1@hotmail.fr>
> CC: "emacs-orgmode@gnu.org" <emacs-orgmode@gnu.org>
> Date: Tue, 26 Jun 2018 05:19:32 +0000
> 
> Just to be factual:
> 1) Does anybody objects the patch as it is --- if not I would push it to the repo ?

It needs to be called out in NEWS.

> 2) Does anybody agrees that the coding of Info-get-token is not futureproof (length of regexp string used for max length of matchable string).

IMO, it's a separate issue and should be discussed separately.

Thanks.

Re: info URL « open at point » patch

[Eli Zaretskii]

> From: Vincent Belaïche <vincent.b.1@hotmail.fr>
> CC: "emacs-devel@gnu.org" <emacs-devel@gnu.org>
> Date: Tue, 26 Jun 2018 05:47:04 +0000
> 
> My point is that for a modular design, the same package that provides
> the browse-url function, should also provide some match-url-at-point-p
> predicate, e.g.

There is such a function: browse-url-url-at-point.

But in general, I don't agree with your assertion: there's nothing
wrong for, e.g., browse-url.el to use a utility function declared
somewhere else.  Modularity doesn't mean each module must be
standalone and self-contained.

RE: info URL « open at point » patch

[Vincent Belaïche]

Hello Eli,
Concerning the patch, I understood that you agree with it provided that
it is upgraded to mention the change in the etc/NEWS file. So I did that
& pushed the change.
Concerning your point « Modularity doesn't mean each module must be
standalone and self-contained », I agree, and I did not say that there
would be anything wrong for e.g. browse-url.el to use a utility function
defined elsewhere. Modules are supposed to interact with each other, and
that implies that they cannot be fully standalone. However, modulary
means that one should observe some functional split: any package, to be
called a package, should have in its documentation some terms of
reference saying its purpose and listing what functions it
accomplishes. While the purpose of the info package is not primarily url
manipulation, I had suspected that this sort function was encompassed by
the package providing the browse-url function, and that is why I stated
that it would be a better modularity if info was relying on a function
provided elsewhere --- which indeed is the opposite statement as saying
that info has to be standalone and self-contain, and as such re-invent
the wheel of url manipulation by itself.
Maybe my mistake was however to assume that 'elsewhere' would be best in
the same package as that providing 'browse-url', but anyhow, I stand on
my point that keeping some URL format specific
"\\(?:f\\(?:ile\\|tp\\)\\|https?\\)://" regexp within the the
Info-follow-nearest-node is not very good from a modularity point of
view.

BTW, the 'browse-url-url-at-point' is not documented by a docstring, so
can we assume that it is usable outside browse-url ?
Anyway, looking at the code I realized that the real work of grabbing
the URL is delegated to the thingatpt package, so my suggestion would be
that info should also use thingatpt. Probably it would be even better
with something like the following construct to remove info URI from
those allowed, as they would better be handled from the info browser
itself:
(let* ((uri-schemes (copy-sequence thing-at-point-uri-schemes))
       (info-uri (car-safe (member "info:" uri-schemes)))
       (thing-at-point-uri-schemes (delq info-uri uri-schemes)))
       (thing-at-point 'url t))
OK, the info browser does not directly knows about info URL, so some
additional work is needed to catch them too. To me this is a real corner
case scenario to refer to a document inside a Texinfo docuemnt via an
info URL: that would mean the document is available only in info format,
ie has not be published in Texinfo. I am not even sure that such
document exists. Aren't info URL meant only to refer to info document
from document written with something else than Texinfo ?
  V.

De : Eli Zaretskii <eliz@gnu.org>
Envoyé : mardi 26 juin 2018 16:34
À : Vincent Belaïche
Cc : emacs-orgmode@gnu.org; brandelune@gmail.com; emacs-devel@gnu.org
Objet : Re: info URL « open at point » patch 
 
> From: Vincent Belaïche <vincent.b.1@hotmail.fr>
> CC: "emacs-devel@gnu.org" <emacs-devel@gnu.org>
> Date: Tue, 26 Jun 2018 05:47:04 +0000
> 
> My point is that for a modular design, the same package that provides
> the browse-url function, should also provide some match-url-at-point-p
> predicate, e.g.
There is such a function: browse-url-url-at-point.
But in general, I don't agree with your assertion: there's nothing
wrong for, e.g., browse-url.el to use a utility function declared
somewhere else.  Modularity doesn't mean each module must be
standalone and self-contained.

Re: info URL « open at point » patch

[Eli Zaretskii]

> From: Vincent Belaïche <vincent.b.1@hotmail.fr>
> CC: "emacs-orgmode@gnu.org" <emacs-orgmode@gnu.org>, "brandelune@gmail.com"
> 	<brandelune@gmail.com>, "emacs-devel@gnu.org" <emacs-devel@gnu.org>
> Date: Wed, 27 Jun 2018 17:39:33 +0000
> 
> Concerning the patch, I understood that you agree with it provided that
> it is upgraded to mention the change in the etc/NEWS file. So I did that
> & pushed the change.

Actually, I expected to see the full changeset before it went in.

For the future, please try to follow the conventions in NEWS, and also
please provide ChangeLog-style entries in the commit log message
describing the places (functions, variables, etc.) where you make
changes.  See CONTRIBUTE for more details.  I fixed the NEWS entry,
but I cannot fix the log entry.

Thanks.