[Orgmode] RFC: Syntax for page numbers in file: links?

[Jan Böcker]

Hello List,

During the discussion in the "protocol for PDFs?" thread, I realized
that docview: links are an almost exact copy of file: links, the only
single difference being that file: takes a line number and docview:
links take a page number.

Up until now, (docview:) links to PDF files have been the only link type
known to me which took a page number. With the upcoming integration of
Xournal and Org that Daniel M. German is working on, there will already
be two of those.

Daniel also wants to add org-store-link functionality to evince, so he
needs a link type with page numbers for PDFs, too. I could (and have in
a proof-of-concept version) modify org-docview.el to open PDFs with an
external viewer, but I think what really should happen is the following:

- We need a syntax to specify an (optional) page number for file:
  links, and make the line number optional as well.
  This might look something like this:

  - file:<path>[:page][::line]
  - file:~/some-file.txt::23    some-file.txt, line 23
  - file:~/document.pdf:4       document.pdf, page 4
  - file:~/document.odf:3::5    document.odf, page 3, line 5

  This is only what comes to my mind immediately about one possibility
  of encoding this.

- org-docview-store-link should return links in the new syntax
  (e.g. file:~/some-doc.pdf:5 instead of docview:~/some-doc.pdf::5)

- the same syntax could also be used to integrate evince and Xournal

- org-file-apps should allow to specify how to pass a page number to
  an external program. Unlike the file name, this is an optional
  argument, as a link may not specify a page number at all.

  I do not know how to do this in an elegant way, maybe let
  the user specify multiple entries - one for links with a page
  number, one for links without.

- the same should apply to line numbers - maybe someone will integrate
  Org with Open Office or some heretic wants to open all text files in
  zile, who knows?

- if a link with a page number is opened, org-file-apps specifies
  "Visit with Emacs", and emacs decides to open it in doc-view-mode,
  doc-view-goto-page should be called with the page number. (I imagine
  this would be possible using the right hooks?)

- Line number and page number also seem somewhat arbitrary as the only
  pieces of data available to point to a specific location inside a
  document. There are HTML fragment identifiers, which AFAIK work in
  http: links but do not in file: links.
  One might also imagine specifying a precise position in a PDF
  using a line number and a percentage to indicate how far the
  page should be scrolled down.

  So if it is feasible at all, we might want an even more general syntax
  to specify a "target location", maybe attributes such as
  [[file:/path/to/file][page=5,line=3][Description]]
  [[file:notes.txt][search="The quick brown fox"][Description]]

  This may obviously create more problems with backward compatibility.


Luckily, there has been no release featuring docview: links yet, so
there still is a chance to correct this mistake without breaking too much.

If there will be no special syntax for page numbers, we could also
interpret the line number as a page number for PDF and Xournal files,
but that number would still need to be passed to an external application
and cause doc-view-goto-page to be called when visiting a PDF in emacs.

I really do not want to create another file: link type with
org-docview.el, which is why I ask y'all to comment!

- Jan