[Emacs-diffs] Changes to forms.texi

[Glenn Morris]

CVSROOT:        /sources/emacs
Module name:    emacs
Changes by:     Glenn Morris <gm>       07/09/06 05:00:10

Index: forms.texi
===================================================================
RCS file: forms.texi
diff -N forms.texi
--- /dev/null   1 Jan 1970 00:00:00 -0000
+++ forms.texi  6 Sep 2007 05:00:10 -0000       1.1
@@ -0,0 +1,985 @@
+\input texinfo                 @c -*-texinfo-*-
address@hidden documentation for forms-mode
address@hidden Written by Johan Vromans, and edited by Richard Stallman
+
address@hidden %**start of header (This is for running Texinfo on a region.)
address@hidden ../info/forms
address@hidden Forms Mode User's Manual
address@hidden vr cp
address@hidden fn cp
address@hidden ky cp
address@hidden
address@hidden
address@hidden odd
address@hidden iftex
address@hidden      @smallbook
address@hidden %**end of header (This is for running Texinfo on a region.)
+
address@hidden
+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.
+
address@hidden
+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.
address@hidden quotation
address@hidden copying
+
address@hidden Emacs
address@hidden
+* Forms: (forms).      Emacs package for editing data bases
+                         by filling in forms.
address@hidden direntry
+
address@hidden
address@hidden 6
address@hidden @titlefont{Forms Mode User's Manual}
address@hidden 4
address@hidden Forms-Mode version 2
address@hidden 1
address@hidden for GNU Emacs 22.1
address@hidden 1
address@hidden April 2007
address@hidden 5
address@hidden Johan Vromans
address@hidden @i{jvromans@@squirrel.nl}
address@hidden
address@hidden 0pt plus 1filll
address@hidden
address@hidden titlepage
+
address@hidden
address@hidden Top
address@hidden 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.
+
address@hidden
+* 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.
address@hidden menu
address@hidden ifnottex
+
address@hidden Forms Example
address@hidden 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:
+
address@hidden
+====== /etc/passwd ======
+
+User : root   Uid: 0   Gid: 1
+
+Name : Super User
+
+Home : /
+
+Shell: /bin/sh
address@hidden 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}.
+
address@hidden Entering and Exiting Forms Mode
address@hidden Entering and Exiting Forms Mode
+
address@hidden @kbd
address@hidden forms-find-file
address@hidden M-x forms-find-file @key{RET} @var{control-file} @key{RET}
+Visit a database using Forms mode.  Specify the name of the
address@hidden file}, not the data file!
+
address@hidden forms-find-file-other-window
address@hidden M-x forms-find-file-other-window @key{RET} @var{control-file} 
@key{RET}
+Similar, but displays the file in another window.
address@hidden table
+
+The command @code{forms-find-file} evaluates the file
address@hidden, 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 @address@hidden/@var{t}}.  For
+example:
+
address@hidden
+--%%-Emacs: passwd-demo          (Forms View 1/54)----All-------
address@hidden 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
address@hidden, and the data file is updated.  If the record
+has fields that aren't included in the display, they are not changed.
+
address@hidden 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.
+
address@hidden Forms Commands
address@hidden 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.
+
address@hidden @kbd
address@hidden forms-next-record
address@hidden C-c C-n
address@hidden 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.
+
address@hidden forms-prev-record
address@hidden C-c C-p
address@hidden 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.
+
address@hidden forms-jump-record
address@hidden C-c C-l
address@hidden C-c C-l
+Jump to a record by number (@code{forms-jump-record}).   Specify
+the record number with a numeric argument.
+
address@hidden forms-first-record
address@hidden C-c <
address@hidden C-c <
+Jump to the first record (@code{forms-first-record}).
+
address@hidden forms-last-record
address@hidden C-c >
address@hidden C-c >
+Jump to the last record (@code{forms-last-record}).  This command also
+recalculates the number of records in the data file.
+
address@hidden forms-next-field
address@hidden TAB
address@hidden @key{TAB}
address@hidden C-c TAB
address@hidden 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.
+
address@hidden forms-toggle-read-only
address@hidden C-c C-q
address@hidden 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.
+
address@hidden forms-insert-record
address@hidden C-c C-o
address@hidden 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}.
+
address@hidden forms-delete-record
address@hidden C-c C-k
address@hidden 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.
+
address@hidden forms-search-forward
address@hidden C-c C-s @var{regexp} @key{RET}
address@hidden 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.
+
address@hidden forms-search-backward
address@hidden C-c C-r @var{regexp} @key{RET}
address@hidden 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.
+
address@hidden
address@hidden forms-exit
address@hidden C-c C-x
address@hidden C-c C-x
+Terminate Forms mode processing (@code{forms-exit}).  The data file is
+saved if it has been modified.
+
address@hidden forms-exit-no-save
address@hidden M-x forms-exit-no-save
+Terminates forms mode processing without saving modified data first.
address@hidden ignore
+
address@hidden forms-prev-field
address@hidden M-x forms-prev-field
+Similar to @code{forms-next-field} but moves backwards.
+
address@hidden forms-save-buffer
address@hidden M-x forms-save-buffer
address@hidden C-x C-s
address@hidden 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}.
+
address@hidden forms-print
address@hidden M-x forms-print
+This command can be used to make a formatted print
+of the contents of the data file.
+
address@hidden table
+
+In addition the command @kbd{M-x revert-buffer} is useful in Forms mode
+just as in other modes.
+
address@hidden
address@hidden forms-forms-scroll
address@hidden scroll-up
address@hidden 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
address@hidden and @code{scroll-down} will perform a
address@hidden and @code{forms-prev-record} when in forms
+mode.  So you can use your favorite page commands to page through the
+data file.
+
address@hidden forms-forms-jump
address@hidden beginning-of-buffer
address@hidden 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
address@hidden when in forms mode.
address@hidden ignore
+
+The following function key definitions are set up in Forms mode
+(whether read-only or not):
+
address@hidden @kbd
address@hidden next
address@hidden next
+forms-next-record
+
address@hidden prior
address@hidden prior
+forms-prev-record
+
address@hidden begin
address@hidden begin
+forms-first-record
+
address@hidden end
address@hidden end
+forms-last-record
+
address@hidden S-Tab
address@hidden forms-prev-field
address@hidden S-Tab
+forms-prev-field
address@hidden table
+
address@hidden Data File Format
address@hidden Data File Format
+
address@hidden record
address@hidden field
address@hidden 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.
+
address@hidden forms-read-file-filter
address@hidden 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
address@hidden @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,
address@hidden is called again to prepare the data buffer
+for further processing.
+
address@hidden pseudo-newline
address@hidden 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
address@hidden  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.
+
address@hidden Control File Format
address@hidden Control File Format
+
address@hidden 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:
+
address@hidden @code
address@hidden forms-file
address@hidden forms-file
+This variable specifies the name of the data file.  Example:
+
address@hidden
+(setq forms-file "my/data-file")
address@hidden example
+
+If the control file doesn't set @code{forms-file}, Forms mode
+reports an error.
+
address@hidden forms-format-list
address@hidden forms-format-list
+This variable describes the way the fields of the record are formatted on
+the screen.  For details, see @ref{Format Description}.
+
address@hidden forms-number-of-fields
address@hidden forms-number-of-fields
+This variable holds the number of fields in each record of the data
+file.  Example:
+
address@hidden
+(setq forms-number-of-fields 10)
address@hidden example
address@hidden 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
address@hidden 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.
+
address@hidden @code
address@hidden forms-field-sep
address@hidden 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:
+
address@hidden
+(setq forms-field-sep "\t")
address@hidden example
+
address@hidden forms-read-only
address@hidden forms-read-only
+If the value is address@hidden, 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:
+
address@hidden
+(set forms-read-only t)
address@hidden example
+
address@hidden forms-multi-line
address@hidden 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
address@hidden, 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:
+
address@hidden
+(setq forms-multi-line "\^k")
address@hidden example
+
address@hidden
address@hidden forms-forms-scroll
address@hidden forms-forms-scroll
address@hidden Mode Commands}, for details.
+
address@hidden forms-forms-jump
address@hidden forms-forms-jump
address@hidden Mode Commands}, for details.
address@hidden ignore
+
address@hidden forms-read-file-filter
address@hidden 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:
+
address@hidden
+(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)
address@hidden example
+
address@hidden forms-write-file-filter
address@hidden 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:
+
address@hidden
+(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)
address@hidden example
+
address@hidden forms-new-record-filter
address@hidden 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.
address@hidden Forms Contents}, for details.
+
address@hidden forms-modified-record-filter
address@hidden  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
address@hidden, no function is called.
address@hidden Forms Contents}, for details.
+
address@hidden forms-insert-after
address@hidden 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.
+
address@hidden forms-check-number-of-fields
address@hidden 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.
address@hidden table
+
address@hidden Format Description
address@hidden The Format Description
+
address@hidden 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.
+
address@hidden @var
address@hidden string
+A string formatting element is inserted in the forms ``as is,'' as text
+that the user cannot alter.
+
address@hidden 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).
+
address@hidden 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.
+
address@hidden forms-fields
+The function you call can access the fields of the record as a list in
+the variable
address@hidden
+
address@hidden 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.
address@hidden table
+
+If a record does not contain the number of fields as specified in
address@hidden, 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:
+
address@hidden
+;; @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"))
address@hidden example
+
+When you construct the value of  @code{forms-format-list}, you should
+usually either quote the whole value, like this,
+
address@hidden
+(setq forms-format-list
+     '(
+       "====== " forms-file " ======\n\n"
+       "User : "    1
+       (make-string 20 ?-)
+       @dots{}
+      ))
address@hidden example
+
address@hidden
+or quote the elements which are lists, like this:
+
address@hidden
+(setq forms-format-list
+      (list
+       "====== " forms-file " ======\n\n"
+       "User : "    1
+       '(make-string 20 ?-)
+       @dots{}
+      ))
address@hidden 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.
+
address@hidden Modifying Forms Contents
address@hidden 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.
+
address@hidden
address@hidden 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.
address@hidden ignore
+
+If the variable @code{forms-modified-record-filter} is address@hidden,
+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
address@hidden  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:
+
address@hidden
+(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)
address@hidden example
+
+If the variable @code{forms-new-record-filter} is address@hidden, 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:
+
address@hidden
+(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)
address@hidden example
+
address@hidden Miscellaneous
address@hidden Miscellaneous
+
address@hidden forms-version
+The global variable @code{forms-version} holds the version information
+of the Forms mode software.
+
address@hidden 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
address@hidden also.  For example:
+
address@hidden
+(setq forms-number-of-fields
+      (forms-enumerate
+       '(field1 field2 field3 @dots{})))
address@hidden 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.
+
address@hidden forms-mode
+If you have visited the control file in normal fashion with
address@hidden 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
address@hidden can decrease the need to use proprietary software.
+
address@hidden Error Messages
address@hidden 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}.
+
address@hidden @code
address@hidden Forms control file error: `forms-file' has not been set
+The variable @code{forms-file} was not set by the control file.
+
address@hidden 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.
+
address@hidden 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.
+
address@hidden Forms control file error: `forms-field-sep' is not a string
address@hidden 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
address@hidden or a single-character string.
+
address@hidden Forms control file error: `forms-multi-line' is equal to 
'forms-field-sep'
+The variable @code{forms-multi-line} may not be equal to
address@hidden for this would make it impossible to distinguish
+fields and the lines in the fields.
+
address@hidden Forms control file error: `forms-new-record-filter' is not a 
function
address@hidden Forms control file error: `forms-modified-record-filter' is not 
a function
+The variable has been set to something else than a function.
+
address@hidden 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.
+
address@hidden Forms format error: field number @var{xx} out of range 
address@hidden
+A field number was supplied in @code{forms-format-list} with a value of
address@hidden, which was not greater than zero and smaller than or equal to
+the number of fields in the forms, @var{nn}.
+
address@hidden Forms format error: @var{fun} is not a function
+The first element of a list which is an element of
address@hidden was not a valid Lisp function.
+
address@hidden 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.
+
address@hidden
address@hidden This applies to Emacs 18 only.
address@hidden Error messages generated while a modified form is being analyzed.
+
address@hidden Parse error: not looking at `...'
+When re-parsing the contents of a forms, the text shown could not
+be found.
+
address@hidden Parse error: cannot find `...'
+When re-parsing the contents of a forms, the text shown, which
+separates two fields, could not be found.
+
address@hidden 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.
address@hidden ignore
+
address@hidden 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
address@hidden  Missing fields will be made empty.
+
address@hidden 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}.
+
address@hidden 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.
+
address@hidden Record number @var{xx} out of range address@hidden
+A jump was made to non-existing record @var{xx}.  @var{yy} denotes the
+number of records in the file.
+
address@hidden Stuck at record @var{xx}
+An internal error prevented a specific record from being retrieved.
+
address@hidden No write access to @code{"address@hidden@code{"}
+An attempt was made to enable edit mode on a file that has been write
+protected.
+
address@hidden 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.
+
address@hidden Wrapped
+A search completed successfully after wrapping around.
+
address@hidden 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.
+
address@hidden 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'.
address@hidden table
+
address@hidden Long Example
address@hidden 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}.
+
address@hidden
+;; 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!}
address@hidden example
+
address@hidden Credits
address@hidden Credits
+
+Bug fixes and other useful suggestions were supplied by
+Harald Hanche-Olsen (@code{hanche@@imf.unit.no}),
address@hidden@@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!
+
address@hidden GNU Free Documentation License
address@hidden GNU Free Documentation License
address@hidden doclicense.texi
+
address@hidden Index
address@hidden Index
address@hidden cp
+
address@hidden
address@hidden
+
address@hidden
+   arch-tag: 2ac9810b-aa49-4ea6-8030-d7f1ecd467ed
address@hidden ignore