Commit 79fdc8a5 authored by Per Cederqvist's avatar Per Cederqvist
Browse files

Fix all @rarg{} arguments that used the wrong argument name. Edit all

request prototypes so that the consistently use semicolon as an
argument delimiter, not an argument terminator.  Add missing @rarg{}
markup.

(Protocol Version History): Remove a trailing space.
(get-membership-old): Use @field{read-texts} instead of @rarg{read-texts}.
(get-created-texts): Added missing '->' token.
(create-anonymous-text): Added @misc{} markup.
(create-person): Use @priv{create-pers} instead of @rarg{create-pers}.
(modify-system-info): Docuent items-to-delete and items-to-add.
(add-member): Document type, including the fact that the
	invitation field is sometimes set automatically.
parent f04c534a
......@@ -2,7 +2,7 @@
@c
@c FIXME: Explain how the garb works with nice and keep-commented
@c
@c $Id: Protocol-A.texi,v 1.109 2001/04/16 18:06:17 ceder Exp $
@c $Id: Protocol-A.texi,v 1.110 2001/04/18 08:22:11 ceder Exp $
@c %**start of header
@setfilename protocol-a.info
@settitle LysKOM Protocol A
......@@ -471,7 +471,7 @@ name was changed, but not the functionality.
@subsection Protocol version 8 (first implemented in lyskomd 1.8.0)
@table @asis
@table @asis
@item Added Functionality
@itemize @bullet
@item
......@@ -3393,7 +3393,7 @@ using LysKOM. Clients are encouraged to use this call creatively.
@table @errorcode
@item string-too-long
@rarg{what-i-am-doing} is too long.
@rarg{what-am-i-doing} is too long.
@end table
......@@ -3404,7 +3404,8 @@ using LysKOM. Clients are encouraged to use this call creatively.
@findex create-person-old
@example
create-person-old [5] (( name : HOLLERITH;
passwd : HOLLERITH; )) -> Pers-No;
passwd : HOLLERITH ))
-> ( Pers-No );
@end example
This call requests that the server create a new person with the name and
......@@ -3477,8 +3478,7 @@ Person @rarg{person} does not exist.
Conference @rarg{person} does not exist or is secret.
@item conference-zero
@c FIXME: detect this error!
@rarg{conference} is zero.
@rarg{person} is zero.
@end table
@node set-priv-bits
......@@ -3487,12 +3487,12 @@ Conference @rarg{person} does not exist or is secret.
@findex set-priv-bits
@example
set-priv-bits [7] (( person : Pers-No;
privileges : Priv-Bits; )) -> ( );
privileges : Priv-Bits )) -> ( );
@end example
This call sets the privileges of a person (see @ref{Security}.) To
successfully issue this call the session must be logged in as a person
with sufficient privileges.
This call sets the privileges of @rarg{person} to
@rarg{privileges}. @ref{Security}. To successfully issue this call the
session must be logged in as a person with sufficient privileges.
@i{Example:}
@example
......@@ -3527,7 +3527,7 @@ and privilege level set to 6 or higher.
@example
set-passwd [8] (( person : Pers-No;
old-pwd : HOLLERITH;
new-pwd : HOLLERITH; )) -> ( );
new-pwd : HOLLERITH )) -> ( );
@end example
This call is used to set the password of a person. Providing
......@@ -3561,7 +3561,7 @@ supervisor of that person and without the @priv{wheel} bit set and
privilege level 7 or higher enabled.
@item invalid-password
@rarg{old-pwd} is invalid or @rarg{new-passwd} is invalid as a password.
@rarg{old-pwd} is invalid or @rarg{new-pwd} is invalid as a password.
@end table
......@@ -3573,7 +3573,7 @@ privilege level 7 or higher enabled.
@findex query-read-texts-old
@example
query-read-texts-old [9] (( person : Pers-No;
conference : Conf-No; ))
conference : Conf-No ))
-> ( Membership-Old );
@end example
......@@ -3621,7 +3621,7 @@ Conference @rarg{conference} does not exist, or is secret.
@findex create-conf-old
@example
create-conf-old [10] (( name : HOLLERITH;
type : Any-Conf-Type; ))
type : Any-Conf-Type ))
-> ( Conf-No );
@end example
......@@ -3704,7 +3704,7 @@ the @conftype{rd-prot} bit is cleared.
@findex delete-conf
@example
delete-conf [11] ( conf : Conf-No; ) -> ( );
delete-conf [11] ( conf : Conf-No ) -> ( );
@end example
This call deletes the conference @rarg{conf} from the LysKOM
......@@ -3737,7 +3737,7 @@ Login required before issuing this call.
@rarg{conf} does not exist or is secret.
@item conference-zero
@rarg{conference} is zero.
@rarg{conf} is zero.
@item permission-denied
Not supervisor of @rarg{conf} and not enough privileges enabled.
......@@ -3810,7 +3810,7 @@ returned instead of the name.
@item undefined-conference
@rarg{conf-no} does not exist or is secret.
@item conference-zero
@rarg{conference} is zero.
@rarg{conf-no} is zero.
@end table
......@@ -3867,7 +3867,7 @@ Login required before issuing this call.
Conference @rarg{conf-no} does not exist or is secret.
@item conference-zero
@rarg{conference} is zero.
@rarg{conf-no} is zero.
@item undefined-person
Person @rarg{pers-no} does not exist
......@@ -3891,7 +3891,7 @@ privileges to change the priorities of person @rarg{pers-no}.
@findex sub-member
@example
sub-member [15] (( conf-no : Conf-No;
pers-no : Pers-No; ))
pers-no : Pers-No ))
-> ( );
@end example
......@@ -3924,7 +3924,7 @@ Login required before issuing this call.
Conference @rarg{conf-no} does not exist or is secret.
@item conference-zero
@rarg{conference} is zero.
@rarg{conf-no} is zero.
@item undefined-person
Person @rarg{pers-no} does not exist.
......@@ -3947,7 +3947,7 @@ Not supervisor of conference @rarg{conf-no} or not supervisor of person
@findex set-presentation
@example
set-presentation [16] (( conf-no : Conf-No;
text-no : Text-No; ))
text-no : Text-No ))
-> ( );
@end example
......@@ -3990,7 +3990,7 @@ Login required before issuing this call.
Conference @rarg{conf-no} does not exist or is secret.
@item conference-zero
@rarg{conference} is zero.
@rarg{conf-no} is zero.
@item permission-denied
Not enough permissions to change presentation of conference
......@@ -4013,7 +4013,7 @@ marks.
@findex set-etc-motd
@example
set-etc-motd [17] (( conf-no : Conf-No;
text-no : Text-No; ))
text-no : Text-No ))
-> ( );
@end example
......@@ -4056,7 +4056,7 @@ Login required before issuing this call.
Conference @rarg{conf-no} does not exist or is secret.
@item conference-zero
@rarg{conference} is zero.
@rarg{conf-no} is zero.
@item permission-denied
Not enough permissions to set the MOTD of conference @rarg{conf-no}.
......@@ -4075,7 +4075,7 @@ marks.
@findex set-supervisor
@example
set-supervisor [18] (( conf-no : Conf-No;
admin : Conf-No; ))
admin : Conf-No ))
-> ( );
@end example
......@@ -4120,7 +4120,7 @@ Conference @rarg{conf-no} or conference @rarg{admin} does not exist or
is secret.
@item conference-zero
@rarg{conference} is zero.
@rarg{conf-no} is zero.
@item permission-denied
Not enough permissions or privileges to change the supervisor of
......@@ -4138,7 +4138,7 @@ conference @rarg{conf-no}.
@findex set-permitted-submitters
@example
set-permitted-submitters [19] (( conf-no : Conf-No;
perm-sub : Conf-No; ))
perm-sub : Conf-No ))
-> ( );
@end example
......@@ -4183,7 +4183,7 @@ Conference @rarg{conf-no} or conference @rarg{perm-sub} does not exist
or is secret.
@item conference-zero
@rarg{conference} is zero.
@rarg{conf-no} is zero.
@item permission-denied
Not enough permissions to change the permitted submitters of conference
......@@ -4199,7 +4199,7 @@ Not enough permissions to change the permitted submitters of conference
@findex set-super-conf
@example
set-super-conf [20] (( conf-no : Conf-No;
super-conf : Conf-No; ))
super-conf : Conf-No ))
-> ( );
@end example
......@@ -4225,7 +4225,7 @@ Login required before issuing this call.
Conference @rarg{conf-no} or conference @rarg{super-conf} does not exist
or is secret.
@item conference-zero
@rarg{conference} is zero.
@rarg{conf-no} is zero.
@item permission-denied
Not enough permissions to change super-conference of conference
@rarg{conf-no}.
......@@ -4270,7 +4270,7 @@ Login required before issuing this call.
@item undefined-conference
Conference @rarg{conf-no} does not exist or is secret.
@item conference-zero
@rarg{conference} is zero.
@rarg{conf-no} is zero.
@item secret-public
@rarg{type} has @conftype{secret} bit but not @conftype{rd-prot}.
@item permission-denied
......@@ -4322,7 +4322,7 @@ Login required before issuing this call.
@item undefined-conference
Conference @rarg{conf-no} does not exist or is secret.
@item conference-zero
@rarg{conference} is zero.
@rarg{conf-no} is zero.
@item permission-denied
Not enough permissions to change the expiration time for conference
@rarg{conf-no}.
......@@ -4371,10 +4371,11 @@ Login required before issuing this call.
-> ( );
@end example
This call has been replaced by @ref{mark-text} and @ref{unmark-text} and
should no longer be used. This call can only set mark-type to a value
in the range 1 to 255 (inclusive). If mark-type is set to 0 the mark
will be removed.
This call has been replaced by @req{mark-text} (@pxref{mark-text}) and
@req{unmark-text} (@pxref{unmark-text}) and should no longer be used.
This call can only set @rarg{mark-type} to a value in the range 1 to
255 (inclusive). If @rarg{mark-type} is set to 0 the mark will be
removed.
@subheading Error codes
......@@ -4406,7 +4407,7 @@ many marks, or cause the text to have too many marks.
@example
get-text [25] (( text : Text-No;
start-char : INT32;
end-char : INT32; ))
end-char : INT32 ))
-> ( HOLLERITH );
@end example
......@@ -4505,7 +4506,7 @@ Attempt to retrieve text number 0.
@findex mark-as-read
@example
mark-as-read [27] (( conference : Conf-No;
text : ARRAY Local-Text-No; ))
text : ARRAY Local-Text-No ))
-> ( );
@end example
......@@ -4569,8 +4570,8 @@ One of the numbers in @rarg{text} is zero.
@findex create-text-old
@example
create-text-old [28] (( text : HOLLERITH;
misc-info : ARRAY Misc-Info; ))
-> ( Text-No; );
misc-info : ARRAY Misc-Info ))
-> ( Text-No );
@end example
Creates a new text with contents from @rarg{text} and recipients
......@@ -4681,7 +4682,7 @@ author.
@example
add-recipient [30] (( text-no : Text-No;
conf-no : Conf-No;
recpt-type : Info-Type; ))
recpt-type : Info-Type ))
-> ( );
@end example
......@@ -4729,7 +4730,7 @@ Login required before issuing this call.
The conference @rarg{conf-no} does not exist.
@item conference-zero
@rarg{conference} is zero.
@rarg{conf-no} is zero.
@item no-such-text
The text @rarg{text-no} does not exist.
......@@ -4765,7 +4766,7 @@ super conf chain.
@findex sub-recipient
@example
sub-recipient [31] (( text-no : Text-No;
conf-no : Conf-No; ))
conf-no : Conf-No ))
-> ( );
@end example
......@@ -4806,7 +4807,7 @@ The conference @rarg{conf-no} is not a recipient of text @rarg{text-no}.
The conference @rarg{conf-no} does not exist or is secret.
@item conference-zero
@rarg{conference} is zero.
@rarg{conf-no} is zero.
@item permission-denied
Not supervisor of text author or conference, and not sender of text to
......@@ -4821,7 +4822,7 @@ Not supervisor of text author or conference, and not sender of text to
@findex add-comment
@example
add-comment [32] (( text-no : Text-No;
comment-to : Text-No; ))
comment-to : Text-No ))
-> ( );
@end example
......@@ -4873,7 +4874,7 @@ The text @rarg{comment-to} already has the maximum number of comments.
@findex sub-comment
@example
sub-comment [33] (( text-no : Text-No;
comment-to : Text-No; ))
comment-to : Text-No ))
-> ( );
@end example
......@@ -4907,7 +4908,7 @@ Login required before issuing this call.
@item no-such-text
One of the texts @rarg{text-no} or @rarg{comment-to} does not exist.
@item not-comment
The text @rarg{text-no} is not a comment to @rarg{comment-too}.
The text @rarg{text-no} is not a comment to @rarg{comment-to}.
@item permission-denied
Not supervisor of author of @rarg{text-no} or not sender of the
comment and not enough privileges set and enable to complete the call
......@@ -4925,7 +4926,7 @@ anyway.
@example
get-map [34] (( conf-no : Conf-No;
first-local-no : Local-Text-No;
no-of-texts : INT32; ))
no-of-texts : INT32 ))
-> ( Text-List );
@end example
......@@ -5053,7 +5054,7 @@ This call always succeeds
@findex get-info-old
@example
get-info-old [36] ( )
-> ( Info-Old; );
-> ( Info-Old );
@end example
This call returns the @type{Info} structure for the server
......@@ -5089,7 +5090,7 @@ This call always succeeds.
@findex add-footnote
@example
add-footnote [37] (( text-no : Text-No;
footnote-to: Text-No; ))
footnote-to: Text-No ))
-> ( );
@end example
......@@ -5142,7 +5143,7 @@ Text @rarg{text-no} is already a footnote to @rarg{footnote-to}.
@findex sub-footnote
@example
sub-footnote [38] (( text-no : Text-No;
footnote-to : Text-No; ))
footnote-to : Text-No ))
-> ( );
@end example
......@@ -5214,7 +5215,7 @@ This call always succeeds.
@findex set-unread
@example
set-unread [40] (( conf-no : Conf-No;
no-of-unread : INT32; ))
no-of-unread : INT32 ))
-> ( );
@end example
......@@ -5449,7 +5450,7 @@ retrieved. @rarg{first} is the first position in the membership list to
retrieve, numbered from 0 and up. @rarg{no-of-confs} is the number of
membership records to retrieve. @rarg{mask} is a set of flags. Currently
the only flag is @rarg{want-read-texts}, which instructs the server not
to send the @rarg{read-texts} array of the memberships.
to send the @field{read-texts} array of the memberships.
The server will return a membership list that is shorter than
@rarg{no-of-confs} if @rarg{no-of-confs} + @rarg{first} is larger than
......@@ -5500,8 +5501,8 @@ person's membership list.
@example
get-created-texts [47] (( person : Pers-No;
first : Local-Text-No;
no-of-texts : INT32; ))
( Text-List );
no-of-texts : INT32 ))
-> ( Text-List );
@end example
This call is obsolete; instead you should use @ref{map-created-texts}.
......@@ -5572,11 +5573,11 @@ text.
@example
get-members-old [48] (( conf : Conf-No;
first : INT16;
no-of-members : INT16; ))
no-of-members : INT16 ))
-> ( ARRAY Pers-No );
@end example
This call returns a list of members of the conference @rarg{conf-no}.
This call returns a list of members of the conference @rarg{conf}.
@rarg{first} is the first index in the membership to return, numbered
from zero and up. @rarg{no-of-members} is the maximum number of members
to return.
......@@ -5612,7 +5613,7 @@ The conference @rarg{conf} does not exist or is secret.
@findex get-person-stat
@example
get-person-stat [49] ( pers-no : Pers-No; )
get-person-stat [49] ( pers-no : Pers-No )
-> ( Person );
@end example
......@@ -5766,7 +5767,7 @@ Person @rarg{pers-no} does not exist or is secret.
@findex send-message
@example
send-message [53] (( recipient : Conf-No;
message : HOLLERITH; )
message : HOLLERITH ))
-> ( );
@end example
......@@ -5913,7 +5914,7 @@ This call always succeeds.
@findex set-user-area
@example
set-user-area [57] (( pers-no : Pers-No;
user-area : Text-No; ))
user-area : Text-No ))
-> ( );
@end example
......@@ -5998,7 +5999,7 @@ This call never fails.
@findex create-anonymous-text-old
@example
create-anonymous-text-old [59] (( text : HOLLERITH;
misc-info : ARRAY Misc-Info; ))
misc-info : ARRAY Misc-Info ))
-> ( Text-No );
@end example
......@@ -6329,7 +6330,7 @@ This call always succeeds.
@findex set-client-version
@example
set-client-version [69] (( client-name : HOLLERITH;
client-version : HOLLERITH; ))
client-version : HOLLERITH ))
-> ( );
@end example
......@@ -6445,7 +6446,7 @@ The session @rarg{session} does not exist.
@findex mark-text
@example
mark-text [72] (( text : Text-No;
mark-type : INT8; ))
mark-type : INT8 ))
-> ( );
@end example
......@@ -6530,7 +6531,7 @@ The text @rarg{text-no} was not marked.
@example
re-z-lookup [74] (( regexp : HOLLERITH;
want-persons : BOOL;
want-confs : BOOL; ))
want-confs : BOOL ))
-> ( ARRAY Conf-Z-Info );
@end example
......@@ -6610,7 +6611,7 @@ This call always succeeds.
@example
lookup-z-name [76] (( name : HOLLERITH;
want-pers : BOOL;
want-confs : BOOL; ))
want-confs : BOOL ))
-> ( ARRAY Conf-Z-Info );
@end example
......@@ -6653,7 +6654,7 @@ This call always succeeds.
@findex set-last-read
@example
set-last-read [77] (( conference : Conf-No;
last-read : Local-Text-No; ))
last-read : Local-Text-No ))
-> ( );
@end example
......@@ -6912,7 +6913,7 @@ This call always succeeds.
@example
who-is-on-dynamic [83] (( want-visible : BOOL;
want-invisible : BOOL;
active-last : INT32; ))
active-last : INT32 ))
-> ( ARRAY Dynamic-Session-Info );
@end example
......@@ -6998,7 +6999,7 @@ This call always succeeds.
@example
create-text [86] (( text : HOLLERITH;
misc-info : ARRAY Misc-Info;
aux-items : ARRAY Aux-Item-Input; ))
aux-items : ARRAY Aux-Item-Input ))
-> ( Text-No );
@end example
......@@ -7067,7 +7068,7 @@ Too many misc-items or aux-items were specified.
@example
create-anonymous-text [87] (( text : HOLLERITH;
misc-info : ARRAY Misc-Info;
aux-items : ARRAY Aux-Item-Input; ))
aux-items : ARRAY Aux-Item-Input ))
-> ( Text-No );
@end example
......@@ -7083,8 +7084,9 @@ explicit support for sending anonymous texts to a server.
It is only possible to send anonymous texts to a conference with the
right flag bit set.
The only Misc-Info items valid for this call are recpt, cc-recpt,
bcc-recpt (protocol version 10) comm-to and footn-to.
The only Misc-Info items valid for this call in the @rarg{misc-info}
array are @misc{recpt}, @misc{cc-recpt}, @misc{bcc-recpt} (introduced
in protocol version 10), @misc{comm-to} and @misc{footn-to}.
@subheading Error codes
......@@ -7132,7 +7134,7 @@ One of the items looks valid but could not be created anyway.
@example
create-conf [88] (( name : HOLLERITH;
type : Any-Conf-Type;
aux-items : ARRAY Aux-Item-Input; ))
aux-items : ARRAY Aux-Item-Input ))
-> ( Conf-No );
@end example
......@@ -7189,7 +7191,7 @@ One of the items looks valid but could not be created anyway.
create-person [89] (( name : HOLLERITH;
passwd : HOLLERITH;
flags : Personal-Flags;
aux-items : ARRAY Aux-Item-Input; ))
aux-items : ARRAY Aux-Item-Input ))
-> ( Pers-No );
@end example
......@@ -7219,7 +7221,7 @@ creation before logging in.
@item permission-denied
The server does not allow anyone to create person and the person
currently logged on does not have the @rarg{create-pers} bit set.
currently logged on does not have the @priv{create-pers} bit set.
@item person-exists
There is already a person named @rarg{name}.
......@@ -7295,7 +7297,7 @@ The conference @rarg{conf-no} does not exist or is secret.
@example
modify-text-info [92] (( text : Text-No;
delete : ARRAY Aux-No;
add : ARRAY Aux-Item-Input; ))
add : ARRAY Aux-Item-Input ))
-> ( );
@end example
......@@ -7329,13 +7331,13 @@ One of the items in @rarg{add} is illegal for some reason.
@example
modify-conf-info [93] (( conf : Conf-No;
delete : ARRAY Aux-No;
add : ARRAY Aux-Item-Input; ))
add : ARRAY Aux-Item-Input ))
-> ( );
@end example
This call deleted the aux-items listed in @rarg{delete} from the
conference @rarg{conference} and then adds the ones listed in @rarg{add}
conference @rarg{conf} and then adds the ones listed in @rarg{add}
to the text. Either list may be empty, and the call is guaranteed to
either completely fail or completely succeed.
......@@ -7345,7 +7347,7 @@ either completely fail or completely succeed.
@item login-first
Login required before issuing this call.
@item undefined-conference
The conference @rarg{conference} does not exist or is secret.
The conference @rarg{conf} does not exist or is secret.
@item aux-item-permission
No permission to delete one or more of the items in @rarg{delete}, or
not enough permissions to add one or more of the items in @rarg{add}.
......@@ -7382,7 +7384,7 @@ This call always succeeds.
@findex modify-system-info
@example
modify-system-info [95] (( items-to-delete : ARRAY Aux-No;
items-to-add : ARRAY Aux-Item-Input; ))
items-to-add : ARRAY Aux-Item-Input ))
-> ( );
@end example
......@@ -7390,6 +7392,10 @@ This call modifies the aux-item list of the server information (which
can be retrieved using @ref{get-info}.) It only succeeds when issued by
a person with the admin bit set and privileges enabled.
The items in @rarg{items-to-delete} are removed, and the items in
@rarg{items-to-add} are added. This call is atomic; either all
deletions or additions succedd, or none of them is made.
@subheading Error codes
@table @errorcode
......@@ -7430,7 +7436,7 @@ This call always succeeds.
@findex set-expire
@example
set-expire [97] (( conf-no : Conf-No;
expire : Garb-Nice; ))
expire : Garb-Nice ))
-> ( );
@end example
......@@ -7456,7 +7462,7 @@ complete the call anyway.
@findex query-read-texts
@example
query-read-texts [98] (( person : Pers-No;
conference : Conf-No; ))
conference : Conf-No ))
-> ( Membership );
@end example
......@@ -7575,7 +7581,7 @@ person's membership list.
pers-no : Pers-No;
priority : INT8;
where : INT16;
type : Membership-Type; ))
type : Membership-Type ))
-> ( );
@end example
......@@ -7583,6 +7589,10 @@ Make the person @rarg{pers-no} a member of conference @rarg{conf-no}.
The membership priority is set to @rarg{priority} and its position in
the membership list is set to @rarg{where}.
The membership flags are set to @rarg{type}. If the current user is
adding a user he isn't supervisor of, the @field{invitation} bit of
@rarg{type} is automatically set by the server.
This call can be used to change the priority, position and flags of a
conference in the person's membership list if the person is already a
member of the conference. The person doing this must either be a
......@@ -7619,7 +7629,7 @@ Login required before issuing this call.
Conference @rarg{conf-no} does not exist or is secret.
@item conference-zero
@rarg{conference} is zero.
@rarg{conf-no} is zero.
@item undefined-person
Person @rarg{pers-no} does not exist
......@@ -7647,11 +7657,11 @@ privileges to change the priorities of person @rarg{pers-no}.
@example
get-members [101] (( conf : Conf-No;
first : INT16;
no-of-members : INT16; ))
no-of-members : INT16 ))
-> ( ARRAY Member );
@end example
This call returns a list of members of the conference @rarg{conf-no}.
This call returns a list of members of the conference @rarg{conf}.
@rarg{first} is the first index in the membership to return, numbered
from zero and up. @rarg{no-of-members} is the maximum number of members
to return.
......@@ -7692,7 +7702,7 @@ The conference @rarg{conf} does not exist or is secret.
@example
set-membership-type [102] (( pers : Pers-No;