Skunkware 5

home *** CD-ROM | disk | FTP | other *** search

/ Skunkware 5 / Skunkware 5.iso / lib / xmbase-grok-1.2 / grok.hlp next >

Wrap

Text File | 1995-07-03 | 59.5 KB | 1,342 lines

%% 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