--- tabea-brainstorming 2002/06/28 15:01:46 1.2
+++ tabea-brainstorming 2002/07/03 10:00:22 1.3
@@ -1,50 +1,63 @@
+ About structured editing
+ ========================
+
Terminology
+ -----------
- structure - structure of the user interface
- template - skeleton(s) of the output file(s) with variables which need expansion using the choices
- data - file that contains the data chosen by the user
- output - file(s) actually written out by tabea.
+ config - structure of the user interface configuration
+ template(s) - skeleton(s) of the output file(s)
+ data - file that contains the data chosen by the user
+ export(s) - file(s) actually written out by tabea.
+ import - legacy (manually edited) file to import data from
Files
+ -----
- - output
-
- One or more files being written out by tabea. It is/they are build
- from template(s) by expanding the embedded variables using lib_var
- with data from the choices file. The output files are usually
- write-only except an import function is provided to build a baseline
- of choice from a pre-existing output, which is typically the case
- when someone has maintained such a file manually before it was taken
- under tabea control or such a file is received from an external
- source.
+ - config
+
+ Menu structure configuration of the user interface. Described in
+ more detail below under "Syntax".
+
+ - template(s)
+
+ Any ASCII file using lib_var syntax for variable expansion.
- data
A single file containing all data chosen by the user. Format is one
- record per logical line. A physical line be extended to a long
- logical line using a trailing BACKSLASH just before the NEWLINE.
- Fields are separated by SPACE. Unused optional fields must be filled
- using a DASH. The following fields exist:
-
- name (mandatory)
- value (optional)
-
- A name might end with SQUARE BRACKET OPEN, any integer and SQUARE
- BRACKET CLOSE, indicating an array. If the integer or the wholly
- squre bracket construct is omited, [0] is assumed.
+ record per logical line which a name followed by an (optional)
+ value. A physical line be extended to a long logical line using a
+ trailing BACKSLASH just before the NEWLINE. Fields are separated by
+ SPACE.
- - template
+ - export(s)
+
+ One or more files being written out by tabea. It is/they are build
+ from template(s) by expanding the embedded variables using lib_var
+ and information from the data file. The output files are usually
+ write-only.
+
+ - import
- Any ASCII file using lib_var syntax for variable expansion.
+ A function may be provided to build a baseline of choices importing
+ a legacy file. This is typically the case when someone has
+ maintained such a file manually before it was taken under tabea
+ control.
- - structure of a item block
+ Syntax
+ ------
- Menu structure of the user interface. Format is one record per
- logical line. A physical line be extended to a long logical line
- using a trailing BACKSLASH just before the NEWLINE. Fields are
- separated by SPACE. Unused optional fields must be filled using a
- DASH. The following fields exist:
+ The configuration consists of one or more "blocks" which are
+ arbitrary collections of items.
+
+ Every block consists of one or more items describing the technical
+ and visible aspects of a single variable whose value is stored in
+ the data file. These values are also used when lib_var expands the
+ variables in template(s) for export.
+
+ Every item has one or more values describing the technical and
+ visible aspects of a user's choices to be assigned to an item.
block {
name (mandatory)
@@ -55,29 +68,35 @@
activate
item {
name (mandatory)
- namevisible
+ visible
description
helptext
helpurl
+ activate
+ verify
type
- defaultvalue
value {
name (mandatory)
visible
description
helptext
helpurl
- verify
- }
- }
- }
+ activate
+ checked
+ selected
+ };
+ };
+ };
- A name might end with SQUARE BRACKET OPEN, any integer and SQUARE
- BRACKET CLOSE, indicating an array. If the integer or the wholly
- squre bracket construct is omited, [0] is assumed.
+ Elements common to blocks, items and values
+ -------------------------------------------
+
+ A name matches [a-zA-Z][0-9a-zA-Z]* and is used when reading and
+ writing the data file and when expanding variables in the
+ template(s) for export.
- A description is a human readable text for name. If omited, name is
- used verbatim.
+ A visible description for humans can be specified. If omited, name
+ is used verbatim.
A helptext is a human readable text for the word "help". If omitted
and "helpurl" is set, it defaults to "help". If "helpurl" is omitted
@@ -85,22 +104,35 @@
The helpurl is the URL to a help page describing the item.
- The defaultvalue is taken if the name is omitted in the data file,
- i.e. the data file did not previously exist, was modfied through an
- external mechanism or an updated structure added a name which did
- not exist in previous versions. It is also used if the
- structure validation failed.
-
- A valuehelptext is a human readable text for the word "help". If omitted
- and "valuehelpurl" is set, it defaults to "help". If "valuehelpurl" is omitted
- no help link is shown at all.
+ An activate condition can be specified to enable a block, item or
+ value. It is a little perl program and uses perl's "eval" to find
+ out the result
+
+ Elements used in items only
+ ---------------------------
+
+ The verify is a regex to check if the data read or the user input is
+ valid. A "verify xxx" is a shortcut for "eval name =~ xxx". If used
+ together with eval both must match.
+
+ The eval is a little perl program and uses perl's "eval" to find out
+ the result. It is a more sophisticated method to check for valid
+ values. If used together with verify both must match.
+
+ The type field is explained below under "All types by example".
+
+ Elements used in values only
+ ----------------------------
+
+ A name describes the default value.
+
+ The checked element is a flag to highlight the value in the menu.
- The valuehelpurl is the URL to a help page describing the value.
+ The select element is a flag to highlight the value in the menu.
- The "verify" is a regex.
+ All types by example
+ --------------------
- The "eval" is a little perl program and uses perl's "eval" to find
- out the result.
Possible types are taken from RFC1866, Section 8.1.2 - 8.1.4
8.1.2.1. Text Field: INPUT TYPE=TEXT
|
