Commit e407ca87 authored by Per Cederqvist's avatar Per Cederqvist
Browse files

(The User Area): The documented format was not the one used by the

	elisp-client and kom++.  Updated the documentation to the
	current practice.
(Future changes): Added a link to Bugzilla for one of the ideas.
parent 364262a7
......@@ -8727,15 +8727,52 @@ information in the server. Most clients use this to store settings a
user has made that are specific to a particular server. There are also
provisions to store settings that are shared between clients.
The user-area is divided into several sub-blocks. The common block is
shared by all clients, and its formats and contents dictated by this
protocol specification. Clients may also create one or more blocks.
The user-area is divided into several sub-blocks. The @code{common} block is
shared by all clients, and its formats and contents are dictated by this
protocol specification. Clients may also create one or more other blocks.
In normal texts, everything up to the first line feed is considered to
be the subject line. The user area is an exception: it does not
contain any subject line.
Each block is encoded as a @type{HOLLERITH} string. A table of
contents is also encoded as a @type{HOLLERITH} string and added first
in the user area. There must be at last one space between each
string, and there might be spaces at the beginning and/or end of the
user-area. Thus, a user-area made up of three blocks will contain
four @type{HOLLERITH}-encoded strings, each separated by at least one
space, and maybe with extra spaces at the beginning or end of the
text.
The table of contents consists of one @type{HOLLERITH}-encoded string
for each block in the user-area. Each string contains the name of the
corresponding block. There is at least one space between each string,
and there may be spaces before the first string and after the last
string. Clients must never create two or more blocks with the same
name.
This format ensures that clients can copy or read past other clients'
blocks without knowing their structure.
@need 2000
@i{Example:}
@example
13H7Hblock-a 1Hb 4Hasdf 5H hjkl
@end example
In the above example, there are two blocks: @code{block-a} and
@code{b}. @code{block-a} contains four bytes, @code{asdf}, while
@code{b} contains five bytes: @w{@code{ hjkl}} (note the leading
space). Below are a few other ways to encode the same user-area:
@example
14H 7Hblock-a 1Hb 4Hasdf 5H hjkl
16H 7Hblock-a 1Hb 4Hasdf 5H hjkl
13H1Hb 7Hblock-a 5H hjkl 4Hasdf
@end example
The entire user-area is coded as a @type{HOLLERITH}. This string in turn
contains a list of pairs of @type{HOLLERITH} strings. Each pair consists
of one string containing the block name and one containing the data. This
format ensures that clients can copy or read past other clients' blocks
without knowing their structure.
The first two example embedd extra (redundant) spaces, and the last
swaps the order of the two blocks.
The following block names have been defined:
@table @code
......@@ -8743,7 +8780,7 @@ The following block names have been defined:
The common block shared by all clients. The format of the common block is
described below.
@item elisp
The block created by the Emacs list client. The format is completely
The block created by the Emacs lisp client. The format is completely
undocumented, but you'll need a lisp reader to parse it.
@item WWW-kom
The block created by the web gateway WWW-kom. It has the same syntax as
......@@ -9182,7 +9219,8 @@ single text as read (but one could argue that it should take a single
no easy way to undo such an operation. You can use
@reqlink{set-last-read} followed by a number of @req{mark-as-read}
calls to get the desired effect, but it would be nice to have a
@code{mark-as-unread} call.
@code{mark-as-unread} call. (This is
@uref{http://bugzilla.lysator.liu.se/show_bug.cgi?id=53, bug 53}.)
@item
If the client issues several request without waiting for a reply, the
......
Markdown is supported
0% or .
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment