Documenting define-generic-mode.

Documenting define-generic-mode.

[Lute Kamstra]

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.

Lute.

Re: Documenting define-generic-mode.

[Richard Stallman]

    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.

Re: Documenting define-generic-mode.

[Lute Kamstra]

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

Re: Documenting define-generic-mode.

[Luc Teirlinck]

Lute Kamstra wrote:

  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.

"Name" sounds like a string.  "need not" sounds like it is up to the
user whether he quotes it or not.  Is this really correct or is it
true that it must not be quoted?  Of course, the same problems apply
to the docstring from which the above quote was copied.

What about:

This macro creates a new generic mode.  @var{mode} (an unquoted symbol)
is the major mode command.

Sincerely,

Luc.

Re: Documenting define-generic-mode.

[Lute Kamstra]

Luc Teirlinck <teirllm@dms.auburn.edu> writes:

> Lute Kamstra wrote:
>
>   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.
>
> "Name" sounds like a string.  "need not" sounds like it is up to the
> user whether he quotes it or not.  Is this really correct or is it
> true that it must not be quoted?  Of course, the same problems apply
> to the docstring from which the above quote was copied.

I wrote the docstring too.  :-)  It's true that it is up to the user to
quote the symbol or not.  define-generic-mode used to be a function,
so MODE needed to be quoted.  When I rewrote it into a macro, I opted
for an unquoted MODE.  Similar defining macros use unquoted symbols
too.  To be backward compatible, quoting the symbol is still allowed.

> What about:
>
> This macro creates a new generic mode.  @var{mode} (an unquoted symbol)
> is the major mode command.

That's fine with me.

Lute.

Re: Documenting define-generic-mode.

[Luc Teirlinck]

Lute Kamstra wrote:

   Similar defining macros use unquoted symbols too.  To be backward
   compatible, quoting the symbol is still allowed.

Then the original text is OK.  I just thought that it _had_ to be
quoted, as in most macros.

Sincerely,

Luc.

Re: Documenting define-generic-mode.

[Luc Teirlinck]

>From my previous reply:

   I just thought that it _had_ to be quoted, as in most macros.

I of course meant unquoted.

Sincerely,

Luc.

Re: Documenting define-generic-mode.

[Richard Stallman]

       Similar defining macros use unquoted symbols too.  To be backward
       compatible, quoting the symbol is still allowed.

    Then the original text is OK.  I just thought that it _had_ to be
    [un]quoted, as in most macros.

For simplicity and consistency, we should document it as using an
unquoted arg.  There is no need to document the compatibility feature
of accepting the arg with a quote.

(It seems to be documented this way already.)

Re: Documenting define-generic-mode.

[Lute Kamstra]

Richard Stallman <rms@gnu.org> writes:

>        Similar defining macros use unquoted symbols too.  To be backward
>        compatible, quoting the symbol is still allowed.
>
>     Then the original text is OK.  I just thought that it _had_ to be
>     [un]quoted, as in most macros.
>
> For simplicity and consistency, we should document it as using an
> unquoted arg.  There is no need to document the compatibility feature
> of accepting the arg with a quote.
>
> (It seems to be documented this way already.)

Apparently, I read your mind.  ;-)

Lute.