Re: Documenting define-generic-mode.

[Lute Kamstra <Lute.Kamstra.lists@xs4all.nl>]

Richard Stallman <rms@gnu.org> writes:

>     Shall I document define-generic-mode in lispref/modes.texi?  I think
>     its own node "Generic Modes", right after the node "Derived Modes",
>     would be appropriate.
>
> You can try drafting something, and I will tell you what I think of
> it.

There you go...

Lute.


Index: lispref/modes.texi
===================================================================
RCS file: /cvsroot/emacs/emacs/lispref/modes.texi,v
retrieving revision 1.98
diff -c -r1.98 modes.texi
*** lispref/modes.texi	28 Apr 2005 11:32:54 -0000	1.98
--- lispref/modes.texi	28 Apr 2005 13:49:05 -0000
***************
*** 103,108 ****
--- 103,110 ----
  * Mode Help::               Finding out how to use a mode.
  * Derived Modes::           Defining a new major mode based on another major
                                mode.
+ * Generic Modes::           Defining a simple major mode that supports
+                               comment syntax and Font Lock mode.
  * Mode Hooks::              Hooks run at the end of major mode functions.
  @end menu
  
***************
*** 798,803 ****
--- 800,806 ----
  
  @node Derived Modes
  @subsection Defining Derived Modes
+ @cindex derived mode
  
    It's often useful to define a new major mode in terms of an existing
  one.  An easy way to do this is to use @code{define-derived-mode}.
***************
*** 860,865 ****
--- 863,918 ----
  @code{define-derived-mode} does that automatically.
  @end defmac
  
+ @node Generic Modes
+ @subsection Generic Modes
+ @cindex generic mode
+ 
+ @dfn{Generic modes} are simple major modes with basic support for
+ comment syntax and Font Lock mode.  They are primarily useful for
+ configuration files.  The macro @code{define-generic-mode} defines a
+ generic mode.  See the file @file{generic-x.el} for some examples of
+ the use of @code{define-generic-mode}.
+ 
+ @defmac define-generic-mode mode comment-list keyword-list font-lock-list auto-mode-list function-list &optional docstring &rest custom-keyword-args
+ This macro creates a new generic mode.  The argument @var{mode} is the
+ name of the command for the generic mode; it need not be quoted.  The
+ optional argument @var{docstring} is the documentation for the mode
+ command.  If you do not supply it, a default documentation string will
+ be used instead.
+ 
+ @var{comment-list} is a list, whose entries are either a single
+ character, a one or two character string or a cons pair.  If the entry
+ is a character or a string, it is added to the mode's syntax table
+ with ``comment starter'' syntax.  If the entry is a cons pair, the
+ elements of the pair are considered to be ``comment starter'' and
+ ``comment ender'' respectively.  (The latter should be @code{nil} if
+ you want comments to end at the end of the line.)  Note that Emacs has
+ limitations regarding comment characters.  @xref{Syntax Tables}.
+ 
+ @var{keyword-list} is a list of keywords to highlight with
+ @code{font-lock-keyword-face}.  Each keyword should be a string.
+ @var{font-lock-list} is a list of additional expressions to highlight.
+ Each entry in this list should have the same form as an entry in
+ @code{font-lock-keywords}.  @xref{Search-based Fontification}.
+ 
+ @var{auto-mode-list} is a list of regular expressions to add to the
+ variable @code{auto-mode-alist}.  These regular expressions are added
+ as soon as @code{define-generic-mode} is called.
+ 
+ @var{function-list} is a list of functions to call to do some
+ additional setup.  The mode command calls these functions just before
+ it runs the mode hook.
+ 
+ The optional @var{custom-keyword-args} are pairs of keywords and
+ values.  They are passed to the generated @code{defcustom} form of the
+ mode hook variable @var{mode}-hook.  The default value for the
+ @samp{:group} keyword is @var{mode} without the possible trailing
+ @samp{-mode}.  Don't use this default group name unless you have
+ written a @code{defgroup} to define that group properly (@pxref{Group
+ Definitions}).  You can specify keyword arguments without specifying a
+ docstring.
+ @end defmac
+ 
  @node Mode Hooks
  @subsection Mode Hooks