empire/empserver
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

Minor xdump documentation edit

Browse source
This commit is contained in:
Markus Armbruster 2008-03-04 21:38:59 +01:00
parent 4c746b5e73
commit 5ef6559c6a
1 changed files with 13 additions and 12 deletions
Download patch file Download diff file Expand all files Collapse all files

25
doc/xdump
View file

@ -171,9 +171,10 @@ precisely specified. We use EBNF (ISO 14977) for syntax, except we
use '-' in meta-identifiers and omit the concatenation symbol ','. use '-' in meta-identifiers and omit the concatenation symbol ','.
table = header { record } footer ; table = header { record } footer ;
header = "XDUMP" space [ "meta" space ] name space timestamp newline ; header = "XDUMP" space [ "meta" space ]
name = name-chr { name-chr } ; identifier space timestamp newline ;
name-chr = ? ASCII characters 33..126 ? ; identifier = id-chr { id-chr } ;
id-char = ? ASCII characters 33..126 except '"#()<>=' ? ;
timestamp = intnum ; timestamp = intnum ;
footer = "/" number newline ; footer = "/" number newline ;
record = [ fields ] newline ; record = [ fields ] newline ;
@ -208,7 +209,7 @@ Notes:
Semantics: Semantics:
* The table name in the header is one of the names in xdump table. * The table identifier in the header is one of the names in xdump table.
* The timestamp increases monotonically. It has a noticeable * The timestamp increases monotonically. It has a noticeable
granularity: game state may change between an xdump and the next granularity: game state may change between an xdump and the next
@ -520,7 +521,7 @@ EBNF changes:
* Header and footer: * Header and footer:
header = "config" name newline colhdr newline ; header = "config" identifier newline colhdr newline ;
colhdr = { identifier [ "(" ( intnum | identifier ) ")" ] } [ "..." ] ; colhdr = { identifier [ "(" ( intnum | identifier ) ")" ] } [ "..." ] ;
footer = "/config" newline ; footer = "/config" newline ;
@ -538,7 +539,7 @@ EBNF changes:
update. update.
- The column header is due to the self-containedness requirement. - The column header is due to the self-containedness requirement.
It contains just the essential bit of meta-data: the column name. It contains just the essential bit of meta-data: the column names.
* Symbolic fields: * Symbolic fields:
@ -658,7 +659,7 @@ and section `Objectives':
enemy ships, nations). enemy ships, nations).
(4) Bandwidth will be minimized (i.e. the format will be as (4) Bandwidth will be minimized (i.e. the format will be as
concise as possible) while remaining human readable (i.e. no concise as possible) while remaining human-readable (i.e. no
binary messages). [Note that data compression may be added at a later binary messages). [Note that data compression may be added at a later
date, but if it is added, it will be added on a separate port to date, but if it is added, it will be added on a separate port to
maintain backwards compatability.] maintain backwards compatability.]
@ -731,14 +732,14 @@ f. The data to sync is not readily available the server.
limited view on certain parts of server game state on certain limited view on certain parts of server game state on certain
events. events.
To be complete, a machine readable protocol must disclose as much To be complete, a machine-readable protocol must disclose as much
information as the human readable output. Tracking server game information as the human-readable output. Tracking server game
state changes cannot do that alone. For instance, lookout tells state changes cannot do that alone. For instance, lookout tells
you ship#, owner and location. That event does not trigger any you ship#, owner and location. That event does not trigger any
state change on the server! state change on the server!
To be correct, a machine readable protocol must disclose no more To be correct, a machine-readable protocol must disclose no more
information than the human readable output. When you observe a information than the human-readable output. When you observe a
server game state change, you can only guess what event triggered server game state change, you can only guess what event triggered
it, and what it disclosed to which player. You're stuck with it, and what it disclosed to which player. You're stuck with
conservative assumptions. That's the death knell for completeness. conservative assumptions. That's the death knell for completeness.
@ -757,7 +758,7 @@ a shortcut, and it didn't work. That doesn't mean there's no way at
all. I believe the only way to get this done right is by tracking all. I believe the only way to get this done right is by tracking
*events*. Whenever something is printed to a player, be it live *events*. Whenever something is printed to a player, be it live
connection or telegram, we need to transmit precisely the same connection or telegram, we need to transmit precisely the same
information in machine readable form. Much more work. information in machine-readable form. Much more work.
xdump shares valuable ideas with C_SYNC, e.g. using selector xdump shares valuable ideas with C_SYNC, e.g. using selector
meta-data. It is, however, much more modest in scope. We're pretty meta-data. It is, however, much more modest in scope. We're pretty