Specify page number in hyperlink [to pdf]

Specify page number in hyperlink [to pdf]

[Joe Riel]

The hyperlink syntax allows specifying a line number, however,
that doesn't do anything (other than force the document to
be opened inside of emacs) with a non-text file (say a pdf).

Is therea an extension to allow specifying a page number
so that a link to a pdf is opened at the specified page?

Re: Specify page number in hyperlink [to pdf]

[Jan Böcker]

On 28.04.2010 20:30, Joe Riel wrote:
> The hyperlink syntax allows specifying a line number, however,
> that doesn't do anything (other than force the document to
> be opened inside of emacs) with a non-text file (say a pdf).
> 
> Is therea an extension to allow specifying a page number
> so that a link to a pdf is opened at the specified page?

There is in the current git version, its not yet documented though.


Add an entry to the variable org-file-apps like this:
("\\.pdf::\\([0-9]+\\)\\'" . "evince \"%s\" -p %1")

Or as seen in the customize interface:
Extension: \.pdf::\([0-9]+\)\'
Command:   evince "%s" -p %1

The subexpression \([0-9]+\) in the regex captures the page number,
which replaces the %1 in the command string. (This example assumes you
want to open your PDFs with evince, which accepts a page number after
the -p option.)

You can then reference a specific page of a PDF like this:
[[file:/path/to/document.pdf::42]]

I had planned to document this yesterday, but unfortunately spent the
better part of the day recovering from a cold. I will send a patch
describing how this works, when exactly the new behaviour kicks in and
the implications for backwards compatibility as soon as I find time to
describe it compactly enough to fit into the docstring.

HTH, Jan


PS: Here is my first draft of the change to the docstring; it does not
mention custom lisp forms yet, and still makes the docstring too long
for my taste. I guess I'll write a separate tutorial on worg which I'll
reference in the docstring, and include in the docstring only one
example of the extended feature and information on backwards compatibility.


 \"regex\"     Regular expression matched against the file name.  For
backward
                compatibility, this can also be a string with only
alphanumeric
                characters, which is then interpreted as an extension.
+
+               If this regular expression captures parts of the
+               match using groups (subexpressions), it is matched
+               against the whole link instead; \"%n\" in a
+               command string will be replaced by the n-th
+               subexpression match, just like \"%s\" is replaced
+               with the file name.
+
+               For backwards compatibility, this behaviour is not
+               triggered if the command string does not contain
+               any \"%n\", i.e. in that case the regexp is still
+               matched against the file name.
+
+               If you want to use groups in your regexp but do not want
+               it matched against the whole link, use shy groups like this:
+	       \"\\(?:txt|html\\)\"

Re: Specify page number in hyperlink [to pdf]

[Joe Riel]

Jan Böcker wrote:
> On 28.04.2010 20:30, Joe Riel wrote:
>   
>> The hyperlink syntax allows specifying a line number, however,
>> that doesn't do anything (other than force the document to
>> be opened inside of emacs) with a non-text file (say a pdf).
>>
>> Is therea an extension to allow specifying a page number
>> so that a link to a pdf is opened at the specified page?
>>     
>
> There is in the current git version, its not yet documented though.
>
>
> Add an entry to the variable org-file-apps like this:
> ("\\.pdf::\\([0-9]+\\)\\'" . "evince \"%s\" -p %1")
>
> Or as seen in the customize interface:
> Extension: \.pdf::\([0-9]+\)\'
> Command:   evince "%s" -p %1
>
> The subexpression \([0-9]+\) in the regex captures the page number,
> which replaces the %1 in the command string. (This example assumes you
> want to open your PDFs with evince, which accepts a page number after
> the -p option.)
>
> You can then reference a specific page of a PDF like this:
> [[file:/path/to/document.pdf::42]]
>
>
>   
Thanks.  Just cloned the git and built.  This feature
 does precisely what I want.

Re: Specify page number in hyperlink [to pdf]

[Joe Riel]

Jan Böcker wrote:
> On 28.04.2010 20:30, Joe Riel wrote:
>   
>> The hyperlink syntax allows specifying a line number, however,
>> that doesn't do anything (other than force the document to
>> be opened inside of emacs) with a non-text file (say a pdf).
>>
>> Is therea an extension to allow specifying a page number
>> so that a link to a pdf is opened at the specified page?
>>     
>
> There is in the current git version, its not yet documented though.
>
>
> Add an entry to the variable org-file-apps like this:
> ("\\.pdf::\\([0-9]+\\)\\'" . "evince \"%s\" -p %1")
>
> Or as seen in the customize interface:
> Extension: \.pdf::\([0-9]+\)\'
> Command:   evince "%s" -p %1
>
> The subexpression \([0-9]+\) in the regex captures the page number,
> which replaces the %1 in the command string. (This example assumes you
> want to open your PDFs with evince, which accepts a page number after
> the -p option.)
>
> You can then reference a specific page of a PDF like this:
> [[file:/path/to/document.pdf::42]]
>
> I had planned to document this yesterday, but unfortunately spent the
> better part of the day recovering from a cold. I will send a patch
> describing how this works, when exactly the new behaviour kicks in and
> the implications for backwards compatibility as soon as I find time to
> describe it compactly enough to fit into the docstring.
>
> HTH, Jan
>   
A related question; can this extension be used with link abbreviations?

I tried

#+LINK: sample file:/home/joe/sample.pdf

with

[[sample::3]]

but that does not work.

Re: Specify page number in hyperlink [to pdf]

[Nick Dokos]

Joe Riel <joer@san.rr.com> wrote:

> Jan Böcker wrote:
> > On 28.04.2010 20:30, Joe Riel wrote:
> >   
> >> The hyperlink syntax allows specifying a line number, however,
> >> that doesn't do anything (other than force the document to
> >> be opened inside of emacs) with a non-text file (say a pdf).
> >>
> >> Is therea an extension to allow specifying a page number
> >> so that a link to a pdf is opened at the specified page?
> >>     
> >
> > There is in the current git version, its not yet documented though.
> >
> >
> > Add an entry to the variable org-file-apps like this:
> > ("\\.pdf::\\([0-9]+\\)\\'" . "evince \"%s\" -p %1")
> >
> > Or as seen in the customize interface:
> > Extension: \.pdf::\([0-9]+\)\'
> > Command:   evince "%s" -p %1
> >
> > The subexpression \([0-9]+\) in the regex captures the page number,
> > which replaces the %1 in the command string. (This example assumes you
> > want to open your PDFs with evince, which accepts a page number after
> > the -p option.)
> >
> > You can then reference a specific page of a PDF like this:
> > [[file:/path/to/document.pdf::42]]
> >
> > I had planned to document this yesterday, but unfortunately spent the
> > better part of the day recovering from a cold. I will send a patch
> > describing how this works, when exactly the new behaviour kicks in and
> > the implications for backwards compatibility as soon as I find time to
> > describe it compactly enough to fit into the docstring.
> >
> > HTH, Jan
> >   
> A related question; can this extension be used with link abbreviations?
> 
> I tried
> 
> #+LINK: sample file:/home/joe/sample.pdf
> 
> with
> 
> [[sample::3]]
> 
> but that does not work.
> 


This happens in org-link-expand-abbrev: it splits sample::3 into
"sample" and "3", looks up "sample" in org-link-abbrev-alist and
performs the replacement, then returns the concatenation of that with
the "3" part, thereby eliminating the "::" marker that would trigger the
further processing necessary to open the pdf file at the given page.

You could try

#+LINK: sample file:/home/joe/sample.pdf::%s

This will work with the [[sample::3]] link, but not with [[sample]].

Alternatively, you could modify the function to keep the "::" marker
(at least conditionally: leave it there if it's already there). That
would make both of the above work and I think all the examples of
section 4.6 would work as well. Here is a very lighly tested patch:

diff --git a/lisp/org.el b/lisp/org.el
index 9920504..3ede9c4 100644
--- a/lisp/org.el
+++ b/lisp/org.el
@@ -7703,6 +7703,7 @@ call CMD."
       (let* ((key (match-string 1 link))
 	     (as (or (assoc key org-link-abbrev-alist-local)
 		     (assoc key org-link-abbrev-alist)))
+	     (colontype (and (match-end 1) (match-beginning 3) (substring (match-string 2 link) 0 (- (match-beginning 3) (match-end 1)))))
 	     (tag (and (match-end 2) (match-string 3 link)))
 	     rpl)
 	(if (not as)
@@ -7713,6 +7714,7 @@ call CMD."
 	   ((string-match "%s" rpl) (replace-match (or tag "") t t rpl))
 	   ((string-match "%h" rpl)
 	    (replace-match (url-hexify-string (or tag "")) t t rpl))
+	   ((string-equal colontype "::") (concat rpl colontype tag))
 	   (t (concat rpl tag)))))
     link))

HTH,
Nick

Re: Specify page number in hyperlink [to pdf]

[Jan Böcker]

On 30.04.2010 10:10, Nick Dokos wrote:
> Joe Riel <joer@san.rr.com> wrote:
> 
>> Jan Böcker wrote:

>> A related question; can this extension be used with link abbreviations?
>>
>> I tried
>>
>> #+LINK: sample file:/home/joe/sample.pdf
>>
>> with
>>
>> [[sample::3]]
>>
>> but that does not work.
>>
> 
> 
> This happens in org-link-expand-abbrev: it splits sample::3 into
> "sample" and "3", looks up "sample" in org-link-abbrev-alist and
> performs the replacement, then returns the concatenation of that with
> the "3" part, thereby eliminating the "::" marker that would trigger the
> further processing necessary to open the pdf file at the given page.
> 
> You could try
> 
> #+LINK: sample file:/home/joe/sample.pdf::%s
> 
> This will work with the [[sample::3]] link, but not with [[sample]].

Because org-link-expand-abbrev only swallows up to two colons, this
would work (but does look rather silly):
[[sample::::3]]

The following will work with [[sample::3]] and [[sample]], but relies on
the fact that evince, when asked to display page 0, ignores the invalid
page number and just displays page 1 instead:

#+LINK: sample file:/home/joe/sample.pdf::0%s



> 
> Alternatively, you could modify the function to keep the "::" marker
> (at least conditionally: leave it there if it's already there). That
> would make both of the above work and I think all the examples of
> section 4.6 would work as well. Here is a very lighly tested patch:
> 
> [snip]

Nick, the only thing I can think of right now that this would break is
[[bugzilla::129]] (assuming the settings from manual section 4.6).

However, AFAIK this is undocumented behaviour, because the manual does
not mention that an extra ":" between linkword and tag will be silently
ignored.

I agree that applying your patch would be the way to go (this problem is
not related to the extended regex features in org-file-apps; it also
happens when linking to a line number in a plain text file).

Actually, it's half bugfix half new feature:
the bug here is that [[sample:::3]] does not work (one would assume it
does from reading the manual), and the feature is that instead of
accepting that, the patch requires [[sample::3]] instead.

So +1 from me to apply the patch.

- Jan

Re: Specify page number in hyperlink [to pdf]

[Nick Dokos]

Jan Böcker <jan.boecker@jboecker.de> wrote:

> Actually, it's half bugfix half new feature:

Right (although we can quibble about the exact proportion :-)), and to
the extent that it is a new feature, some more documentation would need
to be added if the patch is otherwise acceptable.

Nick

Re: Specify page number in hyperlink [to pdf]

[Carsten Dominik]

Hi everyone,

when this discussion is settled, can someone please summarize it for  
me and send me the patch everyone agrees on?

Thanks.

- Carsten

On Apr 30, 2010, at 5:24 PM, Nick Dokos wrote:

> Jan Böcker <jan.boecker@jboecker.de> wrote:
>
>> Actually, it's half bugfix half new feature:
>
> Right (although we can quibble about the exact proportion :-)), and to
> the extent that it is a new feature, some more documentation would  
> need
> to be added if the patch is otherwise acceptable.
>
> Nick
>
>
> _______________________________________________
> Emacs-orgmode mailing list
> Please use `Reply All' to send replies to the list.
> Emacs-orgmode@gnu.org
> http://lists.gnu.org/mailman/listinfo/emacs-orgmode

- Carsten

Re: Specify page number in hyperlink [to pdf]

[Joe Riel]

Nick Dokos wrote:
> Joe Riel <joer@san.rr.com> wrote:
>
>   
>> Jan Böcker wrote:
>>     
>>> On 28.04.2010 20:30, Joe Riel wrote:
>>>   
>>>       
>>>> The hyperlink syntax allows specifying a line number, however,
>>>> that doesn't do anything (other than force the document to
>>>> be opened inside of emacs) with a non-text file (say a pdf).
>>>>
>>>> Is therea an extension to allow specifying a page number
>>>> so that a link to a pdf is opened at the specified page?
>>>>     
>>>>         
>>> There is in the current git version, its not yet documented though.
>>>
>>>
>>> Add an entry to the variable org-file-apps like this:
>>> ("\\.pdf::\\([0-9]+\\)\\'" . "evince \"%s\" -p %1")
>>>
>>> Or as seen in the customize interface:
>>> Extension: \.pdf::\([0-9]+\)\'
>>> Command:   evince "%s" -p %1
>>>
>>> The subexpression \([0-9]+\) in the regex captures the page number,
>>> which replaces the %1 in the command string. (This example assumes you
>>> want to open your PDFs with evince, which accepts a page number after
>>> the -p option.)
>>>
>>> You can then reference a specific page of a PDF like this:
>>> [[file:/path/to/document.pdf::42]]
>>>
>>> I had planned to document this yesterday, but unfortunately spent the
>>> better part of the day recovering from a cold. I will send a patch
>>> describing how this works, when exactly the new behaviour kicks in and
>>> the implications for backwards compatibility as soon as I find time to
>>> describe it compactly enough to fit into the docstring.
>>>
>>> HTH, Jan
>>>   
>>>       
>> A related question; can this extension be used with link abbreviations?
>>
>> I tried
>>
>> #+LINK: sample file:/home/joe/sample.pdf
>>
>> with
>>
>> [[sample::3]]
>>
>> but that does not work.
> This happens in org-link-expand-abbrev: it splits sample::3 into
> "sample" and "3", looks up "sample" in org-link-abbrev-alist and
> performs the replacement, then returns the concatenation of that with
> the "3" part, thereby eliminating the "::" marker that would trigger the
> further processing necessary to open the pdf file at the given page.
>
> You could try
>
> #+LINK: sample file:/home/joe/sample.pdf::%s
>
> This will work with the [[sample::3]] link, but not with [[sample]].
>   
That is fine, though I'll apply the patch.  There does appear to
be another bug, or my misunderstanding.  That is, even
without the link,

  [[file:/home/joe/sample.pdf]]

does not work properly.  That is, clicking on it (mouse 1)
opens the pdf inside emacs rather than in a standalone pdf reader.  
Previously
that wasn't the case (if memory serves).  Using

  [[file:/home/joe/sample.pdf::1]]

for the link opens it in a standalone reader.


Joe

Re: Specify page number in hyperlink [to pdf]

[Nick Dokos]

Joe Riel <joer@san.rr.com> wrote:

> That is fine, though I'll apply the patch.  There does appear to
> be another bug, or my misunderstanding.  That is, even
> without the link,
> 
>  [[file:/home/joe/sample.pdf]]
> 
> does not work properly.  That is, clicking on it (mouse 1)
> opens the pdf inside emacs rather than in a standalone pdf reader.
> Previously
> that wasn't the case (if memory serves).  Using
> 
>  [[file:/home/joe/sample.pdf::1]]
> 
> for the link opens it in a standalone reader.
> 
> 

Probably because you have an explicit setting for the latter in
org-file-apps (as Jan suggested) but not for the former. There are many
twisty passages here, but I think that in the end emacs looks at your
mailcap: if it finds no match there then it opens it itself.

I have 

application/pdf; xpdf -q %s

in my ~/.mailcap and indeed the link opens in xpdf.

HTH,
Nick

Re: Specify page number in hyperlink [to pdf]

[Joe Riel]

Nick Dokos wrote:
> Joe Riel <joer@san.rr.com> wrote:
>
>   
>> That is fine, though I'll apply the patch.  There does appear to
>> be another bug, or my misunderstanding.  That is, even
>> without the link,
>>
>>  [[file:/home/joe/sample.pdf]]
>>
>> does not work properly.  That is, clicking on it (mouse 1)
>> opens the pdf inside emacs rather than in a standalone pdf reader.
>> Previously
>> that wasn't the case (if memory serves).  Using
>>
>>  [[file:/home/joe/sample.pdf::1]]
>>
>> for the link opens it in a standalone reader.
>>
>>
>>     
>
> Probably because you have an explicit setting for the latter in
> org-file-apps (as Jan suggested) but not for the former. There are many
> twisty passages here, but I think that in the end emacs looks at your
> mailcap: if it finds no match there then it opens it itself.
>
> I have 
>
> application/pdf; xpdf -q %s
>
> in my ~/.mailcap and indeed the link opens in xpdf.
>
>   
My /etc/mailcap defines an appropriate application for pdfs.
The problem is that I replaced the existing entry
for pdf in org-file-apps, so that without the page tag there is no match.

Doing

(setq org-file-apps '((auto-mode . emacs)
             ("\\.mm\\'" . default)
             ("\\.x?html?\\'" . default)
             ("\\.pdf::\\([0-9]+\\)\\'" . "evince \"%s\" -p %1")
             ("\\.pdf\\'" . default)   ;; this was the original
             ))

allows links to pdf's without the page tag to open in an external 
application.