From cd5f0ed39358c9375e0a22b2606bb8e9eb6feed8 Mon Sep 17 00:00:00 2001
From: Per Cederqvist <ceder@lysator.liu.se>
Date: Wed, 16 May 2001 22:54:28 +0000
Subject: [PATCH] (Top, Concepts, The Aux-Item List) (Fundamentals, LysKOM Data
Types, Who Information) (Protocol Requests, Asynchronous Messages, Common
Commands): Menu descriptions added. (get-text): @badspell added in
example. (Who Information): These types are all obsolete. Almost.
(Client-Server Dialog): Mention asynchronous messages.
---
doc/Protocol-A.texi | 126 ++++++++++++++++++++++++--------------------
1 file changed, 68 insertions(+), 58 deletions(-)
diff --git a/doc/Protocol-A.texi b/doc/Protocol-A.texi
index 2062eebae..57654fddc 100644
--- a/doc/Protocol-A.texi
+++ b/doc/Protocol-A.texi
@@ -382,23 +382,23 @@ The most up-to-date version if this document can always be found at
@end ifnottex
@menu
-* Preface::
-* Concepts::
-* Fundamentals::
-* LysKOM Data Types::
-* Protocol Requests::
-* Asynchronous Messages::
-* Error Codes::
-* Aux-Item Types::
-* Name Expansion::
-* LysKOM Content Types::
-* The User Area::
-* Writing Clients::
-* Importing and Exporting E-Mail::
-* Future changes::
-* Protocol Version History::
-* Document Edition History::
-* Index::
+* Preface:: What is LysKOM? Who wrote this document?
+* Concepts:: Articles, conferences, aux-items, @dots{}
+* Fundamentals:: The building blocks of Protocol A.
+* LysKOM Data Types:: Domain-specific data types used in Protocol A.
+* Protocol Requests:: Each protocol explained in depth.
+* Asynchronous Messages:: Unsolicited information from the server.
+* Error Codes:: All error codes with explanations.
+* Aux-Item Types:: All predefined aux-item types.
+* Name Expansion:: Looking up the name of a conference or person.
+* LysKOM Content Types:: Predefined content types for articles.
+* The User Area:: Store client-specific settings in the server.
+* Writing Clients:: A few tips for client writers.
+* Importing and Exporting E-Mail:: A few thoughts on e-mail integration.
+* Future changes:: The protocol is not yet perfect.
+* Protocol Version History:: The protocol was even less perfect before.
+* Document Edition History:: Changes in this document.
+* Index:: Index of protocol elements.
@end menu
@node Preface
@@ -444,13 +444,16 @@ This chapter introduces the concepts used in LysKOM, such as articles,
conferences and sessions.
@menu
-* Articles::
-* Conferences::
-* Persons and Sessions::
-* The Misc-Info List::
-* The Aux-Item List::
-* Security::
-* Membership and Reading::
+* Articles:: Reading and writing articles is what
+ LysKOM is about.
+* Conferences:: Articles are organized in conferences.
+* Persons and Sessions:: Persons log on to the LysKOM system.
+* The Misc-Info List:: How articles are organized in comment
+ chains and in conferences.
+* The Aux-Item List:: A generic extension mechanism.
+* Security:: Some persons have more privileges than
+ others.
+* Membership and Reading:: You don't have to read anything twice.
@end menu
@@ -714,11 +717,13 @@ The aux-item list is used as a generic extension mechanism in the LysKOM
server and in protocol A.
@menu
-* About Aux-Items::
-* Predefined Aux-Item Types::
-* Client-Specific Aux-Item Types::
-* Experimental Aux-Item Types::
-* Defining New Aux-Item Types::
+* About Aux-Items:: An introduction to aux-items.
+* Predefined Aux-Item Types:: Predefined aux-items are part of the protocol.
+* Client-Specific Aux-Item Types:: Clients can allocate aux-items for
+ their private use.
+* Experimental Aux-Item Types:: A block of aux-items are reserved for
+ experimental use.
+* Defining New Aux-Item Types:: Creating new aux-item types is easy.
@end menu
@node About Aux-Items
@@ -971,11 +976,11 @@ are built. Simple data types include things like integers and strings
while complex data types include things such as conferences and people.
@menu
-* Notation::
-* Simple Data Types::
-* Connecting to the Server::
-* Client-Server Dialog::
-* Protocol Error Messages::
+* Notation:: The grammar used in this document.
+* Simple Data Types:: BOOL, INT32, ARRAY, @dots{}
+* Connecting to the Server:: The initial handshake.
+* Client-Server Dialog:: Requests, replies, asynchronous messages.
+* Protocol Error Messages:: How the server reacts to syntax errors.
@end menu
@node Notation
@@ -1371,6 +1376,11 @@ error in any situation without choking completely since bugs might
cause the wrong error message to be sent or new errors might be added
later on.
+The server may send asynchronous messages (@pxref{Asynchronous
+Messages}) to the client at any time (but not in the middle of a
+reply). Two important asynchronous messages are
+@async{async-new-text} (@pxref{async-new-text}) and
+@async{async-send-message} (@pxref{async-send-message}).
@node Protocol Error Messages
@section Protocol Error Messages
@@ -1416,20 +1426,20 @@ Since the types defined here are all based on the simple types, the
definitions are more concise in this section.
@menu
-* Common Types::
-* Auxiliary Information::
-* Conference Types::
-* Conference Search Results::
-* Conference Status Types::
-* Archaic way to list conferences::
-* Mapping Local to Global Text Numbers::
-* Server Information::
-* Person Status Types::
-* Membership Information::
-* Article Marks::
-* Article Information::
-* Who Information::
-* Session Information::
+* Common Types:: Simple types used over and over again.
+* Auxiliary Information:: Aux-items and related types.
+* Conference Types:: A few flags for conferences.
+* Conference Search Results:: Name lookup returns these types.
+* Conference Status Types:: Information about a conference.
+* Archaic way to list conferences:: Archaic name lookup result type.
+* Mapping Local to Global Text Numbers:: The Text-Mapping type.
+* Server Information:: Information about an installation.
+* Person Status Types:: Information about a person.
+* Membership Information:: Persons are members of conferences.
+* Article Marks:: Persons can mark articles.
+* Article Information:: Information about an article.
+* Who Information:: Old-style info about logged-on users.
+* Session Information:: New-style info about logged-on users.
@end menu
@node Common Types
@@ -2421,12 +2431,10 @@ introduced in protocol version 10 or later.
)
@end example
-These structures are used to retrieve and set information on who is
-currently using LysKOM. The types marked as ``old'' are obsolete but are
-included for completeness. @type{Who-Info-Old} identifies a user who is
-currently using LysKOM. @type{Who-Info} is used to set information
-about a session and is returned by one obsolete
-call. @type{Who-Info-Ident} is the preferred data type to use.
+These structures are used to retrieve information on who is currently
+using LysKOM. All the requests using these types are obsolete, but
+@type{Who-Info} is used by @async{async-i-am-on}
+(@pxref{async-i-am-on}).
The fields of @type{Who-Info-Old} are
@@ -2656,7 +2664,8 @@ calls are annotated with the protocol version in which they appeared and
their current status.
@menu
-* Protocol Notation::
+* Protocol Notation:: The notation used when describing the
+ requests and their replies.
* login-old:: O Log in to LysKOM. Call 62 is preferred (0)
* logout:: r Log out. Call 62 to log in again (1)
* change-conference:: r Change current conference (2)
@@ -4006,7 +4015,7 @@ as is available will be returned.
@reqexample
@example
1 25 100 0 32766
- @t{=1 @holl{25,Yawn^JNothing is happening}}
+ @t{=1 @holl{25,Yawn@badspell{^J}Nothing is happening}}
2 25 100 5 32766
@t{=2 @holl{20,Nothing is happening}}
3 25 100 0 3
@@ -7581,7 +7590,8 @@ reject them if a client uses it as an argument to
@reqlink{accept-async}.
@menu
-* About Asynchronous Messages::
+* About Asynchronous Messages:: Introductory information about
+ asynchronous messages.
* async-new-text-old:: r A text has been created (0)
* async-i-am-off:: O Logged off (obsolete) (1)
* async-i-am-on-obsolete:: O Client changed i-am-on string (obsolete) (2)
@@ -8837,7 +8847,7 @@ section is to get client writers started on some of these commands, and
to answer some questions that seem to come up over and over again.
@menu
-* What do I have unread::
+* What do I have unread:: How to figure out which articles to present.
@end menu
@node What do I have unread
--
GitLab