From 09c32e4792c27777a1daafed5a5601a6a1769255 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Tue, 14 Mar 2017 15:26:50 -0400 Subject: [PATCH 01/30] doc/liza.texi: Include version.texi before reference of VERSION --- doc/liza.texi | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/doc/liza.texi b/doc/liza.texi index d36f362..f0a3855 100644 --- a/doc/liza.texi +++ b/doc/liza.texi @@ -1,6 +1,7 @@ \input texinfo @c -*-texinfo-*- @c This document is part of the Liza Data Collection Framework manual. @c Copyright (C) 2014 LoVullo Associates, Inc. +@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; @@ -9,17 +10,17 @@ @c Free Documentation License''. @c %**start of header +@include version.texi + @setfilename liza.info @settitle Liza Data Collection Framework v@value{VERSION} @c %**end of header -@include version.texi - @copying This manual is for the Liza Data Collection Framework, version @value{VERSION}. -Copyright @copyright{} 2014 LoVullo Associates, Inc. +Copyright @copyright{} 2014, 2017 LoVullo Associates, Inc. @quotation Permission is granted to copy, distribute and/or modify this document From 0c496299a026d69719b04fc58d3e947a588c5fea Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Wed, 15 Mar 2017 15:31:09 -0400 Subject: [PATCH 02/30] design.texi: Add initial component descriptions --- doc/Makefile.am | 2 + doc/design.texi | 98 +++++++++++++++++++++++++++++++++++++++++++++++++ doc/liza.texi | 12 +++++- doc/macros.texi | 22 +++++++++++ 4 files changed, 132 insertions(+), 2 deletions(-) create mode 100644 doc/design.texi create mode 100644 doc/macros.texi diff --git a/doc/Makefile.am b/doc/Makefile.am index 6c8843b..503b988 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -19,3 +19,5 @@ ## info_TEXINFOS = liza.texi +liza_TEXINFOS = design.texi macros.texi + diff --git a/doc/design.texi b/doc/design.texi new file mode 100644 index 0000000..3de2be8 --- /dev/null +++ b/doc/design.texi @@ -0,0 +1,98 @@ +@c This document is part of the Liza Data Collection Framework manual. +@c Copyright (C) 2017 LoVullo Associates, Inc. +@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 Design +@chapter Design & Architecture + +@emph{N.B. This document may reference features that are not yet + present in Liza; they will be moved into this repository in time.} + +Liza is fundamentally a data collection framework@mdash{ + }a fancy form for collecting, validating, and lightly processing + user data. + +The main components of the system are: + +@table @strong + @cindex Assertion + @item Assertions + Basic validations against bucket data, + producing errors and manipulating control flow. + Invokes triggers to manipulate the UI and document. + Assertions are compiled from Program sources. + + @cindex Bucket + @item Bucket + The key/value store into which all document data are stored. + Supports staging and rollback of data, + processing deltas, + and provides hooks that drive the rest of the system. + + @cindex Calculated Value + @item Calculated Values + A small sub-system for calculating bucket values from other values. + + @cindex Client + @item Client Interface + Basic logic for navigating between steps, + prompting for user actions, + display help text and basic document data, + communicate with server, + etc. + + @cindex Developer Dialog + @item Developer Dialog + Renders information about the system for debugging the client. + Can monitor the bucket, assertions, classification results, and + provides other useful features. + + @cindex Predicate + @item Predicate System + Processes classification data from external classifiers to determine + applicability of specific questions. + These data are used to determine what assertions are performed, + what questions and groups display, + and more. + + @cindex Program + @item Program + Internal representation of the program with delegation of events to + the assertion system. + Contains compiled representation of all steps, groups, questions, + assertions, metadata, and others. + + @cindex Program, User Interface + @cindex User Interface, Program + @item Program UI + Rendering of elements specific to programs, + such as steps, groups, and questions. + This is the equivalent of an HTML form. + Directly monitors the bucket to perform UI updates. + + @cindex Program, XML + @item Program XML + The source code for a program, in XML format. + + @cindex Server + @item Server + Provides REST API for serving programs; saving data; + revalidating, filtering, and recalculating data; + and other types of processing. + Code is shared with the client, + ensuring identical behavior for appropriate behaviors. + + @cindex Type Validation + @cindex Validation, Type + @item Type Validation + Validates and formats bucket values for specific field (question) + types. + For example, a date field must be in a recognized date format, + and will be normalized for display. +@end table diff --git a/doc/liza.texi b/doc/liza.texi index f0a3855..c0d5c1d 100644 --- a/doc/liza.texi +++ b/doc/liza.texi @@ -52,13 +52,21 @@ Free Documentation License''. @top Main @end ifnottex -@c This is where @menu will go +@menu +* Design and Architecture:Design. Design and structure of framework +* Concept Index:: +@end menu @ifnottex @insertcopying @end ifnottex -@c This is where the includes will go. +@include macros.texi +@include design.texi + +@node Concept Index +@unnumbered Concept Index +@printindex cp @bye diff --git a/doc/macros.texi b/doc/macros.texi new file mode 100644 index 0000000..0224276 --- /dev/null +++ b/doc/macros.texi @@ -0,0 +1,22 @@ +@c This document is part of the Liza Data Collection Framework manual. +@c Copyright (C) 2017 LoVullo Associates, Inc. +@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''. + +@c insert appropriate em dash for mode +@iftex +@macro mdash{} +--- +@end macro +@end iftex + +@ifnottex +@macro mdash{} +— +@end macro +@end ifnottex From 05e22b230954bc18b3b17dbc8ac6d3f1d2010d77 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Wed, 15 Mar 2017 15:42:24 -0400 Subject: [PATCH 03/30] Add manual HTML styling This uses GNU Octave's CSS, which formats it like a printed manual using a modern style. It's certainly an opinionated style, but at the very least, the width is important. * Makefile.am (MAKEINFOHTML): Include CSS reference. * liza.css: Add stylesheet. --- doc/Makefile.am | 2 + doc/liza.css | 112 ++++++++++++++++++++++++++++++++++++++++++++++++ 2 files changed, 114 insertions(+) create mode 100644 doc/liza.css diff --git a/doc/Makefile.am b/doc/Makefile.am index 503b988..8dab2e6 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -18,6 +18,8 @@ # along with this program. If not, see . ## +MAKEINFOHTML = $(MAKEINFO) --html --css-include liza.css + info_TEXINFOS = liza.texi liza_TEXINFOS = design.texi macros.texi diff --git a/doc/liza.css b/doc/liza.css new file mode 100644 index 0000000..4f53562 --- /dev/null +++ b/doc/liza.css @@ -0,0 +1,112 @@ +/* +Copyright (C) 2016-2017 Oliver Heimlich + +This file is part of Octave. + +Octave is free software; you can redistribute it and/or modify it +under the terms of the GNU General Public License as published by the +Free Software Foundation; either version 3 of the License, or (at +your option) any later version. + +Octave is distributed in the hope that it will be useful, but WITHOUT +ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or +FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License +for more details. + +You should have received a copy of the GNU General Public License +along with Octave; see the file COPYING. If not, see +. +*/ + +/* Import web font Roboto Condensed, Font Library Version 2015-06-06 */ +@font-face { font-family: 'Roboto Condensed'; src: local('Roboto Condensed Bold'), local('RobotoCondensed-Bold'), + url('https://fontlibrary.org/assets/fonts/roboto-condensed/71405335c70332d94afd24ae4f06c9b2/4b8b4b377e8cb358cf886d13c7bb287c/RobotoCondensedBold.ttf') format('truetype'); + font-weight: bold; font-style: normal; } +@font-face { font-family: 'Roboto Condensed'; src: local('Roboto Condensed Bold Italic'), local('RobotoCondensed-BoldItalic'), + url('https://fontlibrary.org/assets/fonts/roboto-condensed/71405335c70332d94afd24ae4f06c9b2/9b1d05d1b332e5b95ad86e71ca8404fb/RobotoCondensedBoldItalic.ttf') format('truetype'); + font-weight: bold; font-style: italic; } +@font-face { font-family: 'Roboto Condensed'; src: local('Roboto Condensed Italic'), local('RobotoCondensed-Italic'), + url('https://fontlibrary.org/assets/fonts/roboto-condensed/71405335c70332d94afd24ae4f06c9b2/d02fffb6890e4f28023dd149916d1b8a/RobotoCondensedItalic.ttf') format('truetype'); + font-weight: normal; font-style: italic; } +@font-face { font-family: 'Roboto Condensed'; src: local('Roboto Condensed Regular'), local('RobotoCondensed-Regular'), + url('https://fontlibrary.org/assets/fonts/roboto-condensed/71405335c70332d94afd24ae4f06c9b2/b0b1845ecce8ab6a503971e808a8409c/RobotoCondensedRegular.ttf') format('truetype'); + font-weight: normal; font-style: normal; } + +/* Import web font Fantasque Sans Mono, Font Library Version 2016-04-05 */ +@font-face { font-family: 'Fantasque Sans Mono'; src: local('Fantasque Sans Mono Bold'), local('FantasqueSansMono-Bold'), + url('https://fontlibrary.org/assets/fonts/fantasque-sans-mono/b0cbb25e73a9f8354e96d89524f613e7/a46033d3a07d9385620dc83b7655203f/FantasqueSansMonoBold.ttf') format('truetype'); + font-weight: bold; font-style: normal; } +@font-face { font-family: 'Fantasque Sans Mono'; src: local('Fantasque Sans Mono Bold Italic'), local('FantasqueSansMono-BoldItalic'), + url('https://fontlibrary.org/assets/fonts/fantasque-sans-mono/b0cbb25e73a9f8354e96d89524f613e7/b0683ef4c834908aa372ec78dea42349/FantasqueSansMonoBoldItalic.ttf') format('truetype'); + font-weight: bold; font-style: italic; } +@font-face { font-family: 'Fantasque Sans Mono'; src: local('Fantasque Sans Mono Italic'), local('FantasqueSansMono-Italic'), + url('https://fontlibrary.org/assets/fonts/fantasque-sans-mono/b0cbb25e73a9f8354e96d89524f613e7/b78d0a48e4443f797e8d45dcf97594f7/FantasqueSansMonoItalic.ttf') format('truetype'); + font-weight: normal; font-style: italic; } +@font-face { font-family: 'Fantasque Sans Mono'; src: local('Fantasque Sans Mono Regular'), local('FantasqueSansMono-Regular'), + url('https://fontlibrary.org/assets/fonts/fantasque-sans-mono/b0cbb25e73a9f8354e96d89524f613e7/f3fdc4f0f26e4431f54e8b552d55480c/FantasqueSansMonoRegular.ttf') format('truetype'); + font-weight: normal; font-style: normal; } + +/* Use custom fonts */ +code, kbd, samp, tt, pre { font-family: 'Fantasque Sans Mono', monospace; } +code, kbd, samp, tt { font-style: italic; padding: 0 0.1ex; /* slightly increase margin to surrounding text */ } +body, .sansserif { font-family: 'Roboto Condensed', sans-serif; } +h1, h2, h3, h4, h5, .menu-comment, .roman, .menu-preformatted { font-family: 'Roboto Condensed', serif; } + +/* +Use colors from the solarized color theme (sparsely), +the main text will remain in default colors for optimal readability (black on white). +*/ +pre.example, .header, .float-caption, hr +{ + /* base00 ~ body text in light solarized theme */ + color: #657b83; + border-color: #657b83; +} +pre.example +{ + /* base3 ~ background color in light solarized theme */ + background-color: #fdf6e3; + padding: 0.5em; +} +a { color: #268bd2; /* blue */ } +a:visited { color: #d33682; /* magenta */ } + +/* Center floating tables and images */ +.float table, .float img, .float object { margin-left: auto; margin-right: auto; } + +/* Decrease table width, but not on small screens */ +.float table { max-width: 38em; } + +/* Use horizontal lines: above/below tables and after table headers (Chicago Style) */ +.float table, .float th { border-collapse: collapse; border-top: 1px solid black; border-bottom: 1px solid black; } +.float th, .float td { padding: 0.5em; } + +/* Use horizontal ruler with double lines */ +hr { border-width: 0; border-top-width: 3px; border-style: double; } + +/* Smaller gap between subsequent @group blocks */ +.example { margin-bottom: 1em; } +.example + .example { margin-top: -0.5em } + +/* Smaller gap between definition and its description */ +dd > p:first-child { margin-top: 0.5em; } + +/* Limit maximum body width such that text is easier to read */ +body { max-width: 42em; margin-left: 0.5em; margin-right: 0.5em; } + +/* On small screens don't indent the code examples to prevent overflow */ +div.example { margin-left: auto; max-width: 38.8em; } + +/* +Use left margin such that text is easier to read, +but don't sacrifice space on small screens. +*/ +@media screen and (min-width: 43em) +{ + /* Smooth transition for screens between 43em and 57em */ + body { margin-left: auto; margin-right: auto; } + @media (min-width: 57em) + { + body { margin-left: 7.5em; } + } +} From 9403a1d29bae820f7fa3d632ac7c40f9205f07d3 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Wed, 15 Mar 2017 15:51:41 -0400 Subject: [PATCH 04/30] liza.texi: Set document character encoding to UTF-8 --- doc/liza.texi | 2 ++ 1 file changed, 2 insertions(+) diff --git a/doc/liza.texi b/doc/liza.texi index c0d5c1d..220112e 100644 --- a/doc/liza.texi +++ b/doc/liza.texi @@ -14,6 +14,8 @@ @setfilename liza.info @settitle Liza Data Collection Framework v@value{VERSION} + +@documentencoding UTF-8 @c %**end of header @copying From 00e2389a5fffe89b87467d10d8d3b562a35c3b45 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Thu, 16 Mar 2017 13:23:19 -0400 Subject: [PATCH 05/30] macros.texi (helpwanted): Add macro --- doc/design.texi | 246 +++++++++++++++++++++++++++++++++++++++++++++--- doc/macros.texi | 7 ++ 2 files changed, 241 insertions(+), 12 deletions(-) diff --git a/doc/design.texi b/doc/design.texi index 3de2be8..3eecd40 100644 --- a/doc/design.texi +++ b/doc/design.texi @@ -21,15 +21,15 @@ Liza is fundamentally a data collection framework@mdash{ The main components of the system are: @table @strong - @cindex Assertion - @item Assertions + @cindex Assertions + @item @ref{Assertions} Basic validations against bucket data, producing errors and manipulating control flow. Invokes triggers to manipulate the UI and document. Assertions are compiled from Program sources. @cindex Bucket - @item Bucket + @item @ref{Bucket} The key/value store into which all document data are stored. Supports staging and rollback of data, processing deltas, @@ -40,7 +40,7 @@ The main components of the system are: A small sub-system for calculating bucket values from other values. @cindex Client - @item Client Interface + @item @ref{Client} Basic logic for navigating between steps, prompting for user actions, display help text and basic document data, @@ -62,27 +62,27 @@ The main components of the system are: and more. @cindex Program - @item Program - Internal representation of the program with delegation of events to + @item @ref{Program} + Internal representation of the Program with delegation of events to the assertion system. Contains compiled representation of all steps, groups, questions, assertions, metadata, and others. @cindex Program, User Interface @cindex User Interface, Program - @item Program UI - Rendering of elements specific to programs, + @item @ref{Program UI} + Rendering of elements specific to Programs, such as steps, groups, and questions. This is the equivalent of an HTML form. Directly monitors the bucket to perform UI updates. @cindex Program, XML - @item Program XML - The source code for a program, in XML format. + @item @ref{Program XML} + The source code for a Program, in XML format. @cindex Server @item Server - Provides REST API for serving programs; saving data; + Provides REST API for serving Programs; saving data; revalidating, filtering, and recalculating data; and other types of processing. Code is shared with the client, @@ -90,9 +90,231 @@ The main components of the system are: @cindex Type Validation @cindex Validation, Type - @item Type Validation + @item @ref{Validation,,Type Validation} Validates and formats bucket values for specific field (question) types. For example, a date field must be in a recognized date format, and will be normalized for display. @end table + +More information about each can be found in their respective section. + + +@menu +* Assertions:: +* Bucket:: +* Client:: +* Program:: +* Program UI:: +* Program XML:: +* Validation:: +@end menu + + + +@node Assertions +@section Assertions +@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 +@helpwanted + +@menu +* Error Handling:: +@end menu + + +@node Error Handling +@subsection Error Handling + +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 @ref{Validation,,Type Validation}@mdash{ + }verify that questions contain valid data according to their + declared type. + @item @ref{Assertions}@mdash{ + }arbitrary checks on data. +@end enumerate + +Required fields fail serially@mdash{ + }the system will notify the user of the required field, + and direct him/her to it (usually through scrolling). + + +@node Program +@section Program + +@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 + +@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 + +@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. + +@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 + + + +@node Program XML +@section Program XML +@helpwanted + + +@node Validation +@section Validation +@helpwanted + +@menu +* Formatting Values:: +@end menu + + +@node Formatting Values +@subsection Formatting Values + +@cindex Question +@cindex Question, Value Formatting +@helpwanted diff --git a/doc/macros.texi b/doc/macros.texi index 0224276..a9dd018 100644 --- a/doc/macros.texi +++ b/doc/macros.texi @@ -20,3 +20,10 @@ — @end macro @end ifnottex + + +@c indicate that help is needed to produce docs +@macro helpwanted{} +@cindex TODO, Missing Docs +@emph{There's nothing here yet. Maybe you can help?} +@end macro From 1b4ebc13e39cf9fcf05d567ac81bf8b84f3730f1 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Tue, 21 Mar 2017 10:27:36 -0400 Subject: [PATCH 06/30] Add notices and DEVNOTES flag * .gitignore (/config.*): Restrict to root. * configure.ac (DEVNOTES): Add variable. (--enable-devnotes): Add configuration flag. * doc/Makefile.am (liza_TEXINFOS): config.texi dependency. * doc/config.texi.in: Add configuration file. * doc/liza.css: Styling for notices. * doc/liza.texi: Include configuration. Add notice for DEVNOTES. * doc/macros.texi: Add notice macros. * doc/.gitignore (config.texi): Ignore generated file. --- .gitignore | 2 +- configure.ac | 13 ++++++- doc/.gitignore | 1 + doc/Makefile.am | 3 +- doc/config.texi.in | 4 +++ doc/liza.css | 34 +++++++++++++++++++ doc/liza.texi | 22 +++++++++++- doc/macros.texi | 84 +++++++++++++++++++++++++++++++++++++++++----- 8 files changed, 149 insertions(+), 14 deletions(-) create mode 100644 doc/config.texi.in diff --git a/.gitignore b/.gitignore index 6f4a0e4..7634d5d 100644 --- a/.gitignore +++ b/.gitignore @@ -7,7 +7,7 @@ Makefile.in # generated by configure src/version.js -config.* +/config.* Makefile package.json diff --git a/configure.ac b/configure.ac index de67f47..1f13a55 100644 --- a/configure.ac +++ b/configure.ac @@ -41,6 +41,17 @@ AS_IF([node --harmony_destructuring >/dev/null 2>/dev/null], AC_SUBST([NODE_DESTRUCTURE], [--harmony_destructuring])], [AC_MSG_RESULT(no)]) +set_devnotes='@set DEVNOTES' +AC_ARG_ENABLE( + [devnotes], + [AS_HELP_STRING([--enable-devnotes], + [include note for liza developers (enabled by default)])], + [test "x$enableval" != xno || set_devnotes="@c $set_devnotes"]) + +AC_SUBST([SET_DEVNOTES], [$set_devnotes]) + # generate files from their *.in counterparts -AC_CONFIG_FILES([Makefile doc/Makefile package.json src/version.js]) +AC_CONFIG_FILES([Makefile package.json + doc/Makefile doc/config.texi + src/version.js]) AC_OUTPUT diff --git a/doc/.gitignore b/doc/.gitignore index 8e3f7df..6eab057 100644 --- a/doc/.gitignore +++ b/doc/.gitignore @@ -19,3 +19,4 @@ Makefile Makefile.in stamp-vti version.texi +config.texi diff --git a/doc/Makefile.am b/doc/Makefile.am index 8dab2e6..b992de5 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -21,5 +21,4 @@ MAKEINFOHTML = $(MAKEINFO) --html --css-include liza.css info_TEXINFOS = liza.texi -liza_TEXINFOS = design.texi macros.texi - +liza_TEXINFOS = design.texi macros.texi config.texi diff --git a/doc/config.texi.in b/doc/config.texi.in new file mode 100644 index 0000000..314c443 --- /dev/null +++ b/doc/config.texi.in @@ -0,0 +1,4 @@ +@c Manual configuration + +@c whether to include notes for Liza developers +@SET_DEVNOTES@ diff --git a/doc/liza.css b/doc/liza.css index 4f53562..1142098 100644 --- a/doc/liza.css +++ b/doc/liza.css @@ -1,5 +1,6 @@ /* Copyright (C) 2016-2017 Oliver Heimlich +Copyright (C) 2017 LoVullo Associates, Inc. This file is part of Octave. @@ -110,3 +111,36 @@ but don't sacrifice space on small screens. body { margin-left: 7.5em; } } } + +/** added by LoVullo Associates **/ +.doc-notice +{ + border-left: 5px solid #657b83; + margin: 0px; + padding: 0em 0em 0em 0.25em; + padding-block-start: 0.25em; + padding-block-end: 0.25em; +} + +.doc-notice p +{ + margin: 0px; +} + +.doc-notice.dev +{ + border-color: #d33682; +} + +.doc-notice.dev p::before +{ + color: #d33682; + content: '\01F6A7'; + margin-right: 0.5em; +} + +.footnote-notice.dev p:first-child::before +{ + content: '\01F6A7'; + margin-right: 0.5em; +} diff --git a/doc/liza.texi b/doc/liza.texi index 220112e..bce42b7 100644 --- a/doc/liza.texi +++ b/doc/liza.texi @@ -10,7 +10,12 @@ @c Free Documentation License''. @c %**start of header +@include config.texi @include version.texi +@include macros.texi + +@c Developer Notes index (used only if DEVNOTES) +@defindex dn @setfilename liza.info @settitle Liza Data Collection Framework v@value{VERSION} @@ -47,6 +52,12 @@ Free Documentation License''. @insertcopying @end titlepage +@devnotice{ + This manual contains inline notes for developers of Liza.@footnote{ + To disable for user documentation, pass @option{--disable-devnotes} + to @command{configure}.} + For an index of notes@comma{} see @ref{Developer Notes Index}.} + @contents @ifnottex @@ -57,6 +68,9 @@ Free Documentation License''. @menu * Design and Architecture:Design. Design and structure of framework * Concept Index:: +@ifset DEVNOTES +* Developer Notes Index:: Index of pertenant notes for developers of Liza. +@end ifset @end menu @ifnottex @@ -64,11 +78,17 @@ Free Documentation License''. @insertcopying @end ifnottex -@include macros.texi @include design.texi @node Concept Index @unnumbered Concept Index @printindex cp +@ifset DEVNOTES + @node Developer Notes Index + @unnumbered Developer Notes Index + @printindex dn +@end ifset + + @bye diff --git a/doc/macros.texi b/doc/macros.texi index a9dd018..f656e4a 100644 --- a/doc/macros.texi +++ b/doc/macros.texi @@ -8,22 +8,88 @@ @c Texts. A copy of the license is included in the section entitled ``GNU @c Free Documentation License''. -@c insert appropriate em dash for mode -@iftex -@macro mdash{} ---- -@end macro -@end iftex +@c unicode CONSTRUCTION SIGN +@macro constructionsign +🚧 +@end macro + + +@c insert appropriate em dash for mode @ifnottex -@macro mdash{} -— +@macro mdash +@inlinefmtifelse{html, @inlineraw{html,—}, —} @end macro @end ifnottex +@c the macro for TeX for some reason always seems to be followed +@c by a space when applied; #1 consumes it and re-adds if it's +@c not empty +@tex +\gdef\mdash#1{% + ---% + \def\next{#1}% + \ifx\next\empty\relax\else#1\fi% +} +@end tex + + +@c inline documentation notice for some sort of quality +@c improvement or warning +@macro rawnotice{type,text} +@html +
+@end html +@emph{\text\} +@html +
+@end html +@end macro + + +@c vanilla notice +@macro notice{text} +@rawnotice{{},\text\} +@end macro + + +@c notice for developers of liza +@macro devnotice{text} +@ifset DEVNOTES +@html +@end html +@rawnotice{dev,\text\} +@end ifset +@end macro + @c indicate that help is needed to produce docs @macro helpwanted{} @cindex TODO, Missing Docs -@emph{There's nothing here yet. Maybe you can help?} +@dnindex Missing Docs +@notice{There's nothing here yet. Maybe you can help?} +@end macro + + +@c maintenance note for developers +@macro maintenance{desc} +@dnindex Maintenance Concern +@devnotice{This system has maintenance concerns.@footnote{ + @maintfoot{\desc\} +}} +@end macro + +@c encapsulated to avoid bad TeX generation (fails compilation +@c when inlined at call site) +@macro maintfoot{desc} + @html +
+ @end html + \desc\ + + @emph{Developers should evaluate whether extra time should be + allocated for tasks involving this system.} + @html +
+ @end html @end macro From eaacb7c5e058932c5cbdb7ec2a3dc77724961516 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Tue, 21 Mar 2017 10:32:42 -0400 Subject: [PATCH 07/30] doc/Makefile.am (liza_TEXINFOS): Depend upon liza.css To trigger a rebuild when modified. --- doc/Makefile.am | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/doc/Makefile.am b/doc/Makefile.am index b992de5..c38a564 100644 --- a/doc/Makefile.am +++ b/doc/Makefile.am @@ -21,4 +21,4 @@ MAKEINFOHTML = $(MAKEINFO) --html --css-include liza.css info_TEXINFOS = liza.texi -liza_TEXINFOS = design.texi macros.texi config.texi +liza_TEXINFOS = design.texi macros.texi config.texi liza.css From 4ddebbc035f4b5a7ed77af3f94a6035b600d4fac Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Tue, 21 Mar 2017 11:10:58 -0400 Subject: [PATCH 08/30] Add SRCURI configuration for manual * configure.ac (SET_SRCURI): Provide source root to manual. (--with-srcuri): Add configure option. * doc/config.texi.in (SET_SRCURI): Add configuration value. * doc/liza.texi: Add warning if SET_SRCURI is unset when DEVNOTES is set. --- configure.ac | 10 ++++++++++ doc/config.texi.in | 3 +++ doc/liza.texi | 9 +++++++++ 3 files changed, 22 insertions(+) diff --git a/configure.ac b/configure.ac index 1f13a55..641d840 100644 --- a/configure.ac +++ b/configure.ac @@ -50,6 +50,16 @@ AC_ARG_ENABLE( AC_SUBST([SET_DEVNOTES], [$set_devnotes]) +set_srcuri='@c @set SRCURI ' +AC_ARG_WITH( + [srcuri], + [AS_HELP_STRING([--with-srcuri], + [root URI for Liza source code cross-references + (disabled by default)])], + [test "x$withval" = x || set_srcuri="@set SRCURI $withval"]) + +AC_SUBST([SET_SRCURI], [$set_srcuri]) + # generate files from their *.in counterparts AC_CONFIG_FILES([Makefile package.json doc/Makefile doc/config.texi diff --git a/doc/config.texi.in b/doc/config.texi.in index 314c443..c575442 100644 --- a/doc/config.texi.in +++ b/doc/config.texi.in @@ -2,3 +2,6 @@ @c whether to include notes for Liza developers @SET_DEVNOTES@ + +@c URI to root of source tree for manual cross-references +@SET_SRCURI@ diff --git a/doc/liza.texi b/doc/liza.texi index bce42b7..d4d42d6 100644 --- a/doc/liza.texi +++ b/doc/liza.texi @@ -58,6 +58,15 @@ Free Documentation License''. to @command{configure}.} For an index of notes@comma{} see @ref{Developer Notes Index}.} +@ifclear SRCURI +@devnotice{ + Location of Liza source code is unknown. + Source cross-references have been disabled.@footnote{ + To enable source code cross-references, provide the URI to the + root (as you want it to be seen in the manual) via + @option{--with-srcuri=} to @command{configure}.}} +@end ifclear + @contents @ifnottex From 0400b5f84c586e6d22d4e0649472d6cf35f0f779 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Tue, 21 Mar 2017 14:45:54 -0400 Subject: [PATCH 09/30] Properly build and format TeX document This doesn't have formatting (yet?) for notices aside from the basic italics. * design.texi: Move @ref's to end of sentence rather than treating as links on existing text. It otherwise formats undesirably in the PDF. --- doc/design.texi | 28 ++++++++++++++++++---------- 1 file changed, 18 insertions(+), 10 deletions(-) diff --git a/doc/design.texi b/doc/design.texi index 3eecd40..6e46ef9 100644 --- a/doc/design.texi +++ b/doc/design.texi @@ -22,30 +22,33 @@ The main components of the system are: @table @strong @cindex Assertions - @item @ref{Assertions} + @item Assertions Basic validations against bucket data, producing errors and manipulating control flow. Invokes triggers to manipulate the UI and document. Assertions are compiled from Program sources. + @xref{Assertions}. @cindex Bucket - @item @ref{Bucket} + @item Bucket The key/value store into which all document data are stored. Supports staging and rollback of data, processing deltas, and provides hooks that drive the rest of the system. + @xref{Bucket}. @cindex Calculated Value @item Calculated Values A small sub-system for calculating bucket values from other values. @cindex Client - @item @ref{Client} + @item Client Basic logic for navigating between steps, prompting for user actions, display help text and basic document data, communicate with server, etc. + @xref{Client}. @cindex Developer Dialog @item Developer Dialog @@ -62,23 +65,26 @@ The main components of the system are: and more. @cindex Program - @item @ref{Program} + @item Program Internal representation of the Program with delegation of events to the assertion system. Contains compiled representation of all steps, groups, questions, assertions, metadata, and others. + @xref{Program}. @cindex Program, User Interface @cindex User Interface, Program - @item @ref{Program UI} + @item Program UI Rendering of elements specific to Programs, such as steps, groups, and questions. This is the equivalent of an HTML form. Directly monitors the bucket to perform UI updates. + @xref{Program UI}. @cindex Program, XML - @item @ref{Program XML} + @item Program XML The source code for a Program, in XML format. + @xref{Program XML}. @cindex Server @item Server @@ -90,11 +96,12 @@ The main components of the system are: @cindex Type Validation @cindex Validation, Type - @item @ref{Validation,,Type Validation} + @item Type Validation Validates and formats bucket values for specific field (question) types. For example, a date field must be in a recognized date format, and will be normalized for display. + @xref{Validation}. @end table More information about each can be found in their respective section. @@ -153,11 +160,12 @@ There are three layers of error checking:@footnote{ @enumerate @item Required field checking@mdash{ }whether all required questions have been answered. - @item @ref{Validation,,Type Validation}@mdash{ + @item Type Validation@mdash{ }verify that questions contain valid data according to their - declared type. - @item @ref{Assertions}@mdash{ + declared type. @ref{Validation}. + @item Assertions@mdash{ }arbitrary checks on data. + @ref{Assertions}. @end enumerate Required fields fail serially@mdash{ From d7b1fd2f18e282c0e3d0ddec1b165a0c73286628 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Tue, 21 Mar 2017 15:53:48 -0400 Subject: [PATCH 10/30] Better multi-line devnotice styling in manual * liza.css: Better style multi-line notices with icon. * macros.texi (@noticestart, @noticeend): Add. Use instead of @rawnotice. --- doc/liza.css | 11 +++++++++-- doc/macros.texi | 16 ++++++++++------ 2 files changed, 19 insertions(+), 8 deletions(-) diff --git a/doc/liza.css b/doc/liza.css index 1142098..635de76 100644 --- a/doc/liza.css +++ b/doc/liza.css @@ -117,13 +117,13 @@ but don't sacrifice space on small screens. { border-left: 5px solid #657b83; margin: 0px; - padding: 0em 0em 0em 0.25em; padding-block-start: 0.25em; padding-block-end: 0.25em; } .doc-notice p { + padding-left: 1em; margin: 0px; } @@ -134,9 +134,16 @@ but don't sacrifice space on small screens. .doc-notice.dev p::before { + display: block; + float: left; color: #d33682; content: '\01F6A7'; - margin-right: 0.5em; + margin-left: -1.5em; +} + +.doc-notice.dev p +{ + padding-left: 1.75em; } .footnote-notice.dev p:first-child::before diff --git a/doc/macros.texi b/doc/macros.texi index f656e4a..6c32561 100644 --- a/doc/macros.texi +++ b/doc/macros.texi @@ -36,11 +36,13 @@ @c inline documentation notice for some sort of quality @c improvement or warning -@macro rawnotice{type,text} +@macro noticestart{type} @html
@end html -@emph{\text\} +@end macro + +@macro noticeend{} @html
@end html @@ -49,16 +51,18 @@ @c vanilla notice @macro notice{text} -@rawnotice{{},\text\} +@noticestart{} +@emph{\text\} +@noticeend @end macro @c notice for developers of liza @macro devnotice{text} @ifset DEVNOTES -@html -@end html -@rawnotice{dev,\text\} + @noticestart{dev} + @emph{\text\} + @noticeend @end ifset @end macro From b6c90450081b3f5ab364ca3fe25927e50a482cba Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Tue, 21 Mar 2017 15:57:30 -0400 Subject: [PATCH 11/30] Add @exnotice to manual liza.css: Style exnotice macros.texi (@exnotice): Add macro. --- doc/liza.css | 6 ++++++ doc/macros.texi | 8 ++++++++ 2 files changed, 14 insertions(+) diff --git a/doc/liza.css b/doc/liza.css index 635de76..740e230 100644 --- a/doc/liza.css +++ b/doc/liza.css @@ -151,3 +151,9 @@ but don't sacrifice space on small screens. content: '\01F6A7'; margin-right: 0.5em; } + +/* "Example:" */ +.doc-notice.ex strong:first-child +{ + color: #657b83; +} diff --git a/doc/macros.texi b/doc/macros.texi index 6c32561..67e494a 100644 --- a/doc/macros.texi +++ b/doc/macros.texi @@ -97,3 +97,11 @@ @end html @end macro + + +@c simple textual example +@macro exnotice{text} +@noticestart{ex} +@strong{Example:} \text\ +@noticeend +@end macro From e477b15298a9d985e0138eac26f65819b4b24db1 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Tue, 21 Mar 2017 16:36:41 -0400 Subject: [PATCH 12/30] Add @srcref to manual doc/macros.texi (@srcref): Add macro. --- doc/macros.texi | 15 +++++++++++++++ 1 file changed, 15 insertions(+) diff --git a/doc/macros.texi b/doc/macros.texi index 67e494a..c4388b4 100644 --- a/doc/macros.texi +++ b/doc/macros.texi @@ -105,3 +105,18 @@ @strong{Example:} \text\ @noticeend @end macro + + +@c link to source file if URI is known, otherwise display +@c the path to the file +@ifset SRCURI +@macro srcref{path, display} +@url{@value{SRCURI}/\path\, @code{\display\}} +@end macro +@end ifset + +@ifclear SRCURI +@macro srcref{path, display} +@file{\path\} +@end macro +@end ifclear From a700d275de3864c95997d12963f0c3b4a5c4e030 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Tue, 21 Mar 2017 16:36:52 -0400 Subject: [PATCH 13/30] doc/design.texi (Managing Error State): Add section text --- doc/design.texi | 47 +++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 47 insertions(+) diff --git a/doc/design.texi b/doc/design.texi index 6e46ef9..45ba2e9 100644 --- a/doc/design.texi +++ b/doc/design.texi @@ -153,6 +153,14 @@ More information about each can be found in their respective section. @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.} @@ -168,9 +176,48 @@ There are three layers of error checking:@footnote{ @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 Program From 0e29ddd5ebe102f0181ab12b509f3f1f845a10b0 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Tue, 21 Mar 2017 16:39:56 -0400 Subject: [PATCH 14/30] doc/design.texi (Design & Architecture): Convert note to notice --- doc/design.texi | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/doc/design.texi b/doc/design.texi index 45ba2e9..50132ae 100644 --- a/doc/design.texi +++ b/doc/design.texi @@ -11,8 +11,9 @@ @node Design @chapter Design & Architecture -@emph{N.B. This document may reference features that are not yet - present in Liza; they will be moved into this repository in time.} +@notice{ + N.B. This document may reference features that are not yet + present in Liza; they will be moved into this repository in time.} Liza is fundamentally a data collection framework@mdash{ }a fancy form for collecting, validating, and lightly processing From 041cde783a57c87eb3025163aa1460f5ccaa9bef Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Tue, 21 Mar 2017 16:55:18 -0400 Subject: [PATCH 15/30] doc/design.texi (Assertions): Add maintenance concerns --- doc/design.texi | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/doc/design.texi b/doc/design.texi index 50132ae..7d234e6 100644 --- a/doc/design.texi +++ b/doc/design.texi @@ -122,6 +122,20 @@ More information about each can be found in their respective section. @node Assertions @section Assertions +@maintenance{ + 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.}} + @helpwanted From 87fb6277f7c40f2f24df9ce56fdbef9fce545330 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Tue, 21 Mar 2017 17:00:31 -0400 Subject: [PATCH 16/30] doc/design.texi (Client): Add maintenance concerns --- doc/design.texi | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/doc/design.texi b/doc/design.texi index 7d234e6..5839d26 100644 --- a/doc/design.texi +++ b/doc/design.texi @@ -158,6 +158,13 @@ More information about each can be found in their respective section. @node Client @section Client +@maintenance{ + 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.} + @helpwanted @menu From f93539a82729a4e9e497a8bd81e1f8cf9e7a7c72 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Wed, 22 Mar 2017 12:15:45 -0400 Subject: [PATCH 17/30] doc/macros.texi (@mvnotice): Add macro --- doc/macros.texi | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/doc/macros.texi b/doc/macros.texi index c4388b4..388c874 100644 --- a/doc/macros.texi +++ b/doc/macros.texi @@ -107,6 +107,15 @@ @end macro +@c needs to be moved into liza +@macro mvnotice{text} +@noticestart{mv} +All or part of this system needs to be moved into Liza.@footnote{ + \text\} +@noticeend +@end macro + + @c link to source file if URI is known, otherwise display @c the path to the file @ifset SRCURI From a7368d1b527a7d54ca7de75f08aad7f4735b279d Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Wed, 22 Mar 2017 12:16:03 -0400 Subject: [PATCH 18/30] doc/design.texi (Program): Add matinenance and mv notices --- doc/design.texi | 15 +++++++++++++++ doc/macros.texi | 2 +- 2 files changed, 16 insertions(+), 1 deletion(-) diff --git a/doc/design.texi b/doc/design.texi index 5839d26..7d197e3 100644 --- a/doc/design.texi +++ b/doc/design.texi @@ -244,6 +244,21 @@ Error state is managed by @node Program @section Program +@maintenance{ + 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}.} + +@mvnotice{ + The core @code{Program} class that causes maintenance concerns needs + to be added to Liza. + It is currently mocked as necessary in test cases.} + @cindex Program The @dfn{Program} is a declarative representation of an entire system. diff --git a/doc/macros.texi b/doc/macros.texi index 388c874..be46533 100644 --- a/doc/macros.texi +++ b/doc/macros.texi @@ -110,7 +110,7 @@ @c needs to be moved into liza @macro mvnotice{text} @noticestart{mv} -All or part of this system needs to be moved into Liza.@footnote{ +@emph{All or part of this system needs to be moved into Liza.}@footnote{ \text\} @noticeend @end macro From 2475cc37a62e91de283be5505ccc73003b312b1f Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Wed, 22 Mar 2017 12:28:33 -0400 Subject: [PATCH 19/30] doc/macros.texi (@srcrefraw): Add macro I do not think Texinfo supports optional macro arguments. --- doc/macros.texi | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/doc/macros.texi b/doc/macros.texi index be46533..a70200f 100644 --- a/doc/macros.texi +++ b/doc/macros.texi @@ -122,10 +122,18 @@ @macro srcref{path, display} @url{@value{SRCURI}/\path\, @code{\display\}} @end macro + +@macro srcrefraw{path} +@url{@value{SRCURI}/\path\, @code{\path\}} +@end macro @end ifset @ifclear SRCURI @macro srcref{path, display} +@srcrefraw{\path\} +@end macro + +@macro srcrefraw{path} @file{\path\} @end macro @end ifclear From b7adc3b844cd652eaa72b3f932b9a736651247ec Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Wed, 22 Mar 2017 12:30:00 -0400 Subject: [PATCH 20/30] doc/macros.texi (@refactornotice): Add macro --- doc/macros.texi | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/doc/macros.texi b/doc/macros.texi index a70200f..b963462 100644 --- a/doc/macros.texi +++ b/doc/macros.texi @@ -99,6 +99,14 @@ @end macro +@c non-critical maintenance notes +@macro refactor{desc} +@dnindex Refactor +@devnotice{Portions of this system need refactoring.@footnote{ + \desc\}} +@end macro + + @c simple textual example @macro exnotice{text} @noticestart{ex} From 3dfde49f763edf3aa117dcfbb63feb27a2fe6d30 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Wed, 22 Mar 2017 12:40:43 -0400 Subject: [PATCH 21/30] doc/design.texi (Program UI): Add notices (Client): Add reference to Program UI in notice. --- doc/design.texi | 22 +++++++++++++++++++++- 1 file changed, 21 insertions(+), 1 deletion(-) diff --git a/doc/design.texi b/doc/design.texi index 7d197e3..a6373ad 100644 --- a/doc/design.texi +++ b/doc/design.texi @@ -163,7 +163,9 @@ More information about each can be found in their respective section. @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.} + Code is to be extracted out of this class as it is touched. + + The other system mammoth is @code{Ui} (@pxref{Program UI}).} @helpwanted @@ -277,6 +279,19 @@ Programs are ideally compiled from a @ref{Program XML,,Program@tie{}XML} @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. +} + +@mvnotice{ + All @file{program/ui/} contents still need to be moved into Liza.} + @cindex Program, User Interface @cindex User Interface, Program @@ -328,6 +343,11 @@ It also displays question help text (also configured through the XML) @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 From 637ae01e9549aa32cdb732fb632d7c07b2b45ce2 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Wed, 22 Mar 2017 14:55:06 -0400 Subject: [PATCH 22/30] doc/macros.texi (@tip): Add macro doc/liza.css: Add tip notice styling. --- doc/liza.css | 19 +++++++++++++++---- doc/macros.texi | 7 +++++++ 2 files changed, 22 insertions(+), 4 deletions(-) diff --git a/doc/liza.css b/doc/liza.css index 740e230..902eb4f 100644 --- a/doc/liza.css +++ b/doc/liza.css @@ -132,16 +132,27 @@ but don't sacrifice space on small screens. border-color: #d33682; } -.doc-notice.dev p::before +.doc-notice.dev p::before, +.doc-notice.tip p::before { display: block; float: left; - color: #d33682; - content: '\01F6A7'; margin-left: -1.5em; } -.doc-notice.dev p +.doc-notice.dev p::before +{ + color: #d33682; + content: '\01F6A7'; +} + +.doc-notice.tip p::before +{ + content: '\261E'; +} + +.doc-notice.dev p, +.doc-notice.tip p { padding-left: 1.75em; } diff --git a/doc/macros.texi b/doc/macros.texi index b963462..0c4593d 100644 --- a/doc/macros.texi +++ b/doc/macros.texi @@ -124,6 +124,13 @@ @end macro +@macro tip{text} +@noticestart{tip} +\text\ +@noticeend +@end macro + + @c link to source file if URI is known, otherwise display @c the path to the file @ifset SRCURI From 2ed43ba98600e82e85b2650aa87135ce2040b4a1 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Wed, 22 Mar 2017 14:55:24 -0400 Subject: [PATCH 23/30] doc/macros.texi (@xmlnode, @xmlattr): Add macros --- doc/macros.texi | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/doc/macros.texi b/doc/macros.texi index 0c4593d..1464cfe 100644 --- a/doc/macros.texi +++ b/doc/macros.texi @@ -152,3 +152,13 @@ @file{\path\} @end macro @end ifclear + + +@c XML formatting +@macro xmlnode{name} +@samp{\name\} +@end macro + +@macro xmlattr{name} +@samp{@@\name\} +@end macro From 8d09c2d8c328f8847b38e25f6670952070cf098a Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Thu, 23 Mar 2017 09:41:41 -0400 Subject: [PATCH 24/30] doc/macros.texi: Fix PDF output issues with @maintenance doc/macros.texi (@maintstart, @maintend): Add macros. (@maintenance): Use them. --- doc/design.texi | 12 +++++++++--- doc/macros.texi | 22 ++++++++++++++++++---- 2 files changed, 27 insertions(+), 7 deletions(-) diff --git a/doc/design.texi b/doc/design.texi index a6373ad..a0277ff 100644 --- a/doc/design.texi +++ b/doc/design.texi @@ -122,7 +122,8 @@ More information about each can be found in their respective section. @node Assertions @section Assertions -@maintenance{ +@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. @@ -135,6 +136,7 @@ More information about each can be found in their respective section. system. @emph{The latter option is preferred, and would be more powerful with less maintenance.}} +@maintend @helpwanted @@ -158,7 +160,8 @@ More information about each can be found in their respective section. @node Client @section Client -@maintenance{ +@maintstart +@footnote{ The client is largely managed by a single class, @srcref{src/client/Client.js, Client}, which has grown out of control. @@ -166,6 +169,7 @@ More information about each can be found in their respective section. 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 @@ -246,7 +250,8 @@ Error state is managed by @node Program @section Program -@maintenance{ +@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, @@ -255,6 +260,7 @@ Error state is managed by With that said, it is one of the least touched classes (thus its state); developers rarely have the need to touch @code{Program}.} +@maintend @mvnotice{ The core @code{Program} class that causes maintenance concerns needs diff --git a/doc/macros.texi b/doc/macros.texi index 1464cfe..7c2d597 100644 --- a/doc/macros.texi +++ b/doc/macros.texi @@ -76,13 +76,27 @@ @c maintenance note for developers -@macro maintenance{desc} +@c +@c N.B. use @maintstart and @maintend manually if using multiple +@c paragraphs otherwise PDF output (TeX) breaks; we'll figure out +@c a better solution in the future +@macro maintstart{} @dnindex Maintenance Concern -@devnotice{This system has maintenance concerns.@footnote{ - @maintfoot{\desc\} -}} +@noticestart{dev} +This system has maintenance concerns. @end macro +@macro maintend +@noticeend +@end macro + +@macro maintenance{desc} +@maintstart +@footnote{\desc\} +@maintend +@end macro + + @c encapsulated to avoid bad TeX generation (fails compilation @c when inlined at call site) @macro maintfoot{desc} From b05d48a5720529cabc884c2391c79fb69b8c50bd Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Thu, 23 Mar 2017 09:41:59 -0400 Subject: [PATCH 25/30] doc/macros.texi (@progxml): Add macro --- doc/macros.texi | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/doc/macros.texi b/doc/macros.texi index 7c2d597..bea11be 100644 --- a/doc/macros.texi +++ b/doc/macros.texi @@ -176,3 +176,9 @@ This system has maintenance concerns. @macro xmlattr{name} @samp{@@\name\} @end macro + + +@c text to avoid repeated e.g. ties and other formatting +@macro progxml +Program@tie{}XML +@end macro From 5abfedeb542c8feb30b9c5c5a14678275e72f6e1 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Thu, 23 Mar 2017 09:42:17 -0400 Subject: [PATCH 26/30] doc/liza.css: Example block and float styling --- doc/liza.css | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/doc/liza.css b/doc/liza.css index 902eb4f..a1d3412 100644 --- a/doc/liza.css +++ b/doc/liza.css @@ -68,10 +68,18 @@ pre.example /* base3 ~ background color in light solarized theme */ background-color: #fdf6e3; padding: 0.5em; + font-size: 0.9em; } a { color: #268bd2; /* blue */ } a:visited { color: #d33682; /* magenta */ } +/** added by LoVullo Associates **/ +.float +{ + margin-block-start: 2em; + margin-block-end: 2em; +} + /* Center floating tables and images */ .float table, .float img, .float object { margin-left: auto; margin-right: auto; } From f89c311d1dede72b2363747bc48e6a554c6165b8 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Thu, 23 Mar 2017 09:50:59 -0400 Subject: [PATCH 27/30] doc/liza.texi: Add predicate system documentation --- doc/design.texi | 112 ++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 112 insertions(+) diff --git a/doc/design.texi b/doc/design.texi index a0277ff..5e23622 100644 --- a/doc/design.texi +++ b/doc/design.texi @@ -64,6 +64,7 @@ The main components of the system are: These data are used to determine what assertions are performed, what questions and groups display, and more. + @xref{Predicate System}. @cindex Program @item Program @@ -112,6 +113,7 @@ More information about each can be found in their respective section. * Assertions:: * Bucket:: * Client:: +* Predicate System:: * Program:: * Program UI:: * Program XML:: @@ -248,6 +250,74 @@ 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 @@ -420,6 +490,48 @@ Groups support a number of @dfn{group styles} that determine how @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 + + + +@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 From bff17bdbb6487b086abccaea0155d356c2a61297 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Thu, 23 Mar 2017 10:31:42 -0400 Subject: [PATCH 28/30] doc/liza.css: Change font This imports from Google, which is a privacy risk. These should be moved to be hosted locally; their download can be scripted. --- doc/liza.css | 38 ++++++++------------------------------ 1 file changed, 8 insertions(+), 30 deletions(-) diff --git a/doc/liza.css b/doc/liza.css index a1d3412..8f28275 100644 --- a/doc/liza.css +++ b/doc/liza.css @@ -19,39 +19,17 @@ along with Octave; see the file COPYING. If not, see . */ -/* Import web font Roboto Condensed, Font Library Version 2015-06-06 */ -@font-face { font-family: 'Roboto Condensed'; src: local('Roboto Condensed Bold'), local('RobotoCondensed-Bold'), - url('https://fontlibrary.org/assets/fonts/roboto-condensed/71405335c70332d94afd24ae4f06c9b2/4b8b4b377e8cb358cf886d13c7bb287c/RobotoCondensedBold.ttf') format('truetype'); - font-weight: bold; font-style: normal; } -@font-face { font-family: 'Roboto Condensed'; src: local('Roboto Condensed Bold Italic'), local('RobotoCondensed-BoldItalic'), - url('https://fontlibrary.org/assets/fonts/roboto-condensed/71405335c70332d94afd24ae4f06c9b2/9b1d05d1b332e5b95ad86e71ca8404fb/RobotoCondensedBoldItalic.ttf') format('truetype'); - font-weight: bold; font-style: italic; } -@font-face { font-family: 'Roboto Condensed'; src: local('Roboto Condensed Italic'), local('RobotoCondensed-Italic'), - url('https://fontlibrary.org/assets/fonts/roboto-condensed/71405335c70332d94afd24ae4f06c9b2/d02fffb6890e4f28023dd149916d1b8a/RobotoCondensedItalic.ttf') format('truetype'); - font-weight: normal; font-style: italic; } -@font-face { font-family: 'Roboto Condensed'; src: local('Roboto Condensed Regular'), local('RobotoCondensed-Regular'), - url('https://fontlibrary.org/assets/fonts/roboto-condensed/71405335c70332d94afd24ae4f06c9b2/b0b1845ecce8ab6a503971e808a8409c/RobotoCondensedRegular.ttf') format('truetype'); - font-weight: normal; font-style: normal; } - -/* Import web font Fantasque Sans Mono, Font Library Version 2016-04-05 */ -@font-face { font-family: 'Fantasque Sans Mono'; src: local('Fantasque Sans Mono Bold'), local('FantasqueSansMono-Bold'), - url('https://fontlibrary.org/assets/fonts/fantasque-sans-mono/b0cbb25e73a9f8354e96d89524f613e7/a46033d3a07d9385620dc83b7655203f/FantasqueSansMonoBold.ttf') format('truetype'); - font-weight: bold; font-style: normal; } -@font-face { font-family: 'Fantasque Sans Mono'; src: local('Fantasque Sans Mono Bold Italic'), local('FantasqueSansMono-BoldItalic'), - url('https://fontlibrary.org/assets/fonts/fantasque-sans-mono/b0cbb25e73a9f8354e96d89524f613e7/b0683ef4c834908aa372ec78dea42349/FantasqueSansMonoBoldItalic.ttf') format('truetype'); - font-weight: bold; font-style: italic; } -@font-face { font-family: 'Fantasque Sans Mono'; src: local('Fantasque Sans Mono Italic'), local('FantasqueSansMono-Italic'), - url('https://fontlibrary.org/assets/fonts/fantasque-sans-mono/b0cbb25e73a9f8354e96d89524f613e7/b78d0a48e4443f797e8d45dcf97594f7/FantasqueSansMonoItalic.ttf') format('truetype'); - font-weight: normal; font-style: italic; } -@font-face { font-family: 'Fantasque Sans Mono'; src: local('Fantasque Sans Mono Regular'), local('FantasqueSansMono-Regular'), - url('https://fontlibrary.org/assets/fonts/fantasque-sans-mono/b0cbb25e73a9f8354e96d89524f613e7/f3fdc4f0f26e4431f54e8b552d55480c/FantasqueSansMonoRegular.ttf') format('truetype'); - font-weight: normal; font-style: normal; } +/** modified by LoVullo Associates **/ +/** TODO: loading fonts from Google is a privacy issue; download as part + of build and self-host **/ +@import url('https://fonts.googleapis.com/css?family=Noto+Sans'); +@import url('https://fonts.googleapis.com/css?family=Roboto+Mono'); /* Use custom fonts */ -code, kbd, samp, tt, pre { font-family: 'Fantasque Sans Mono', monospace; } +code, kbd, samp, tt, pre { font-family: 'Roboto Mono', monospace; } code, kbd, samp, tt { font-style: italic; padding: 0 0.1ex; /* slightly increase margin to surrounding text */ } -body, .sansserif { font-family: 'Roboto Condensed', sans-serif; } -h1, h2, h3, h4, h5, .menu-comment, .roman, .menu-preformatted { font-family: 'Roboto Condensed', serif; } +body, .sansserif { font-family: 'Noto Sans', sans-serif; } +h1, h2, h3, h4, h5, .menu-comment, .roman, .menu-preformatted { font-family: 'Noto Sans', serif; } /* Use colors from the solarized color theme (sparsely), From 7c6b8848955ff4047f5bd42ef5d0cee816c4d745 Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Thu, 23 Mar 2017 10:38:22 -0400 Subject: [PATCH 29/30] doc/design.texi (Group Styles): Put table into float --- doc/design.texi | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/doc/design.texi b/doc/design.texi index 5e23622..dd03d04 100644 --- a/doc/design.texi +++ b/doc/design.texi @@ -430,7 +430,9 @@ 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? @@ -483,6 +485,8 @@ Groups support a number of @dfn{group styles} that determine how @tab@center Y @tab@center Y @end multitable +@caption{Group styles and index support} +@end float From 632ffe74c03bb6f78cb152754f61c646d01f491c Mon Sep 17 00:00:00 2001 From: Mike Gerwitz Date: Thu, 23 Mar 2017 12:18:41 -0400 Subject: [PATCH 30/30] .gitlab-ci.yml: Add --with-srcuri to build step --- .gitlab-ci.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.gitlab-ci.yml b/.gitlab-ci.yml index 68d0917..3802814 100644 --- a/.gitlab-ci.yml +++ b/.gitlab-ci.yml @@ -12,7 +12,7 @@ build: stage: build script: - autoreconf -fvi - - ./configure + - ./configure --with-srcuri="$SRCURI" - npm install - make all check info pdf html artifacts: