Basic member file documentation.

doc/formats.md

@@ -58,8 +58,6 @@ Processed source is scanned for known keys. Known keys are:
 * mail
 * phone
 * born
-* joined
-* destroyed
 
 Multiple instances of single key are considered an error.
 
@@ -68,6 +66,8 @@ Unknown keys are considered a warning.
 Valid multikeys are converted to single key with list of values and
 line numbers as the value for such key. Multikeys are:
 
+* joined
+* destroyed
 * card
 * desfire
 * credit
@@ -75,6 +75,14 @@ line numbers as the value for such key. Multikeys are:
 * studentstop
 * suspendstart
 * suspendstop
+* chairstart
+* chairstop
+* councilstart
+* councilstop
+* revisionstart
+* revisionstop
+* grantstart
+* grantstop
 
 The result is a valid dictionary of keys and multikeys.
 
@@ -85,8 +93,8 @@ After getting a valid dictionary from the 2nd pass, the data gets interpreted.
 
 ### Pass Markers
 
-All start/stop (student and suspend at the moment) markers are joined
+All start/stop markers are joined into lists of markers, retaining
-into lists of markers, retaining source position information.
+source position information.
 
 ### Info
 

doc/hackerbase.1

@@ -260,6 +260,124 @@ transaction file.
 
 .SS Member Files
 
+Before parsing the configuration file all comments are removed. The
+comments start with the \fB#\fR character and continue until the end
+of the line.
+
+All empty lines and lines containing only whitespace charecters are
+removed.
+
+Remaining lines are parsed as follows - leading whitespace is stripped
+and first token comprised of non-whitespace characters is taken as
+configuration key. The remainder of the line without leading
+whitespace is then taken as given configuration option value.
+
+This pre-processed source is scanned for mandatory known single-keys:
+
+.RS
+.IP \[bu] 2
+nick - member username (nickname)
+.IP \[bu]
+name - first name and surname
+.IP \[bu]
+mail - valid email which is used for contacting this member
+.IP \[bu]
+phone - either a valid phone number or information that member does
+not have a registered phone
+.RE
+
+.P
+The following single-keys are optional:
+
+.RS
+.IP \[bu] 2
+born - year, month or exact birth date
+.RE
+
+.P
+The following generic keys can be present multiple times:
+
+.RS
+.IP \[bu] 2
+card - RFID card id (non-desfire) for physical access to the space
+.IP \[bu]
+desfire - RFID desfire card id for physical access to the space
+.IP \[bu]
+credit - amount added to this member balance with month or exact date
+of credit and optional reason for this credit record
+.RE
+
+.P
+These multi-keys are converted to keys where value is a list of all
+values collected for given key.
+
+.P
+The following period start/stop keys can be present multiple times as
+well:
+
+.RS
+.IP \[bu] 2
+joined - month or exact date of membership start
+.IP \[bu]
+destroyed - month or exact date right after membership end
+.IP \[bu]
+studentstart - month or exact date of student status start
+.IP \[bu]
+studentstop - month or exact date right after student status end
+.IP \[bu]
+suspendstart - month or exact date when member is already considered suspended
+.IP \[bu]
+suspendstop - month or exact date when the member is no longer considered suspended
+.RE
+
+.P
+The following organizational bodies membership start/stop keys can
+also be present multiple times:
+
+.RS
+.IP \[bu] 2
+chairstart - exact date when this chair was elected
+.IP \[bu]
+chairstop - exact date of the first day when this member is no longer a chair
+.IP \[bu]
+councilstart - exact date when this council member was elected
+.IP \[bu]
+councilstop - exact date of the first day when this member is no longer a council member
+.IP \[bu]
+revisionstart - exact date when this revision committee member was elected
+.IP \[bu]
+revisionstop - exact date of the first day when this member is no longer a revision committee member
+.IP \[bu]
+grantstart - exact date when this grant committee member was elected
+.IP \[bu]
+grantstop - exact date of the first day when this member is no longer a grant committee member
+.RE
+
+.P
+All the start/stop keys are coalesced into lists of periods. If for
+given period the stop key is missing an open interval is assumed. The
+resulting keys are as follows:
+
+.RS
+.IP \[bu] 2
+member
+.IP \[bu]
+student
+.IP \[bu]
+suspend
+.IP \[bu]
+chair
+.IP \[bu]
+council
+.IP \[bu]
+revision
+.IP \[bu]
+grant
+.RE
+
+These keys with lists of periods are then used for determining member
+status at given date (which defaults to current date).
+
 .SS Bank Account Statements
 
 The CSV files with bank account statements are stored in the directory
@@ -287,23 +405,17 @@ When checking for \fB\-unpaired\fR transactions, only transactions
 with ID greater than the numeric value stored in this file are
 considered.
 
+No comments, whitespace, or any other content is allowed in this file.
+
 .SH "CONFIGURATION"
 
 The default path with the initial hackerbase configuration is stored
 in "/etc/hackerbase" but this can be overriden by \fB\-config\fR
 command-line option.
 
-Before parsing the configuration file all comments are removed. The
+The basic parsing is the same as with \fBMember Files\fR. But after
-comments start with the \fB#\fR character and continue until the end
+getting a list of pairs of keys with values, no further processing is
-of the line.
+performed.
-
-All empty lines and lines containing only whitespace charecters are
-removed.
-
-Remaining lines are parsed as follows - leading whitespace is stripped
-and first token comprised of non-whitespace characters is taken as
-configuration key. The remainder of the line without leading
-whitespace is then taken as given configuration option value.
 
 A sample configuration for Brmlab installation in "/etc/hackerbase"
 is: