%% intro
	INTRODUCTION

	Grok is a program to present unstructured data in a row/column format
	using an index card paradigm. Each database row (line) is a card; each
	database column (field) is an item in the card. Items can be presented
	in the card as various types and shapes. The presentation of a database
	is determined by a "form".

	The concepts of "forms" and "databases" are separate. Forms are created
	once, and determine the layout and presentation of the unstructured
	data in the database. Each form references a database. A database may
	be referenced by more than one form. To select a database for display
	and editing, use the Database pulldown (actually, the database pulldown
	lists forms, which reference the databases; the name "form" in the menu
	bar may be too non-obvious for users not concerned with the man behind
	the curtain).

	Creating or changing a form is a more involved process that needs to be
	done only when a new type of database is created. Normally, users only
	work with existing forms, using them to edit data in databases. For
	more information on creating or changing forms, refer to the User's
	Manual.

	Assuming that the form already exists, the first step is choosing a
	form (database) to display and edit. This can be done with the Database
	pulldown, or by naming the form (database) on the command line, as in

	    grok phone

	The window will resize itself to accomodate the card, and all cards
	in the database will be listed in the summary area. The first card
	will also be displayed in the card area at the bottom of the window.
	The selection of cards displayed in the summary can be changed with
	the Search button or the Query pulldown. A different card can be
	displayed in the card area by pressing the left mouse button on a line
	in the summary, or by using the next/previous arrows at the bottom
	left of the window.

	To edit a card, simply press on the inset button or green radio/flag
	button to be changed. Editable text buttons are pink, read-only text
	buttons are gray (as an exception, large "note" text entry areas are
	always gray). Shaded (grayed-out) buttons cannot be accessed because
	some condition specified by the form designer is not met. After changing
	a card, it must be written back to disk by choosing Save or Quit in the
	File pulldown. Choosing another database from the Database pulldown
	also writes back. A blank card can be added to the database by pressing
	the New button; the Delete button (irreversibly) deletes a card.

	The actual meaning of buttons and items in the card area is completely
	up to the form designer.
%% trouble
	TROUBLESHOOTING

	*  On SGI systems, if the icon doesn't show a picture, copy the icon
	    picture Grok.icon into your ~/.icons directory. If you don't have
	    one and don't want one, set the grok*noIcon resource to False in
	    your ~/.Xdefaults file. It may be necessary to restart 4Dwm to
	    register the icon after copying it to ~/.icons.

	*  The grok program uses quite a few colormap entries. Although there
	    is a black&white fallback mode, you may have problems starting other
	    programs that also need many colormap entries. The only workaround
	    is to kill grok when you don't need it.

	*  If radio and toggle buttons appear gray regardless of the colToggle
	    resource, make sure that the sgiMode resource is False.

	If you have problems you can't resolve, or if you have suggestions
	for new features, or porting instructions for new platforms, send mail
	to me at thomas@bitrot.in-berlin.de.

	IF YOU MAIL, DO NOT FORGET TO INCLUDE YOUR VERSION NUMBER
	AS REPORTED BY "grok -v". If you ask me for patches or files, also tell
	me whether you have the gzip compression program.

	Mail me to subscribe to the mailing list, grok@bitrot.in-berlin.de.
%% files
	FILES AND PROGRAMS

	Grok searches for forms and databases in four places and presents them
	in the Database pulldown in the order they are found: the current
	directory, ./grokdir, ~/.grok, and GLIB/grokdir (GLIB stands for the
	GLIB path set in the Imakefile or Makefile.alt when grok was compiled;
	the default is /usr/local/lib). The path the current database was read from
	can be displayed with Help->Database.

	Grok stores all forms in the ~/.grok directory, unless a full path is
	given in the top two lines of the form editor. Forms determine the
	presentation of data in cards. Form files have a .gf extension. By
	default, the databases themselves are stored in the path defined by
	the form if it begins with / or ~. If it doesn't, the database is searched
	for in the directory the form was read from. Databases have a .db
	extension. Multiple forms may reference the same database. Forms
	may also reference databases elsewhere, or no databases at all in the
	case of procedural databases. The ~/.grok directory also contains the
	.grokrc file, which stores preferences.

	Form files and the preferences file are strictly Ascii. Databases are
	usually also Ascii, but need not be. When editing Databases with a text
	editor, make sure to properly escape field and line delimiters with
	backslashes, or great chaos will result.

	The grok executable itself is stored in the GBIN directory; the grok.hlp
	file and the public grokdir directory (see above) are stored in the GLIB
	directory. Both GBIN and GLIB are defined in the Imakefile or Makefile.alt.
	The defaults are /usr/local/bin and /usr/local/lib, respectively.

	The distribution contains a color icon image file Grok.icon in SGI RGB
	format. It should be copied to ~/.icons. This only works on SGI systems.
	There is also a Grok.fti file that is an SGI-conforming desktop icon.
%% help
	GETTING HELP

	To get general help on a popup menu, press the Help button in that
	popup menu.

	To get help on a pulldown menu in the main window, install the pulldown
	menu by pressing and releasing the left mouse button on the menubar
	button, then press the HELP or F1 keyboard key. The Database, Sort, and
	Query pulldowns are completely determined by the author of the form
	which describes the database, they are not grok features. Grok only
	adds the "All" entry into the Query menu which puts all cards into the
	summary list.

	Help on most buttons is available by choosing "On Context" in the Help
	pulldown, and then pressing on a button or field. Every help window
	contains a Context button that does the same thing as "On Context".
%% resources
	VARIABLES AND X RESOURCES

	grok uses the following environment variables:

	   GROK_FORM defines a directory that is searched for *.gf form files to
	   be put into the database pulldown. This directory is searched first.
	   It replaces the default directory ".".

	   GROK_PATH is another directory to find files such as grok.hlp.

	   PATH is searched next if a file is not found in $GROK_PATH.

	   HOME is substituted for "~" in paths.

	   USER is used if the "user" keyword is used in an expression.

	To get a list of default X resources of the "grok" program, run it with
	the -d option. The output can be directly appended to the .Xdefaults
	file in your home directory or saved into a file "Grok" in your
	app-defaults directory. If you install a system wide app-default file
	make sure that lines do not start with "grok"; otherwise users might
	not be able to override the setup. Omit the application name or use
	the application class name "Grok".

	    noIcon: don't draw anything into the icon. This should be used on
		SGI systems so that 4Dwm uses the color picture as an icon.
		The color icon should be moved to ~/.icons/Plan.icon .
	    background: background color for all menus
	    colStd: foreground color for text
	    colSheet: background color for help and print-window windows
	    colBack: gray background color for uneditable text, and charts
	    colTextBack: pink background color for editable texts
	    colToggle: color of toggle and flag buttons
	    colCanvBack: background of card canvas in form editor
	    colCanvFrame: color of item frames in card canvas in form editor
	    colCanvBox: blue item box color in card canvas in form editor
	    colCanvSel: yellow for selected items in card canvas in form editor
	    colCanvText: color of text in items in card canvas in form editor
	    colChartAxis: color of X/Y axis and axis labels of charts
	    colChartGrid: color of grid lines subdividing charts
	    colChartBox: color of outline of bars in charts
	    colChart0..7: available colors of chart bars
	    sgiMode: if False on IRIX 5.x systems, do not use the desktop look
	    useSchemes: on IRIX 5.x systems, Lascaux or some other color scheme
	    menubar*fontList: font for menubar and pulldowns
	    fontList: default font for buttons and titles
	    helpFont: small font used for help windows
	    helvFont: "Helv" font used in cards if selected in form editor
	    helvObliqueFont: "HelvO" font used in cards if selected in form editor
	    helvSmallFont: "HelvS" font used in cards if selected in form editor
	    helvLargeFont: "HelvB" font used in cards if selected in form editor
	    courierFont: "Courier" font used in cards if selected in form editor,
		must be fixed-width, is also used in the summary
	    labelFont: font used for charts
%% help_ctx
	CONTEXT

	To get help for a button, press the Context button, and then the
	button you need help for. This button is equivalent to the On Context
	item in the help pulldown.
%% help_done
	DONE

	Remove the help popup.
%% pd_file
	FILE PULLDOWN

	Print:
	     Print selected cards to printer or files.

	Preferences:
	     Pops up a window that allows changing the global configuration.

	Form Editor:
	     Edit current form:
	        Start the form editor on the current database. Editing forms
	        means to change the representation of the data in a card, the
	        layout and types of card items and the summary format can be
	        changed. The "form" is the description of the representation
	        of data, while the "database" is a file containing unstructured
	        data. Note that editing forms is a rather complicated procedure,
	        compared to using the main menu.

	     Create new form from scratch:
	        Clear the main menu and start the form editor with no preset
	        form. This is used to start a new form that is different from
	        all existing forms. The new form will be put into the Database
	        pulldown when it is finished.

	     Create, use current as template:
	        Start the form editor. The current form as selected from the
	        Database pulldown provides the defaults. A new form name must
	        be entered. This is used to start a new form that is more or
	        less similar to an existing form.

	About:
	     Pops up a window displaying the program version and an address
	     to complain to if something doesn't work.

	Save:
	     Save the current database unconditionally, whether it was modified
	     or not. If it was modified, the fact is noted under the Search line. The
	     database is also saved if it was modified when Quit is chosen, or if
	     a new database is selected from the Database pulldown, or if a form
	     editor is started.

	Quit:
	     Save the current database if it was modified, and exit. This is equivalent
	     to double-clicking the mwm corner button. Warning - if grok runs
	     under twm, window manager kills will NOT save, and exit without
	     warning.

	Rambo Quit:
	     Quit without saving. Changes made to cards after the last Save
	     will be lost. You will be asked to confirm if changes were made.
%% rambo
	RAMBO QUIT

	You have made changes to the current database that have not been
	saved to disk. If you want to discard these changes, press OK. If
	you want to save the changes, press Cancel, and choose Quit from
	the File pulldown.
%% pd_dbase
	DATABASE PULLDOWN

	Strictly speaking, the pulldown name is a misnomer. Databases are
	unstructured data that need a "form" for defining the presentation
	in a card. The Database pulldown selects a form, which in turn
	references the database itself. For the casual user, this distinction
	is of no consequence, and "Database" seemed to be a more obvious
	name.

	Grok searches for databases in four places and presents them in the
	Database pulldown in the order they are found: the current directory,
	./grokdir, ~/.grok, and GLIB/grokdir (GLIB stands for the GLIB path set
	in the Imakefile or Makefile.alt when grok was compiled; the default
	is /usr/local/lib). Help->Database can be used to show the actual path
	the database was read from, and will be saved to if it is modified.

	All files ending in .gf will be put into the database pulldown, with
	the .gf removed. Choosing an item will load the new form and the
	database it references. The window will resize to fit the new card.

	If the current database was modified when a new database is loaded,
	it is written back to disk first, as if File->Save had been used.

	If the form specifies a default query (added with the Queries button in
	the form editor), only a subset of available cards may be displayed in
	the summary initially. Use Query->All to show all cards.
%% pd_section
	SECTION PULLDOWN

	Databases can be divided into sections. If the database file is a
	directory, every file in it or its subdirectories becomes a section.
	When a database is read, all its section files are read. The section
	pulldown can be used to select one or all sections for display in the
	summary list in the main window.

	If the database has sections, it is necessary to select a section
	before adding a card. The new card will be put into the current
	section. The card can be moved to another section later with the
	section popup button to the right of the "Delete" button at the
	bottom of the main window (this button only appears if grok is
	compiled with Motif library version 1.2 or greater).
%% pd_sort
	SORT PULLDOWN

	Sorts the database by a named database item. The database has no
	inherent order; new cards are simply appended to the end, and a
	database saved (File->Save) after sorting will come up in the same
	order is had when it is reloaded unless the form has a built-in default
	sort (defined with the form editor).

	When sorting, leading white space is skipped. If both strings to
	compare are numeric (begin with a digit or a period), they are
	compared numerically. Otherwise, they are compared lexicographically.
	Note that columns of type Date, subtype Time contain both date and
	time, although only the time is shown. The date does figure in the
	sort order.

	Most databases have a default sort order that was specified when the
	form was created. When sorting by another column, the default column
	becomes the secondary sort criterium. That is, if a rolodex normally
	sorted by name is re-sorted by group, each group will be sorted by
	name internally.
%% pd_query
	QUERY PULLDOWN

	The items of this pulldown determine which cards are shown in the
	summary. The list always begins with All, which puts all available
	cards into the summary. All other items were defined by the designer
	of the form. Except for the "All" query, queries either search all
	cards for matches, or only those already in the summary (if incremen-
	tal searches are enabled in the File->Preferences menu).

	To change, add, or delete queries, choose File->Form editor->Edit
	current form, and press the Queries button. That menu also allows you
	to choose a query that is done automatically when the database is
	loaded. Choose Help->Expression grammar for an explanation of query
	expressions.

	The search button near the top of the main window offers an alternative
	way of selecting a set of cards to display in the summary. Optionally,
	queries from the Query pulldown can be shown as search strings. Choose
	File->Preferences and press Help for details.
%% search
	SEARCH

	Enter a search string and press Return to select a subset of cards to
	be displayed in the summary below the search button. After searching,
	any card can be chosen from the summary by pressing on a line. All
	items of a card are searched that permit searching (this was defined
	when the form that controls the presentation of the card was created).
	Searching is a simple string search. All cards in the database are
	searched for matches, unless incremental searches are enabled in the
	File->Preferences menu, in which case only those cards already in the
	summary are searched.

	The last 20 searches are remembered and can be retrieved using the
	previous/next arrow buttons. The Search button is equivalent to
	pressing the Return key in the search string area. Optionally, queries
	from the Query pulldown can be shown as search strings, see the
	File->Preferences popup.

	If the search string begins with an opening parenthesis or an opening
	brace, text searching is replaced by an expression search. All cards
	for which the expression does not return an empty string or a string
	beginning with 'f' (if the expression begins with '{') or a numeric value
	0 (if the expression begins with '('). For an explanation of expressions
	and the difference between '{' and '(', choose the Expression Grammar
	item in the Help pulldown.

	If the search string is "*", all cards are put into the summary. This
	is equivalent to selecting "All" from the Query pulldown.

	All other strings are searched for. Case is not significant.
%% addsect
	ADD SECTION

	Databases can have multiple sections, each containing zero or more
	cards. Each section is written to a separate file in a directory
	~/.grok/databasename. When a section is added, a new empty file is
	created in this directory, with the name of the section followed by
	the extension ".db". If the database did not have sections, the
	directory is created and all cards are moved into the new section;
	otherwise the new section is empty. No sections can be added to a
	procedural database.

	Press the Add button to add the new section, or Cancel to abort.
%% info
	INFO LINE

	Displays the form (database) name, the number of cards in the summary,
	and the total number of cards. If the database has been modified since
	it was loaded, "(modified)" is displayed. If the database cannot be modified
	because either the database file has no write permission or because the
	form designer specified that the database is read-only (near the top of the
	form editor window), "(read-only)" is displayed.

	For more information about the current form and database, choose the
	Database item from the Help pulldown. For an explanation of the
	difference between forms and databases, choose Help->Introduction.
%% pos
	NEXT/PREV

	Switch to the next or previous card, by scrolling the highlight in
	the summary up or down. Cards not shown in the summary will be
	skipped. To display all cards in the summary, choose All in the
	Query pulldown.
%% new
	NEW

	Create a new blank card. The new card is appended to the end of the
	database; use the Sort pulldown to re-sort. The summary is cleared.
%% del
	DELETE

	Delete the current card.
%% dup
	DUP

	Create a copy of the current card, append it to the end of the
	database, and display it in the card window for editing. Use the
	Sort pulldown to re-sort.
%% sect
	SECTION

	The button displays the section the current card belongs to, if
	there are sections. Press to get a list of defined sections; drag
	the mouse and release to select a section. The card will be moved
	to that new section. If there are no sections, this button stays
	blank. Sections that came from files without write permission are
	grayed out in the popup.
%% summary
	SUMMARY

	The summary shows one line for each card that satisfies the selection
	done with the Search button or the Query pulldown. The layout is
	determined by the form, which can be changed with File->Edit Form.
%% letters
	LETTERS

	These buttons select all cards whose sorted column begins with the
	respective character. The sorted column is the column the database was
	last sorted by, using the Sort pulldown. Most databases get default-
	sorted when loaded. The search ignores all whitespace and punctuation
	characters except underscores. The letters row can be turned off with
	the File->Preferences menu.

	If the `Letter search checks all words' flag in the Preferences menu
	is on, the letter search is modified such that the first letter of all
	words, instead of just the first word, in the sorted column is checked.
	This is useful for people's names to search for first and last initial.

	The "misc" button selects all empty columns or words that begin
	with underscores or digits.
%% card
	CARD

	The card shows a single line of the database chosen with the Database
	pulldown. First, select a set of cards, using the Search button or the
	Query pulldown. Choose a card from the resulting summary listing by
	selecting it, or use the next/previous arrows to scroll. The New button
	adds an empty card to the database. After editing the card, write the
	database back to disk using the File->Save or File->Quit buttons, or
	by selecting another database from the Database pulldown. For more
	details, choose Introduction from the Help pulldown in the top right corner.
%% print
	PRINT

	The print menu prints selected cards of the current database. Databases
	can be selected with the Database pulldown. The order of the cards printed
	is the same as in the summary list. The data is printed by writing to stdin
	of the spooler commands as defined with the Preferences menu, or to a
	file, or to a window.

	Cards to print: selects which cards should be printed. Current only
	    prints only the card currently displayed in the lower half of the
	    main menu. Search or query prints all cards displayed in the
	    summary window in the upper half of the main menu, and All
	    prints all cards.

	Output format: specifies which information to include in the printout.
	    Summary generates a simple hardcopy of the summary list in the
	    main menu. Summary with notes prints all note fields in addition
	    to the summary line, as text blocks below the respective summary
	    line. Cards prints all printable data fields in a two-column list.

	Output quality: ASCII prints straight ascii text; overstrike ASCII is
	    equivalent but uses backspacing to achieve boldface and underlines;
	    and PostScript attempts to improve readability by using different fonts
	    and lines. Overstrike output is understood by programs such as more
	    or less. This setting determines whether the PostScript print spooler
	    or the ASCII print spooler, as defined in the Preferences menu, is used.

	Output device: Printer sends the data to the spooler as defined in the
	    Preferences menu. File writes to a file, and Window creates a
	    window and displays the data.

	The Print button starts the operation; the Cancel button removes the
	Print popup without generating output. Changed settings in the menu
	are remembered either way.
%% editprint
	PRINT WINDOW

	This window was created with the File->Print function. In the print
	panel, the output device was set to Window. Other choices are Printer
	or File. This window is supposed to be a preview. Only plain ASCII
	can be displayed. The contents reflect the selection in Cards to
	print in the print panel. Once installed, the window does not change.
%% msg_clear
	CLEAR

	Delete all contents of the editor window. If a file is being displayed,
	it is not deleted; if Clear is pressed by accident use Cancel.
%% msg_delete
	DELETE

	Delete all contents of the editor window, and terminate the editor.
	If a file was being displayed in the window, it is deleted on disk.
%% msg_cancel
	CANCEL

	Discard all changes to the text and exit the editor without saving.
%% msg_done
	DONE / SAVE

	This button is labelled "Save" if the text is editable, and "Done"
	if not. "Save" writes the changes back and terminates the editor.
	"Done" dismisses the window without saving.

	This is equivalent to double-clicking the window manager button in
	the top left corner of the window decoration.
%% pref
	PREFERENCES

	The preferences menu changes global configuration. The configuration
	data is written to the ~/.grok/.grokrc file when the Done button is
	pressed.

	12-hour mode toggles the format of Date items in the card to either
	    12-hour am/pm format, or to 24-hour format.

	Month/day/year mode toggles the format of Date items in the card to
	    either mm/dd/yy format, or to dd.mm.yy format. It also provides
	    the default interpretation of input or file dates that contain neither
	    slashes nor dots.

	Show query search expression, if turned on, will display the search
	    expression used by a query when an item from the Query pulldown
	    (other than All) is selected. The query expression can then be
	    modified manually and re-applied using the Search button.

	Enable search by initial letter, if enabled, inserts a row of buttons
	    A..Z, `misc', and `all' below the summary that select all cards
	    whose sorted column begins with the respective character. The
	    sorted column is the column the database was last sorted by, using
	    the Sort pulldown. Most databases get default-sorted when loaded.
	    The search ignores all whitespace and punctuation characters
	    except underscores.
	    NOTE: changing this mode takes effect only when grok is restarted.

	Incremental searches and queries, if enabled, base every new search,
	    query, and letter search on the results of the previous. Instead
	    of searching all cards, only those displayed in the summary are
	    searched. This does not apply to the "All" search; it always puts
	    all cards into the summary.

	Letter search checks all words: this flag modifies the letter search,
	    if enabled, such that the first letter of all words in the sorted
	    column is checked. This is useful for people's names to search for
	    first and last initial.

	Print spoolers: the system command that is used to print PostScript or
	    ASCII, respectively. The print mode depends on the Print Quality
	    setting in the Print menu. Typical settings are lp (System V) or
	    lpr (BSD). ASCII and PostScript spoolers can be set independently
	    in case special PostScript options or lptops scripts need to be
	    run. Full shell syntax (using the shell in $SHELL) is supported,
	    including pipes and redirections.
	
	Summary lines: the number of lines displayed in the summary window below
	    the search area. This choice takes effect only when grok is restarted.

	Card scaling factor: if the screen resolution is very low, it may be
	    necessary to enter a number less than 1 to reduce the sizes of items
	    in the card at the bottom of the screen. 0.75 or 0.5 are recommended.
	    This takes effect only when the next database is loaded.
%% pref_done
	DONE

	Remove the preferences menu, and write the changes back to
	the ~/.grok/.grokrc file.
%% queries
	DEFAULT QUERIES

	There are four columns of buttons:

	- If the button in the first column is off, the query is disabled. The
	  query will stay in the Default Query popup, but will not appear in
	  the Query pulldown in the main window.

	- Only one button can be on in the second column. The column with
	  this button on, if any, selects the query that is executed when the
	  database is read from disk. If no button in the second column is on,
	  no query is done on startup and all cards are shown in the summary
	  (unless a query was specified on the command line). The button in
	  the first column need not be on for a default query.

	- The Name column specifies the string that will be displayed in the
	  Query pulldown in the main window.

	- The Query Expression column specifies an expression that determines
	  which cards to display in the summary when <Name> is selected in the
	  Query pulldown in the main window. The expression is applied to all
	  cards in the database in turn, and all cards that match are put into
	  the summary. An expression is said to match if it begins with a '{'
	  and returns a non-null string that does not begin with 'f' after stripping
	  leading white space; or if it begins with '(' and returns a string that is
	  not numerically equal to zero.

	For a description of legal search expression, choose Help->Grammar, or
	refer to the User's Manual.
%% dq_delete
	DELETE

	To delete a query, press on its Name or Query Expression button, and
	press the Delete button. Pressing Delete again will delete the next
	query which took the previously deleted query's place. Delete cannot
	be undone.
%% dq_dupl
	DUPLICATE

	To duplicate a query, press on its Name or Query Expression button, and
	press the Duplicate button. The new query will be inserted just below
	the duplicated query. After duplicating, edit the Name and Expression.
%% dq_done
	DONE

	Remove the Default Query popup. The queries will be written into the
	form file in when the Done button is pressed in the Form Editor window
	(which contains the Queries button that installed the Default Query
	popup).
%% edit
	FORM EDITOR

	A form is a description of a card, which presents the contents of a
	database. A database is just an anonymous two-dimensional array of
	strings. The first step when creating a form is naming the form and
	the database it presents. The form name is the name that appears in
	the Database pulldown in the main menu (it's called the Database
	pulldown because users need not be aware of the distinction between
	forms and databases). The database is named separately.

	Both the form name and database names are also the file names the
	form and the database will be stored in. The form name gets the
	extension ".gf", and non-procedural databases get the extension ".db"
	tacked on if the names are not fully qualified (i.e., do not begin with
	/ or ~). The default directory for forms is ~/.grok and the default
	directory for databases is the directory the form was read from. See
	the Help->Database popup to see which paths are actually used.

	The next step is specifying the field delimiter. Databases are two-
	dimensional arrays of strings. Rows are separated by newlines and
	columns are separated by the field delimiter. Default is a colon.
	The /etc/passwd file, for example, is an example of a database with a
	colon as the field separator. The \t and \123 notations are supported.

	A read-only database does not permit the user to use the Save item
	in the File pulldown; it will not be possible to change the database.
	Procedural databases are not read from a file but from a program; the
	database string is a shell string that grok will call with a first argument
	"-r" (when reading the database) or "-w" (when saving the database),
	and the form name as entered in the top line as second argument.

	The comment should contain the author of the form and its version.



	CANVAS

	After specifying the general form parameters, fields can be added to
	the form canvas, or existing fields can be clicked in the canvas and
	modified or deleted. The canvas is a separate window that contains
	a simplified representation of the card as it will appear in the main
	menu when loaded. Changing the size of the canvas window will change
	the size of the card. It is often a good idea to start with a window
	size that is too large and shrink it as the last step.

	The canvas has two sections, the "static" part at the top and the
	"card" part at the bottom. Both are separated by a divider that can be
	dragged vertically by clicking and dragging the small square sash near
	the right end of the divider line, which is at the top edge of the
	canvas by default. Fields placed above the divider go into the static
	part; fields placed below the divider go into the card part. The static
	part stays active and sensitive independently of the card being
	displayed; general statistics and card-independent buttons are normally
	placed here. The card part changes with every new card that is selected,
	fields that display data from the card must be in this part.

	The static and card part are very similar. Generally, fields of type
	Input, Time, Note, Choice, Flag, and everything else (such as Print)
	that refers fields in the current card (using expression terms such as
	"_fieldname") must go into the card part so it can be desensitized if
	no card is selected. Putting such fields in the static part would allow
	the user to enter data into nonexisting cards because the field would
	not get desensitized when no card is displayed. This is not enforced.



	FIELDS

	Fields are either choice or toggle buttons or text entry buttons that
	represent a string in the database, or decorative fields such as
	labels, or text strings that compute values based on strings in the
	database (any string, not just one in the current card). There are
	various options for fields that can be specified in the inset control
	area in the lower section of the form editor. Note that the Choice
	type is the only one that is not autonomous; Choice fields are linked
	with other Choice fields such that only one of the Choice fields with
	identical names can be active at any time. In all other cases, no two
	fields can have the same name.

	For a detailed description of the different types of fields, and for a
	description of the grammar of the simple query language that can be
	used for defaults or queries, see the programmer's manual that is
	distributed as a PostScript document as part of the release. The
	Help->Grammar popup in the main window gives a quick reference.



	BUTTONS

	A preview function is available for viewing the card as it will appear
	in the main window. The Done button saves the form and exits the form
	editor. Before saving, the form will be checked; a window with error
	messages will appear and the form editor will refuse to save if the
	form contains errors. The form can also be checked with the Debug
	button; no window will appear if no errors are found. The Cancel button
	will discard the edited form and exit the form editor without saving.

	The Queries button allows entry of the queries that appear in the
	Queries pulldown in the main menu. Queries are search expressions
	that select a certain subset of available cards, and put the cards
	that satisfied the expression in the summary for the user to select.

	The Def Help button attaches a help text to the form. An editor is
	started that allows entering a text describing the current form, and
	how to use the fields and buttons. This help text will be displayed
	when the user presses the Help button in the lower right corner of
	the main window, in addition to some general text that grok adds.
%% form_cancel
	CANCEL

	Press OK to exit the form editor without writing changes to disk,
	if you made any. (The confirmation popup will appear even if the
	form did not change.)
%% procdbedit
	PROCEDURAL DATABASE

	If the Edit button in the form editor is pressed, the `procedural' flag
	is turned on. The form's data will then read the database by executing
	a script rather than by opening a file. This editor window lets you
	edit this script.

	Scripts should always begin with a line containing
	
	  #!/bin/sh 
	
	or something similar. The script gets two arguments when executed:
	$1 is either "-r" or "-w". If $1 is "-r", the script is supposed to print
	the generated database data to stdout, using echo or something
	similar, one card per line consisting of fields separated by the form's
	field delimiter character (a colon `:' by default). Trailing blank fields
	and trailing field delimiters can be omitted. If $1 is "-w", grok will print
	the database in the same format to stdin of the script, without trailing
	blank fields or colons. The second argument, $2, is the name of the
	form as entered in the top button in the form editor window, without
	path and without ".gf" extension.

	The permissions of the file will be changed to 700 (read, write,
	execute for the owner only) when it is written back.

	There is no way to return error conditions.
%% fe_form
	FORM AND DATABASE NAME

	The form name is the name that appears in the Database pulldown
	in the main menu (it's called the Database pulldown because users
	need not be aware of the distinction between forms and databases).
	A database is always referenced by the name of the form that
	describes its layout. When a new form or database is created, a
	new unique name must be chosen.

	Both the form name and database names are also the file names the
	form and the database will be stored in. The form name gets the
	extension ".gf", and non-procedural databases get the extension ".db"
	tacked on if the names are not fully qualified (i.e., do not begin with
	/ or ~). If the database is procedural, the database file is a script, and
	has no .db or any other extension. This script is executed to read or
	write data. See help on the Edit button for details.

	When a database or form is read, the path it was read from is stored;
	when the database or form is changed, it is written back to that path.
	When a new database is created, and its name does not begin with /
	or ~ as defined in the second line of the form editor, it is stored in
	the same directory as its form file. The default is always ~/.grok.
	See the Help->Database popup to see which paths are actually used.
%% fe_delim
	DATABASE FIELD DELIMITER

	Databases are two-dimensional arrays of strings; rows are separated
	by newlines and columns are separated by the field delimiter. Default
	is a colon. The /etc/passwd file, for example, is an example of a
	database with a colon as the field separator. \t and \123 notations are
	accepted. \0 and \n cannot be used as field delimiters.
%% fe_rdonly
	READ ONLY

	If set, the database is read-only and cannot be written back using the
	File->Save function. The effect is similar to what happens if the user
	has no write permission for the database file.
%% fe_proc
	PROCEDURAL, EDIT

	Procedural databases are not read from a file but from a program; the
	database string is a shell string that grok will append "-r" (when
	reading the database) or "-w" (when saving the database) to, followed
	by the form name. That is, when the database "x" (as specified in the
	"Referenced database" field) is read and "procedural" is on, grok will
	execute "x -r formname", and expect "x" to echo a delimiter-separated
	list of strings to stdout. Unless the database is read-only, the script
	must accept data on stdin if it is run as "x -w formname".

	An executable can be used in place of a script, but then the Edit
	button cannot and should not be used.
%% fe_query
	QUERIES

	The Queries button allows entry of the queries that appear in the
	Queries pulldown in the main menu. Queries are search expressions
	that select a certain subset of available cards, and put the cards
	that satisfied the expression in the summary for the user to select.
%% fe_help
	DEF HELP

	The Def Help button attaches a help text to the form. An editor is
	started that allows entering a text describing the current form, and
	how to use the fields and buttons. This help text will be displayed
	when the user presses the Help button in the lower right corner of
	the main window.
%% fe_debug
	DEBUG

	Check the form for inconsistencies, and display an error and warning
	popup if problems are found. No popup will appear if the form is free
	of errors. The Done button will do the same checks, and will refuse
	to exit the for editor if problems are found.
%% fe_preview
	PREVIEW

	Display a menu with a card as it will appear in the main window. The
	card is not interactive and does not display valid database contents,
	but will show labels with the correct dimensions. This is useful to
	determine whether all labels fit into their allocated size; the canvas
	is not always a good indicator for this.

	The preview window will remain on the screen, unchanged, until the
	window manager button in the top left corner of the decoration is
	double-clicked.
%% fe_cancel
	CANCEL

	Terminate the form editor without writing back changes. All changes
	that have been made since the form editor was installed are discarded.
	To avoid accidentally losing the changes, a confirmation popup is
	installed; this popup is installed even if no changes have been made.
%% fe_done
	DONE

	Check the form. If no errors are found, write the form back to disk
	and terminate the form editor. If errors are found, an error popup lists
	the problems, and the form editor is not terminated. The form editor
	can be terminated without writing back with the Cancel button.
%% fe_add
	ADD

	Add a field to the form. The currently selected field, if any (high-
	lighted yellow on the canvas), is duplicated, and reasonable defaults
	are filled in. The new field is put below the bottom field in the
	canvas. If the canvas is too small, it may be positioned off-window
	where it cannot be seen; make the canvas larger in this case.

	After adding, the new field is selected, and the buttons below the Add
	button can be used to specify type and attributes of the new field.
%% fe_delete
	DELETE

	Delete the currently selected field. The selected field is highlighted
	yellow on the canvas.
%% fe_type
	FIELD TYPE

	The type of the field. The type determines the appearance of the field
	as well as its behavior and connection to the database. Some fields
	are connected directly to database fields, others are derived or purely
	decorative. The types are:

	Input:  this field allows direct display of database strings. User
	        input into this field is copied directly into the database.

	Time:   this type is equivalent to Input fields, except that only
	        date, time, and duration are displayed and can be entered.
	        Four different formats can be selected with Time format.

	Note:   this type is also equivalent to Input fields, but supports
	        multi-line text. Scrollbars will be displayed if the text
	        does not fit into the defined space.

	Label:  labels are purely decorative. They are static, no expressions
	        can be used for dynamically changing the text. Many other field
	        types, such as Input, come with built-in labels.

	Print:  print fields look like Input fields, but display the result of
	        evaluating an expression. No data can be entered into Print
	        fields, they are always read-only.

	Choice: all Choice fields that have the same internal field name are
	        implicitly connected to the same database string. Only one of
	        them can be on. The choice/flag code of the Choice item that
	        is on is stored in the database.

	Flag:   flag fields are similar to Choice fields, but they are not
	        connected to other Flag fields, and must have a unique internal
	        name. Their choice/flag code is stored in the database if the
	        flag is on. The database string is empty if the flag is off.

	Button: buttons execute an expression when pressed.

	Chart:  chart fields display statistics in a bar chart. No input is
	        possible.

	When the type of an existing field is changed, attributes not
	applicable to the new field type will disappear from the menu but
	will be remembered internally, and will be restored when the type is
	changed back, until another form or database is loaded.
%% fe_flags
	FLAGS

	Searchable:   all fields marked searchable will be searched when a
	              search string is used in the main menu. Searching means
	              that the referenced database field will be searched, and
	              the card will be put into the summary if a match is found.

	Read only:    if set, no data can be entered. Read-only input or time
	              fields are displayed with a gray background.

	Not sortable: fields that are not sortable will not appear in the Sort
	              pulldown in the main menu.

	Default sort: only one field can have the default sort flag set. This
	              field is the field the database will be sorted by when
	              the database is loaded from disk. It is also the secondary
	              sort criterium if the user re-sorts the database with the
	              Sort pulldown.

	If a flag of a Choice item is changed, the same flag of all Choice
	items with the same internal field name is also changed.
%% fe_int
	INTERNAL FIELD NAME

	The internal field name is a unique identifier for a field. Fields that
	reference a database column, such as Input or Flag fields, implicitly
	name the database column. For example, if database column 3 is shown
	in an Input field named "three", then the database column 3 can be
	referenced in expressions as either "_3" or "_three". The first database
	column is number 0.

	Choice fields are an exception to the uniqueness rule. Multiple Choice
	fields can share an internal field name. All choice fields with the same
	field name write into the same database column (which means that
	their Database column number must also agree). Grok makes sure that
	only one of the choice fields with matching field names is on at any
	time. When changing attributes such as flags or input defaults of a
	Choice item, all other choice items with the same name also change.

	The field name is a constant. No expression is allowed.
%% fe_column
	DATABASE COLUMN

	Fields that reference a database column must specify which column.
	Columns are numbered from 0. No two fields can reference the same
	column, with the exception of choice fields (only one of which can
	be on at any time), because that would have the side effect of giving
	more than one name to a database column. See Internal field name.

	It is usually a good idea to number database columns consecutively,
	and not omit any column number unless a database column exists but
	is not used by the form.

	If the database column of a Choice item is changed, the column of all
	Choice items with the same internal field name is also changed.

	The database column is a constant. No expression is allowed.
%% fe_sum
	SUMMARY COLUMN, WIDTH

	If the width is nonzero, the field is put into the summary in the main
	window. The width is the number of characters that go into the list.
	Grok separates columns by two spaces. The sum of all widths should
	not exceed 79 because they would get truncated to 79 characters
	when printed (File->Print can print summaries).

	The summary column specifies the order of fields with nonzero summary
	widths in the summary. The fields with the lowest summary column number
	appears in the leftmost column. It is not necessary to choose column
	numbers consecutively, they define the sort order and not absolute
	column numbers. No two fields (except choice fields that also also
	share the internal field name) may have the same summary column
	number if they have a nonzero width.

	If the summary column or width of a Choice item is changed, the column
	and width of all Choice items with the same internal field name are
	also changed.

	The summary column and width are constants. No expressions are
	allowed.
%% fe_flag
	CHOICE/FLAG CODE

	Choice and Flag codes specify the string that gets put into the
	database if the choice or flag field is "on". This code is a static string.
	All choice codes for one database column should all be different, and
	care should be taken that all possible codes that can appear in the
	database have a Choice field with a matching code.

	If the flag code matches the database string, the string specified in
	the "shown in summary as" button is put into the summary if the
	Summary width number is greater than 0. The flag codes themselves
	are usually too unmnemonic for the summary. Note that if the database
	is sorted by this column, it is sorted by the database string and not
	the string in the summary.
%% fe_time
	TIME FORMAT

	Time fields can have one of four display formats:

	Date:      A date in day.month.year or month/day/year format, depending
	           on the setting in the File->Preferences menu. The date may
	           have a time part that is not displayed.

	Time:      A time in hour:minute [ap] format. US format is enabled with
	           the File->Preferences menu. The time may have a date part
	           that is not displayed.

	Date+time: Both the date and the time are displayed, date first.

	Duration:  The number is interpreted as a number of seconds, and is
	           displayed in hour:minute (no a/p) format.
	
	Note that internal calculations are always done in seconds. If the
	result is not in the range used by the time format (such as numbers
	greater than 24*60*60 for Time, or numbers not dividable by 24*60*60
	without remainder for Date) are displayed by ignoring the undisplayed
	part. This may give unexpected results when sorting.
%% fe_ljust
	LABEL JUSTIFICATION

	The label may be left-justified, centered, or right-justified in the
	space allocated for it on the canvas. This not only applies to Label
	fields, but also to the label part (left or top part) of Input, Time,
	Note, Flag, and Choice fields. Use the Preview button to see the effect.
%% fe_lfont
	LABEL FONT

	The label can be displayed as Helvetica, Helvetica Oblique (slanted),
	Helvetica Narrow, Helvetica Bold (large), or Courier. The Helvetica
	fonts are proportionally-spaced; the Courier font is fixed size (all
	characters have the same width).

	It is recommended that Helvetica is used for labels, and Courier is
	used as input font for Input, Time, and Note fields. It is highly
	recommended to use Courier as input font for Note fields because
	printing functions (File->Print) print notes using a fixed-size font.
%% fe_ltxt
	LABEL TEXT

	Most fields have a label part that display a static text as entered
	as label text. No expressions are allowed. Use the Preview button to
	display the result to make sure that the text fits into the allocated
	space.
%% fe_ijust
	INPUT JUSTIFICATION

	The input may be left-justified, centered, or right-justified in the
	space allocated for it on the canvas. Fields that allow text input
	include Input, Time, and Note fields. Left justification is recommended.
%% fe_ifont
	INPUT FONT

	The input can be displayed as Helvetica, Helvetica Oblique (slanted),
	Helvetica Narrow, Helvetica Bold (large), or Courier. The Helvetica
	fonts are proportionally-spaced; the Courier font is fixed size (all
	characters have the same width). Fields that allow text input include
	Input, Time, and Note fields.

	It is recommended that Helvetica is used for labels, and Courier is
	used as input font for Input, Time, and Note fields. It is highly
	recommended to use Courier as input font for Note fields because
	printing functions (File->Print) print notes using a fixed-size font.
%% fe_range
	MAX INPUT LENGTH

	The maximum input length determines the maximum number of characters
	that can be entered into Input, Time, and Note fields. The default is
	100 for Input and Time fields, and 10000 for Note fields. When the
	maximum is reached, the field will stop accepting keyboard input. It
	is a common and annoying error to use a number that is too small for
	Note fields. There is no space saving in the database, and little
	space saving overall, in using low numbers. The maximum input length
	is a constant, no expression may be used.
%% fe_def
	INPUT DEFAULT

	For fields that can be used to change the database, such as Input
	fields, this string specifies the default value when a new card is
	created using the New button at the bottom of the main window. This
	string can be an expression.

	If the input default of a Choice item is changed, the default of all
	Choice items with the same internal field name is also changed. The
	default for a choice item should evaluate to one of the flag/choice
	codes of the Choice items, or new cards will be created with none
	of the alternatives set.

	NOTE -- if the field has type Time, the input default expression
	should evaluate to a number of seconds, not to a string containing
	a date. For example, to make the Time field default to today, use
	(date), not {date}.
%% fe_pattern
	INPUT PATTERN

	This string is a mask that user input must satisfy to be accepted as
	input and stored into the database. It can be an expression.
%% fe_gray
	GRAYED OUT IF

	If the expression evaluates to true, the field is grayed out and can
	not be manipulated by the user. The expression is re-evaluated when
	the user changes another field. This can be used to disallow entry
	into fields under certain conditions. See also the help text on the
	skip-if expression button.
%% fe_inv
	INVISIBLE IF

	If the expression evaluates to true after the database has been read
	in, the field will not be displayed in the card, leaving empty space.
	Unlike Grayed-out-if, it is evaluated only once when the database is
	read. This can be used, for example, to hide database fields when the
	wrong user accesses the database by using an expression using the
	"user" or "uid" keywords.
%% fe_ro
	READ-ONLY IF

	If the expression evaluates to true after the database has been read
	in, the field will not allow input into the database, as if the
	Read-only flag had been set in the form editor. Like Invisible-if, it
	is evaluated only once when the database is read. This can be used,
	for example, to disallow other users from changing certain database
	fields by using an expression using the "user" or "uid" keywords.
%% fe_skip
	SKIP IF

	When the user enters data and presses the Return key on an Input
	or Time field, grok puts the cursor into the next field automatically.
	The next field is the next field to the right if there is one in the
	same row, or the next one below otherwise. The next field is skipped
	if its skip-if expression evaluates to TRUE at the time of the search,
	and the search continues with the next field after that.

	This can be used to lead the user to the next field applicable to
	entries done earlier; for example, the ``maiden name'' field in a
	rolodex application could be skipped if an earlier Choice button
	indicates that the person is male.

	Skip-if does not prevent users from pressing on the skipped button
	explicitly. Use `grayed-out-if' to prevent that.
%% fe_press
	ACTION WHEN PRESSED

	If the type of the field is Button, this expression is evaluated when
	the user presses the button. This will generally be an expression with
	a side effect, such as an assignment to a variable, or a `switch' or a
	`system' function. The latter calls a Unix system function.
%% fe_result
%% fe_query
%% grammar
	GRAMMAR

	This is a quick reference only. For details, refer to the manual. n
	stands for numerical expressions, and s stands for string expressions.
	In general, numerical expressions are enclosed in (), and string
	expressions are enclosed in {}. Booleans use 0 or "0" for false and 1
	or "1" for true. Note that short-circuiting with ?: && || does not work.

	Numerical Operations: arithmetic operators use standard C precedences.

	  (n)             number
	  {s}             in number context, convert string to a number
	  n ? n : n    select n2 if n1 is nonzero, n3 if zero
	  n , n          evaluate both numbers, return second
	  -n            sign change
	  !n              boolean NOT
	  ~n             bitwise NOT
	  n + n         add
	  n - n         subtract
	  n * n         multiply
	  n / n          divide, n/0 is 1
	  n % n        modulus, n%0 is 1
	  n & n        bitwise AND
	  n && n      boolean AND
	  n | n          bitwise OR
	  n || n         boolean OR
	  n ^ n         bitwise XOR
	  n << n       bitwise left shift
	  n >> n       bitwise right shift
	  n == n       equal
	  n != n        not equal
	  n < n         less than
	  n > n         greater than
	  n <= n       less than or equal
	  n >= n       greater than or equal
	  sqrt (n)      square root
	  exp (n)       exponential
	  log (n)        logarithm to base 10
	  ln (n)          logarithm to base e
	  pow(n, n)    n1 raised to n2
	  sin (n)        sine
	  cos (n)       cosine
	  tan (n)        tangent
	  asin (n)      arc sine
	  acos (n)     arc cosine
	  atan (n)      arctangent
	  atan2(n,n)  quadrant-aligned arctangent
	  len (s)        string length
	  bound(n,n,n)   n1 bounded by n2 and n3


	String Operations: note that string comparisons return strings, and
	must be enclosed in braces {} if && or || or other numerical operators
	are used on the result. Printf arguments generally need to be
	parenthesized also.

	  "string"      literal string
	  {s}             string
	  (n)             in string context, convert number to string
	  s ; s           evaluate both strings, return second
	  s . s           concatenate strings
	  s ? s : s     select s2 if s1 evaluates nz, s3 if zero
	  s == s       strings are equal
	  s != s         strings are not equal
	  s < s          lexicographically less than
	  s > s          lexicographically greater than
	  s <= s        lexicographically less than or equal
	  s >= s        lexicographically greater than or equal
	  chop(s)      s without trailing newline
	  substr(s,n,n)  substring of the s1; n1 is start index and n2 is length
	  printf (args)   formatted string, args is comma-separated expr list


	Variables: variables are letters a through z that can hold strings or
	numbers. When a variable is assigned to, the result of the assignment
	is returned. All variables are reset to the empty string (or 0) when a
	database is loaded from disk.

	  var              value of variable
	  var = s        assign string to variable
	  var = n        assign number to variable
	  var .= s        append string to variable
	  var += n      add number to variable
	  var -= n      subtract number from variable
	  var *= n      multiply variable by number
	  var /= n       divide variable by number
	  var %= n     assign modulo with number to variable
	  var &= n      logical AND with variable
	  var |= n        logical OR with variable
	  var++          post-increment
	  var--          post-decrement
	  ++var          pre-increment
	  --var          pre-decrement


	Database Access

	  _field             database field of current card, field is number or name
	  _field [n]        database field from any card
	  this                number of current card, 0 is first
	  last                number of last card
	  avg (_field)    average of field in all cards
	  qavg (_field)   average of field in current query result
	  dev (_field)    standard deviation of field in all cards
	  qdev (_field)   standard deviation of field in current query result
	  min (_field)    minimum value of field in all cards
	  qmin (_field)   minimum value of field in current query result
	  max (_field)   maximum value of field in all cards
	  qmax (_field)  maximum value of field in current query result
	  sum (_field)   sum of field in all cards
	  qsum (_field)  sum of field in current query result
	  dbase            name of current database file
	  form              name of the current file
	  prevform       name of the previous form file

	  search("", "")              do nothing
	  search("", "*")            put all cards in summary
	  search("", "{expr}")    all cards for which {expr} is not "0" or empty
	  search("", "(expr)")    all cards for which (expr) is not 0
	  search("", "string")     all cards that contain search string
	  search("name", "x")   switch to form "name", then do query "x"


	Operating System Access

	  system (s)      execute shell command and return stdout
	  $envvar         environment variable
	  host               local host name
	  user               user's login name
	  uid                 user's numeric user ID
	  gid                 user's numeric group ID
	  access(s,n)   1 if any/r/w/x permission for file s for n=0/1/2/4
	  beep              ring terminal bell, return ""
	  error (args)    like printf but into a window, return ""


	Time Conversion: dates and times are stored as number of seconds since
	January 1, 1970. Durations are stored as number of seconds. Note that
	this means that a time is a significantly larger number than a duration,
	even if both have the same hh:mm string representation.

	  time               current time as hh:mm or hh:mm[ap]
	  time (n)          number as hh:mm or hh:mm[ap]
	  date               today's date as dd.mm.yy or mm/dd/yy
	  date (n)         number as dd.mm.yy or mm/dd/yy
	  duration(n)    number of seconds as hh:mm
	  date              seconds since January 1, 1970
	  year (n)         n as four-digit year
	  month (n)      n as month 1..12
	  day (n)          n as day 1..31
	  hour (n)         n as hour 0..23
	  minute (n)      n as minute 0..59
	  second (n)     n as second 0..59
	  julian (n)        n as julian date 0..365
	  leap (n)         1 if the time n is in a leap year, 0 otherwise
