Node:The User Area, Next:, Previous:LysKOM Content Types, Up:Top


The User Area

The user area is a regular text that is used to store client-specific 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 are dictated by this protocol specification. Clients may also create one or more other blocks.

In normal texts, everything up to the first linefeed 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 HOLLERITH string. A table of contents is also encoded as a 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 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 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.

Example: 

        13H7Hblock-a 1Hb 4Hasdf 5H hjkl

In the above example, there are two blocks: block-a and b. block-a contains four bytes, asdf, while b contains five bytes:  hjkl (note the leading space). Below are a few other ways to encode the same user-area: 

        14H 7Hblock-a 1Hb 4Hasdf 5H hjkl
        16H 7Hblock-a  1Hb   4Hasdf  5H hjkl
        13H1Hb 7Hblock-a 5H hjkl 4Hasdf

The first two examples embed extra (redundant) spaces, and the last swaps the order of the two blocks.

The following block names have been defined:

common
The common block shared by all clients. The format of the common block is described below.
elisp
The block created by the Emacs lisp client. The format is completely undocumented, but you'll need a lisp reader to parse it.
WWW-kom
The block created by the web gateway WWW-kom. It has the same syntax as the common block, but the keys and values are not documented.
rkom
Used by Anders Magnusson <ragge@ludd.luth.se>.

If you're writing a client that uses the user-area, please let us know what you name your client's block.

The Common Block

This defines the structure of the common block. The common block contains a list of variable settings. Each variable setting consists of a name, some whitespace, and a value. Settings are separated by a linefeed character. The values can be of several different types (such as integers, strings, booleans, lists of stuff) but they are all encoded as HOLLERITHs. The reason for this is to simplify for clients that need to ignore the value, and so it is possible to add new value types without confusing old clients.

The grammar below defines the syntax of the common block. 

common-block    :   settings
settings        :   settings setting
                |   /* empty */
setting         :   variable ' ' value '\n'
variable        :   [A-Za-z-_0-9]+
value           :   HOLLERITH

The values contain structure within the HOLLERITH. The following grammar defines the data types that are currently used. Clients must be prepared to ignore values that have other data types. 

boolean         :   1 | 0
integer         :   -?[0-9]+
string-list     :   string-list ' ' HOLLERITH
                |   HOLLERITH

Currently the following variables are used, but more may be added, and clients must cope with variables they know nothing of in the common block. (Doing so is easy, as all values are encoded as HOLLERITHs.)

created-texts-are-read
True if the user wants texts s/he creates to be marked as read automatically. boolean.
dashed-lines
True if the user wants dashed lines around the text body when it's displayed. boolean.
presence-messages
True if the user wants messages about people logging in and logging out of LysKOM. boolean.
print-number-of-unread-on-entrance
True if the user wants to see the number of unread texts when entering a conference. boolean.
read-depth-first
True if the user wants to read text in depth-first order. boolean.
reading-puts-comments-in-pointers-last
True if the user wants the client to display comment links after the text body. boolean.
confirm-multiple-recipients
True if the user wants the client to ask for confirmation before sending a text to many conferences. boolean.
default-mark
The default mark to set on marked texts. integer.
language
Preferred languages, in priority order. string-list.

This contains a list of ISO 639 language codes. ISO 639-2 should be used for languages that have a 2-character language code. For other languages, ISO 639-1 should be used. http://lcweb.loc.gov/standards/iso639-2/langcodes.html contains a list of the current language codes.

The client should configure its user interface to use the first language in the list that it supports. Example: a client that supports English and Swedish would use: