Mike Gerwitz

Activist for User Freedom

aboutsummaryrefslogtreecommitdiffstats
path: root/doc
diff options
context:
space:
mode:
authorMike Gerwitz <gerwitzm@lovullo.com>2017-06-20 10:29:52 -0400
committerMike Gerwitz <gerwitzm@lovullo.com>2017-06-21 10:52:46 -0400
commitd2dd9636146e98b3813ca1bc84488ca951fdea22 (patch)
tree1593a7a6fd2c0c8a980830cb5c9e87a43677d547 /doc
parenta1d5e7d3c5a7fb51acd61be98deccbd574e5f300 (diff)
downloadliza-d2dd9636146e98b3813ca1bc84488ca951fdea22.tar.gz
liza-d2dd9636146e98b3813ca1bc84488ca951fdea22.tar.bz2
liza-d2dd9636146e98b3813ca1bc84488ca951fdea22.zip
doc: Extract design sections into own chapters
* assert.texi, bucket.texi, client.texi, pred.texi, program.texi, validation.texi: New files. * design.texi: Extract text into above. * liza.texi: Add @menu references and @include each new file.
Diffstat (limited to 'doc')
-rw-r--r--doc/Makefile.am4
-rw-r--r--doc/assert.texi29
-rw-r--r--doc/bucket.texi23
-rw-r--r--doc/client.texi98
-rw-r--r--doc/design.texi439
-rw-r--r--doc/liza.texi12
-rw-r--r--doc/pred.texi74
-rw-r--r--doc/program.texi222
-rw-r--r--doc/validation.texi25
9 files changed, 487 insertions, 439 deletions
diff --git a/doc/Makefile.am b/doc/Makefile.am
index ccbd36a..2e84fc2 100644
--- a/doc/Makefile.am
+++ b/doc/Makefile.am
@@ -21,7 +21,9 @@
MAKEINFOHTML = $(MAKEINFO) --html --css-include liza.css
info_TEXINFOS = liza.texi
-liza_TEXINFOS = design.texi macros.texi config.texi liza.css \
+liza_TEXINFOS = macros.texi config.texi liza.css \
+ design.texi assert.texi bucket.texi client.texi \
+ pred.texi program.texi validation.texi \
diagram/event-graph.svg
diagram/%.svg: diagram/%.dot
diff --git a/doc/assert.texi b/doc/assert.texi
new file mode 100644
index 0000000..ce16ce9
--- /dev/null
+++ b/doc/assert.texi
@@ -0,0 +1,29 @@
+@c This document is part of the Liza Data Collection Framework manual.
+@c Copyright (C) 2017 R-T Specialty, LLC.
+@c
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3
+@c or any later version published by the Free Software Foundation;
+@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+@c Texts. A copy of the license is included in the section entitled ``GNU
+@c Free Documentation License''.
+
+@node Assertions
+@chapter Assertions
+@maintstart
+@footnote{
+ Assertions are compiled from the Program XML (@pxref{Program XML}).
+ Rather than using a library,
+ it compiles a mess of largely duplicate code inline.
+ This system needs to be @emph{replaced},
+ not modified.
+
+ A replacement can either be in the form of a library (removing most
+ if not all code generation from the Program XML compiler),
+ or possibly compile into classifications and use the classification
+ system.
+ @emph{The latter option is preferred,
+ and would be more powerful with less maintenance.}}
+@maintend
+
+@helpwanted
diff --git a/doc/bucket.texi b/doc/bucket.texi
new file mode 100644
index 0000000..2e844c2
--- /dev/null
+++ b/doc/bucket.texi
@@ -0,0 +1,23 @@
+@c This document is part of the Liza Data Collection Framework manual.
+@c Copyright (C) 2017 R-T Specialty, LLC.
+@c
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3
+@c or any later version published by the Free Software Foundation;
+@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+@c Texts. A copy of the license is included in the section entitled ``GNU
+@c Free Documentation License''.
+
+@node Bucket
+@chapter Bucket
+@helpwanted
+
+@menu
+* Value Assignment:Bucket Assignment. Writing data to the Bucket.
+@end menu
+
+
+@c TODO
+@node Bucket Assignment
+@section Bucket Value Assignment
+@helpwanted
diff --git a/doc/client.texi b/doc/client.texi
new file mode 100644
index 0000000..8955264
--- /dev/null
+++ b/doc/client.texi
@@ -0,0 +1,98 @@
+@c This document is part of the Liza Data Collection Framework manual.
+@c Copyright (C) 2017 R-T Specialty, LLC.
+@c
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3
+@c or any later version published by the Free Software Foundation;
+@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+@c Texts. A copy of the license is included in the section entitled ``GNU
+@c Free Documentation License''.
+
+@node Client
+@chapter Client
+@maintstart
+@footnote{
+ The client is largely managed by a single class,
+ @srcref{src/client/Client.js, Client},
+ which has grown out of control.
+ @code{Client} mediates essentially the entire system.
+ Code is to be extracted out of this class as it is touched.
+
+ The other system mammoth is @code{Ui} (@pxref{Program UI}).}
+@maintend
+
+@helpwanted
+
+@menu
+* Error Handling::
+@end menu
+
+
+@node Error Handling
+@section Error Handling
+
+@maintenance{
+ The complexity of this system and integration into legacy
+ layers has caused maintenance trouble in the past.
+ Each of the error checking layers need to be integrated
+ to reduce complexity.}
+
+@cindex Error
+@cindex Failure
+There are three layers of error checking:@footnote{
+ Primarily for legacy reasons.
+ They are being consolodated as the system is touched.}
+
+@enumerate
+ @item Required field checking@mdash{
+ }whether all required questions have been answered.
+ @item Type Validation@mdash{
+ }verify that questions contain valid data according to their
+ declared type. @ref{Validation}.
+ @item Assertions@mdash{
+ }arbitrary checks on data.
+ @ref{Assertions}.
+@end enumerate
+
+@cindex Required Field
+@cindex Field, Required
+@cindex Field, Fixed
+@cindex Error, Fixed
+@cindex Error, Required
+@cindex Fixed, Error
+Required fields fail serially@mdash{
+ }the system will notify the user of the required field,
+ and direct him/her to it (usually through scrolling).
+A field is marked as @dfn{fixed} according to the rules
+ in @ref{Managing Error State}.
+
+
+@menu
+* Managing Error State:: Determining when failures should be marked as ``fixed''
+@end menu
+
+
+@node Managing Error State
+@subsection Managing Error State
+
+@cindex Failure Stack
+@cindex Error Stack
+Each failure caused by assertions is associated with a
+ @dfn{failure stack}.
+The stack represents the trail of assertions that have run,
+ containing the ids of all values asserted against.
+When any field or classification changes that is represented on the
+ failure stack,
+ the failure for the failed field associated with that failure stack
+ is cleared.
+
+@exnotice{
+ If an assertion for some question @var{foo} first checked the value
+ of bucket field @var{bar},
+ and within its failure checked the value @var{c:predicate},
+ the failure stack would contain both of those ids.
+ If either @var{bar} or the @var{predicate} classification changed,
+ the question @var{foo} would have its error cleared.}
+
+Error state is managed by
+ @srcref{src/validate/ValidStateMonitor.js, ValidStateMonitor}.
diff --git a/doc/design.texi b/doc/design.texi
index 7bde80d..c054464 100644
--- a/doc/design.texi
+++ b/doc/design.texi
@@ -102,441 +102,4 @@ The main components of the system are:
@xref{Validation}.
@end table
-More information about each can be found in their respective section.
-
-
-@menu
-* Assertions::
-* Bucket::
-* Client::
-* Predicate System::
-* Program::
-* Program UI::
-* Program XML::
-* Validation::
-@end menu
-
-
-
-@node Assertions
-@section Assertions
-@maintstart
-@footnote{
- Assertions are compiled from the Program XML (@pxref{Program XML}).
- Rather than using a library,
- it compiles a mess of largely duplicate code inline.
- This system needs to be @emph{replaced},
- not modified.
-
- A replacement can either be in the form of a library (removing most
- if not all code generation from the Program XML compiler),
- or possibly compile into classifications and use the classification
- system.
- @emph{The latter option is preferred,
- and would be more powerful with less maintenance.}}
-@maintend
-
-@helpwanted
-
-
-
-@node Bucket
-@section Bucket
-@helpwanted
-
-@menu
-* Value Assignment:Bucket Assignment. Writing data to the Bucket.
-@end menu
-
-
-@c TODO
-@node Bucket Assignment
-@subsection Bucket Value Assignment
-@helpwanted
-
-
-
-@node Client
-@section Client
-@maintstart
-@footnote{
- The client is largely managed by a single class,
- @srcref{src/client/Client.js, Client},
- which has grown out of control.
- @code{Client} mediates essentially the entire system.
- Code is to be extracted out of this class as it is touched.
-
- The other system mammoth is @code{Ui} (@pxref{Program UI}).}
-@maintend
-
-@helpwanted
-
-@menu
-* Error Handling::
-@end menu
-
-
-@node Error Handling
-@subsection Error Handling
-
-@maintenance{
- The complexity of this system and integration into legacy
- layers has caused maintenance trouble in the past.
- Each of the error checking layers need to be integrated
- to reduce complexity.}
-
-@cindex Error
-@cindex Failure
-There are three layers of error checking:@footnote{
- Primarily for legacy reasons.
- They are being consolodated as the system is touched.}
-
-@enumerate
- @item Required field checking@mdash{
- }whether all required questions have been answered.
- @item Type Validation@mdash{
- }verify that questions contain valid data according to their
- declared type. @ref{Validation}.
- @item Assertions@mdash{
- }arbitrary checks on data.
- @ref{Assertions}.
-@end enumerate
-
-@cindex Required Field
-@cindex Field, Required
-@cindex Field, Fixed
-@cindex Error, Fixed
-@cindex Error, Required
-@cindex Fixed, Error
-Required fields fail serially@mdash{
- }the system will notify the user of the required field,
- and direct him/her to it (usually through scrolling).
-A field is marked as @dfn{fixed} according to the rules
- in @ref{Managing Error State}.
-
-
-@menu
-* Managing Error State:: Determining when failures should be marked as ``fixed''
-@end menu
-
-
-@node Managing Error State
-@subsubsection Managing Error State
-
-@cindex Failure Stack
-@cindex Error Stack
-Each failure caused by assertions is associated with a
- @dfn{failure stack}.
-The stack represents the trail of assertions that have run,
- containing the ids of all values asserted against.
-When any field or classification changes that is represented on the
- failure stack,
- the failure for the failed field associated with that failure stack
- is cleared.
-
-@exnotice{
- If an assertion for some question @var{foo} first checked the value
- of bucket field @var{bar},
- and within its failure checked the value @var{c:predicate},
- the failure stack would contain both of those ids.
- If either @var{bar} or the @var{predicate} classification changed,
- the question @var{foo} would have its error cleared.}
-
-Error state is managed by
- @srcref{src/validate/ValidStateMonitor.js, ValidStateMonitor}.
-
-
-
-@node Predicate System
-@section Predicate System
-@maintstart
-@footnote{
- New programs (using the old incarnation of TAME) use the classifier
- embedded into the rater by TAME.
- Old ones, however, still use the @dfn{Global Classifier}.
- This system isn't as well tested as TAME's@mdash{
- }which needs to work properly for the sake of calculating premium@mdash{
- }and has suffered from a number of bugs in the past.
-
- The solution is to migrate all programs to TAME and remove that old
- code.}
-@maintend
-
-@tip{
- For a practical application of these concepts, see its use in the
- Program@tie{}XML (@pxref{Specifying Predicates}).}
-
-@cindex Predicate
-@cindex Classifier
-@cindex Applicability
-@cindex Domain of discourse, Predicate
-The @dfn{predicate system} determines the @dfn{applicability} of
- certain objects (like questions and assertions) by associating them
- with predicates.
-The domain of discourse (variables which may be quantified) is listed
- in @ref{t:predicate-dod}.
-
-What it means for some object to be applicable depends on the context.
-
-@float Table, t:predicate-dod
-@multitable @columnfractions 0.25 0.10 0.65
- @headitem Type @tab Prefix @tab Description
-
- @item Classifications
- @tab @emph{None}
- @tab Results of applying an external @dfn{classifier} to the bucket
- (@pxref{Bucket}).
-
- @item Bucket Truth Predicate
- @tab @code{q:}
- @tab
- Whether the given name in the bucket (@pxref{Bucket}) is
- non-empty and non-zero.
- The prefix @samp{q:} refers to its most common use
- case---questions (@pxref{Program UI,,Program@tie{}UI}).
-@end multitable
-@caption{Predicate system domain of discourse}
-@end float
-
-This system is limited to universal quantification over the domain of
- discourse.
-For other quantifiers and higher-order logic,
- defer to one of the systems that contributes to the domain of
- discourse,
- like the classifier.@footnote{
- This is usually TAME.
- The Program XML also supports inline classifications
- with TAME's syntax (@pxref{Specifying Predicates}).}
-
-Predicates are usually specified in the Program XML
- (@pxref{Specifying Predicates}) and compiled into the program
- (@pxref{Program}).
-
-
-
-@node Program
-@section Program
-@maintstart
-@footnote{
- The @code{Program} class was one of the first prototypes created,
- and has evolved poorly with the rest of the system.
- It is the base class for all compiled programs,
- and it glues together too many other systems with a terrible
- API and little to no encapsulation.
-
- With that said, it is one of the least touched classes (thus its
- state); developers rarely have the need to touch @code{Program}.}
-@maintend
-
-
-@cindex Program
-The @dfn{Program} is a declarative representation of an entire system.
-It is the highest level of abstraction from a data perspective.
-The user observes and interacts with a Program using the
- @ref{Program UI,,Program@tie{}UI}.
-
-@cindex Program, XML
-Programs contain a lot of metadata that is not in a convenience
- human-readable (or modifiable) format,
- some of which are redundant.
-Programs are ideally compiled from a @ref{Program XML,,Program@tie{}XML}
- document.
-
-
-
-@node Program UI
-@section Program UI
-@maintenance{
- The @code{Ui} class,
- in addition to @srcref{src/client/Client,Client} (@pxref{Client}),
- represent the two monoliths of the system.
- This mediates all UI-related tasks,
- and still has far too many concerns with far too many
- dependencies.
- Code is to be extracted out of this class as it is touched.
-}
-
-
-@cindex Program, User Interface
-@cindex User Interface, Program
-The @dfn{Program UI} renders a @ref{Program} as a form.
-
-@cindex Step
-@cindex Group
-At the highest level,
- steps are rendered in a tab-like manner,
- above the main form content.
-A step contains groups,
- which in turn contain elements such as questions.
-Groups are delimited in some manner defined by their style
- (@pxref{Group Styles}).
-
-@cindex Question
-@cindex Question, Value Formatting
-@cindex Bucket, Updating
-Questions are rendered as form fields.
-Any time the respective @ref{Bucket} field is changed,
- the form field is updated to reflect those changes,
- after having first been formatted with the appropriate validator
- (@pxref{Formatting Values}).
-When a question is changed by the user,
- the value is expected to be propagated to the Bucket
- (@pxref{Bucket Assignment}).
-
-@cindex Navigation Bar
-@cindex User Interface, Navigation Bar
-@cindex User Interface, Button Navigation
-Navigation between steps can be done via the
- @dfn{Navigation Bar} above the step@tie{}content,
- or using ``Go@tie{}Back'' and ``Continue'' buttons at the foot of the
- step@tie{}content.
-
-@cindex Sidebar
-A @dfn{Sidebar} is rendered adjacent to the step content.
-It displays the name of the Program,
- as well as configurable metadata (usually through the @samp{sidebar}
- node of the @ref{Program XML,,Program@tie{}XML}).
-It also displays question help text (also configured through the XML)
- and any error messages (@pxref{Error Handling}).
-
-@menu
-* Group Styles:: Different ways of displaying groups of questions to
- the user.
-@end menu
-
-
-@node Group Styles
-@subsection Group Styles
-@refactor{
- Some group styles still use jQuery;
- they should be modified to use modern formatters and Liza DOM
- abstractions (see @srcrefraw{src/ui/field}
- and @srcrefraw{src/ui/styler}).}
-
-@cindex Group, Styling
-Groups support a number of @dfn{group styles} that determine how
- they are delimited from other groups;
- how the elements they contain are rendered and laid out;
- and how multiple indexes are displayed, added, and removed.
-A list of available styles is detailed in @ref{t:group-styles}.
-
-@float Table, t:group-styles
-@multitable @columnfractions 0.15 0.65 0.10 0.10
- @headitem Name @tab Description @tab Multi-Index? @tab Add/Remove Index?
-
- @item @samp{default}
- @tab
- Groups are unstyled by default@mdash{
- }they render elements as flat fields like a traditional form.
- Only the first index of elements is rendered.
- @tab@center N
- @tab@center N
-
- @item @samp{collapsetable}
- @tab
- Renders element label in the leftmost column like @samp{sidetable}.
- Indexes are groups of rows delimited by headings,
- which collapse the respective group of rows when clicked.
- @tab@center Y
- @tab@center Add
-
- @item @samp{sidetable}
- @tab
- Renders elements as rows with label in the leftmost column rather
- than the top row.
- Each index is rendered as a column.
- @tab@center Y
- @tab@center Add
-
- @item @samp{tabbedblock}
- @tab
- Each group is rendered as a block,
- with each index rendered as a tab to the right of it.
- Clicking a tab toggles the body content to the associated index.
- Elements are rendered within the box.
- @tab@center Y
- @tab@center N
-
- @item @samp{tabbed}
- @tab
- Like @samp{default},
- but each index has a tab at the top of the group.
- Clicking a tab toggles the body content to the associated index.
- @tab@center Y
- @tab@center Y
-
- @item @samp{table}
- @tab
- A vanilla table with elements as columns,
- their labels across the top row.
- Each index is rendered in its own row.
- @tab@center Y
- @tab@center Y
-@end multitable
-@caption{Group styles and index support}
-@end float
-
-
-
-@node Program XML
-@section Program XML
-@helpwanted
-
-@menu
-* Specifying Predicates::
-@end menu
-
-
-@node Specifying Predicates
-@subsection Specifying Predicates
-
-Object predicates (@pxref{Predicate System}) are specified using the
- @xmlattr{when} attribute of certain nodes.
-It must contain a string of references understood by the system
- (see domain of discourse, @ref{Predicate System}),
- all of which much match for the predicate to be true.
-
-@float Figure, f:pred-when
-@example
- <question id="describe" type="noyes"
- label="Any special notes for this location?" />
-
- <question id="vacant_desc" type="textarea"
- when="q:describe vacant property"
- label="Show only when a vacant property with the
- question 'describe' non-empty and non-zero" />
-@end example
-@caption{Using the @xmlattr{when} attribute}
-@end float
-
-In @ref{f:pred-when} above,
- question @samp{vacant_desc} will be applicable when @emph{all} of
- the values of @samp{vacant}, @samp{property},
- and@tie{}@samp{q:describe} are true.@footnote{
- @xref{Predicate System} for what ``true'' means for a particular
- variable in the domain of discourse.}
-Within the context of the @progxml,
- this concretely means that the classifications
- @samp{vacant} and@tie{}@samp{property} are true,
- and that the question @samp{describe} is answered ``yes''.
-It reads as a sentence:
- ``@samp{vacant_desc}'' is applicable when we should @tie{}``describe
- a vacant property''.
-
-
-
-@node Validation
-@section Validation
-@helpwanted
-
-@menu
-* Formatting Values::
-@end menu
-
-
-@node Formatting Values
-@subsection Formatting Values
-
-@cindex Question
-@cindex Question, Value Formatting
-@helpwanted
+More information about each can be found in their respective chapter/section.
diff --git a/doc/liza.texi b/doc/liza.texi
index d091cd9..e8591a8 100644
--- a/doc/liza.texi
+++ b/doc/liza.texi
@@ -76,6 +76,12 @@ Free Documentation License''.
@menu
* Design and Architecture:Design. Design and structure of framework
+* Assertions::
+* Bucket::
+* Client::
+* Predicate System::
+* Program::
+* Validation::
* License:: Document License
* Concept Index::
@ifset DEVNOTES
@@ -89,6 +95,12 @@ Free Documentation License''.
@end ifnottex
@include design.texi
+@include assert.texi
+@include bucket.texi
+@include client.texi
+@include pred.texi
+@include program.texi
+@include validation.texi
@include license.texi
@node Concept Index
diff --git a/doc/pred.texi b/doc/pred.texi
new file mode 100644
index 0000000..8ee01eb
--- /dev/null
+++ b/doc/pred.texi
@@ -0,0 +1,74 @@
+@c This document is part of the Liza Data Collection Framework manual.
+@c Copyright (C) 2017 R-T Specialty, LLC.
+@c
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3
+@c or any later version published by the Free Software Foundation;
+@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+@c Texts. A copy of the license is included in the section entitled ``GNU
+@c Free Documentation License''.
+
+@node Predicate System
+@chapter Predicate System
+@maintstart
+@footnote{
+ New programs (using the old incarnation of TAME) use the classifier
+ embedded into the rater by TAME.
+ Old ones, however, still use the @dfn{Global Classifier}.
+ This system isn't as well tested as TAME's@mdash{
+ }which needs to work properly for the sake of calculating premium@mdash{
+ }and has suffered from a number of bugs in the past.
+
+ The solution is to migrate all programs to TAME and remove that old
+ code.}
+@maintend
+
+@tip{
+ For a practical application of these concepts, see its use in the
+ Program@tie{}XML (@pxref{Specifying Predicates}).}
+
+@cindex Predicate
+@cindex Classifier
+@cindex Applicability
+@cindex Domain of discourse, Predicate
+The @dfn{predicate system} determines the @dfn{applicability} of
+ certain objects (like questions and assertions) by associating them
+ with predicates.
+The domain of discourse (variables which may be quantified) is listed
+ in @ref{t:predicate-dod}.
+
+What it means for some object to be applicable depends on the context.
+
+@float Table, t:predicate-dod
+@multitable @columnfractions 0.25 0.10 0.65
+ @headitem Type @tab Prefix @tab Description
+
+ @item Classifications
+ @tab @emph{None}
+ @tab Results of applying an external @dfn{classifier} to the bucket
+ (@pxref{Bucket}).
+
+ @item Bucket Truth Predicate
+ @tab @code{q:}
+ @tab
+ Whether the given name in the bucket (@pxref{Bucket}) is
+ non-empty and non-zero.
+ The prefix @samp{q:} refers to its most common use
+ case---questions (@pxref{Program UI,,Program@tie{}UI}).
+@end multitable
+@caption{Predicate system domain of discourse}
+@end float
+
+This system is limited to universal quantification over the domain of
+ discourse.
+For other quantifiers and higher-order logic,
+ defer to one of the systems that contributes to the domain of
+ discourse,
+ like the classifier.@footnote{
+ This is usually TAME.
+ The Program XML also supports inline classifications
+ with TAME's syntax (@pxref{Specifying Predicates}).}
+
+Predicates are usually specified in the Program XML
+ (@pxref{Specifying Predicates}) and compiled into the program
+ (@pxref{Program}).
diff --git a/doc/program.texi b/doc/program.texi
new file mode 100644
index 0000000..76d6482
--- /dev/null
+++ b/doc/program.texi
@@ -0,0 +1,222 @@
+@c This document is part of the Liza Data Collection Framework manual.
+@c Copyright (C) 2017 R-T Specialty, LLC.
+@c
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3
+@c or any later version published by the Free Software Foundation;
+@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+@c Texts. A copy of the license is included in the section entitled ``GNU
+@c Free Documentation License''.
+
+
+@node Program
+@chapter Program
+@maintstart
+@footnote{
+ The @code{Program} class was one of the first prototypes created,
+ and has evolved poorly with the rest of the system.
+ It is the base class for all compiled programs,
+ and it glues together too many other systems with a terrible
+ API and little to no encapsulation.
+
+ With that said, it is one of the least touched classes (thus its
+ state); developers rarely have the need to touch @code{Program}.}
+@maintend
+
+
+@cindex Program
+The @dfn{Program} is a declarative representation of an entire system.
+It is the highest level of abstraction from a data perspective.
+The user observes and interacts with a Program using the
+ @ref{Program UI,,Program@tie{}UI}.
+
+@cindex Program, XML
+Programs contain a lot of metadata that is not in a convenience
+ human-readable (or modifiable) format,
+ some of which are redundant.
+Programs are ideally compiled from a @ref{Program XML,,Program@tie{}XML}
+ document.
+
+@menu
+* Program UI::
+* Program XML::
+@end menu
+
+@node Program UI
+@section Program UI
+@maintenance{
+ The @code{Ui} class,
+ in addition to @srcref{src/client/Client,Client} (@pxref{Client}),
+ represent the two monoliths of the system.
+ This mediates all UI-related tasks,
+ and still has far too many concerns with far too many
+ dependencies.
+ Code is to be extracted out of this class as it is touched.
+}
+
+
+@cindex Program, User Interface
+@cindex User Interface, Program
+The @dfn{Program UI} renders a @ref{Program} as a form.
+
+@cindex Step
+@cindex Group
+At the highest level,
+ steps are rendered in a tab-like manner,
+ above the main form content.
+A step contains groups,
+ which in turn contain elements such as questions.
+Groups are delimited in some manner defined by their style
+ (@pxref{Group Styles}).
+
+@cindex Question
+@cindex Question, Value Formatting
+@cindex Bucket, Updating
+Questions are rendered as form fields.
+Any time the respective @ref{Bucket} field is changed,
+ the form field is updated to reflect those changes,
+ after having first been formatted with the appropriate validator
+ (@pxref{Formatting Values}).
+When a question is changed by the user,
+ the value is expected to be propagated to the Bucket
+ (@pxref{Bucket Assignment}).
+
+@cindex Navigation Bar
+@cindex User Interface, Navigation Bar
+@cindex User Interface, Button Navigation
+Navigation between steps can be done via the
+ @dfn{Navigation Bar} above the step@tie{}content,
+ or using ``Go@tie{}Back'' and ``Continue'' buttons at the foot of the
+ step@tie{}content.
+
+@cindex Sidebar
+A @dfn{Sidebar} is rendered adjacent to the step content.
+It displays the name of the Program,
+ as well as configurable metadata (usually through the @samp{sidebar}
+ node of the @ref{Program XML,,Program@tie{}XML}).
+It also displays question help text (also configured through the XML)
+ and any error messages (@pxref{Error Handling}).
+
+@menu
+* Group Styles:: Different ways of displaying groups of questions to
+ the user.
+@end menu
+
+
+@node Group Styles
+@subsection Group Styles
+@refactor{
+ Some group styles still use jQuery;
+ they should be modified to use modern formatters and Liza DOM
+ abstractions (see @srcrefraw{src/ui/field}
+ and @srcrefraw{src/ui/styler}).}
+
+@cindex Group, Styling
+Groups support a number of @dfn{group styles} that determine how
+ they are delimited from other groups;
+ how the elements they contain are rendered and laid out;
+ and how multiple indexes are displayed, added, and removed.
+A list of available styles is detailed in @ref{t:group-styles}.
+
+@float Table, t:group-styles
+@multitable @columnfractions 0.15 0.65 0.10 0.10
+ @headitem Name @tab Description @tab Multi-Index? @tab Add/Remove Index?
+
+ @item @samp{default}
+ @tab
+ Groups are unstyled by default@mdash{
+ }they render elements as flat fields like a traditional form.
+ Only the first index of elements is rendered.
+ @tab@center N
+ @tab@center N
+
+ @item @samp{collapsetable}
+ @tab
+ Renders element label in the leftmost column like @samp{sidetable}.
+ Indexes are groups of rows delimited by headings,
+ which collapse the respective group of rows when clicked.
+ @tab@center Y
+ @tab@center Add
+
+ @item @samp{sidetable}
+ @tab
+ Renders elements as rows with label in the leftmost column rather
+ than the top row.
+ Each index is rendered as a column.
+ @tab@center Y
+ @tab@center Add
+
+ @item @samp{tabbedblock}
+ @tab
+ Each group is rendered as a block,
+ with each index rendered as a tab to the right of it.
+ Clicking a tab toggles the body content to the associated index.
+ Elements are rendered within the box.
+ @tab@center Y
+ @tab@center N
+
+ @item @samp{tabbed}
+ @tab
+ Like @samp{default},
+ but each index has a tab at the top of the group.
+ Clicking a tab toggles the body content to the associated index.
+ @tab@center Y
+ @tab@center Y
+
+ @item @samp{table}
+ @tab
+ A vanilla table with elements as columns,
+ their labels across the top row.
+ Each index is rendered in its own row.
+ @tab@center Y
+ @tab@center Y
+@end multitable
+@caption{Group styles and index support}
+@end float
+
+
+
+@node Program XML
+@section Program XML
+@helpwanted
+
+@menu
+* Specifying Predicates::
+@end menu
+
+
+@node Specifying Predicates
+@subsection Specifying Predicates
+
+Object predicates (@pxref{Predicate System}) are specified using the
+ @xmlattr{when} attribute of certain nodes.
+It must contain a string of references understood by the system
+ (see domain of discourse, @ref{Predicate System}),
+ all of which much match for the predicate to be true.
+
+@float Figure, f:pred-when
+@example
+ <question id="describe" type="noyes"
+ label="Any special notes for this location?" />
+
+ <question id="vacant_desc" type="textarea"
+ when="q:describe vacant property"
+ label="Show only when a vacant property with the
+ question 'describe' non-empty and non-zero" />
+@end example
+@caption{Using the @xmlattr{when} attribute}
+@end float
+
+In @ref{f:pred-when} above,
+ question @samp{vacant_desc} will be applicable when @emph{all} of
+ the values of @samp{vacant}, @samp{property},
+ and@tie{}@samp{q:describe} are true.@footnote{
+ @xref{Predicate System} for what ``true'' means for a particular
+ variable in the domain of discourse.}
+Within the context of the @progxml,
+ this concretely means that the classifications
+ @samp{vacant} and@tie{}@samp{property} are true,
+ and that the question @samp{describe} is answered ``yes''.
+It reads as a sentence:
+ ``@samp{vacant_desc}'' is applicable when we should @tie{}``describe
+ a vacant property''.
diff --git a/doc/validation.texi b/doc/validation.texi
new file mode 100644
index 0000000..8ad0e29
--- /dev/null
+++ b/doc/validation.texi
@@ -0,0 +1,25 @@
+@c This document is part of the Liza Data Collection Framework manual.
+@c Copyright (C) 2017 R-T Specialty, LLC.
+@c
+@c Permission is granted to copy, distribute and/or modify this document
+@c under the terms of the GNU Free Documentation License, Version 1.3
+@c or any later version published by the Free Software Foundation;
+@c with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+@c Texts. A copy of the license is included in the section entitled ``GNU
+@c Free Documentation License''.
+
+@node Validation
+@chapter Validation
+@helpwanted
+
+@menu
+* Formatting Values::
+@end menu
+
+
+@node Formatting Values
+@section Formatting Values
+
+@cindex Question
+@cindex Question, Value Formatting
+@helpwanted