Skip to content

GitLab

Commit 8ca2c302 authored by Per Cederqvist's avatar Per Cederqvist
Browse files

(@reqexample): New macro. Use it in front of every example of request 

	usage.  Previously, many but not all examples were introduced
	by a @i{Example:} line.  That line is now included in the
	@reqexample macro, together with a "@need 2000" statement.
parent c7888e7f
Hide whitespace changes
Inline Side-by-side
doc/Protocol-A.texi
View file @ 8ca2c302
......@@ -3,8 +3,10 @@
@c FIXME: Explain how the garb works with nice and keep-commented
@c FIXME: @i{Example:} is only used in front of some examples.
@c FIXME: Make all types clickable in HTML (and info?)
@c FIXME: Example [20].
@c FIXME: I]M in examples introduces spurious blank lines in DVI output.
@c
@c $Id: Protocol-A.texi,v 1.121 2001/04/30 22:00:10 ceder Exp $
@c $Id: Protocol-A.texi,v 1.122 2001/04/30 22:22:33 ceder Exp $
@c %**start of header
@setfilename protocol-a.info
@settitle LysKOM Protocol A
......@@ -196,6 +198,13 @@
@code{\n\}
@end macro
@c @reqexample is used immediately before Protocol-A example
@c fragments.
@macro reqexample
@need 2000
@i{Example:}
@end macro
@ifinfo
This is the LysKOM Protocol A specification, edition
@value{PROTOEDITION}. It specifies version @value{PROTOVER} of the
......@@ -3552,7 +3561,7 @@ The new person will be a member of exactly one conference: the
associated mailbox. That membership will have priority 255 and (of
course) position 0. All flags of the membership will be 0.
@i{Example:}
@reqexample
@example
1 5 24HLysKOM Statistics Daemon 6Hsecret
@t{=1 6}
......@@ -3626,7 +3635,7 @@ This call sets the privileges of @rarg{person} to
@rarg{privileges}. @xref{Security}. To successfully issue this call the
session must be logged in as a person with sufficient privileges.
@i{Example:}
@reqexample
@example
1 7 6 0010000000000000
@t{=1}
......@@ -3668,7 +3677,7 @@ password is changed to @rarg{new-pwd}. Any person may set it's own
password. In addition persons with sufficient privileges may ser other
persons' passwords.
@i{Example:}
@reqexample
@example
1 8 5 6Hgazonk 7Ht9go8hw
@t{=1}
......@@ -3718,7 +3727,7 @@ and @rarg{conference} is the conference in question.
Calling @req{query-read-texts-old} does not require the session to be
logged in.
@i{Example:}
@reqexample
@example
1 9 6 1
@t{=1 32 5 11 12 7 93 1 193 1 1 20 133 3 @{ 135 136 137 @}}
......@@ -3764,7 +3773,7 @@ returns the conference number of the newly created conference.
To use this call the session must have logged in as a user with
privileges to create conferences (@pxref{Security}).
@i{Example:}
@reqexample
@ifnottex
@example
1 50 8
......@@ -3844,7 +3853,7 @@ database. Only privileged users and the supervisors of a conference may
delete it. If the conference is a mailbox the corresponding person will
also be deleted.
@i{Example:}
@reqexample
@example
1 50 7
@t{=1 4HTest 1001
......@@ -3891,7 +3900,7 @@ is corrupt.)
This call returns a list of conferences matching the string @rarg{name}.
lookup-name has been superseded by @reqlink{lookup-z-name}.
@i{Example:}
@reqexample
@example
1 12 3Ha d
@t{=1 3 @{ 217 674 1582 @} @{ 0000 1001 0000 @}}
......@@ -3973,7 +3982,7 @@ member of the conference.
In protocol version 10, setting the priority to zero sets the passive
bit in the membership. The actual priority is not changed.
@i{Example:}
@reqexample
@example
1 46 119 0 10 0
@t{=1 1 @{ 49 14 17 13 8 91 5 255 1 119 255 0 0 * @}}
......@@ -4032,7 +4041,7 @@ Removes the person @rarg{pers-no} from the membership list of conference
@rarg{conf-no} and remove the conference from the person's list of
memberships.
@i{Example:}
@reqexample
@example
1 46 5 0 100 0
@t{=1 2 @{ 44 14 19 10 5 96 1 161 1 1 0 0 0 *
......@@ -4091,7 +4100,7 @@ being deleted automatically and removes such protection from the old
presentation. In lyskomd this is implemented by increasing the mark
count on presentation texts.
@i{Example:}
@reqexample
@example
1 50 6
@t{=1 11HDavid Byers 1001
......@@ -4158,7 +4167,7 @@ message. To remove an old message without setting a new one, use a
automatic deletion and removes such protection from the old message just
as @reqlink{set-presentation}.
@i{Example:}
@reqexample
@example
1 50 6
@t{=1 11HDavid Byers 1001
......@@ -4218,7 +4227,7 @@ conference. The result is that all members of the conference
@rarg{admin} become supervisors of the conference @rarg{conf-no}.
Typically, but not always, @rarg{admin} will be a mailbox.
@i{Example:}
@reqexample
@example
1 50 4
@t{=1 17HNyheter om LysKOM 0000
......@@ -4283,7 +4292,7 @@ the conference. When a person tries to submit an article but does not
have the right to do so, the client is expected to send the article to
the super-conference instead.
@i{Example:}
@reqexample
@example
1 50 4
@t{=1 17HNyheter om LysKOM 0000
......@@ -4342,7 +4351,7 @@ Makes the conference @rarg{super-conf} the super-conference of the
conference @rarg{conf-no}. When an article is submitted to a conference
that does not accept it, it is sent to the super-conference instead.
@i{Example:}
@reqexample
@example
@end example
......@@ -4383,6 +4392,7 @@ Before protocol version 8, @rarg{type} could only be four bits. Starting
with protocol version 8, either a four-bit conference type or an
@type{Extended-Conf-Type} is allowed.
@reqexample
@example
1 78 4
@t{=1 17HNyheter om LysKOM 00001000 1 77}
......@@ -4437,6 +4447,7 @@ Sets the expiration time for articles in conference @rarg{conf-no} to
time of each conference it is sent to may be deleted by the LysKOM
server unless it has marks.
@reqexample
@example
1 78 4
@t{=1 17HNyheter om LysKOM 00000000 1 77}
......@@ -4477,6 +4488,7 @@ Not enough permissions to change the expiration time for conference
This call returns the list of marks the current user has set.
@reqexample
@example
1 23
@t{=1 3 @{ 13020 100 13043 95 12213 95 @}}
......@@ -4553,6 +4565,7 @@ using @reqlink{get-text-stat}. It is also permitted to request a character
position beyond the actual end of the text, in which case as much text
as is available will be returned.
@reqexample
@example
1 25 100 0 32766
@t{=1 25HYawn^JNothing is happening}
......@@ -4607,6 +4620,7 @@ either be removed or converted to a similar one. Specifically,
or omitted entirely.
@reqexample
@example
1 26 100
@t{=1 7 35 16 15 6 96 1 196 1 14 1 22 1
......@@ -4649,6 +4663,7 @@ Marks text @rarg{text} in conference number @rarg{conference} as read
for the current user. This call updates the membership record for the
user.
@reqexample
@example
1 9 6 7
@t{=1 20 32 11 17 6 96 3 198 1 7 1 240 0 *}
......@@ -4726,6 +4741,7 @@ The only Misc-Info items valid for this call are @misc{recpt},
@misc{cc-recpt}, @misc{bcc-recpt} (protocol version 10),
@misc{comm-to} and @misc{footn-to}.
@reqexample
@example
1 28 20HExample\nMessage body 3 @{ 0 5 1 112 2 33467 @}
@t{:16 0 33502 13 16 15 16 6 97 3 196 1 119 1 20 0}
......@@ -4788,6 +4804,7 @@ an unknown misc item in the misc-info list.
Deletes the text @rarg{text} from the LysKOM database, if the person
issuing the command may do so.
@reqexample
@example
1 29 33467
@t{=1}
......@@ -4835,6 +4852,7 @@ Since protocol version 10 the @rarg{recpt-type} parameter is a
argument was a @type{BOOL}, that indicated if the recipient should be
a @misc{cc-recpt} (when true) or @misc{recpt} (when false).
@reqexample
@example
1 26 1
@t{=1 2 22 12 17 6 97 4 197 1 5 4 256 1 0 *}
......@@ -4910,6 +4928,7 @@ Removes @rarg{conf-no} from the list of recipients of text
by the supervisor of the recipients of the text or by the supervisor of
the author.
@reqexample
@example
1 26 1
@t{=1 2 22 12 17 6 97 4 197 1 5 4 256 1}
......@@ -4968,6 +4987,7 @@ has been created. The normal procedure for creating comments is to add a
@misc{comm-to} element to the text's misc-info list when the text is
created (@pxref{The Misc-Info List}).
@reqexample
@example
1 26 1
@t{=1 2 22 12 17 6 97 4 197 1 5 4 256 1 0 *}
......@@ -5016,6 +5036,7 @@ The text @rarg{comment-to} already has the maximum number of comments.
This call removes the text @rarg{text-no} from @rarg{comment-to}'s list
of comments.
@reqexample
@example
1 26 1
@t{=1 2 22 12 17 6 97 4 197 1 5 4 256 1 1 @{ 3 2 @}}
......@@ -5101,6 +5122,7 @@ If no texts at all exists in @rarg{conf-no} the resulting array will be
empty, and @rarg{first-local-no} will be set to the number the next text
to be created will receive.
@reqexample
@example
1 34 119 10 5
@t{=1 10 5 @{ 0 0 466 478 391 @}}
......@@ -5165,6 +5187,7 @@ ever has existed in this conference.
This call simply returns the local time according to the server.
@reqexample
@example
1 35
@t{=1 23 47 19 17 6 97 4 197 1}
......@@ -5199,6 +5222,7 @@ This call has been superceded by @reqlink{get-info}.
This call can be issued without logging in.
@reqexample
@example
1 36
@t{=1 10900 1 2 3 4 1}
......@@ -5234,6 +5258,7 @@ Add a footnote link between the text @rarg{footnote-to} and the text
has been created. Only the author of both texts is allowed to add
the footnote link.
@reqexample
@example
1 26 1
@t{=1 2 22 12 17 6 97 4 197 1 5 4 256 1 0 *}
......@@ -5284,6 +5309,7 @@ Text @rarg{text-no} is already a footnote to @rarg{footnote-to}.
This call removes the text @rarg{text-no} from @rarg{footnote-to}'s list
of footnotes. Only the author of a footnote may remove it.
@reqexample
@example
1 26 1
@t{=1 2 22 12 17 6 97 4 197 1 5 4 256 1 1 @{ 5 2 @}}
......@@ -5365,6 +5391,7 @@ better implemented using the @reqdlink{set-last-read} call@linkhere{}
which explicitly sets the @field{last-text-read} field of the
membership.
@reqexample
@example
1 9 5 6
@t{=1 1 34 21 17 6 97 4 197 1 6 100 0 0 *}
......@@ -5407,6 +5434,7 @@ privileged person, with the proper privileges enabled. A somewhat less
convenient way of doing this is to use the @reqdlink{set-info}
call@linkhere{}.
@reqexample
@example
1 36
@t{=1 10900 1 2 3 4 0}
......@@ -5449,6 +5477,7 @@ that make any sense right now are 0 and 255. This call may be issued
by any person, but without the right privilege bits set, it has no
effect.
@reqexample
@example
1 41 1
@t{%1 12 0}
......@@ -5483,6 +5512,7 @@ its database is current. Processing of requests is normally blocked
until this call has completed, but the exact details depend on the
server implementation. This call is privileged in most implementations.
@reqexample
@example
1 42 255
@t{=1}
......@@ -5519,6 +5549,7 @@ Administrator bit not set or privileges not enabled.
This call instructs the server to save all data and shut down.
@rarg{exit-val} is currently not used. This call is privileged.
@reqexample
@example
1 42 255
@t{=1}
......@@ -5595,6 +5626,7 @@ if the passive bit in the membership record has been set (either by a
set-membership-type or by setting the priority of the conference to
zero.)
@reqexample
@example
1 46 5 0 3 1
@t{=1 2 @{ 49 14 17 13 8 91 5 255 1 5 255 0 0 * }
......@@ -5665,6 +5697,7 @@ difference was not intentional, but it is now too late to change the
semantics of either @req{get-map} or @req{get-created-texts}.
Besides, they are both obsolete calls.})
@reqexample
@example
1 47 5 0 100
@t{=1 1 8 @{ 1 2 3 4 5 6 7 8 @}}
......@@ -5718,6 +5751,7 @@ This call returns a list of members of the conference @rarg{conf}.
from zero and up. @rarg{no-of-members} is the maximum number of members
to return.
@reqexample
@example
1 48 1 0 100
@t{=1 4 @{ 7 8 9 10 @}}
......@@ -5758,6 +5792,7 @@ all the information a client usually needs since the name is not
included in the Person data structure. Use @reqlink{get-conf-stat} on the
same number to get additional information about the person.
@reqexample
@example
1 49 8
@t{=1 44Hbyers@@lage.lysator.liu.se 0000010000000000 00000000}
......@@ -5800,6 +5835,7 @@ handle @type{Conference} structures with an arbitrary number of flag
bits since we may decide to change the behavior of this call in the
future.
@reqexample
@example
1 50 1
@ifnottex
......@@ -5871,6 +5907,7 @@ Passive memberships are never returned.
The returned conference numbers will be returned in the same order as
they appear on the persons list of memberships.
@reqexample
@example
1 52 7
@t{=1 2 @{ 1 6 @}}
......@@ -5912,6 +5949,7 @@ This call sends the message @rarg{message} to all members of
@rarg{recipient} that are currently logged in. If @rarg{recipient} is
0, the message is sent to all sessions that are logged in.
@reqexample
@example
1 53 4 14HThis is a test
@t{=1}
......@@ -5988,6 +6026,7 @@ Session number zero is always interpreted as the session making the
call, so the easiest way to disconnect the current session is to
disconnect session zero.
@reqexample
@example
1 56
@t{=1 7}
......@@ -6031,6 +6070,7 @@ The session @rarg{session-no} does not exist.
This call simply returns the session number of the session issuing the
call.
@reqexample
@example
1 56
@t{=1 7}
......@@ -6060,6 +6100,7 @@ database to the text @rarg{user-area}. The user area is used to store
client data for a particular person. @xref{The User Area}, for more
details.
@reqexample
@example
1 49 7
@t{=1 43Hdavby@@lage.lysator.liu.se 0000010000000000 00000000}
......@@ -6108,6 +6149,7 @@ of the server may also have been adjusted manually from time to time.
This protocol specification does not mandate what the server should do
in such cases.
@reqexample
@example
1 58 49 6 22 19 6 97 6 199 1
@t{=1 11}
......@@ -6155,6 +6197,7 @@ The only Misc-Info items valid for this call in the @rarg{misc-info}
array are @misc{recpt}, @misc{cc-recpt}, @misc{bcc-recpt} (introducted
in protocol version 10), @misc{comm-to} and @misc{footn-to}.
@reqexample
@example
1 28 20HExample\nMessage body 3 @{ 0 5 1 112 2 33467 @}
@t{:16 0 33502 13 16 15 16 6 97 3 196 1 0 1 20 0}
......@@ -6218,6 +6261,7 @@ This call returns the next readable text in the database created after
text @rarg{start}. @rarg{start} does not have to be a valid or readable
text number, as shown in the examples.
@reqexample
@example
1 60 0
@t{=1 2}
......@@ -6251,6 +6295,7 @@ This call returns the first readable text in the database created most
recently before @rarg{start}. @rarg{start} does not have to be a valid
or readable text number, as shown in the examples.
@reqexample
@example
1 61 134217727
@t{=1 11}
......@@ -6293,6 +6338,7 @@ will have the invisible flag set.
Invisible sessions are primarily used by software agents that do not act
on the behalf of real users.
@reqexample
@example
1 62 7 6Hgazonk 1
@t{=1}
......@@ -6489,6 +6535,7 @@ The following names are currently registered:
@end multitable
@reqexample
@example
1 56
@t{=1 7}
......@@ -6593,6 +6640,7 @@ Currently, servers do not associate any particular meaning to the
different types of marks, but that may change in the future. Currently,
servers should not delete texts that have marks, except by user request.
@reqexample
@example
1 23
@t{=1 0 *}
......@@ -6635,6 +6683,7 @@ Already the maximum number of marks on text @rarg{text}.
This call removes any marks the logged-in person has set on the text
@rarg{text-no}.
@reqexample
@example
1 23
@t{=1 1 @{ 110 230 @}}
......@@ -6681,6 +6730,7 @@ See also @ref{lookup-z-name}, for an alternative way to look up names.
Refer to @ref{Name Expansion}, for more details on how name lookup
works.
@reqexample
@example
1 74 2H.* 1 1
@t{=1 4 @{ 15HTest Conference 0000 10 11HDavid Byers 1001 6}
......@@ -6725,6 +6775,7 @@ returned by this call are primarily useful for presenting to the user. A
client should not use this call to determine what the server's
capabilities are.
@reqexample
@example
1 75
@t{=1 9 7Hlyskomd 5H1.9.0}
......@@ -6760,6 +6811,7 @@ See also @ref{re-z-lookup}, for an alternative way to look up names.
Refer to @ref{Name Expansion}, for details on the matching process.
@reqexample
@example
1 76 0H 1 1
@t{=1 4 @{ 15HTest Conference 0000 10 11HDavid Byers 1001 6}
......@@ -6798,6 +6850,7 @@ issuing the call has read in conference @rarg{conference} is
@rarg{last-read}. This call is typically used when a user wants to have
a specific number of unread texts in a particular conference.
@reqexample
@example
1 9 7 6
@t{=1 2 4 22 18 6 97 5 198 1 6 100 6 0 *}
......@@ -6845,6 +6898,7 @@ objects in memory, so this call is significantly faster than
This is also currently the only way to get all the flag bits of the
conference.
@reqexample
@example
1 50 6
@t{=1 8HTestconf 0000 1 34 21 17 6 97 4 197 1}
......@@ -6888,7 +6942,7 @@ This call sets the server information retrieved by
ignored (but must be present); all other fields are stored permanently
in the LysKOM database. This is a privileged call.
@i{Example:}
@reqexample
@example
1 79 10901 1 2 3 4 1080
@t{=1}
......@@ -6945,7 +6999,7 @@ requested asynchronous messages may be retrieved using the
Don't forget that message type 12 is personal, group and global
text messages. Most users will not want these turned off.
@i{Example:}
@reqexample
@example
1 80 2 @{ 7 9 @}
@t{=1}
......@@ -6999,7 +7053,7 @@ messages that are not listed in the result of this call. Even though
those messages are turned off, the server may decide to send them under
certain circumstances.
@i{Example:}
@reqexample
@example
1 81
@t{=1 7 @{ 0 5 7 9 11 12 13 @}}
......@@ -7608,7 +7662,7 @@ and @rarg{conference} is the conference in question.
Calling @req{query-read-texts} does not require the session to be logged in.
@i{Example:}
@reqexample
@example
1 98 6 1
@t{=1 32 5 11 12 7 93 1 193 1 1 20 133}
......@@ -7670,6 +7724,7 @@ member list that the person requesting the list does not have sufficient
privileges to see may be cleared. Cleared elements simply have all
fields set to zero.
@reqexample
@example
1 99 5 0 3 1
@t{=1 2 @{ 49 14 17 13 8 91 5 255 1 5 255 0 0 * 5 00000000}
......@@ -7732,6 +7787,7 @@ member of the conference. The person doing this must either be a
supervisor of the affected person, or have sufficient privileges
enabled.
@reqexample
@example
1 99 119 0 10 0
@t{=1 1 @{ 49 14 17 13 8 91 5 255 1 119 255 0 0 * 119 00001111 @}}
......@@ -7802,6 +7858,7 @@ Some of the elements of the result may be cleared if the person
requesting the information does not have sufficient privileges to see
the contents. Cleared elements simply have all fields set to zero.
@reqexample
@example
1 101 1 0 100
@t{=1 4 @{ 7 7 00000000 8 8 00000000 9 8 00000000 }
......@@ -7898,6 +7955,7 @@ texts the client wants information about. Legal values for
The server will return a sparse or dense Text-Mapping depending on the
how many deleted texts there are after @rarg{first-local-no}.
@reqexample
@example
1 103 93 1 5
@t{=1 1 7 1 1 1 6 @{ 1003 1005 1009 1029 0 1034 @}}
......
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