[Gzz] Incomplete PEG: fenpdf spec 1

[Tuomas Lukka]

==========================================================================
PEG fenpdf_v1_spec_1--tjl: FenPDF v1 first specification
==========================================================================

:Authors:  Tuomas J. Lukka
:Date-Created: 2003-07-28
:Last-Modified: $Date: 2003/07/30 09:11:45 $
:Revision: $Revision: 1.4 $
:Status:   Incomplete
:Stakeholders: benja, mudyc, humppake
:Scope:    Major
:Type:     Policy

.. Affect-PEGs:


We need a common vision for what FenPDF 1.0 will look like. 
Currently there are lots of good ideas, but several people
pulling in slightly different directions.

Everything in this PEG is very much under discussion - if you see
something you don't like, say it


Issues
======

- Should ``CONTENTLINK`` RDF vocabulary be included?
  We should be as conservative as possible; we shall have
  transclusions anyway.

  OTOH, clinks have their uses.

  Hmm, for v1.0 maybe we should have *either* clinks *or*
  pdf transclusions but not both?

- RDF for cursors / bookmarks? Is just two views good enough
  for browsing? Accidental severing of contacts. Need some way to get anywhere.

  PROPOSED RESOLUTION: TREETIME for now.

- "overall view" of the whole space? -- embed to 2D somehow for a map?

  RESOLVED: Later. Needs experiments first

- ``rmb_action_switch--humppake``?
  Gives more actions for the mouse, but may be confusing; the UI is definitely
  not self-explanatory then.

  RESOLVED: Later.

- Should left-button click+drag select or move?

  PROPOSED RESOLUTION: move. Shift for select. Clicking and dragging
  for moving *feels* right.

- Do we need bookmarks and overall views - would simply connecting the previous
  and next canvas and pageimagescrolls in time order?

  PROPOSED RESOLUTION: Use TREETIME and provide interface for it.

- Should the elements in the system contain their insertion time?
  As wallclock time or a tree (when merging)?

  PROPOSED RESOLUTION: Use TREETIME and provide interface for it.

- What were benja's suggestions - couldn't find a PEG

Introduction
============

This is a PEG that's different from most - it changes the whole perspective.
Instead of looking outwards and pushing the envelope, this PEG tries
for the first time to actually contain a complete working system.

This PEG will select what goes in and what does not for FenPDF 1.0.

Not having something in this feature set does certainly not mean that
it's abandoned or that it's a bad idea: it just means that we will
not include that functionality into FenPDF 1.0 even if it is implemented,
in order to keep things simple or for some other reason.

FenPDF 1.0 is kind of a "director's cut" (a term Ted sometimes used), 
and it's expected that there will be parallel versions, with different
names and identities that do almost the same thing but differently.
These are good for experiments and competition is healthy -- the same
components can be assembled differently by different people.

This spec is **extremely** conservative as to which features are taken 
in. We need a working baseline 1.0 that remains the same and functional.
We need to get *using* is asap. The policy is that we take in exactly what
*has* to be there for a working FenPDF. Including TREETIME or something like
it is because all points of the system must remain reachable.

This is the first spec PEG - once accepted, the specification here will be 
moved 
to the main docs/ directory and be amended only through future PEGs.

Note that evolution of the FenPDF PEG is not the only way to add new features
and e.g. canvas / document types. FenPDF is only the first applitude 
we will try to settle. There will be others (fencode, fenwrite, ... ?) which
will operate within the same graph.

Structure
=========

In a sense, this the most important part of this PEG: this part specifies
the structure that will be used within our research group when test-using
fenpdf. No other RDF nodes will be allowed in the common data base, until
the next version of FenPDF (1.1?), or v1.0 of some other applitude is defined.

Everyone may use their own user interfaces, but the shared structure is
set in stone here.

RDF
---

The structure behind FenPDF consists 
of the RDF structure in ``CANVAS2D``, ``FF``, ``RDF`` (type), and 
``STRUCTLINK``.

As long as FenPDF is the only applitude used,
all other RDF words are either randomly generated ``urn-5`` words or literals.

This means that the structure is: 

- Canvases containing nodes at specific locations

- directional links between nodes

- contents for the nodes

Xanalogical
-----------

As this is FenPDF, version 1.0 will support only text and page spans.
Content links will not be supported, only transclusions.
For text spans, URN5 text spans will be used - storing the keystrokes
in their own blocks is an extra complication for now.

User interface
==============

While the Structure was an important part, the user interface is the most 
*difficult* one.
There are several possible directions and we need to select one for FenPDF 1.0.

One that we will provide as a backwards-compatibility option in later versions 
of FenPDF
if it is seen to be good.

Requirements
------------

- Need to be able to easily get whole PDF zoomed, without bg, easily movable

- Easily get 2-view mode for linking 

- Attach custom controllers easily

- should be possible to figure out without manual

- easy to insert new PDFs - error handling?

    - pool control

- history path accessible

- buoys carefully tuned: no clutter, easy to understand and control

    - debug mode: show where buoy locations come from!

- easy switch between fullscreen and windowed mode - window size taken 
  into account naturally

Overall visuals
---------------

Whatever is under the cursor *shall* show it somehow, e.g. main view by 
slightly changing color 
of irregu edges, text nodes by lightening, etc. *EVERYTHING* must do this.

Foci
----

Two foci, shown on top 

Buoy placement
--------------

There are several different kinds of buoys in this system:

Canvas-Canvas
    These are directed and can occur on either side.
    The buoy should show some context but not too much
    to avoid going to too small zoom.

Canvas-PDF Transclusion
    Always to the right.
    Max. 20 pages of the whole document are shown.
    

PDF-Canvas Transclusion
    Always to the left
    Here, enough context needs to be shown since the transclusion 
    is just the same as the anchor.



Bindings
--------

Left mouse button:
    
    click
        go to

    click + drag on main view
        pan

    shift + click + drag on main view
        select

    click + drag on a selection in main view
        drag into other view for creating transclusion


Right mouse button:
    
    click + drag on main view
        adjust zoom. Up = zoom out, down = zoom in.

    click
        context menu

middle mouse button:

    click + drag anywhere
        move view separator up / down

    click on main view
        X11 paste to insertion cursor

Context Menus
-------------

On struct-connected buoys: "Unlink this buoy"

For any object, "Delete this X" where X is "Text", "Paper", "PDF file", 
"transclusion"


Visible buttons
---------------

Action buttons everywhere:

    Import PS/PDF

    New paper

    Save

    Quit

Toggles everywhere:

    Fancy papers

Toggles in pdf mode:

    Reading zoom

These buttons shall have the ubiquitous 3D look, with the toggles having
the old Tk look, with a square in them that is lit or unlit based on the state
(need to distinguish between buttons and toggles somehow).

They shall react to mouseovers and mouse clicks instantly with visual feedback.

The buttons shall be placed to the upper left corner, stacked vertically, and 
shall
be relatively small (10-15pixels high)

Some space between action buttons and toggles.

Versioning / Merging
====================