From 42259dd3b1bed0fd4cee508dbf5b90ee6fa95f2a Mon Sep 17 00:00:00 2001
From: Joris van der Hoeven <vdhoeven@lix.polytechnique.fr>
Date: Mon, 23 Apr 2012 13:31:19 +0000
Subject: [PATCH] Complete documentation of basic buffer API

---
 about/changes/change-log.en.tm         |  5 ++++
 devel/scheme/buffer/buffer-api.en.tm   |  3 +++
 devel/scheme/buffer/buffer-intro.en.tm | 34 +++++++++++++++++++++++++-
 3 files changed, 41 insertions(+), 1 deletion(-)

diff --git a/about/changes/change-log.en.tm b/about/changes/change-log.en.tm
index ff1b98e..4d6ff8f 100644
--- a/about/changes/change-log.en.tm
+++ b/about/changes/change-log.en.tm
@@ -8,8 +8,13 @@
   <section|Changes from version 1.0.7 to 1.0.7.16>
 
   <\itemize>
+    <item>Reorganized buffer management and documentation of the new API
+    (1.0.7.16).
+
     <item>Rudimentary support for version control using SVN (1.0.7.16).
 
+    <item>Rudimentary support for graphical macros without text (1.0.7.16).
+
     <item>First rudimentary spreadsheet facility (1.0.7.15).
 
     <item>Special editing mode for writing <TeXmacs> documentation
diff --git a/devel/scheme/buffer/buffer-api.en.tm b/devel/scheme/buffer/buffer-api.en.tm
index 42c0639..4a2b38c 100644
--- a/devel/scheme/buffer/buffer-api.en.tm
+++ b/devel/scheme/buffer/buffer-api.en.tm
@@ -79,6 +79,9 @@
   <|explain>
     Set the contents of the buffer <scm-arg|buf> to the rich tree
     <scm-arg|rich-t>, <abbr|resp.> get the rich contents of <scm-arg|buf>.
+    Rich trees do not only contain the actual body of the document, but also
+    some meta-data, such as its style, initial values of environment
+    variables, and other auxiliary data attached to the document.
   </explain>
 
   <\explain>
diff --git a/devel/scheme/buffer/buffer-intro.en.tm b/devel/scheme/buffer/buffer-intro.en.tm
index da1ba32..821a572 100644
--- a/devel/scheme/buffer/buffer-intro.en.tm
+++ b/devel/scheme/buffer/buffer-intro.en.tm
@@ -5,7 +5,39 @@
 <\body>
   <tmdoc-title|Introduction>
 
-  \;
+  There are three main kinds of objects for buffer management in <TeXmacs>:
+
+  <\description>
+    <item*|Buffers>Every open <TeXmacs> document is stored in a unique
+    editable buffer. Buffers typically admit a<nbsp>one to one correspondence
+    to files on disk or elsewhere on the web. Some buffers are of a<nbsp>more
+    auxiliary nature, such as automatically generated help buffers. All
+    buffers admit a unique URL. In the case of auxiliary buffers, this URL is
+    really a read-only ``placeholder'', so saving this kind of buffers is
+    impossible (of course, it remains possible to save the buffer under a new
+    name).
+
+    <item*|Views>It is possible to have multiple views on the same buffer.
+    Every view is identified by a<nbsp>unique automatically generated URL,
+    which again acts as a placeholder.
+
+    <item*|Windows>Views (contrary to the buffers themselves) can be
+    displayed in actual windows. Currently, any <TeXmacs> window contains a
+    unique view and a view may only be displayed in one window at the same
+    time (of course, it is possible to display different views on the same
+    buffer in different windows). Windows are again represented by
+    automatically generated<nbsp>URLS.
+  </description>
+
+  <\remark>
+    In the future, views and windows should really be considered as documents
+    themselves. Changes in the view will be automatically propagated (or not)
+    to the corresponding buffer, and the other views. Windows will contain a
+    document which specifies its layout (menus and toolbars). The
+    corresponding view (or views) will be an active hyperlink (or active
+    hyperlinks). The current APIs already reflect these future development
+    intentions.
+  </remark>
 
   <tmdoc-copyright|2012|Joris van der Hoeven>