Updated doc directory.

4 files changed, 5 insertions, 330 deletions

diff --git a/doc/Images.txt b/doc/Images.txt
index 6a36e6f5..62082e48 100644
--- a/doc/Images.txt
+++ b/doc/Images.txt
@@ -1,5 +1,8 @@
  January 2009, --Jcid
 
+Update June 2015: See also doc/dw-images-and-backgrounds.doc, or
+../html/dw-images-and-backgrounds.html (generated by doxygen).
+
                               ------
                               IMAGES
                               ------
diff --git a/doc/Imgbuf.txt b/doc/Imgbuf.txt
deleted file mode 100644
index f4a56660..00000000
--- a/doc/Imgbuf.txt
+++ /dev/null
@@ -1,177 +0,0 @@
-Aug 2004, S.Geerken@ping.de
-
-=============
-Image Buffers
-=============
-
-General
-=======
-
-Image buffers depend on the platform (see DwRender.txt), but have a
-general, platform independant interface, which is described in this
-section. The next section describes the Gdk version of Imgbuf.
-
-The structure ImgBuf will become part of the image processing, between
-image data decoding and the widget DwImage. Its purposes are
-
-   1. storing the image data,
-   2. handling scaled versions of this buffer, and
-   3. drawing.
-
-The latter must be done independently from the window.
-
-Storing Image Data
-------------------
-Imgbuf supports five image types, which are listed in the table
-below. The representation defines, how the colors are stored within
-the data, which is passed to a_Imgbuf_copy_row().
-
-                  | bytes per |
-        type      |   pixel   |      representation
-   ---------------+-----------+-------------------------
-    RGB           |     3     | red, green, blue
-    RGBA          |     4     | red, green, blue, alpha
-    gray          |     1     | gray value
-    indexed       |     1     | index to colormap
-    indexed alpha |     1     | index to colormap
-
-The last two types need a colormap, which is set by
-a_Imgbuf_set_cmap(), which must be called before
-a_Imgbuf_copy_row(). This function expects the colors as 32 bit
-unsigned integers, which have the format 0xrrbbgg (for indexed
-images), or 0xaarrggbb (for indexed alpha), respectively.
-
-Scaling
--------
-The buffer with the original size, which was created by
-a_Imgbuf_new(), is called root buffer. Imgbuf provides the ability to
-scale buffers. Generally, both root buffers, as well as scaled
-buffers, may be shared, memory management is done by reference
-counters.
-
-Via a_Imgbuf_get_scaled_buf(), you can retrieve a scaled buffer. The
-way, how this function works in detail, is described in the code, but
-generally, something like this works always, in an efficient way:
-
-   old_buf = cur_buf;
-   cur_buf = a_Imgbuf_get_scaled_buf(old_buf, with, height);
-   a_Imgbuf_unref (old_buf);
-
-Old_buf may both be a root buffer, or a scaled buffer.
-
-(As an exception, there should always be a reference on the root
-buffer, since scaled buffers cannot exist without the root buffer, but
-on the other side, do not hold references on it. So, if in the example
-above, old_buf would be a root buffer, and there would, at the
-beginning, only be one reference on it, new_buf would also be
-destroyed, along with old_buf. Therefore, an external reference must
-be added to the root buffer, which is in dillo done within the dicache
-module.)
-
-The root buffer keeps a list of all children, and all operations
-operating on the image data (a_Imgbuf_copy_row() and
-a_Imgbuf_set_cmap()) are delegated to the scaled buffers, when
-processed, and inherited, when a new scaled buffer is created. This
-means, that they must only be performed for the root buffer.
-
-Drawing
--------
-There are two situations, when drawing is necessary:
-
-   1. To react on expose events, the function a_Imgbuf_draw() can be
-      used. Notice that the exact signature of this function is
-      platform dependant.
-
-   2. When a row has been copied, it has to be drawn. To determine the
-      area, which has to be drawn, the function
-      a_Imgbuf_get_row_area() should be used. In dillo, the dicache
-      module will first call a_Img_copy_row(), and then call
-      a_Dw_image_draw_row() for the images connected to this image
-      buffer. a_Dw_image_draw_row() will then call
-      p_Dw_widget_queue_draw(), with an area determined by
-      a_Imgbuf_get_row_area().
-
-
-The Gdk Implementation
-======================
-
-The Gdk implementation is used by the Gtk+ platform. [... todo]
-
-
-Global Scalers
-==============
-
-In some cases, there is a context, where images have to be scaled
-often, by a relatively constant factor. For example, the preview
-window (GtkDwPreview) draws images via the Imgbuf draw functions, but
-uses scaled buffers. Scaling such a buffer each time it is needed,
-causes huge performance losses. On the other hand, if the preview
-window would keep these scaled buffers (e.g. by lazy mapping of the
-original buffer to the scaled buffer), the scaled buffers get never
-freed, since the view is not told about, when the original buffer is
-not needed anymore. (n.b., that currently, the scaled buffers are
-destroyed, when the original buffer is destroyed, but this may change,
-and even this would leave "zombies" in this mapping structure, where
-the values refer to dead pointers).
-
-It is sufficient, that references on the scaled buffers are referred
-somehow, so that they do not get destroyed between different
-usages. The caller (in this case the preview) simply requests a scaled
-buffer, but the Imgbuf returns this from the list of already scaled
-buffers.
-
-These references are hold by special structures, which are called
-"scalers". There are two types of scalers, local scalers, which are
-bound to image buffers, and global scalers, which refer to multiple
-scalers.
-
-What happens in different situations:
-
-   - The caller (e.g. the preview) requests a scaled buffer. For this,
-     it uses a special method, which also passes the global image
-     scaler, which was created before (for the preview, there is a 1-1
-     association). The Imgbuf uses this global image scaler, to
-     identify the caller, and keeps a list of them. If this global
-     scaler is not yet in the list, it is added, and a local scaler is
-     created.
-
-
-
-  -
-
-There are three images in the page, i1a, i1b, and i2. I1a and i1b
-refer to the same image recource, represented by the root image buffer
-iba, which original size is 200 x 200. I1a is displayed in original
-size, while i1b is displayed at 100 x 100. I2 refers to an other
-recource, ibb, which has the size 300 x 300. I2 is shown in original
-size.
-
-
-                :DwRenderLayout ------------------- :DwPage ----------.
-                     /    \                                           |
-               ,----'      `----.               ,------ i1a:DwImage --+
-              /                  \              |                     |
-     view1:GtkDwViewport  view2:GtkDwPreview    | ,---- i1b:DwImage --|
-                                  |             | |                   |
-   ,------------------------------'             | | ,-- i2: DwImage --'
-   |                                            | | |
-   |      ,-------------------------------------' | |
-   |      |      ,--------------------------------' |
-   |      |      |                             ,----'
-   |      |      |                             |
-   |      V      |                             V
-   | iba:Imgbuf  |                        ibb:Imgbuf -- 30x30
-   |   |  |      V                             |          ^
-   |   |  +- 100x100 ,- 20x20 ,- 10x10         |          |
-   |   |  |          |    ^   |   ^            |          |
-   |   |  `----------+----|---'   |            `--.    ,--'
-   |   |   ,--------------'       |               |    |
-   |   |   |   ,------------------'               |    |
-   |   |   |   |                                  |    |
-   | lca:ImgbufLSc                            lcb:ImgbufLSc
-   | (factor 1/10)                            (factor 1/10)
-   |        \                                      /
-   |         `-----------.    ,-------------------'
-   |                      \  /
-   `------------------> scl:ImgbufGSc
-                        (factor 1/10)
diff --git a/doc/Makefile.am b/doc/Makefile.am
index 8ade3d15..71c7c32d 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -11,8 +11,8 @@ EXTRA_DIST = \
 	dw-widget-sizes.doc \
 	dw-changes.doc \
 	dw-images-and-backgrounds.doc \
-	dw-dw-out-of-flow.doc \
-	dw-dw-out-of-flow-2.doc \
+	dw-out-of-flow.doc \
+	dw-out-of-flow-2.doc \
 	fltk-problems.doc \
 	rounding-errors.doc \
 	uml-legend.doc \
@@ -38,9 +38,7 @@ EXTRA_DIST = \
 	HtmlParser.txt \
 	IO.txt \
 	Images.txt \
-	Imgbuf.txt \
 	NC_design.txt \
-	Selection.txt \
 	Dpid.txt \
 	CCCwork.txt \
 	README \
diff --git a/doc/Selection.txt b/doc/Selection.txt
deleted file mode 100644
index 7904bd94..00000000
--- a/doc/Selection.txt
+++ /dev/null
@@ -1,149 +0,0 @@
-Apr 2003, S.Geerken@ping.de
-Last update: Dec 2004
-
-=========
-Selection
-=========
-
-The selection module (selection.[ch]) handles selections, as well as
-activation of links, which is closely related.
-
-
-General Overview
-================
-
-The selection module defines a structure "Selection", which is
-associated to GtkDwViewport, and so to a widget tree. The selection
-state is controlled by "abstract events", which are sent by single
-widgets by calling one of the following functions:
-
-   a_Selection_button_press    for button press events,
-   a_Selection_button_release  for button release events, and
-   a_Selection_button_motion   for motion events (with pressed mouse
-                               button).
-
-The widget must construct simple iterators (DwIterator), which will be
-transferred to extended iterators (DwExtIterator), see below for more
-details. All event handling functions have the same signature, the
-arguments in detail are:
-
-    - DwIterator *it           the iterator pointing on the item under
-                               the mouse pointer,
-    - gint char_pos            the exact (character) position within
-                               the iterator,
-    - gint link                if this item is associated with a link,
-                               its number (see DwImage, section
-                               "signals" for the meaning), otherwise
-                                -1,
-    - GdkEventButton *event    the event itself; only the button is
-                               used,
-    - gboolean within_content  TRUE, if there is some selectable
-                               content unter the mouse cursor; if set
-                               to FALSE, the "full screen" feature is
-                               used on double click.
-
-In some cases, char_pos would be difficult to determine. E.g., when
-the DwPage widget decides that the user is pointing on a position
-_at_the_end_ of an image (DwImage), it constructs a simple iterator
-pointing on this image widget. In a simple iterator, that fact that
-the pointer is at the end, would be represented by char_pos == 1. But
-when transferring this simple iterator into an extended iterator, this
-simple iterator is discarded and instead the stack has an iterator
-pointing to text at the top. As a result, only the first letter of the
-ALT text would be copied.
-
-To avoid this problem, widgets should in this case pass SELECTION_EOW
-(end of word) as char_pos, which is then automatically reduced to the
-actual length of the extended(!) iterator.
-
-The return value is the same as in DwWidget event handling methods.
-I.e., in most cases, they should simply return it. The events
-"link_pressed", "link_released" and "link_clicked" (but not
-"link_entered") are emitted by these functions, so that widgets which
-let the selection module handle links, should only emit "link_entered"
-for themselves. (See DwImage.txt for a description of this.)
-
-
-Selection State
-===============
-
-Selection interferes with handling the activation of links, so the
-latter is also handled by the selection module. Details are based on
-following guidelines:
-
-   1. It should be simple to select links and to start selection in
-      links. The rule to distinguish between link activation and
-      selection is that the selection starts as soon as the user leaves
-      the link. (This is, IMO, a useful feature. Even after drag and
-      drop has been implemented in dillo, this should be somehow
-      preserved.)
-
-   2. The selection should stay as long as possible, i.e., the old
-      selection is only cleared when a new selection is started.
-
-The latter leads to a model with two states: the selection state and
-the link handling state.
-
-The general selection works, for events not pointing on links, like
-this (numbers in parantheses after the event denote the button, "n"
-means arbitrary button):
-
-                                  motion(1)
-                                  ,-----.
-                                  |     |
-          press(1) on non-link    V     |
-   NONE -----------------------> SELECTING <----------------.
-    ^                                |                      |
-    |                                | release(1)           |
-    |                                |                      | press(1)
-    |                    no          V           yes        |
-    `----------------------- Anything selected? --------> SELECTED
-
-The selected region is represented by two DwExtIterators.
-
-Links are handled by a different state machine:
-
-    ,-----------------------------.
-    |                             |
-    |                   Switch to selection
-    |                 (SELECTING) for n == 1.
-    |                             ^
-    |                             | no
-    |                             |            yes
-    |                    Still the same link? --.
-    |                             ^             |
-    |                             |             |
-    |                             | motion(n)   |
-    V     press(n) on links       |             |
-   NONE ---------------------> PRESSED(n) <-----'
-    ^                             |
-    |                             | release(n)
-    |                             |
-    |                             V            yes
-    |                    Still the same link? -----------------.
-    |                             |                            |
-    |                             | no                         V
-    |                             V                Send "clicked" signal.
-    |                  Switch to selection                     |
-    |                 (SELECTED) for n == 1.                   |
-    |                             |                            |
-    |`----------------------------'                            |
-    |                                                          |
-    `----------------------------------------------------------'
-
-Switching to selection simply means that the selection state will
-eventually be SELECTED/SELECTING, with the original and the actual
-position making up the selection region. This happens for button 1,
-events with buttons other than 1 do not affect selection at all.
-
-
-TODO
-====
-
-* a_Selection_button_motion currently always assumes that button 1 has
-  been pressed (since otherwise it would not do anything). This should
-  be made a bit cleaner.
-
-* The selection should be cleared, when the user selects something
-  somewhere else (perhaps switched into "non-active" mode, as some
-  Gtk+ widgets do).