Mercurial > emacs

changeset 84298:a475365b2236

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
Move here from ../../man
author Glenn Morris <rgm@gnu.org>
date Thu, 06 Sep 2007 05:00:10 +0000
parents 626284ff7a1a
children 34ba5367ab56
files doc/misc/forms.texi
diffstat 1 files changed, 985 insertions(+), 0 deletions(-) [+]
line wrap: on
line diff
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/misc/forms.texi	Thu Sep 06 05:00:10 2007 +0000
@@ -0,0 +1,985 @@
+\input texinfo			@c -*-texinfo-*-
+@c documentation for forms-mode
+@c Written by Johan Vromans, and edited by Richard Stallman
+
+@comment %**start of header (This is for running Texinfo on a region.)
+@setfilename ../info/forms
+@settitle Forms Mode User's Manual
+@syncodeindex vr cp
+@syncodeindex fn cp
+@syncodeindex ky cp
+@iftex
+@finalout
+@setchapternewpage odd
+@end iftex
+@c      @smallbook
+@comment %**end of header (This is for running Texinfo on a region.)
+
+@copying
+This file documents Forms mode, a form-editing major mode for GNU Emacs.
+
+Copyright @copyright{} 1989, 1997, 2001, 2002, 2003, 2004,
+2005, 2006, 2007 Free Software Foundation, Inc.
+
+@quotation
+Permission is granted to copy, distribute and/or modify this document
+under the terms of the GNU Free Documentation License, Version 1.2 or
+any later version published by the Free Software Foundation; with no
+Invariant Sections, with the Front-Cover texts being ``A GNU
+Manual,'' and with the Back-Cover Texts as in (a) below.  A copy of the
+license is included in the section entitled ``GNU Free Documentation
+License'' in the Emacs manual.
+
+(a) The FSF's Back-Cover Text is: ``You have freedom to copy and modify
+this GNU Manual, like GNU software.  Copies published by the Free
+Software Foundation raise funds for GNU development.''
+
+This document is part of a collection distributed under the GNU Free
+Documentation License.  If you want to distribute this document
+separately from the collection, you can do so by adding a copy of the
+license to the document, as described in section 6 of the license.
+@end quotation
+@end copying
+
+@dircategory Emacs
+@direntry
+* Forms: (forms).	Emacs package for editing data bases
+			  by filling in forms.
+@end direntry
+
+@titlepage
+@sp 6
+@center @titlefont{Forms Mode User's Manual}
+@sp 4
+@center Forms-Mode version 2
+@sp 1
+@center for GNU Emacs 22.1
+@sp 1
+@center April 2007
+@sp 5
+@center Johan Vromans
+@center @i{jvromans@@squirrel.nl}
+@page
+@vskip 0pt plus 1filll
+@insertcopying
+@end titlepage
+
+@ifnottex
+@node Top
+@top Forms Mode
+
+Forms mode is an Emacs major mode for working with simple textual data
+bases in a forms-oriented manner.  In Forms mode, the information in
+these files is presented in an Emacs window in a user-defined format,
+one record at a time.  The user can view records or modify their
+contents.
+
+Forms mode is not a simple major mode, but requires two files to do its
+job: a control file and a data file.  The data file holds the
+actual data to be presented.  The control file describes
+how to present it.
+
+@menu
+* Forms Example::               An example: editing the password data base.
+* Entering and Exiting Forms Mode::
+                                How to visit a file in Forms mode.
+* Forms Commands::              Special commands to use while in Forms mode.
+* Data File Format::            How to format the data file.
+* Control File Format::         How to control forms mode.
+* Format Description::          How to define the forms layout.
+* Modifying Forms Contents::    How to modify.
+* Miscellaneous::               Forms mode messages and other remarks.
+* Error Messages::              List of error messages forms mode can produce.
+* Long Example::                A more complex control file example.
+* GNU Free Documentation License:: The license for this documentation.
+* Credits::                     Thanks everyone.
+* Index::                       Index to this manual.
+@end menu
+@end ifnottex
+
+@node Forms Example
+@chapter Forms Example
+
+Let's illustrate Forms mode with an example.  Suppose you are looking at
+the @file{/etc/passwd} file, and the screen looks like this:
+
+@example
+====== /etc/passwd ======
+
+User : root   Uid: 0   Gid: 1
+
+Name : Super User
+
+Home : /
+
+Shell: /bin/sh
+@end example
+
+As you can see, the familiar fields from the entry for the super user
+are all there, but instead of being colon-separated on one single line,
+they make up a forms.
+
+The contents of the forms consist of the contents of the fields of the
+record (e.g. @samp{root}, @samp{0}, @samp{1}, @samp{Super User})
+interspersed with normal text (e.g @samp{User : }, @samp{Uid: }).
+
+If you modify the contents of the fields, Forms mode will analyze your
+changes and update the file appropriately.  You cannot modify the
+interspersed explanatory text (unless you go to some trouble about it),
+because that is marked read-only (@pxref{Text Properties,,, elisp, The
+Emacs Lisp Reference Manual}).
+
+The Forms mode control file specifies the relationship between the
+format of @file{/etc/passwd} and what appears on the screen in Forms
+mode.  @xref{Control File Format}.
+
+@node Entering and Exiting Forms Mode
+@chapter Entering and Exiting Forms Mode
+
+@table @kbd
+@findex forms-find-file
+@item M-x forms-find-file @key{RET} @var{control-file} @key{RET}
+Visit a database using Forms mode.  Specify the name of the
+@strong{control file}, not the data file!
+
+@findex forms-find-file-other-window
+@item M-x forms-find-file-other-window @key{RET} @var{control-file} @key{RET}
+Similar, but displays the file in another window.
+@end table
+
+The command @code{forms-find-file} evaluates the file
+@var{control-file}, and also visits it in Forms mode.  What you see in
+its buffer is not the contents of this file, but rather a single record
+of the corresponding data file that is visited in its own buffer.  So
+there are two buffers involved in Forms mode: the @dfn{forms buffer}
+that is initially used to visit the control file and that shows the
+records being browsed, and the @dfn{data buffer} that holds the data
+file being visited.  The latter buffer is normally not visible.
+
+Initially, the first record is displayed in the forms buffer.
+The mode line displays the major mode name @samp{Forms}, followed by the
+minor mode @samp{View} if the data base is read-only.  The number of the
+current record (@var{n}) and the total number of records in the
+file(@var{t}) are shown in the mode line as @samp{@var{n}/@var{t}}.  For
+example:
+
+@example
+--%%-Emacs: passwd-demo          (Forms View 1/54)----All-------
+@end example
+
+If the buffer is not read-only, you may change the buffer to modify the
+fields in the record.  When you move to a different record, the contents
+of the buffer are parsed using the specifications in
+@code{forms-format-list}, and the data file is updated.  If the record
+has fields that aren't included in the display, they are not changed.
+
+@vindex forms-mode-hooks
+Entering Forms mode runs the normal hook @code{forms-mode-hooks} to
+perform user-defined customization.
+
+To save any modified data, you can use @kbd{C-x C-s}
+(@code{forms-save-buffer}).  This does not save the forms buffer (which would
+be rather useless), but instead saves the buffer visiting the data file.
+
+To terminate Forms mode, you can use @kbd{C-x C-s} (@code{forms-save-buffer})
+and then kill the forms buffer.  However, the data buffer will still
+remain.  If this is not desired, you have to kill this buffer too.
+
+@node Forms Commands
+@chapter Forms Commands
+
+The commands of Forms mode belong to the @kbd{C-c} prefix, with one
+exception: @key{TAB}, which moves to the next field.  Forms mode uses
+different key maps for normal mode and read-only mode.  In read-only
+Forms mode, you can access most of the commands without the @kbd{C-c}
+prefix, but you must type ordinary letters instead of control
+characters; for example, type @kbd{n} instead of @kbd{C-c C-n}.
+
+If your Emacs has been built with X-toolkit support, Forms mode will
+provide its own menu with a number of Forms mode commands.
+
+@table @kbd
+@findex forms-next-record
+@kindex C-c C-n
+@item C-c C-n
+Show the next record (@code{forms-next-record}).  With a numeric
+argument @var{n}, show the @var{n}th next record.
+
+@findex forms-prev-record
+@kindex C-c C-p
+@item C-c C-p
+Show the previous record (@code{forms-prev-record}).  With a numeric
+argument @var{n}, show the @var{n}th previous record.
+
+@findex forms-jump-record
+@kindex C-c C-l
+@item C-c C-l
+Jump to a record by number (@code{forms-jump-record}).   Specify
+the record number with a numeric argument.
+
+@findex forms-first-record
+@kindex C-c <
+@item C-c <
+Jump to the first record (@code{forms-first-record}).
+
+@findex forms-last-record
+@kindex C-c >
+@item C-c >
+Jump to the last record (@code{forms-last-record}).  This command also
+recalculates the number of records in the data file.
+
+@findex forms-next-field
+@kindex TAB
+@item @key{TAB}
+@kindex C-c TAB
+@itemx C-c @key{TAB}
+Jump to the next field in the current record (@code{forms-next-field}).
+With a numeric argument @var{n}, jump forward @var{n} fields.  If this command
+would move past the last field, it wraps around to the first field.
+
+@findex forms-toggle-read-only
+@kindex C-c C-q
+@item C-c C-q
+Toggles read-only mode (@code{forms-toggle-read-only}).  In read-only
+Forms mode, you cannot edit the fields; most Forms mode commands can be
+accessed without the prefix @kbd{C-c} if you use the normal letter
+instead (for example, type @kbd{n} instead of @kbd{C-c C-n}).  In edit
+mode, you can edit the fields and thus change the contents of the data
+base; you must begin Forms mode commands with @code{C-c}.  Switching
+to edit mode is allowed only if you have write access to the data file.
+
+@findex forms-insert-record
+@kindex C-c C-o
+@item C-c C-o
+Create a new record and insert it before the current record
+(@code{forms-insert-record}).  It starts out with empty (or default)
+contents for its fields; you can then edit the fields.  With a numeric
+argument, the new record is created @emph{after} the current one.
+See also @code{forms-modified-record-filter} in @ref{Modifying Forms
+Contents}.
+
+@findex forms-delete-record
+@kindex C-c C-k
+@item C-c C-k
+Delete the current record (@code{forms-delete-record}).  You are
+prompted for confirmation before the record is deleted unless a numeric
+argument has been provided.
+
+@findex forms-search-forward
+@kindex C-c C-s @var{regexp} @key{RET}
+@item C-c C-s @var{regexp} @key{RET}
+Search forward for @var{regexp} in all records following this one
+(@code{forms-search-forward}).  If found, this record is shown.
+If you give an empty argument, the previous regexp is used again.
+
+@findex forms-search-backward
+@kindex C-c C-r @var{regexp} @key{RET}
+@item C-c C-r @var{regexp} @key{RET}
+Search backward for @var{regexp} in all records following this one
+(@code{forms-search-backward}).  If found, this record is shown.
+If you give an empty argument, the previous regexp is used again.
+
+@ignore
+@findex forms-exit
+@kindex C-c C-x
+@item C-c C-x
+Terminate Forms mode processing (@code{forms-exit}).  The data file is
+saved if it has been modified.
+
+@findex forms-exit-no-save
+@item M-x forms-exit-no-save
+Terminates forms mode processing without saving modified data first.
+@end ignore
+
+@findex forms-prev-field
+@item M-x forms-prev-field
+Similar to @code{forms-next-field} but moves backwards.
+
+@findex forms-save-buffer
+@item M-x forms-save-buffer
+@kindex C-x C-s
+@itemx C-x C-s
+Forms mode replacement for @code{save-buffer}. When executed in the
+forms buffer it will save the contents of the (modified) data buffer
+instead. In Forms mode this function will be bound to @kbd{C-x C-s}.
+
+@findex forms-print
+@item M-x forms-print
+This command can be used to make a formatted print
+of the contents of the data file.
+
+@end table
+
+In addition the command @kbd{M-x revert-buffer} is useful in Forms mode
+just as in other modes.
+
+@ignore
+@vindex forms-forms-scroll
+@findex scroll-up
+@findex scroll-down
+If the variable @code{forms-forms-scrolls} is set to a value other
+than @code{nil} (which it is, by default), the Emacs functions
+@code{scroll-up} and @code{scroll-down} will perform a
+@code{forms-next-record} and @code{forms-prev-record} when in forms
+mode.  So you can use your favorite page commands to page through the
+data file.
+
+@vindex forms-forms-jump
+@findex beginning-of-buffer
+@findex end-of-buffer
+Likewise, if the variable @code{forms-forms-jump} is not @code{nil}
+(which it is, by default), Emacs functions @code{beginning-of-buffer}
+and @code{end-of-buffer} will perform @code{forms-first-record} and
+@code{forms-last-record} when in forms mode.
+@end ignore
+
+The following function key definitions are set up in Forms mode
+(whether read-only or not):
+
+@table @kbd
+@kindex next
+@item next
+forms-next-record
+
+@kindex prior
+@item prior
+forms-prev-record
+
+@kindex begin
+@item begin
+forms-first-record
+
+@kindex end
+@item end
+forms-last-record
+
+@kindex S-Tab
+@findex forms-prev-field
+@item S-Tab
+forms-prev-field
+@end table
+
+@node Data File Format
+@chapter Data File Format
+
+@cindex record
+@cindex field
+@vindex forms-field-sep
+Files for use with Forms mode are very simple---each @dfn{record}
+(usually one line) forms the contents of one form.  Each record consists
+of a number of @dfn{fields}, which are separated by the value of the
+string @code{forms-field-sep}, which is @code{"\t"} (a Tab) by default.
+
+@vindex forms-read-file-filter
+@vindex forms-write-file-filter
+If the format of the data file is not suitable enough you can define the
+filter functions @code{forms-read-file-filter} and
+@code{forms-write-file-filter}. @code{forms-read-file-filter} is called
+when the data file is read from disk into the data buffer. It operates
+on the data buffer, ignoring read-only protections. When the data file
+is saved to disk @code{forms-write-file-filter} is called to cancel the
+effects of @code{forms-read-file-filter}. After being saved,
+@code{forms-read-file-filter} is called again to prepare the data buffer
+for further processing.
+
+@cindex pseudo-newline
+@vindex forms-multi-line
+Fields may contain text which shows up in the forms in multiple lines.
+These lines are separated in the field using a ``pseudo-newline''
+character which is defined by the value of the string
+@code{forms-multi-line}.  Its default value is @code{"\^k"} (a Control-K
+character).  If it is
+set to @code{nil}, multiple line fields are prohibited.
+
+If the data file does not exist, it is automatically created.
+
+@node Control File Format
+@chapter Control File Format
+
+@cindex control file
+The Forms mode @dfn{control file} serves two purposes.  First, it names
+the data file to use, and defines its format and properties.  Second,
+the Emacs buffer it occupies is used by Forms mode to display the forms.
+
+The contents of the control file are evaluated as a Lisp program.  It
+should set the following Lisp variables to suitable values:
+
+@table @code
+@vindex forms-file
+@item forms-file
+This variable specifies the name of the data file.  Example:
+
+@example
+(setq forms-file "my/data-file")
+@end example
+
+If the control file doesn't set @code{forms-file}, Forms mode
+reports an error.
+
+@vindex forms-format-list
+@item forms-format-list
+This variable describes the way the fields of the record are formatted on
+the screen.  For details, see @ref{Format Description}.
+
+@vindex forms-number-of-fields
+@item forms-number-of-fields
+This variable holds the number of fields in each record of the data
+file.  Example:
+
+@example
+(setq forms-number-of-fields 10)
+@end example
+@end table
+
+If the control file does not set @code{forms-format-list} a default
+format is used.  In this situation, Forms mode will deduce the number of
+fields from the data file providing this file exists and
+@code{forms-number-of-records} has not been set in the control file.
+
+The control file can optionally set the following additional Forms mode
+variables.  Most of them have default values that are good for most
+applications.
+
+@table @code
+@vindex forms-field-sep
+@item forms-field-sep
+This variable may be used to designate the string which separates the
+fields in the records of the data file.  If not set, it defaults to the
+string @code{"\t"} (a Tab character).  Example:
+
+@example
+(setq forms-field-sep "\t")
+@end example
+
+@vindex forms-read-only
+@item forms-read-only
+If the value is non-@code{nil}, the data file is treated read-only.  (Forms
+mode also treats the data file as read-only if you don't have access to
+write it.)  Example:
+
+@example
+(set forms-read-only t)
+@end example
+
+@vindex forms-multi-line
+@item forms-multi-line
+This variable specifies the @dfn{pseudo newline} separator that allows
+multi-line fields.  This separator goes between the ``lines'' within a
+field---thus, the field doesn't really contain multiple lines, but it
+appears that way when displayed in Forms mode.  If the value is
+@code{nil}, multi-line text fields are prohibited.  The pseudo newline
+must not be a character contained in @code{forms-field-sep}.
+
+The default value is @code{"\^k"}, the character Control-K.  Example:
+
+@example
+(setq forms-multi-line "\^k")
+@end example
+
+@ignore
+@vindex forms-forms-scroll
+@item forms-forms-scroll
+@xref{Forms Mode Commands}, for details.
+
+@vindex forms-forms-jump
+@item forms-forms-jump
+@xref{Forms Mode Commands}, for details.
+@end ignore
+
+@findex forms-read-file-filter
+@item forms-read-file-filter
+This variable holds the name of a function to be called after the data
+file has been read in. This can be used to transform the contents of the
+data file into a format more suitable for forms processing.
+If it is @code{nil}, no function is called.  For example, to maintain a
+gzipped database:
+
+@example
+(defun gzip-read-file-filter ()
+  (shell-command-on-region (point-min) (point-max)
+                           "gzip -d" t t))
+(setq forms-read-file-filter 'gzip-read-file-filter)
+@end example
+
+@findex forms-write-file-filter
+@item forms-write-file-filter
+This variable holds the name of a function to be called before writing
+out the contents of the data file.
+This can be used to undo the effects of @code{forms-read-file-filter}.
+If it is @code{nil}, no function is called.  Example:
+
+@example
+(defun gzip-write-file-filter ()
+  (make-variable-buffer-local 'require-final-newline)
+  (setq require-final-newline nil)
+  (shell-command-on-region (point-min) (point-max)
+                           "gzip" t t))
+(setq forms-write-file-filter 'gzip-write-file-filter)
+@end example
+
+@findex forms-new-record-filter
+@item forms-new-record-filter
+This variable holds a function to be called whenever a new record is created
+to supply default values for fields.  If it is @code{nil}, no function is
+called.
+@xref{Modifying Forms Contents}, for details.
+
+@findex forms-modified-record-filter
+@item  forms-modified-record-filter
+This variable holds a function to be called whenever a record is
+modified, just before updating the Forms data file.  If it is
+@code{nil}, no function is called.
+@xref{Modifying Forms Contents}, for details.
+
+@findex forms-insert-after
+@item forms-insert-after
+If this variable is not @code{nil}, new records are created @emph{after} the
+current record. Also, upon visiting a file, the initial position will be
+at the last record instead of the first one.
+
+@findex forms-check-number-of-fields
+@item forms-check-number-of-fields
+Normally each record is checked to contain the correct number of fields.
+Under certain circumstances, this can be undesirable.
+If this variable is set to @code{nil}, these checks will be bypassed.
+@end table
+
+@node Format Description
+@chapter The Format Description
+
+@vindex forms-format-list
+  The variable @code{forms-format-list} specifies the format of the data
+in the data file, and how to convert the data for display in Forms mode.
+Its value must be a list of Forms mode @dfn{formatting elements}, each
+of which can be a string, a number, a Lisp list, or a Lisp symbol that
+evaluates to one of those.  The formatting elements are processed in the
+order they appear in the list.
+
+@table @var
+@item string
+A string formatting element is inserted in the forms ``as is,'' as text
+that the user cannot alter.
+
+@item number
+A number element selects a field of the record.  The contents of this
+field are inserted in the display at this point.  Field numbers count
+starting from 1 (one).
+
+@item list
+A formatting element that is a list specifies a function call.  This
+function is called every time a record is displayed, and its result,
+which must be a string, is inserted in the display text.  The function
+should do nothing but returning a string.
+
+@vindex forms-fields
+The function you call can access the fields of the record as a list in
+the variable
+@code{forms-fields}.
+
+@item symbol
+A symbol used as a formatting element should evaluate to a string, number,
+or list; the value is interpreted as a formatting element, as described
+above.
+@end table
+
+If a record does not contain the number of fields as specified in
+@code{forms-number-of-fields}, a warning message will be printed.  Excess
+fields are ignored, missing fields are set to empty.
+
+The control file which displays @file{/etc/passwd} file as demonstrated
+in the beginning of this manual might look as follows:
+
+@example
+;; @r{This demo visits @file{/etc/passwd}.}
+
+(setq forms-file "/etc/passwd")
+(setq forms-number-of-fields 7)
+(setq forms-read-only t)                 ; @r{to make sure}
+(setq forms-field-sep ":")
+;; @r{Don't allow multi-line fields.}
+(setq forms-multi-line nil)
+
+(setq forms-format-list
+      (list
+       "====== /etc/passwd ======\n\n"
+       "User : "    1
+       "   Uid: "   3
+       "   Gid: "   4
+       "\n\n"
+       "Name : "    5
+       "\n\n"
+       "Home : "    6
+       "\n\n"
+       "Shell: "    7
+       "\n"))
+@end example
+
+When you construct the value of  @code{forms-format-list}, you should
+usually either quote the whole value, like this,
+
+@example
+(setq forms-format-list
+     '(
+       "====== " forms-file " ======\n\n"
+       "User : "    1
+       (make-string 20 ?-)
+       @dots{}
+      ))
+@end example
+
+@noindent
+or quote the elements which are lists, like this:
+
+@example
+(setq forms-format-list
+      (list
+       "====== " forms-file " ======\n\n"
+       "User : "    1
+       '(make-string 20 ?-)
+       @dots{}
+      ))
+@end example
+
+Forms mode validates the contents of @code{forms-format-list} when you
+visit a database.  If there are errors, processing is aborted with an
+error message which includes a descriptive text.  @xref{Error Messages},
+for a detailed list of error messages.
+
+If no @code{forms-format-list} is specified, Forms mode will supply a
+default format list.  This list contains the name of the file being
+visited, and a simple label for each field indicating the field number.
+
+@node Modifying Forms Contents
+@chapter Modifying The Forms Contents
+
+If @code{forms-read-only} is @code{nil}, the user can modify the fields
+and records of the database.
+
+All normal editing commands are available for editing the contents of the
+displayed record.  You cannot delete or modify the fixed, explanatory
+text that comes from string formatting elements, but you can modify the
+actual field contents.
+
+@ignore
+@c This is for the Emacs 18 version only.
+If the contents of the forms cannot be recognized properly, this is
+signaled using a descriptive text.  @xref{Error Messages}, for more info.
+The cursor will indicate the last part of the forms which was
+successfully parsed.  It's important to avoid entering field contents
+that would cause confusion with the field-separating fixed text.
+@end ignore
+
+If the variable @code{forms-modified-record-filter} is non-@code{nil},
+it is called as a function before the new data is written to the data
+file.  The function receives one argument, a vector that contains the
+contents of the fields of the record.
+
+The function can refer to fields with @code{aref} and modify them with
+@code{aset}.  The first field has number 1 (one); thus, element 0 of the
+vector is not used.  The function should return the same vector it was
+passed; the (possibly modified) contents of the vector determine what is
+actually written in the file.  Here is an example:
+
+@example
+(defun my-modified-record-filter (record)
+  ;; @r{Modify second field.}
+  (aset record 2 (current-time-string))
+  ;; @r{Return the field vector.}
+  record)
+
+(setq forms-modified-record-filter 'my-modified-record-filter)
+@end example
+
+If the variable @code{forms-new-record-filter} is non-@code{nil}, its
+value is a function to be called to fill in default values for the
+fields of a new record.  The function is passed a vector of empty
+strings, one for each field; it should return the same vector, with
+the desired field values stored in it.  Fields are numbered starting
+from 1 (one).  Example:
+
+@example
+(defun my-new-record-filter (fields)
+  (aset fields 5 (login-name))
+  (aset fields 1 (current-time-string))
+  fields)
+
+(setq forms-new-record-filter 'my-new-record-filter)
+@end example
+
+@node Miscellaneous
+@chapter Miscellaneous
+
+@vindex forms-version
+The global variable @code{forms-version} holds the version information
+of the Forms mode software.
+
+@findex forms-enumerate
+It is very convenient to use symbolic names for the fields in a record.
+The function @code{forms-enumerate} provides an elegant means to define
+a series of variables whose values are consecutive integers.  The
+function returns the highest number used, so it can be used to set
+@code{forms-number-of-fields} also.  For example:
+
+@example
+(setq forms-number-of-fields
+      (forms-enumerate
+       '(field1 field2 field3 @dots{})))
+@end example
+
+This sets @code{field1} to 1, @code{field2} to 2, and so on.
+
+Care has been taken to keep the Forms mode variables buffer-local, so it
+is possible to visit multiple files in Forms mode simultaneously, even
+if they have different properties.
+
+@findex forms-mode
+If you have visited the control file in normal fashion with
+@code{find-file} or a like command, you can switch to Forms mode with
+the command @code{M-x forms-mode}.  If you put @samp{-*- forms -*-} in
+the first line of the control file, then visiting it enables Forms mode
+automatically.  But this makes it hard to edit the control file itself,
+so you'd better think twice before using this.
+
+The default format for the data file, using @code{"\t"} to separate
+fields and @code{"\^k"} to separate lines within a field, matches the
+file format of some popular database programs, e.g. FileMaker.  So
+@code{forms-mode} can decrease the need to use proprietary software.
+
+@node Error Messages
+@chapter Error Messages
+
+This section describes all error messages which can be generated by
+forms mode.  Error messages that result from parsing the control file
+all start with the text @samp{Forms control file error}.  Messages
+generated while analyzing the definition of @code{forms-format-list}
+start with @samp{Forms format error}.
+
+@table @code
+@item Forms control file error: `forms-file' has not been set
+The variable @code{forms-file} was not set by the control file.
+
+@item Forms control file error: `forms-number-of-fields' has not been set
+The variable @code{forms-number-of-fields} was not set by the control
+file.
+
+@item Forms control file error: `forms-number-of-fields' must be a number > 0
+The variable @code{forms-number-of-fields} did not contain a positive
+number.
+
+@item Forms control file error: `forms-field-sep' is not a string
+@itemx Forms control file error: `forms-multi-line' must be nil or a one-character string
+The variable @code{forms-multi-line} was set to something other than
+@code{nil} or a single-character string.
+
+@item Forms control file error: `forms-multi-line' is equal to 'forms-field-sep'
+The variable @code{forms-multi-line} may not be equal to
+@code{forms-field-sep} for this would make it impossible to distinguish
+fields and the lines in the fields.
+
+@item Forms control file error: `forms-new-record-filter' is not a function
+@itemx Forms control file error: `forms-modified-record-filter' is not a function
+The variable has been set to something else than a function.
+
+@item Forms control file error: `forms-format-list' is not a list
+The variable @code{forms-format-list} was not set to a Lisp list
+by the control file.
+
+@item Forms format error: field number @var{xx} out of range 1..@var{nn}
+A field number was supplied in @code{forms-format-list} with a value of
+@var{xx}, which was not greater than zero and smaller than or equal to
+the number of fields in the forms, @var{nn}.
+
+@item Forms format error: @var{fun} is not a function
+The first element of a list which is an element of
+@code{forms-format-list} was not a valid Lisp function.
+
+@item Forms format error: invalid element @var{xx}
+A list element was supplied in @code{forms-format-list} which was not a
+string, number or list.
+
+@ignore
+@c This applies to Emacs 18 only.
+@c Error messages generated while a modified form is being analyzed.
+
+@item Parse error: not looking at `...'
+When re-parsing the contents of a forms, the text shown could not
+be found.
+
+@item Parse error: cannot find `...'
+When re-parsing the contents of a forms, the text shown, which
+separates two fields, could not be found.
+
+@item Parse error: cannot parse adjacent fields @var{xx} and @var{yy}
+Fields @var{xx} and @var{yy} were not separated by text, so could not be
+parsed again.
+@end ignore
+
+@item Warning: this record has @var{xx} fields instead of @var{yy}
+The number of fields in this record in the data file did not match
+@code{forms-number-of-fields}.  Missing fields will be made empty.
+
+@item Multi-line fields in this record - update refused!
+The current record contains newline characters, hence can not be written
+back to the data file, for it would corrupt it.  Probably you inserted a
+newline in a field, while @code{forms-multi-line} was @code{nil}.
+
+@item Field separator occurs in record - update refused!
+The current record contains the field separator string inside one of the
+fields. It can not be written back to the data file, for it would
+corrupt it. Probably you inserted the field separator string in a field.
+
+@item Record number @var{xx} out of range 1..@var{yy}
+A jump was made to non-existing record @var{xx}.  @var{yy} denotes the
+number of records in the file.
+
+@item Stuck at record @var{xx}
+An internal error prevented a specific record from being retrieved.
+
+@item No write access to @code{"}@var{file}@code{"}
+An attempt was made to enable edit mode on a file that has been write
+protected.
+
+@item Search failed: @var{regexp}
+The @var{regexp} could not be found in the data file. Forward searching
+is done from the current location until the end of the file, then
+retrying from the beginning of the file until the current location.
+Backward searching is done from the current location until the beginning
+of the file, then retrying from the end of the file until the current
+location.
+
+@item Wrapped
+A search completed successfully after wrapping around.
+
+@item Warning: number of records changed to @var{nn}
+Forms mode's idea of the number of records has been adjusted to the
+number of records actually present in the data file.
+
+@item Problem saving buffers?
+An error occurred while saving the data file buffer. Most likely, Emacs
+did ask to confirm deleting the buffer because it had been modified, and
+you said `no'.
+@end table
+
+@node Long Example
+@chapter Long Example
+
+The following example exploits most of the features of Forms mode.
+This example is included in the distribution as file @file{forms-d2.el}.
+
+@example
+;; demo2 -- demo forms-mode     -*- emacs-lisp -*-
+
+;; @r{This sample forms exploit most of the features of forms mode.}
+
+;; @r{Set the name of the data file.}
+(setq forms-file "forms-d2.dat")
+
+;; @r{Use @code{forms-enumerate} to set field names and number thereof.}
+(setq forms-number-of-fields
+      (forms-enumerate
+       '(arch-newsgroup                 ; 1
+         arch-volume                    ; 2
+         arch-issue                     ; and ...
+         arch-article                   ; ... so
+         arch-shortname                 ; ... ... on
+         arch-parts
+         arch-from
+         arch-longname
+         arch-keywords
+         arch-date
+         arch-remarks)))
+
+;; @r{The following functions are used by this form for layout purposes.}
+;;
+(defun arch-tocol (target &optional fill)
+  "Produces a string to skip to column TARGET.
+Prepends newline if needed.
+The optional FILL should be a character, used to fill to the column."
+  (if (null fill)
+      (setq fill ? ))
+  (if (< target (current-column))
+      (concat "\n" (make-string target fill))
+    (make-string (- target (current-column)) fill)))
+;;
+(defun arch-rj (target field &optional fill)
+  "Produces a string to skip to column TARGET\
+ minus the width of field FIELD.
+Prepends newline if needed.
+The optional FILL should be a character,
+used to fill to the column."
+  (arch-tocol (- target (length (nth field forms-fields))) fill))
+
+;; @r{Record filters.}
+;;
+(defun new-record-filter (the-record)
+  "Form a new record with some defaults."
+  (aset the-record arch-from (user-full-name))
+  (aset the-record arch-date (current-time-string))
+  the-record)                           ; return it
+(setq forms-new-record-filter 'new-record-filter)
+
+;; @r{The format list.}
+(setq forms-format-list
+     (list
+       "====== Public Domain Software Archive ======\n\n"
+       arch-shortname
+       " - "                    arch-longname
+       "\n\n"
+       "Article: "              arch-newsgroup
+       "/"                      arch-article
+       " "
+       '(arch-tocol 40)
+       "Issue: "                arch-issue
+       " "
+       '(arch-rj 73 10)
+       "Date: "                 arch-date
+       "\n\n"
+       "Submitted by: "         arch-from
+       "\n"
+       '(arch-tocol 79 ?-)
+       "\n"
+       "Keywords: "             arch-keywords
+       "\n\n"
+       "Parts: "                arch-parts
+       "\n\n====== Remarks ======\n\n"
+       arch-remarks
+     ))
+
+;; @r{That's all, folks!}
+@end example
+
+@node Credits
+@chapter Credits
+
+Bug fixes and other useful suggestions were supplied by
+Harald Hanche-Olsen (@code{hanche@@imf.unit.no}),
+@code{cwitty@@portia.stanford.edu},
+Jonathan I. Kamens,
+Per Cederqvist  (@code{ceder@@signum.se}),
+Michael Lipka (@code{lipka@@lip.hanse.de}),
+Andy Piper (@code{ajp@@eng.cam.ac.uk}),
+Frederic Pierresteguy  (@code{F.Pierresteguy@@frcl.bull.fr}),
+Ignatios Souvatzis
+and Richard Stallman (@code{rms@@gnu.org}).
+
+This documentation was slightly inspired by the documentation of ``rolo
+mode'' by Paul Davis at Schlumberger Cambridge Research
+(@code{davis%scrsu1%sdr.slb.com@@relay.cs.net}).
+
+None of this would have been possible without GNU Emacs of the Free
+Software Foundation.  Thanks, Richard!
+
+@node GNU Free Documentation License
+@appendix GNU Free Documentation License
+@include doclicense.texi
+
+@node Index
+@unnumbered Index
+@printindex cp
+
+@contents
+@bye
+
+@ignore
+   arch-tag: 2ac9810b-aa49-4ea6-8030-d7f1ecd467ed
+@end ignore