Re: Djvu mode

["Roland Winkler" <winkler@gnu.org>]

On Mon Oct 3 2011 Camm Maguire wrote:
> I have some questions, but I wonder if you would mind posting a short
> series of keystrokes and their effects as I did to help me get a quick
> grasp of the features.  I've looked at the bindings, but commands
> which I think should be adding annotations seem to be producing no
> effect on the 'A' *djvu* output page for example.

Oops, now I see what you mean.

The buffer *djvu* is only intended for those special cases that can
not (yet) be handled by the existing commands and tools.

A normal work flow is as follows:

To visit a djvu file use fjvu-find-file. This is the only entry
point to this package. You may want to bind this command to a key
you like. I use

  (global-set-key "\C-cd" 'djvu-find-file)

If you use this command to visit file foo.djvu, it puts you into the
(not editable) buffer foo@djvu. Normally, this buffer is all you
need.

The menu bar of this buffer lists most of the commands with their
repsective key bindings. For example, you can:

- Use `g' to go to the page you want. (Yes, this package operates on
  one page at a time. I guess that anything else would be too slow
  for large documents.)

- Use `v' to (re)start djview using the position in foo.djvu
  matching where point is in foo@djvu. (I find djview fast enough
  for this, even for larger documents.)

- To highlight a region in foo.djvu mark the corresponding region in
  foo@djvu (as usual, transient-mark-mode comes handy for this).
  Then type `h' and add a comment in the minibuffer if you like.
  Type C-x C-s to save this editing. Then type `v' to (re)start
  djview to show what you have done.

- The editing of the text, annotation and outline (bookmark) layers
  really happens in the buffers foo@djvu-t.el, foo@djvu-a.el, and
  foo@djvu-o.el. (The djvused syntax used in these buffers is so
  close to elisp that it was natural to give these buffers a
  djvu-edit-mode that is derived from emacs-lisp-mode.)

  You can check what is happening by switching to these buffers. The
  respective switching commands put point in these buffers such that
  it matches where you were in foo@djvu.

  The menu bar lists a few low-level commands available for editing
  these buffers directly. If you know the djvused syntax, sometimes
  it can also be helpful to do such editing "by hand".

- But wait: The syntax in the annotations buffer foo@djvu-a.el is a
  slightly modified djvused syntax. djvused can only highlight
  rectangles. So the highlighting of larger regions of text must use
  multiple rectangles (i.e., multiple djvused "mapareas"). To make
  editing easier, these are combined in the buffer foo@djvu-a.el.
  (Before saving these things, they are converted using the proper
  djvused syntax.)

  When you visit a djvu file, djvu-mode recognizes mapareas
  belonging together by checking that "everything else in these
  mapareas except for the rects" is the same. So if you entered a
  (unique) comment, this allows djvu-mode to combine all the
  mapareas when you visit such a file the second time. Without a
  comment, this fails!

I guess I can put this description into djvu.el.

Roland