Index: ossp-pkg/tabea/tabea-brainstorming RCS File: /v/ossp/cvs/ossp-pkg/tabea/tabea-brainstorming,v rcsdiff -q -kk '-r1.2' '-r1.3' -u '/v/ossp/cvs/ossp-pkg/tabea/tabea-brainstorming,v' 2>/dev/null --- 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