Skip to content

GitLab

Commit a4d01471 authored by David Byers's avatar David Byers
Browse files

Initial checkin

parent 94506c0c
Hide whitespace changes
Inline Side-by-side
Showing with 356 additions and 0 deletions
doc/manual/etiquette.xml 0 → 100644
View file @ a4d01471
<?xml version='1.0' encoding='iso-8859-1' ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"docbook/dtd/xml/4.2/docbookx.dtd" [
<!ENTITY % fnc SYSTEM "fnc.ent">
<!ENTITY % var SYSTEM "var.ent">
%fnc; <!-- LysKOM functions -->
%var; <!-- LysKOM variables -->
]>
<book lang="en">
<chapter id="chapter:etiquette">
<title>Etiquette</title>
<para>
Do not add more conferences as recipients to a text than is
necessary. Although a text may be relevant to the topic of
several conferences, it may not be appropriate in all of
them. Think before you act.
</para>
<para>
There are some rules of etiquette that apply to recipients.
The rules may vary from LysKOM system to LysKOM system, but
here these guidelines are unlikely to get you into trouble.
</para>
<para>
When moving a text from one conference to another, or when
you write a comment and decide that one of the default
recipients isn't relevant any more, leave the original
recipient as a carbon copy recipient. This ensures that
members of the original recipient will have a chance to
notice the move.
</para>
<para>
Do not add people's mailboxes as recipients without
thinking. The client will sometimes add letterboxes
automatically or semi-automatically when appropriate.
</para>
<para>
Do not <emphasis>remove</emphasis> people's mailboxes as
recipients, or convert them to carbon copy recipients when
writing comments. It is up to the user themselves to do
this. Most of the time, when a letterbox appears as a
recipient, it is because the person in question isn't a
member of any of regular recipients of the text, but still
wants to participate in the discussion.
</para>
</chapter>
</book>
doc/manual/glossary.xml 0 → 100644
View file @ a4d01471
<?xml version='1.0' encoding='iso-8859-1' ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"docbook/dtd/xml/4.2/docbookx.dtd">
<book lang="en">
<glossary>
<title>Glossary</title>
<glossdiv>
<title>English</title>
<glossentry id="gloss:text:en">
<glossterm>text</glossterm>
<glossdef>
<para>See <xref linkend="chapter:texts"/> for details.</para>
</glossdef>
</glossentry>
<glossentry>
<glossterm id="gloss:comment:en">comment</glossterm>
<glossdef>
<para>See <xref linkend="texts:comments"/> for details.</para>
</glossdef>
</glossentry>
</glossdiv>
<glossdiv>
<title>Svenska</title>
<glossentry>
<glossterm>text</glossterm>
<glosssee otherterm="gloss:text:en">Se den engelska termen "text"</glosssee>
</glossentry>
<glossentry>
<glossterm>kommentar</glossterm>
<glosssee otherterm="gloss:comment:en">Se den engelska termen "comment"</glosssee>
</glossentry>
</glossdiv>
</glossary>
</book>
doc/manual/intro.xml 0 → 100644
View file @ a4d01471
<?xml version='1.0' encoding='iso-8859-1' ?>
<!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
"docbook/dtd/xml/4.2/docbookx.dtd" [
<!ENTITY % fnc SYSTEM "fnc.ent">
<!ENTITY % var SYSTEM "var.ent">
%fnc; <!-- LysKOM functions -->
%var; <!-- LysKOM variables -->
]>
<book lang="en">
<chapter>
<title>Introduction to LysKOM</title>
<para>
LysKOM is an electronic conferencing system, similar in
function, but different in execution, to the many message
message boards that have come into existence on the Internet.
</para>
<para>
The concepts behind LysKOM date back to the 1970s, when
researchers in Stockholm developed QZ-KOM, the first bulletin
board system in Sweden. In many ways, LysKOM is a direct
descendent of QZ-KOM, designed to be familiar to users of QZ-KOM
and its derivatives.
</para>
<para>
Unlike QZ-KOM and most of its derivatives, LysKOM is a
client-server system and there are a number of clients to choose
from, of which the Emacs Lisp client (commonly known as the
elisp client) is the best, most feature-rich, most portable and
most popular. Other popular clients include a web-based client
(WebKOM) and a Windows-based client (WinKOM). There are several
other clients in varying states of completeness.
</para>
</chapter>
</book>
interndoc/errors 0 → 100644
View file @ a4d01471
PRINTING ERROR MESSAGES
David Byers
This file describes how errors can be reported to the user.
All developers should know this.
VARIABLES
The client has the following variables that are relevant to error
reporting:
lyskom-errno (variable). The last error reported by the server (or
possibly the result of the last command).
lyskom-err-stat (variable). The most recent error status
information reported by the server.
lyskom-error-codes (variable). This variable maps error names to
error codes. It exists so that we can use symbolic error names in
other places.
lyskom-error-texts (strings). This string set contains default
error strings for all errors. These are used when no specific
error string is available when reporting an error.
REPORTING ERRORS
There are too many functions for reporting errors.
lyskom-report-command-answer reports the result of a command. It
will print "done" or "didn't work", a newline and a description of
the error, if there was one. Use this to report how a command
goes. You should insert a text such as "Doing something..."
without a newline at the end before calling this function.
lyskom-insert-error inserts an error message. It is used by
lyskom-report-command-answer to print the error message. It uses
lyskom-get-error-text to get the error string.
lyskom-get-error-text returns the text for an error. By supplying
the optional error-descriptions argument you can supply a list of
context-specific error messages.
lyskom-current-error returns a string describing the most recently
reported error. Its functionality is really subsumed by
lyskom-get-error-text.
CONTEXT-SENSITIVE ERROR REPORTING
You can supply an alist of context-specific error strings to most
of the above functions. The list is an alist where the car is an
error code (symbolic or numeric) and the cdr is the error string
to insert for that error.
interndoc/membership 0 → 100644
View file @ a4d01471
HOW THE MEMBERSHIP LIST WORKS
David Byers
This file aims to explain how the client stores the memberships of
a person.
If you are working with the membership list in any way, such as
changing priorities or positions, you absolutely need to know
this.
1. API
There are a number of functions for managing the membership list,
many of which are internal to membership list management. This
section describes the functions that should be used.
lyskom-add-memberships-to-membership
lyskom-insert-membership
lyskom-replace-membership
lyskom-remove-membership
lyskom-membership-position
lyskom-membership-length
lyskom-init-membership
lyskom-get-membership
lyskom-try-get-membership
All other membership-related functions in reading.el are internal.
2. History
The membership list was formerly stored in lyskom-membership, but
due to the extreme inefficiency of this, it had to be changed.
There were two problems with storing the membership list as a
simple list:
a. Every time new data was inserted into the list the entire list
had to be sorted. After sorting the entire list had to be
scanned to update the position field of all memberships.
b. Finding a membership corresponding to a conference required a
linear scan over the entire membership list.
A lot of time was wasted particularly when logging on due to the
structure of the data. A data structure that could be maintained
in sorted order at all times and supported rapid lookup of
memberships would have been better.
The first attempt at upgrading was a linear list backed by an
assoc list mapping conference numbers to memberships. Since assoc
lists are searched by the C kernel, this eliminated point b, but
there were problems maintaining consitency between the list and
the assoc list.
The second attempt involved replacing the list with an AVL tree.
The AVL tree supports O(log n) insertion, resulting in an overall
time to build the initial tree during logon to O(n log n). The
assoc list was replaced by a hash table for even more rapid lookup
of conference numbers (is is still an assoc list if hash tables
are not supported).
The AVL tree solution performed well, but altering priorities and
positions was difficult since these were used as sort keys in the
AVL tree.
3. Current data structure
The current impleentation has replaced the AVL tree with a doubly
linked list that is maintained in sort order. Insertions are done
by linear search of the list from the front or back. A heuristic
determines which end to start at. The result is that inserting an
element that is to go last on the list is always a constant-time
operation. Since data being inserted during login is usually close
to pre-sorted and inserted in order, this reduces the time to
build the initial list to an O(n) operation.
3.1 Insertions
Insertions are handled by lyskom-membership-list-insert. Based on
the priority of the new membership and the prioriries of the first
and last element, this function decides whether to call
lyskom-membership-list-append or lyskom-membership-list-prepend.
lyskom-membership-list-prepend searches the membership list from
the front until it finds the position where the new membership
should go. lyskom-membership-list-append does the same, but
searches from the end of the list.
When the position is located, the new membership is inserted into
the list. Both functions then scan the list from the new element
towards the end, adjusting the position field of each membership
to ensure that no two memberships have the same position.
3.2 Deletions
Deletions are handled by lyskom-membership-list-delete. This
function unlinks the element to be deleted from the list and scans
the list from that position forward, decrementing all position
fields by one.
3.3 Movement
Movements are handled by lyskom-membership-list-move. Starting
with the element that has been changed, this function scans either
forward or backwards in the list for the position to which the
element should move, adjusting the position of all elements along
the way. It then moves the element within the list.
4. Notes
The client will keep the membership list sorted in order of
priority, and the data structures reflect this order. That means
that the membership position in the server may differ from the
position recorded in the client.
interndoc/vardoc 0 → 100644
View file @ a4d01471
VARIABLE DOCUMENTATION
Variable documentation strings that are intended for inclusion in the
printed manual must follow these conventions.
* The docstring must start with two asterisks.
* Literal strings will possibly be italicized. They may span lines.
* Code and cross references are indicated with `'
`kom-<something>' --- Cross-reference to variable or command
`lyskom-<something>' --- Cross-reference to variable or command
`<UPPERCASE>' --- Format as a replaceable
`<anything>' --- Format as a constant
non-nil --- Special case for nil
* To insert a table indent the block from the left, and make second
and last lines all dashes. Rows are separated with empty lines. Be
careful to start multi-line cells all on the same column. Watch out
for the effects of escaped characters in earlier cells.
The table ends at the second all-dash line.
* Indicate blocks of preformatted text with a line consisting of a
single unindented < before and > after.
* Indicate bulleted lists with * at the start of the paragraph. Each
bullet item may consist of a single paragraph only.
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