ossp-pkg/tabea/tabea-brainstorming
1.3
About structured editing
========================
Terminology
-----------
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
-----
- 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 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.
- 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
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.
Syntax
------
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)
visible
description
helptext
helpurl
activate
item {
name (mandatory)
visible
description
helptext
helpurl
activate
verify
type
value {
name (mandatory)
visible
description
helptext
helpurl
activate
checked
selected
};
};
};
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 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
no help link is shown at all.
The helpurl is the URL to a help page describing the item.
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 select element is a flag to highlight the value in the menu.
All types by example
--------------------
Possible types are taken from RFC1866, Section 8.1.2 - 8.1.4
8.1.2.1. Text Field: INPUT TYPE=TEXT
<p>Street Address: <input name=street><br>
Postal City code: <input name=city size=16 maxlength=16><br>
Zip Code: <input name=zip size=10 maxlength=10 value="99999-9999"><br>
item {
name street
visible "Street Address:"
type text
}
item {
name city
visible "Postal City code:"
type text[16][16]
}
item {
name zip
visible "Zip Code:"
type text[10][10]
value {
name "99999-9999"
}
}
8.1.2.2. Password Field: INPUT TYPE=PASSWORD
<p>Name: <input name=login> Password: <input type=password name=passwd>
item {
name login
visible "Name:"
type text
}
item {
name passwd
visible "Password:"
type password
}
8.1.2.3. Check Box: INPUT TYPE=CHECKBOX
<p>What flavors do you like?
<input type=checkbox name=flavor value=vanilla checked>Vanilla<br>
<input type=checkbox name=flavor value=strawberry>Strawberry<br>
<input type=checkbox name=flavor value=chocolate checked>Chocolate<br>
item {
name flavor
visible "What flavors do you like?"
type checkbox
value {
name vanilla
visible "Vanilla"
checked
}
value {
name strawberry
visible "Strawberry"
}
value {
name chocolate
visible "Chocolate"
checked
}
}
8.1.2.4. Radio Button: INPUT TYPE=RADIO
<p>Which is your favorite?
<input type=radio name=flavor value=vanilla checked>Vanilla<br>
<input type=radio name=flavor value=strawberry>Strawberry<br>
<input type=radio name=flavor value=chocolate>Chocolate<br>
item {
name flavor
visible "Which is your favorite?"
type radio
value {
name vanilla
visible "Vanilla"
checked
}
value {
name strawberry
visible "Strawberry"
}
value {
name chocolate
visible "Chocolate"
}
}
8.1.2.5. Image Pixel: INPUT TYPE=IMAGE
<input type=image name=point src=map.gif>
In a form this type allows an image to be used as a substitution
for a submit button.
<img alt=\"gif not found\" src=1.gif>
item {
name point
visible "Choose a point on the map:"
type image
value {
name "map.gif"
}
}
8.1.2.6. Hidden Field: INPUT TYPE=HIDDEN (FIXME do we really need this?)
<input type=hidden name=context value="l2k3j4l2k3j4l2k3j4lk23">
item {
name context
type hidden
value {
name "l2k3j4l2k3j4l2k3j4lk23"
}
}
8.1.2.7. Submit Button: INPUT TYPE=SUBMIT
<input type=submit name=recipient value=internal><br>
<input type=submit name=recipient value=world>
item {
name recipient
type submit
value {
name internal
}
value {
name world
}
}
8.1.2.8. Reset Button: INPUT TYPE=RESET
You may clear the form and start over at any time: <input type=reset>
item {
description "You may clear the form and start over at any time:"
type reset
}
8.1.3. Selection: SELECT
8.1.3.1. Option: OPTION
<SELECT NAME="flavor" SIZE="2">
<OPTION>Vanilla
<OPTION>Strawberry
<OPTION value="RumRasin">Rum and Raisin
<OPTION selected>Peach and Orange
</SELECT>
item {
name flavor
type select[2] //or type selectmultipe[2]
value {
name "Vanilla"
}
value {
name "Strawberry"
}
value {
name RumRasin
visible "Rum and Raisin"
}
value {
name "Peach and Orange"
selected
}
}
8.1.4. Text Area: TEXTAREA
<TEXTAREA NAME="address" ROWS=6 COLS=64>
HaL Computer Systems
1315 Dell Avenue
Campbell, California 95008
</TEXTAREA>
item {
name "address"
type textarea[64][6]
value {
name "HaL Computer Systems\n1315 Dell Avenue\nCampbell, California 95008"
}
}
Example: Generic RAID configuration
block {
name BEGIN
visible "RAID configurator"
description "Please configure your redundant array of independent disks now"
helptext info
helpurl http://www.raid.org
activate #always
item {
name numdrives
visible "Number of drives [1...9]"
description "enter the total number of drives in the array including redundant and spare drives"
helptext ?
helpurl http://www.counting.org/basics
activate #always
type text[1]
defaultvalue 1
verify ^[123456789]$
eval $numdrives ~= ^[123456789]$
}
item {
name raidlevel
activate numdrives~=.
type radio
defaultvalue 0
value {
name 0
visible "RAID 0"
}
value {
name 1
activate numdrives~=^[2468]$ #even
}
value {
name 4
activate numdrives~=^[3456789]$ #>=3
}
value {
name 5
activate numdrives~=^[3456789]$ #>=3
}
value {
name 10
activate numdrives~=^[48]$ #multiple of 4
}
value {
name 1+HOT
activate numdrives~=^[3579]$ #odd AND >=3
}
value {
name 4+HOT
activate numdrives~=^[456789]$ #>=4
}
value {
name 5+HOT
activate numdrives~=^[456789]$ #>=4
}
}
}
block {
name END
visible "commit suicide now"
activate numdrives~=. && raidlevel~=^[0145](+HOT)?$
item {
name "Finish"
type button
}
}
Example: Jumpstart Disk and Raid Configuration
block {
name BEGIN
visible "Disk Configuration"
description "Please configure the number of disks and the RAID"
helptext info
helpurl
activate #always
item {
name numdrives
visible "Number of drives [1...9]"
description "enter the total number of drives in the array including redundant and spare drives"
helptext ?
helpurl http://www.counting.org/basics
activate #always
type text[1]
(type popup_menu[1] )
defaultvalue 1
verify ^[12]$
}
item {
name raidlevel
activate numdrives~=.
type radio
defaultvalue 0
item
value {
name 0
visible "RAID 0"
}
value {
name 1
activate numdrives~=^[2]$ #even
}
}
item {
name sizeofdisk
}
item {
name slices
visible 'Slice definition'
item {
name slice0
visible "Definition of slice0"
item {
name size
visible "Define the size of sclice"
verify sizeofdisk - size0 - size1 ..... -size7 >= 0
}
item {
name moutpoint
visible "Define the mount point of slice"
type popup_menu[7} # Dependencies to other slice types
verify # Depencies to other slices
}
item {
name slice1
visible "Definition of slice1"
item {
name size
visible "Define the size of sclice"
}
item {
name moutpoint
visible "Define the mount point of slice"
type popup_menu[7} # Dependencies to other slice types
verify #
}
item {
name slice2
visible "Definition of slice2"
item {
name size
visible "Define the size of sclice"
}
item {
name moutpoint
visible "Define the mount point of slice"
type popup_menu[7} # Dependencies to other slice types
verify #
}
item {
name slice3
visible "Definition of slice3"
item {
name size
visible "Define the size of sclice"
}
item {
name moutpoint
visible "Define the mount point of slice"
type popup_menu[7} # Dependencies to other slice types
verify #
}
item {
name slice4
visible "Definition of slice4"
item {
name size
visible "Define the size of sclice"
}
item {
name moutpoint
visible "Define the mount point of slice"
type popup_menu[7} # Dependencies to other slice types
verify #
}
item {
name slice5
visible "Definition of slice5"
item {
name size
visible "Define the size of sclice"
}
item {
name moutpoint
visible "Define the mount point of slice"
type popup_menu[7} # Dependencies to other slice types
verify #
}
item {
name slice6
visible "Definition of slice6"
item {
name size
visible "Define the size of sclice"
}
item {
name moutpoint
visible "Define the mount point of slice"
type popup_menu[7} # Dependencies to other slice types
verify #
}
item {
name slice7
visible "Definition of slice7"
item {
name size
visible "Define the size of sclice"
}
item {
name moutpoint
visible "Define the mount point of slice"
type popup_menu[7} # Dependencies to other slice types
verify #
}
}
}
}
}
block {
name pruefen
type submit
}
block {
name clean
type reset
}
block {
name END
visible "commit suicide now"
activate numdrives~=. && raidlevel~=^[0145](+HOT)?$
item {
name "Finish"
type button
}
}
