This is Info file database.info, produced by Makeinfo-1.55 from the input file database.texi.  File: database.info, Node: Top, Next: Introduction, Prev: (dir), Up: (dir) * Menu: * Introduction:: Introduction * Installation:: Installation * Database mode:: Database mode * Database view mode:: Database view mode * Database edit mode:: Database edit mode * Searching:: Searching * Sorting:: Sorting * Summary mode:: Summary mode * Marking and omitting:: Marking and omitting * Reports:: Reports * Specifying the display format:: Specifying the display format * Designing a database:: Designing a database * Record field types:: Record field types * Database file layout:: Database file layout * How information is displayed:: How information is displayed * Customization:: Customization * Database representation:: Database representation * Naming conventions:: Naming conventions * Function Index:: Function Index * Variable Index:: Variable Index * Concept Index:: Concept Index -- The Detailed Node Listing -- Introduction * Organization of this manual:: Organization of this manual * Invoking EDB:: Invoking EDB * Example EDB session:: Example EDB session * Terminology:: Terminology Installation * EDB is in beta test:: EDB is in beta test * In case of trouble:: In case of trouble In case of trouble * Data display buffer:: Data display buffer * Variables:: Variables * Exiting Emacs or saving files:: Exiting Emacs or saving files * Compiling EDB:: Compiling EDB * Using the mouse:: Using the mouse * Long file names:: Long file names * Emacs 19:: Emacs 19 * Debugging EDB:: Debugging EDB * Reporting bugs:: Reporting bugs Database view mode * Moving around in the database:: Moving around in the database * Changing to edit mode:: Changing to edit mode * Undoing all changes to a record:: Undoing all changes to a record * Making changes permanent:: Making changes permanent * Adding and removing records:: Adding and removing records * Exiting database mode:: Exiting database mode Database edit mode * Exiting edit mode:: Exiting edit mode * Undoing changes to a field:: Undoing changes to a field * Moving from record to record:: Moving from record to record * Moving from field to field:: Moving from field to field * Movement within a field:: Movement within a field * Editing a field:: Editing a field * Getting help:: Getting help Searching * Search patterns:: Search patterns Sorting * Sorting functions:: Sorting and ordering functions Marking and omitting * Setting the mark and omit bits:: Setting the mark and omit bits * Movement among marked and omitted records:: Movement among marked and omitted records * Details of omitting:: Details of omitting Reports * Bugs in report generation:: Bugs in report generation Specifying the display format * Changing display formats:: Changing display formats * Execution of format file eval expressions:: Execution of format file eval expressions * Making additional data display buffers:: Making additional data display buffers Designing a database * Creating a new database:: Creating a new database * Manipulating database fields:: Manipulating database fields Record field types * Specifying a record field type:: Specifying a record field type * Predefined record field types:: Predefined record field types * The recordfieldspec structure:: The recordfieldspec structure Database file layout * Internal file layout:: Internal file layout * Regular file layout:: Regular file layout * Tagged file layout:: Tagged file layout * Nonregular file layout:: Nonregular file layout * Reading from disk:: What happens when a database is read in from disk Regular file layout * How to specify regular file layouts:: How to specify regular file layouts * Resolving ambiguities:: Resolving ambiguities * Problems with end-of-file newlines:: Problems with end-of-file newlines How to specify regular file layouts * The sepinfo structure:: The sepinfo structure * Sepinfo examples:: Examples of setting record and field separators Nonregular file layout * Nonregular database example:: Example of database in nonregular file layout How information is displayed * Display specifications:: Display specifications * Predefined displaytypes:: Predefined displaytypes * Enumeration displaytypes:: Enumeration types * Defining new displaytypes:: Defining new displaytypes * Display specification optional parameters:: Display specification optional parameters * Display specification abbreviations:: Display specification abbreviations Display specifications * Predefined displaytypes:: Predefined displaytypes * Defining new displaytypes:: Defining new displaytypes * Display specification optional parameters:: Display specification optional parameters * Display specification abbreviations:: display specification abbreviations Predefined displaytypes * Date displaytype:: Date displaytype * Time displaytype:: Time displaytype Enumeration types * One-character enumeration displaytypes:: One-character enumeration displaytypes * Multi-character enumeration displaytypes:: Multi-character enumeration displaytypes Customization * Auxiliary files:: Auxiliary and format files * Hooks and customization functions:: Hooks and customization functions * Local variables:: Local variables * Global variables:: Global variables Hooks and customization functions * Load and read hooks:: Load and read hooks * Database minor mode hooks:: Database minor mode hooks * Record display hooks:: Record display hooks * Edit mode hooks:: Edit mode hooks * Display format change hooks:: Display format change hooks * Recordfieldspec change hooks:: Recordfieldspec change hooks Local variables * Per-data-display-buffer variables:: Per-data-display-buffer variables * Per-database variables:: Per-database variables Database representation * The database structure:: The database structure * Mapping over the database:: Mapping over the database * Manipulating records:: Manipulating records The database structure * The link structure:: The link structure Creating and copying records * Accessing record fields:: Accessing record fields * Mapping over record fields:: Mapping over record fields Naming conventions * Function and variable naming conventions:: Function and variable naming conventions * File naming conventions:: File naming conventions  File: database.info, Node: Introduction, Next: Installation, Prev: Top, Up: Top Introduction ************ EDB is a database program for GNU Emacs. It permits users to manipulate structured (or not-so-structured) data within Emacs and provides many of the usual database features, including: * Flexible, customizable file layouts. Data may contain any character, including those used to delimit fields and records. Files read and written by the database may have arbitrary formats. * Typed fields (e.g. integer, date, string); fields may also be subject to additional constraints (prime number, date before today, string that appears in some other record, etc.). * Arbitrary data display formats for viewing records. Multiple display formats can be open on a database simultaneously, viewing the same or different records. The data display format can be automatically chosen based on the record's field values. * Selective display of only those records of interest; others become temporarily user-invisible. * Standard GNU Emacs editing commands, which work only within data fields and not on the surrounding text. * Database summaries, which show in a single buffer one or more lines of information about each record. * Sorting, with an easy-to-use a graphical interface for defining the sorting criteria; most sorting orders you would care about are easy to specify, but arbitrary ones are also permitted. * Merging and reconciliation of databases. * Reports generated from database information. * Highly customizable via the underlying programming language, Emacs Lisp; many hooks and useful variables are provided to make this even easier. * Documented by an 80-page manual. EDB is more ambitious--and therefore more complex--than its forerunners (such as Forms Mode by Johan Vromans ). While other packages don't provide as much functionality as EDB, they may be more appropriate for simple needs. * Menu: * Organization of this manual:: Organization of this manual * Invoking EDB:: Invoking EDB * Example EDB session:: Example EDB session * Terminology:: Terminology  File: database.info, Node: Organization of this manual, Next: Invoking EDB, Up: Introduction Organization of this manual =========================== This manual contains two major parts. The first part describes how to use EDB to manipulate an existing database, and the second part describes how to design a new database. The first part--which could be called the EDB User Manual--first presents basic commands such as starting up the database, adding, deleting, and modifying records, and searching; then it describes features for the more advanced user, such as sorting, displaying record summaries, marking or ignoring certain records, and producing reports. The second part--which could be called the EDB Database Designer Manual--describes the three forms that database information can take: when being manipulated by EDB, when stored on disk, and when displayed on the screen. Separate chapters discuss specifying each of these representations. The manual then goes on to discuss customization hooks and explains some of the lower-level implementation details that an advanced designer may need to know.  File: database.info, Node: Invoking EDB, Next: Example EDB session, Prev: Organization of this manual, Up: Introduction Invoking EDB ============ You need three files to run EDB: a data file, a format file, and an auxiliary file. The data file (usual suffix `.dat') contains the information that makes up the database. The format file (usual suffix `.fmt') specifies how the fields of a particular record appear in the data display buffer, where the user may view or edit one record at a time. The auxiliary file (usual suffix `.dba') contains additional information about the database, such as the number of fields in each record, the layout of the data file (including what characters or strings serve as field and record separators), customizations, etc. A fourth type of file is the report format file, which is a format file used in generating reports printed on the screen, to a file, or to a printer; *note Reports::.. For examples of data, format, and auxiliary files, a description of how to create your own, and pointers to even more information, *note Creating a new database::., or see the examples provided with EDB (*note Installation::.). You can combine the format and auxiliary files (by placing the additional information at the end of the format file, in the "Local variables" section), but it is simpler to consider the two files separately. There may be many different ways to lay out a record on the screen, so a database could have many different format files; for the time being we will concentrate on the format file which is used first, which is called the primary format file, even though it might not be the one that is used most often. When invoking the database, you typically only need to name the data file; the names of the others will be inferred from its name (*note Auxiliary files::.) or may be mentioned explicitly by it. The `db-find-file' command starts up the database: `M-x db-find-file' Read a database from DATABASE-FILE; prompts when called interactively. If the database file doesn't specify a format and the format file can't be inferred from DATABASE-FILE, the user is prompted for it too. The user is always prompted for the format if prefix arg PROMPT-FOR-FORMAT is non-`nil'. If the database is already read in and PROMPT-FOR-FORMAT is `nil', the existing database buffer is merely selected. When called non-interactively, argument PROMPT-FOR-FORMAT may be a string, the name of a format file to use. You can also arrange that `find-file' automatically invokes EDB when called on a database file; see *Note Installation:: for details. The usual save-file and write-file keystrokes are rebound in all database modes. `C-x C-s' (`db-save-database') Save the database to disk in the default save file. Any changes to the current record are processed first. The default save file is the file it was last saved to or read from. If optional arg QUERY is specified, the user is asked first. Optional second arg QUIETLY suppresses messages regarding the filename. `C-x C-w' (`db-write-database-file') Save the database to disk in file FILENAME; it becomes the default save file. Any changes to the current record are processed first. If FILENAME is not specified, the user is prompted for it. Optional second arg QUIETLY suppresses messages regarding the filename.  File: database.info, Node: Example EDB session, Next: Terminology, Prev: Invoking EDB, Up: Introduction Example EDB session =================== This section describes some of the most frequently used EDB commands. All of the commands used here are more fully documented elsewhere in the manual. For a very brief introduction to database mode, its submodes (view mode and edit mode), the data display buffer, EDB concepts, and more, *note Database mode::.. `M-x db-find-file RET forms-demo2.dat RET' Load the database. After calling `db-find-file', you may be asked for the name of the format file if EDB can't infer it from the name or contents of the data file. *Note Invoking EDB::. When the database finishes loading, the data display buffer is visible and EDB is in database view mode (*note Database view mode::.). `n' `p' Go to the next or previous record (*note Moving around in the database::.). The data display buffer is in view mode, which is read-only and does not permit editing (*note Database view mode::.). `TAB' `C-n' Go to the first field and switch to database edit mode. *Note Changing to edit mode::, and *Note Database edit mode::. Once you are on a field, printing characters insert themselves and the other usual editing commands will work as well. `TAB' moves to the next field, and `C-n' moves to a field on the next line (or to the next line of this field, if it spans multiple lines). *Note Moving from field to field::, and *Note Movement within a field::. `M-TAB' `C-p' Like `TAB' and `C-n', but move backward by fields or lines. `M-s' Search for a value in the current field. *Note Searching::. `C-c C-c' Return to view mode. `h' `D' See a summary of all the records of the database; `h' stands for "headers" and D stands for "Directory". *Note Summary mode::. You can move around in the summary buffer using ordinary movement commands, and the record under point will be displayed in the data display buffer. Use `v' or `e' to return to the data display buffer; `v' puts you in view mode and `e' puts you in edit mode. `M-x db-sort `RET'' Invoke the database sort interface, which permits easy specification of how records should be sorted, and then perform the sort. Type `C-h m' or `?' for help while in the database sort interface (or anywhere in EDB). *Note Sorting::. `C-x C-s' Save to disk any changes you have made to the database. `C-h m' Display a list of commands. This command works in all Emacs modes (and in paricular, in all EDB modes). `q' `x' Quit EDB. `q' just buries the buffer; `x' also offers to save if changes have been made. EDB provides many more commands than these; see this manual's table of contents (*note Top::.) or index (*note Concept Index::.) to find the topic that interests you.  File: database.info, Node: Terminology, Prev: Example EDB session, Up: Introduction Terminology =========== A database is a collection of records, each of which is comprised of fields. A record's fields are usually all related to some central object or concept; for instance, they might describe various information about a particular person such as name, address, and phone number. All records of a database have the same structure (they contain the same fields), though typically different records will have different information in the fields. EDB permits database records to be viewed, edited, and manipulated in a structured way.  File: database.info, Node: Installation, Next: Database mode, Prev: Introduction, Up: Top Installation ************ FTP the files from `theory.lcs.mit.edu:/pub/emacs/edb/'; the package is in a single compressed tar file `edb.tar.Z', and the individual files can also be obtained from the `code' subdirectory. Install the files in your Emacs load path (probably in a directory of their own). You can add a directory to your Emacs lisp load path by putting something similar to the following in your `.emacs' file: (setq load-path (cons (expand-file-name "~/emacs/edb") load-path)) Finally, cause EDB to be autoloaded by putting the following in your `.emacs' file: (autoload 'db-find-file "database" "EDB database package" t) (autoload 'load-database "database" "EDB database package" t) (autoload 'byte-compile-database "database" "EDB database package" t) Now, when you start up Emacs, you will already be able to execute `db-find-file'; EDB will be loaded automatically. (You may also wish to autoload function `edb-update'; see *Note EDB is in beta test::.) See below if you wish to byte-compile the EDB sources. Here is one way to arrange to automatically run EDB when you read a database file via the usual `find-file' command (ordinarily bound to `C-x C-f'), whether or not you choose to autoload EDB. This only works on databases which have been stored in EDB internal file layout (*note Internal file layout::.). (setq find-file-hooks (cons 'after-find-file-edb find-file-hooks)) (defun after-find-file-edb () "If this is a database file in EDB internal file layout, run EDB." ;; When this is called, we are at the beginning of the buffer. (if (looking-at ";; Database file written by EDB") (progn (require 'database) (db-this-buffer) ;; db-this-buffer kills the current buffer; and an error results ;; when Emacs tries to switch back to it. find-file-noselect ;; uses the buf variable to hold the new buffer. (setq buf (buffer-name (current-buffer)))))) Naturally, running EDB will do you little good without a database to manipulate; for information about creating a new database or using an existing one (EDB can handle nearly any file layout imaginable and many that aren't), see *Note Designing a database::. You may also want to use existing databases as guides, or to help familiarize yourself with EDB. A number of examples can be found in the compressed tar file `examples.tar.Z' or in the `examples/' subdirectory of `theory.lcs.mit.edu:/pub/emacs/edb/' (the two locations contain the same examples). You can test out function `after-find-file-edb' by performing `find-file' on `forms-demo2-int.dat'. It is strongly recommended that you run EDB byte-compiled, as otherwise it is very sluggish. To byte-compile EDB, type `M-x byte-compile-database RET'. (You may need to load EDB first, by typing `M-x load-library RET database RET' or `M-x load-file RET database.el RET', in order to define this function.) If you perform the byte-compilation yourself rather than using the `byte-compile-database' function, you *must* fully load the code before compiling it, by typing `C-u M-x load-database RET'. For more details, *Note Compiling EDB::. The texinfo documentation must be processed using release 2 of texinfo (which is available via anonymous ftp from `prep.ai.mit.edu', directory `pub/gnu'), but the resulting Info files can be read using any Info reader. If you don't have texinfo version 2, you can get the EDB documentation pre-processed in info format from `theory.lcs.mit.edu:/pub/emacs/edb/', files `database.info' and `database.info-[123456]' (seven files in all). Similarly, that directory contains ready-to-print versions of the manual (file `database.dvi' or `database.ps'). * Menu: * EDB is in beta test:: EDB is in beta test * In case of trouble:: In case of trouble  File: database.info, Node: EDB is in beta test, Next: In case of trouble, Up: Installation EDB is in beta test =================== EDB is a project I undertook because the existing tools for manipulating structured information in Emacs were lacking features I considered important. EDB now meets my needs--and those of a number of other users--but it still contains some important lacunae. I will fill these in as I can. I encourage users of EDB to mention which ones are most important to them, so that I can decide in what order to undertake the many projects on my "to do" list. I encourage you even more strongly to contribute code for features currently lacking--then you'll be sure of its inclusion in EDB, and you'll be helping others as well. EDB has been in use since the summer of 1991, but it has not been exhaustively and systematically tested, so it may still contain bugs. Please send me bug reports and (if possible) bug fixes, and I'll correct the problems in the next release. The mailing list `edb-list@theory.lcs.mit.edu' is intended for discussions relating to EDB: trading extensions, sharing experiences, asking questions, reporting bugs and bug fixes, and distributing updates to EDB. Send requests to be added to (or removed from) the list to `edb-list-request@theory.lcs.mit.edu'. You can make it easy to install updates of EDB by putting something like the following in your `.emacs' file: (setq edb-directory "~/emacs/edb") (autoload 'edb-update "database" "EDB database package" t) Then, when you receive a message containing diffs for a new version of EDB, you only have to type `M-x edb-update RET' in order to install them. `M-x edb-update' Install the EDB update found in the current buffer after point. EDB is assumed to be in the directory specified by `edb-directory'. If you have trouble with this command, it is likely that your version of EDB is not exactly the same as the last release. You might have an old release, or you might have a pre-release. (When users request features or report bugs, I sometimes place a pre-release of the next version of EDB on theory.lcs.mit.edu so that their problems are corrected right away.) `edb-directory' A string, the name of the directory containing the EDB source files. If `edb-directory' is not set, the user is prompted for the location of the files, which should all be in a single directory. These diffs are also available by anonymous ftp from `theory.lcs.mit.edu:/pub/emacs/edb/diffs/'. The filenames are of the form `edb-diff-OLDVERSION-NEWVERSION.Z', and the files are compressed patch files. To apply such a patch, uncompress it, connect to your EDB directory, and run the patch program with the diff file as input, like so: `patch < edb-diff-1.14-1.15'. Don't forget to load EDB and byte-recompile your EDB source directory\n" (use `M-x byte-compile-database RET') if you run EDB compiled. If you have been running a prerelease of this version, you must get the entire distribution from `theory.lcs.mit.edu'.  File: database.info, Node: In case of trouble, Prev: EDB is in beta test, Up: Installation In case of trouble ================== * Menu: * Data display buffer:: Data display buffer * Variables:: Variables * Exiting Emacs or saving files:: Exiting Emacs or saving files * Compiling EDB:: Compiling EDB * Using the mouse:: Using the mouse * Long file names:: Long file names * Emacs 19:: Emacs 19 * Debugging EDB:: Debugging EDB * Reporting bugs:: Reporting bugs  File: database.info, Node: Data display buffer, Next: Variables, Up: In case of trouble Data display buffer ------------------- In the data display buffer, if point is not where EDB expects it to be, or if other information gets out of synch, you may get an error message about a string not being found in the buffer where it was expected. (In order to prevent this sort of confusion, the user is prohibited from aborting when a record is being displayed in the database format buffer; this is done by setting `inhibit-quit' to `t', if `db-debug-p' is non-`nil'.) When it looks like point is not in the field it should be in or the text surrounding the fields has been illegally modified, EDB automatically calls the following function and displays the message "I was confused about where I was. Changes to the field might have been lost." (This error message is produced by function `db-parse-buffer-error'.) In the unlikely event that the data display buffer does get confused and is not automatically corrected, you can call the function yourself. `M-x db-emergency-restore-format' Replace a format with a fresh one; use this if the format gets munged. Changes made to the current field since last moving onto it may be lost. If optional prefix arg RECOMPUTE is non-`nil', `display-record' recomputes the displayed text as well.  File: database.info, Node: Variables, Next: Exiting Emacs or saving files, Prev: Data display buffer, Up: In case of trouble Variables --------- You may find that in some cases the documentation strings and/or default values of some variables are missing--as if the variables hadn't been defined yet. That's because they aren't defined yet; they are associated with part of EDB which hasn't been loaded because it hasn't been needed yet. The documentation and default values will appear when that part of EDB is loaded (if you set such variables, your values will not be replaced). Such variables are correctly declared buffer-local (if appropriate), so you can set them without fear of the changes affecting other buffers.  File: database.info, Node: Exiting Emacs or saving files, Next: Compiling EDB, Prev: Variables, Up: In case of trouble Exiting Emacs or saving files ----------------------------- If you find you are unable to exit Emacs or to execute `mde-save-some-buffers' (which replaced `save-some-buffers', which is ordinarily bound to `C-x s') because Emacs is trying to manipulate a database which doesn't exist or because an EDB bug is triggered by the attempt to save an existing database, you can set the variable `db-databases' to `nil'. This indicates to EDB that there are no databases read into memory and, therefore, no operations will be attempted on them as a part of saving all modified Emacs buffers. `db-databases' Assoc list of database names and databases.  File: database.info, Node: Compiling EDB, Next: Using the mouse, Prev: Exiting Emacs or saving files, Up: In case of trouble Compiling EDB ------------- Expected compilation errors ........................... When EDB is compiled with Jamie Zawinski's optimizing byte-compiler, (available from the GNU Emacs Lisp Code Archive at `archive.cis.ohio-state.edu'), several errors will be signalled. The following are expected errors which result from insufficiently fine control of the (otherwise outstanding) byte-compiler's error output. * Functions `with-electric-help' and `x-flush-mouse-queue' are not known to be defined. EDB supports electric-help and X Windows when they are present, but they may not be in many environments. No run-time error will be raised by the absence of these features. * Function `link-set-record' is defined as both af unction and a macro. This function is automatically defined when the link structure is defined, but EDB needs a different definition for the function than the one provided by the link structure creator. Load EDB before compiling it ............................ You must always fully load EDB before attempting to byte-compile it. The easiest way to ensure this is to compile EDB by using function `byte-compile-database', which automatically fully loads EDB. Otherwise, do `C-u M-x load-database RET' to load a full uncompiled version of EDB before you compile. You may need to load EDB before doing this (in order to define the `load-database' function), but do not omit this step even if you have already loaded EDB. It is not enough to simply do `(require 'database)' or call `db-find-file', since neither of those actions loads all of EDB, only parts of it. There are two reasons for loading the code before compiling it. The first is that, when the byte-compiler encounters an unknown symbol used in function position, it assumes that it is a function and attempts to funcall it. If the symbol is later defined to be a macro, this leads to a runtime error. The second reason is that, if the variable `db-disable-debugging-support' is non-`nil' (most users will want to use the default value, which is `t') when compilation occurs, then code for assisting debugging will be compiled out and the code will be slightly smaller and faster, because it will not contain conditional code for printing status reports and intermediate results. One symptom of compiling EDB without having loaded it is a message along the lines of `Invalid function: (macro ...)'. (EDB's implementation uses macros for efficiency, so problems result if, when compiling, an unknown symbol is assumed to be a function but is actually later defined as a macro.) Another symptom is that variables defined in autoloaded files will be reported as "not known to be defined." A problem with compiling EDB when an old version is loaded is that, if macro definitions have changed, the old definitions will be compiled into the new code. `M-x load-database' Load all the files of EDB, the Emacs database. With prefix arg, load source, not compiled, code; EDB will run interpreted. This function is a good candidate for autoloading. `M-x byte-compile-database' Compile source (.el) files in EDB, the Emacs database, which need it. If optional prefix argument ALL is non-`nil', every source file is recompiled. `M-x byte-compile-database-all' Compile all source (.el) files in EDB, the Emacs database, unconditionally. Calls `byte-compile-database'. No insert-hook .............. EDB uses `db-insert' instead of `insert'. However, Emacs has a byte-code for `insert', so EDB's redefinition may be ignored in compiled code. Emacs should really provide an `insert-hook' variable; version 19 does (two of them, in fact).  File: database.info, Node: Using the mouse, Next: Long file names, Prev: Compiling EDB, Up: In case of trouble Using the mouse --------------- EDB redefines various text deletion and insertion commands to ensure that inter-field text is not deleted, that indentation is correctly added and removed when appropriate, and so forth. When cutting or pasting is done with the mouse, however, these function redefined by EDB are bypassed and the data display buffer can be manipulated almost arbitrarily. This can cause various problems; `x-paste-text' often raises errors or produces incorrect results. There are no known problems with using the mouse to select fields and to move around within fields. Correcting this bug does not have high priority, but users are encouraged to help find a solution or to provide a fix. One solution might be redefining the functions that are called when mouse deletion or insertion occurs; it might also be possible to use insertion-hooks or deletion-hooks, in versions of Emacs that provide them.  File: database.info, Node: Long file names, Next: Emacs 19, Prev: Using the mouse, Up: In case of trouble Long file names --------------- EDB's files were named to accommodate systems which limit filenames to 14 characters or less; this is why the `backtrace-fix' package was renamed `backtracef' and other file names (like `db-interfa.el' appear to be truncated. There is one remaining problem, however. When the Texinfo documentation is converted into an Info tree, files with names like `database.info-3' are created, but the Info files are (all) saved as `database.info-'. Users with this problem can rename `database.texi' to `edb.texi' and modify the `setfilename' in its third line to refer to `edb.info'; then the resulting files `edb.info-1' through `edb.info-6' will be saved correctly. Some of the example files may also have names with more than fourteen characters.  File: database.info, Node: Emacs 19, Next: Debugging EDB, Prev: Long file names, Up: In case of trouble Emacs 19 -------- EDB is fully compatible with GNU Emacs 19 (and with Lucid GNU Emacs 19), though it does not yet take advantage of any of Emacs 19's special features (such as pull-down menus, modification hooks, and read-only regions). GNU Emacs 19 (but not Lucid's version) may appear to hang while reading EDB format files. Emacs 19's regular expression routines are POSIX-compliant and, in some cases, much slower than the old version. (Some searches that used to take fracions of a second now take the better part of an hour!) This Emacs bug evidences itself when EDB is searching for display specifications in the format file, and in particular, if no display specifications contain optional parameters (following a comma), then EDB will read the format file quickly. Format files containing many complicated display specifications may take minutes or even hours to read. Emacs has not hung, but it will respond extremely slowly to user input. Once the format file has been read, EDB performs as well under Emacs 19 as it does under Emacs 18.  File: database.info, Node: Debugging EDB, Next: Reporting bugs, Prev: Emacs 19, Up: In case of trouble Debugging EDB ------------- Enabling debugging messages ........................... Two useful sources of information for locating a problem in EDB are backtraces and the database log. If you encounter an EDB error, you should generate a backtrace and a database log; even if they do not provide you any information, they may help others who will see your bug report. Execute the following command and then repeat the commands that caused an error previously. `M-x db-prepare-to-debug' Prepare to debug EDB. Set variables `debug-on-error', `db-disable-debugging-support', and db-debug-p. Also load uncompiled EDB source. EDB's source code contains calls to debugging macros which print useful messages and save them in the `*Database-Log*' buffer for later examination. By default, the calls to these macros are removed at compile time; this results in slightly smaller, faster code. The following variables control this behavior. `db-disable-debugging-support' If non-`nil', then debugging calls will be compiled out of the source and the variable db-debug-p will have no effect. Setting this variable at run-time has no effect if you are running EDB compiled; you must set it when you compile EDB, or run EDB interpreted. Defaults to `t'. `db-debug-p' T if database debugging is enabled. Defaults to `nil'. Has no effect on code compiled with `db-disable-debugging-support' set. Printing circular structures ............................ EDB's internal representation of the database structure is circular; if you try to print it, Emacs will signal an error. This is a particular problem when debugging functions that manipulate a database. EDB provides a partial fix by including the `backtracef' (originally `backtrace-fix'; the name was changed to accommodate systems with 14-character maximum file name lengths) package, which at least lets `backtrace' operate in the presence of circular structures; this can let you know where the specific problem lies. A more complete fix is the custom-print package, which defines versions of the printing commands which support printing circular structures. You will also need to use a debugger which knows about these functions; Edebug version 2.7 or higher fits the bill and is well worth using in its own right. Both custom-print and Edebug are available by anonymous ftp from the GNU Emacs Lisp Code Directory at `archive.cis.ohio-state.edu', which is rooted at the directory `/pub/gnu/emacs/elisp-archive'. The files of interest are `functions/custom-print.el.Z' and `packages/edebug.tar.Z'. After installing these packages (see their documentation for details), you can simply do something like (setq print-level 4) to make circular structures easily debugable. Be sure to reset `print-level' and `print-length' to `nil' before byte-compiling! (If you do not, the byte-compiled code may contain a `#' in place of some of the byte codes, resulting in the error message "Invalid read syntax: "#"".) One way to do this is to put the following code in your `.emacs' file: (setq pre-byte-compile-file-hook (function (lambda () (setq print-level nil print-length nil)))) (insert-hooks 'byte-compile-file 'pre-byte-compile-file-hook) You can get Noah Friedman's `insert-hooks.el' from the GNU Emacs Lisp Code Directory.  File: database.info, Node: Reporting bugs, Prev: Debugging EDB, Up: In case of trouble Reporting bugs -------------- If you have problems with EDB or think you've found a bug, please report it to Michael Ernst; he doesn't promise to do anything but he might well want to fix it. Questions about EDB that are not answered in the manual are welcome as well; if the manual is unclear, that's a bug in the documentation. Suggestions for new features or modifications are always welcome (and implementations of such features, even more so); input from users determines which features are moved to the front of EDB's "to-do" list and which ones users apparently don't care about. The `edb-list' mailing list (*note EDB is in beta test::.) is also a valuable resource for users of EDB. Before reporting a bug or trying to fix it yourself, please perform the following steps. First, make sure you are using the most recent version of EDB, since the problem may have already been fixed. The most recent version of EDB can always be found in directory `theory.lcs.mit.edu:/pub/emacs/edb/'; the file `code/database.el' contains the version number, which is also apparent from the filenames of the contents of directory `diffs/'. You can find out which version of EDB you have by looking in your version of `database.el' or by typing `C-h v edb-version RET'. Second, read the appropriate manual sections, so you understand how EDB ought to be behaving (and whether your bug is considered a feature). Third, try to isolate the problem (for instance, by using the smallest possible data, format, and auxiliary files). If the problem causes an error (usually causing Emacs to beep and display a message in the echo area), then run command `db-prepare-to-debug' and then reproduce the error. This will produce a backtrace and a database log. For further debugging techniques, *note Debugging EDB::.. Send a bug report which includes all of the following information. * A description of how to reproduce the bug and what you expected to occur. * The version of EDB you are running (do `M-x edb-version RET') and the version of Emacs (do `M-x emacs-version RET'). * All files necessary to reproduce the bug, including the database file, the format file, and the auxiliary file, if any. I promise not to look at the content of your database file or distribute it; if you feel uncomfortable sending it nonetheless, construct another one that will result in the same error. Reproducing these files, when they are absent, usually takes longer than tracking down the bug, so if they are not included, I cannot promise to take any action on the bug. * The backtrace and the database log (found in the `*Backtrace*' and `*Database Log*' buffers).  File: database.info, Node: Database mode, Next: Database view mode, Prev: Installation, Up: Top Database mode ************* A single database record (typically the "current record") is viewed in a data display buffer.(1) The layout and formatting of the data display buffer--where and how the fields of the current record are shown, and what fixed explanatory text surrounds them--is specified by a data display format. Only the database fields can be edited; the explanatory text is fixed. Creating a new data display format is described in *Note Specifying the display format::. Creating a new data display buffer (with the same or a different data display format) is described in *Note Making additional data display buffers::. Viewing summary information about all database records at once is described in *Note Summary mode::. Database mode has two basic submodes, view mode (*note Database view mode::.) and edit mode (*note Database edit mode::.). These modes are used, respectively, when examining or manipulating records and when changing information in a particular record. Keystrokes have different meanings in these two modes. In view mode no editing may be done, and many printable characters are redefined to make manipulation of the database easy (for instance, `n' moves to the next record). In edit mode point is in a field of the current record which is being edited; most printable keys insert themselves, and other editing and movement commands work in the ordinary way. In the data display buffer, where database records are ordinarily viewed and edited, one of these two modes is always in effect. (You may be tempted to directly edit a raw database file in its on-disk layout. Do so only if you know what you are doing, and never change a database buffer out of database mode.) The mode line indicates which mode you are in. It looks something like: -***-Database: machine-dbase (Edit Abbrev 42/431)---All------------ The mode line consists of three modification indicators, the word `Database:' (which reminds you that you are in database mode), the name of the database file being manipulated, minor mode information within parentheses, and the usual percentage-of-screen-visible indicator. The minor mode information consists of the database submode (such as view, edit, or summary), any other minor modes which are turned on (such as Abbrev Mode), the number of the current record, and the total number of records in the database. Ordinarily the Emacs mode line contains only one modification indicator consisting of two dashes (not modified), asterisks (modified), or percent signs (read-only). The EDB mode line contains three modification indicators, one each for the database, the displayed record, and the current field. The field indicator is `*' if the field under point has been modified, `-' if it has not, and `%' if it is read-only or if no field is under point (for instance, if the data display buffer is in database view mode rather than database edit mode). The database is modified only when a changed record is written into it; changes to the displayed record (also called the current record) do not immediately affect the database proper. This permits such modifications to be conveniently undone. (*Note Undoing all changes to a record::, and *Note Making changes permanent::.) The upshot of this is that the current record may be modified without the database being modified, since the database is considered modified only when the current record has been processed and the resulting value placed in the database. A similar situation exists for the current field and the displayed record. (*Note Undoing changes to a field::.) Do not attempt to directly change the major mode of a database buffer; if a database buffer is placed in another mode, the database functions will cease working (they refuse to operate on non-database buffers, since the consequences of such action could be severe); for instance, you may be unable to save any of your work due to errors raised in the execution of `save-some-buffers'. Furthermore, EDB makes assumptions about where point is located in view and edit modes; violating these can cause changes to the current record to be lost. ---------- Footnotes ---------- (1) The data display buffer was previously called the format buffer; this is one reason that all of the variables and functions relating to it start with the `dbf-' prefix.  File: database.info, Node: Database view mode, Next: Database edit mode, Prev: Database mode, Up: Top Database view mode ****************** The data display buffer is in view mode whenever field information is not being edited. Most commands to move from record to record and to manipulate records (sorting, printing reports, showing summaries, etc.) are performed in view mode. Basic operations are described here; more complicated ones, such as searching (*note Searching::.), are given sections of their own. * Menu: * Moving around in the database:: Moving around in the database * Changing to edit mode:: Changing to edit mode * Undoing all changes to a record:: Undoing all changes to a record * Making changes permanent:: Making changes permanent * Adding and removing records:: Adding and removing records * Exiting database mode:: Exiting database mode  File: database.info, Node: Moving around in the database, Next: Changing to edit mode, Up: Database view mode Moving around in the database ============================= `n' (`db-next-record') Go to the ARGth next record. In that record, go to the current field, if any. `p' (`db-previous-record') Go to the ARGth previous record. In that record, go to the current field, if any. `<' `M-<' (`db-first-record') Show the database's first record. With optional prefix argument, ignores omitting. `>' `M->' (`db-last-record') Show the database's last record. With optional prefix argument, ignores omitting. `j' (`db-jump-to-record') Show the database's ARGth record. Omitting is ignored unless optional argument RESPECT-OMITTING is specified. There are two special hybrid commands that show more of the current record if there's more to see and otherwise show the next (or previous) record. `SPC' (`db-next-screen-or-record') Go to the ARGth next screenful of this display, or to the ARGth next record, if this is the last screenful of this display. If point is in the summary buffer and the data display buffer is not visible, then move to the next record. `DEL' (`db-previous-screen-or-record') Go to the ARGth previous screenful of this display, or to the ARGth previous record, if this is the first screenful of this display. If point is in the summary buffer and the data display buffer is not visible, then move to the previous record.  File: database.info, Node: Changing to edit mode, Next: Undoing all changes to a record, Prev: Moving around in the database, Up: Database view mode Changing to edit mode ===================== When in database view mode, you cannot edit the record being displayed without first changing to database edit mode; this is done by moving to the field you wish to edit. You can click the mouse on the field you wish to edit, or move to the first or last field (and from there to the desired field) via the following keystrokes: `TAB' `C-n' `e' (`db-first-field') Move to first field. `C-p' `M-TAB' (`db-last-field') Move to last field.  File: database.info, Node: Undoing all changes to a record, Next: Making changes permanent, Prev: Changing to edit mode, Up: Database view mode Undoing all changes to a record =============================== `C-x u' (`db-revert-record') Set the record to be the same as the corresponding one in the database. In other words, undo any changes made since entering this record. `C-x r' (`db-revert-database') Replace the database with the data on disk. This undoes all changes since the database was last saved. You can also undo changes to only a particular field; see *Note Undoing changes to a field::.