Commit 4c3ca617 authored by Per Cederqvist's avatar Per Cederqvist
Browse files

(Extracted grammar): New appendix that discusses the extracted files.

parent d571771f
......@@ -406,6 +406,7 @@ The most up-to-date version if this document can always be found at
* The User Area:: Store client-specific settings in the server.
* Membership visibility:: How the security features interacts.
* Measured Properties:: Load average, number of processed requests...
* Extracted grammar:: If you want to generate code, read this.
* Writing Clients:: A few tips for client writers.
* Importing and Exporting E-Mail:: A few thoughts on e-mail integration.
* Some Client-specific Aux-Item Types:: Informative info about more aux-items.
......@@ -10554,6 +10555,74 @@ The number of bytes waiting in the send and receive queues.
@end table
@node Extracted grammar
@appendix Extracted grammars (informative)
The file @file{Protocol-A.texi} is the authoritative standard for
protocol A. However, it has a two problems:
@itemize @bullet
@item The Texinfo markup makes it hard for a program to extract
information--and once a program is written, we might change the
Texinfo markup, so that the program has to be updated.
@item We often rename requests and data types, in order to have good
names for the most recommended functions and types. However, a
program that uses a datatypemight fail if that type suddenly is
altered.
@end itemize
To overcome these problems, and better server client writers that want
to generate the protocol-level code automatically from the
specification, a few variants of the grammar is available as separate
files. In some of these files, the names have been changed to
@dfn{stable} names that will not change as the protocol evolves.
Currently, these three grammars exists:
@table @file
@item protocol-a-full.txt
The full Protocol A specification, with stable names.
@item protocol-a-recommended.txt
The recommended requests and asynchronous messages, and all types they
need, with stable names.
@item protocol-a-current.txt
The recommended requests and asynchronous messages, with the names
used in this specification.
@end table
@c FIXME: I still awaiting a go-ahead from some authors of this
@c document regarding the license. For now, it is restrictive.
@c
@c These generated files are in the public domain, so you are free to use
@c them any way you like.
The files are generated by @file{doc/checkargs.py} in the
lyskom-server distribution. Adding more output formats is fairly
easy. Let us know, preferably via Bugzilla, if a new output format
would be useful for you. It is the intention that the format of the
above-mentioned files will not change. The file format should be
self-explanatory once you have read the protocol specification. It
does contain some comments that should be useful.
The stable names are generated by this process:
@itemize @bullet
@item Don't modify builtin types such as @type{INT32}.
@item Remove the suffixes @samp{-old}, @samp{-older} and @samp{-Old},
unless that would introduce an ambiguity.
@item Unless the name already has a version suffix, add one.
@end itemize
All files mentioned above are reachable via
@uref{http://www.lysator.liu.se/lyskom/protocol/}.
@node Writing Clients
@appendix Writing Clients (informative)
......
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