Re: on viewport; doc review request & questions

[Jeremy Hankins <nowan nowan org>]

Teika Kazura <teika lavabit com> writes:
> On Sat, 21 Nov 2009 12:05:29 -0600, Jeremy Hankins wrote:
>> Teika Kazura <teika lavabit com> writes:
>> 
>>> Hi, I've done some work on viewport, especially in doc. 
>
>> [... ]and window-relative-position,
>> since that's exactly what window-relative-position is supposed to do.
>
> Sorry, I was wrong on window-relative-position. (The opposite of
> your case. ;) Oh, I made wrong changes on doc, too. I'll fix it.

Ok.  I've also gone through sawfish.texi on viewports and made some
edits; mostly typos and such (then/than, that sort of thing), but some
more substantive.  I'll attach a diff.

But we should obviously get rid of either window-relative-position or
window-absolute-position.  But what should the name be?  To my mind
window-absolute-position seems like a very strange and non-intuitive
name for something that gives the position of a window relative to the
vp it occupies, but what do others think?

>>> I've renamed viewport-offset to viewport-offset-pixel.
>> 
>> Why?  It was named viewport-offset to match the viewport-x-offset and
>> viewport-y-offset variables.  If you think it should be renamed, how
>> about viewport-offset-coords, and viewport-[xy]-offset-coords?  "Pixel"
>> in my mind suggests bits of light on the display, which isn't really
>> right here. 
>
> What's needed is the disambiguation between (2048 . 768) and (2 . 1).
> "Coordinates" and "xy" can mean both. Those who read viewport.jl
> are first forced to decipher this distinction, so my change is in
> the right direction. I'll put a comment on viewport-x-offset that 
> it's pixel.
>
> Yes, I feel a bit peculiar about "pixel". Yet coordinates in raw X are
> by pixel.

I disagree.  Most of the code in viewport.jl deals with coordinates as
screen coordinates, not col/row coordinates.  The col/row bit is really
a pretty thin layer on top of the viewport module, so the presumption
should be that coordinates are "pixel" coordinates.  Any time a row and
column are expected they should be described as a row and column, not as
coordinates.

Perhaps a comment in the file and/or a paragraph in sawfish.texi should
make this more clear.  But adding -pixel onto everything in viewport.jl
that isn't a col/row would be excessive, and adding only to some things
would be confusing.  viewport-offset-pixel is an uncomfortable mouthful
to type or say and (imo) confusing.

diff --git a/man/sawfish.texi b/man/sawfish.texi
index cfe831d..1889f0d 100644
--- a/man/sawfish.texi
+++ b/man/sawfish.texi
@@ -4003,32 +4003,36 @@ Disable all frame parts that are a member of @var{class} in
 @cindex Viewports
 @cindex Large Desktop
 
-Sawfish can have the virtual desktop size larger then the computer
-screen size. This notion is called ``viewport'' in Sawfish.
+Sawfish can have a virtual desktop which is larger than the computer's
+screen size. This is done through the use of viewports.
 
-Viewport can be thought that it displays a portion of virtual desktop,
-and the entire virtual desktop consists of the grid of ``cells'' whose
-size is of the physical screen. Viewport sits on a cell.
+A viewport can be thought of as a screen-sized hole through which you
+can view a portion of the virtual desktop.  The entire virtual desktop
+consists of the grid of ``cells'' whose size is that of the physical
+screen. Viewport sits on a cell.
 
-Technically speaking, the word ``viewport'' should mean the currently
-displayed part of the entire desktop. But in Sawfish, the entire
-desktop is wrongly called ``viewport'', too. When focused to
-enlargement, ``large desktop'' is the correct nomenclature, but
-simply calling it ``workspace'' = ``virtual desktop'' are correct, too,
-for most cases.
+Sometimes the word ``viewport'' is used to mean the entire
+larger-than-normal desktop.  This is natural, but not techically
+correct.  When focused to enlargement, ``large desktop'' is the correct
+nomenclature, but simply calling it the ``workspace'' or the ``virtual
+desktop'' are correct too.
 
 @defvar viewport-dimensions
-The number of viewports of the virtual desktop. This is a cons cell
- code{(columns . rows)}.  Defaults to @code{(1 . 1)}.
+The dimensiosn of the virtual destkop.  This is a cons cell
+ code{(columns . rows)}.  Defaults to @code{(1 . 1)}.  The number of
+viewports in the virtual desktop is @code{columns} times @code{rows}.
 
-If @code{viewport-boundary-mode} is @code{dynamic} (@pxref{Dynamic 
-Viewport}), then this variable is the current size of the current
-workspace, and does not have the meaning as a user option.
+If @code{viewport-boundary-mode} is @code{dynamic} (see @pxref{Dynamic
+Viewport}) then this variable is the current size of the current
+workspace and should not be set by the user.
 @end defvar
 
 @defun set-number-of-viewports width height
 Change @code{viewport-dimensions} to have the value
- code{(@var{width} . @var{height})}.
+ code{(@var{width} . @var{height})}.  If @code{viewport-boundary-mode}
+is @code{dynamic} then this sets the minimum dimensions of the virtual
+workspace (see @pxref{Dynamic Viewport}) rather than setting the
+dimensions directly.
 @end defun
 
 @menu
@@ -4073,7 +4077,7 @@ When set to @code{wrap-around}, it behaves as if the leftmost viewport
 and the rightmost are connected. Same for the top and bottom.
 
 If it is set to @code{dynamic}, then the workspace size changes
-automatically. For detail, see @xref{Dynamic Viewport}.
+automatically. For details, see @xref{Dynamic Viewport}.
 @end defvar
 
 @defun viewport-honor-workspace-edges
@@ -4095,28 +4099,23 @@ which is specified as @code{(column . row)}. The return value is the
 cons cell @code{(x . y)}. The values are in pixel, and are negative if
 it lies at left or above the current viewport.
 
- var{viewport} can be non existent one. If @var{viewport} is @code{nil} it
-is understood as the current viewport, i.e., @code{(0 . 0)} will be
+ var{viewport} does not have to exist; the value that would be correct
+if the viewport did exist is returned.  If @var{viewport} is @code{nil}
+it is understood as the current viewport, i.e., @code{(0 . 0)} will be
 returned.
 @end defun
 
-Actually, Sawfish can move viewport by any pixels, not only by
-screen size. Here're low level functions to do it.
-
- defun warp-viewport x y
-Change the position of the viewport, such that location
- code{(@var{x}, @var{y})} is at the top-left of the display. The unit
-is by pixels.
- end defun
+Normally it is most convenient to shift viewports by multiples of the
+screen dimensions so that the viewports form a grid on the virtual
+desktop.  @code{set-screen-viewport} and @code{move-viewport} by hiding
+the details of calculating the proper position for the viewport.  But it
+is possible to access the lower-level functions and gain greater control
+over the position of the viewport.
 
 @defun set-viewport x y
 Change the position of the viewport, such that location
- code{(@var{x}, @var{y})} is at the top-left of the display. The unit
-is by pixels.
-
-Unlike @code{warp-viewport}, the change takes place by dividing the
-motion into @code{scroll-viewport-steps} steps, and redisplaying after
-each step in the motion.
+ code{(@var{x}, @var{y})} is at the top-left of the display.  So
+ code{(set-viewport 0 -5)} will shift the viewport up five pixels.
 @end defun
 
 @defvr Customizable scroll-viewport-steps
@@ -4129,18 +4128,19 @@ is done. The upper limit for customization is 50.
 
 This variable is used for @code{set-viewport}. All interactive commands
 defined by Sawfish call this function, so this variable is important
-for user.
+for the user.
 @end defvr
 
 @node Dynamic Viewport, Windows and Viewports, Viewport Functions, Viewports
 @section Dynamic Viewport
 
-If the variable @code{viewport-boundary-mode} (@pxref{Viewport
-Functions}) is set to @code{dynamic}, the viewport is ``dynamic''. If
-dynamic viewport is enabled, then each workspace has its size
-indepedent of other workspaces, and it is automatically resized so
-that it contains all windows plus the current viewport. The size is set at
-Sawfish startup, and each time you move viewport.
+Normally the viewport cannot move beyond the limits set by
+ code{viewport-dimensions}   But if you set
+ code{viewport-boundary-mode} to the symbol @code{dynamic} then this
+limitation is removed.  The viewport is allowed to range as far as you
+wish.  Sawfish will still keep track of the dimensions of the virtual
+workspace but it will do so by noticing where windows are placed and
+what part of the virtual workspace is displayed in the viewport.
 
 Even in dynamic viewport, the top-left cell is always @code{(0, 0)},
 and the cell indices are never negative.
@@ -4149,15 +4149,24 @@ The dynamic viewport is still an experimental feature, and its
 specification may change.
 
 @defvar viewport-minimum-dimensions
-This is only useful if dynamic viewport is enabled. It means that
- code{viewport-dimensions} gets never less than this variable. 
+This is only useful if dynamic viewport is enabled.
+ code{viewport-dimensions} will never be set to less than
+ code{viewport-minimum-dimensions}, unless it is a change requested by
+the user, either by using the configuration interface or by calling
+ code{set-number-of-viewports} 
 
 If setting @code{viewport-minimum-dimensions} by hand (not by the
 customization interface) be sure to call
- code{viewport-minimum-size-changed} after doing so.
-
-If the viewport is not dynamic, it is automatically set to the same
-value as @code{viewport-dimensions}.
+ code{viewport-minimum-size-changed} after doing so to ensure that the
+new minimum dimensions immediately go into effect.
+
+If @code{set-number-of-viewports} is called to set the viewport
+dimensions @code{viewport-minimum-dimensions} will be set to the same
+value.  Also, if (using the configuration interface) you set the
+viewport dimensions to less than @code{viewport-minimum-dimensions} then
+ code{viewport-minimum-dimensions} will be adjusted to match.  This way
+those who are not using dynamic viewports do not need to worry about
+ code{viewport-minimum-dimensions} 
 @end defvar
 
 Under dynamic viewport, @code{viewport-dimensions} is the current size
@@ -4173,7 +4182,7 @@ holding the top-left corner of @var{window}.
 
 @defun window-relative-position w
 Returns in a cons cell the coodinates of the window relative to the
-current viewport.
+viewport it occupies.
 @end defun
 
 @defun window-outside-viewport-p window &optional viewport

-- 
Jeremy Hankins <nowan nowan org>