[ANN] org-docview.el - Link to PDF files from org-mode

[ANN] org-docview.el - Link to PDF files from org-mode

[Jan Böcker]

[-- Attachment #1: Type: TEXT/PLAIN, Size: 1003 bytes --]

Hello,

the new doc-view-mode in emacs 23 can be used to view DVI, PDF and 
PostScript files. I have written a custom link type for org-mode to allow 
linking to those files from org-mode.

This is the first thing besides .emacs customization that I have written 
in elisp; as such, any feedback would be much appreciated.
I have only tested it with PDF files so far, but it should work with 
anything doc-view-mode can display.

The attached file adds support for org-store-link inside doc-view-mode 
buffers. The link syntax is:
 	docview:/path/to/file.pdf:<page>
where <page> is the page number to visit.

To use it, copy it to your load path as org-docview.el and add

 	(require 'org-docview)

to your .emacs file.

I'd also like to suggest to integrate this functionality into the 
standard org-mode distribution, as emacs 23 includes doc-view-mode by default.

I am releasing the code under the terms of the GNU General Public License, 
Version 3 or later.

Jan Böcker

[-- Attachment #2: Type: TEXT/PLAIN, Size: 969 bytes --]

;;; org-docview.el --- support for links to doc-view-mode buffers

(require 'org)

(org-add-link-type "docview" 'org-docview-open)
(add-hook 'org-store-link-functions 'org-docview-store-link)

(defun org-docview-open (link)
  (when (string-match "\\(.*\\):\\([0-9]+\\)$"  link)
    (let* ((path (match-string 1 link))
	   (page (string-to-number (match-string 2 link))))
      (org-open-file path 1) ;; let org-mode open the file (in-emacs = 1)
      ;; so that org-link-frame-setup is respected
      (doc-view-goto-page page)
      )))

(defun org-docview-store-link ()
  "Store a link to a docview buffer"
  (when (eq major-mode 'doc-view-mode)
    ;; This buffer is in doc-view-mode
    (let* ((path buffer-file-name)
	   (page (doc-view-current-page))
	   (link (concat "docview:" path ":" (number-to-string page)))
	   (description ""))
      (org-store-link-props
       :type "docview"
       :link link))))

(provide 'org-docview)

[-- Attachment #3: Type: text/plain, Size: 204 bytes --]

_______________________________________________
Emacs-orgmode mailing list
Remember: use `Reply All' to send replies to the list.
Emacs-orgmode@gnu.org
http://lists.gnu.org/mailman/listinfo/emacs-orgmode

Re: [ANN] org-docview.el - Link to PDF files from org-mode

[Leo]

On 2009-08-12 19:25 +0100, Jan Böcker wrote:
> the new doc-view-mode in emacs 23 can be used to view DVI, PDF and
> PostScript files. I have written a custom link type for org-mode to
> allow linking to those files from org-mode.

If doc-view-mode could provide native support for those file types, it'd
be much more realistic to replace standard viewers provided by the os.
Unfortunately the last time I checked which is quite a while ago, it
converted those files into images and use Emacs to view them.

A proper pdf viewer is crucial to academic workers and in each of the
major operating systems, there are free capable viewers available. So if
this feature is to be in org core, please don't make it the default.

Thanks.

Leo

-- 
Emacs uptime: 2 days, 4 hours, 16 minutes, 37 seconds

doc-view-mode (was: Re: [ANN] org-docview.el - Link to PDF files from org-mode)

[Óscar Fuentes]

Leo <sdl.web@gmail.com> writes:

> If doc-view-mode could provide native support for those file types, it'd
> be much more realistic to replace standard viewers provided by the os.
> Unfortunately the last time I checked which is quite a while ago, it
> converted those files into images and use Emacs to view them.

Converting the pdf|ps|dvi file to images is exactly what your favourite
viewer does. The problem with doc-view-mode is that it converts *all*
pages on the document to image *files* which are left on some place of
the hard disk.

If doc-view-mode supported the conversion of just the current page to be
displayed on the screen, without leaving behind thousands of image
files, it would be a decent document reader.

[snip]

-- 
Óscar Fuentes
Desarrollo de Software

Re: doc-view-mode (was: Re: [ANN] org-docview.el - Link to PDF files from org-mode)

[Leo]

On 2009-08-12 20:30 +0100, Óscar Fuentes wrote:
> Converting the pdf|ps|dvi file to images is exactly what your
> favourite viewer does.

Could you provide a link to this? I'd like to know more about the
details.

However, whatever the pdf viewer does, a proper one makes working with
pdf files pleasant. For example, skim on OS X is a decent one.

Leo

-- 
Emacs uptime: 2 days, 5 hours, 24 minutes, 39 seconds

Re: doc-view-mode

[Óscar Fuentes]

Leo <sdl.web@gmail.com> writes:

> On 2009-08-12 20:30 +0100, Óscar Fuentes wrote:
>> Converting the pdf|ps|dvi file to images is exactly what your
>> favourite viewer does.
>
> Could you provide a link to this? I'd like to know more about the
> details.

See the source code of your favourite document viewer.

There is a simple explanation: the screen shows only images, hence
whatever you want to see on the screen must be converted to a image
first.

> However, whatever the pdf viewer does, a proper one makes working with
> pdf files pleasant. For example, skim on OS X is a decent one.

I agree but `pleasant' is a subjective appreciation. doc-view-mode
implements partial scrolling (advance only 90% or so on each screen
down, so the line at the bottom becomes the line at the top) but the pdf
readers I use on Linux (okular) and Windows (Foxit) doesn't implement
this feature, so I often need to micro-adjust the view for reading the
line at the top or the bottom. This is a PITA and the reason why
doc-view-mode is more pleasant for reading books than the other
mentioned viewers.

IIRC OS X has built-in support for ps and pdf, so maybe the doc viewer
there does the same a plain text viewer does on any OS: use the services
provided by the OS for rendering the image.

-- 
Óscar

Re: doc-view-mode

[Tassilo Horn]

Óscar Fuentes <ofv@wanadoo.es> writes:

Hi Óscar,

>> If doc-view-mode could provide native support for those file types,
>> it'd be much more realistic to replace standard viewers provided by
>> the os.  Unfortunately the last time I checked which is quite a while
>> ago, it converted those files into images and use Emacs to view them.

This conversion by ghostscript is needed, cause emacs supports PNG
images, but doesn't support some native PDF/PS/DVI rendering.

Joachim Verona currently works on integrating the imagemagick library
with emacs.  When that is done, at least zooming in doc-view won't
trigger a new conversion run.

> Converting the pdf|ps|dvi file to images is exactly what your
> favourite viewer does.  The problem with doc-view-mode is that it
> converts *all* pages on the document to image *files* which are left
> on some place of the hard disk.

I think that's the only practical solution, else you would have to wait
about a scond when switching to the next page.  The doc-view version in
emacs 23 does a pretty good job in hiding the conversion process, for
example by converting from the current page on instead from the first.

Why are many files a problem for you?  With that approach, opening a
document for the second time works instantly.  And by default those
images are stored somewhere in /tmp:

,----[ C-h v doc-view-cache-directory RET ]
| doc-view-cache-directory is a variable defined in `doc-view.el'.
| Its value is "/tmp/docview1000"
| 
| Documentation:
| The base directory, where the PNG images will be saved.
| 
| You can customize this variable.
`----

On my system, /tmp is cleaned on startup.  And you can always invoke

,----[ C-h f doc-view-clear-cache RET ]
| doc-view-clear-cache is an interactive compiled Lisp function in
| `doc-view.el'.
| 
| (doc-view-clear-cache)
| 
| Delete the whole cache (`doc-view-cache-directory').
`----

to get rid of the images.

Bye,
Tassilo

Re: doc-view-mode

[Óscar Fuentes]

Hello Tassilo.

Tassilo Horn <tassilo@member.fsf.org> writes:

>> Converting the pdf|ps|dvi file to images is exactly what your
>> favourite viewer does.  The problem with doc-view-mode is that it
>> converts *all* pages on the document to image *files* which are left
>> on some place of the hard disk.
>
> I think that's the only practical solution, else you would have to wait
> about a scond when switching to the next page.

I have no problem waiting a second or two, although some experimentation
shows that it is pretty fast opening a small pdf doc and even faster
refreshing the image after M-x doc-view-enlarge. This is on Linux with
a 2.4 GHz CPU.

[snip]

> Why are many files a problem for you?  With that approach, opening a
> document for the second time works instantly.  And by default those
> images are stored somewhere in /tmp:

As said above, instantaneous response is not required for me. The
problem with converting all the document to image files is that I often
open large pdf's (several thousand pages) and small/medium dynamically
generated pdf's. This would create tens of thousands of image files on a
busy day (no exaggerating) which would require several gigabytes.

Perhaps the most important problem with converting the full doc to image
files is that it is a cpu and filesystem intensive process that can take
a long time (think a fully illustrated 1000 page pdf). It steals cpu
cycles on a busy machine (I often read while a long build or test suite
is running) and drains battery on laptops/netbooks.

[snip]

IMHO, a user-configurable switch for "render this page and delete it
before rendering the next" would be okay. More advanced options like
keeping just the last N recently viewed pages of M documents (plus the
succesive page of the current one) would be nice too, but if
doc-view-mode supported the simple one-page option, it would be fine for
me.

P.D.:

After some experimentation with doc-view it seems to me that the file
image cache system is flawed: open a large pdf file -> doc-view starts
conversion -> enlarge -> doc-view cancels previous conversion, throws
away the files, and starts a new one -> shring -> cancel, throw and
restart again, etc -> close the pdf view -> open the same pdf view -> if
the cache I guess you thought that creating separate caches
for every new zoom level would be too much caching :-)

It seems there is a bug: open a large pdf -> before the conversion ends,
kill the buffer -> open the pdf again -> the conversion is not resumed,
only those pages converted on the previous session are accesible.

-- 
Óscar

Re: doc-view-mode

[Tassilo Horn]

Óscar Fuentes <ofv@wanadoo.es> writes:

> As said above, instantaneous response is not required for me. 

For most users, it is.  I open a doc and then I usually use PageDown to
go to the page I want (if it's not too far back).  If each PageDown
would start a new conversion, that would be damn slow.

Also, searching with C-s (followed by more C-s like in isearch) would be
hard.

> The problem with converting all the document to image files is that I
> often open large pdf's (several thousand pages) and small/medium
> dynamically generated pdf's. This would create tens of thousands of
> image files on a busy day (no exaggerating) which would require
> several gigabytes.

Well, here's a workaround for your situation.  Let's say foo.pdf
contains 5000 pages, and you only want to see page 2500.

  1. Open it; doc-view starts conversion from page 1
  2. Hit M-g M-g 2500 RET; conversion stops and restarts at page 2500
     which will be displayed to you
  3. Hit K to kill the further conversion
  4. Now, only page 2500 (and the few following pages that where
     converted) will be accessible

> IMHO, a user-configurable switch for "render this page and delete it
> before rendering the next" would be okay. More advanced options like
> keeping just the last N recently viewed pages of M documents (plus the
> succesive page of the current one) would be nice too, but if
> doc-view-mode supported the simple one-page option, it would be fine
> for me.

I think that would add quite much complexity for not too much gain.
Basically, the overall conversion approach would need to be changed and
searching and other stuff would need to be adapted...

> P.D.:
>
> After some experimentation with doc-view it seems to me that the file
> image cache system is flawed: open a large pdf file -> doc-view starts
> conversion -> enlarge -> doc-view cancels previous conversion, throws
> away the files, and starts a new one -> shring -> cancel, throw and
> restart again, etc -> close the pdf view -> open the same pdf view ->
> if the cache I guess you thought that creating separate caches for
> every new zoom level would be too much caching :-)

Yep.

> It seems there is a bug: open a large pdf -> before the conversion
> ends, kill the buffer -> open the pdf again -> the conversion is not
> resumed, only those pages converted on the previous session are
> accesible.

Yes, I know.  That's because ghostscript has no option to check the
number of pages in a pdf/ps file...  So the best you can do is to clear
the page in that case...

Bye,
Tassilo

Re: Re: [ANN] org-docview.el - Link to PDF files from org-mode

[Carsten Dominik]

On Aug 12, 2009, at 8:45 PM, Leo wrote:

> On 2009-08-12 19:25 +0100, Jan Böcker wrote:
>> the new doc-view-mode in emacs 23 can be used to view DVI, PDF and
>> PostScript files. I have written a custom link type for org-mode to
>> allow linking to those files from org-mode.
>
> If doc-view-mode could provide native support for those file types,  
> it'd
> be much more realistic to replace standard viewers provided by the os.
> Unfortunately the last time I checked which is quite a while ago, it
> converted those files into images and use Emacs to view them.
>
> A proper pdf viewer is crucial to academic workers and in each of the
> major operating systems, there are free capable viewers available.  
> So if
> this feature is to be in org core, please don't make it the default.

I don't really see how this would be a problem.  Jan does
not propose to make "file:" links use docview to display
a pdf file.  But when a user is looking at a file in docview,
it does make sense to make store link point to the docview
of the file, I would think.  No conflict in sight.

- Carsten

>
> Thanks.
>
> Leo
>
> -- 
> Emacs uptime: 2 days, 4 hours, 16 minutes, 37 seconds
>
>
>
> _______________________________________________
> Emacs-orgmode mailing list
> Remember: use `Reply All' to send replies to the list.
> Emacs-orgmode@gnu.org
> http://lists.gnu.org/mailman/listinfo/emacs-orgmode

Re: [ANN] org-docview.el - Link to PDF files from org-mode

[Leo]

On 2009-08-12 22:33 +0100, Carsten Dominik wrote:
>> So if this feature is to be in org core, please don't make it the
>> default.
>
> I don't really see how this would be a problem. Jan does not propose
> to make "file:" links use docview to display a pdf file. But when a
> user is looking at a file in docview, it does make sense to make store
> link point to the docview of the file, I would think. No conflict in
> sight.
>
> - Carsten

In this case, no conflict ;)

-- 
Emacs uptime: 2 days, 9 hours, 29 minutes, 41 seconds