changeset 84156:7bf75f354de1

Move to ../doc/emacs/, misc/
author Glenn Morris <rgm@gnu.org>
date Thu, 06 Sep 2007 04:36:37 +0000
parents 092e0ef56d7d
children 60fb8ba0c0bb
files man/forms.texi
diffstat 1 files changed, 0 insertions(+), 985 deletions(-) [+]
line wrap: on
line diff
--- a/man/forms.texi	Thu Sep 06 04:36:32 2007 +0000
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,985 +0,0 @@
-\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