From 82233bead8b9d6075a8dd7449a06d37edad1b03a Mon Sep 17 00:00:00 2001 From: Chong Yidong Date: Sat, 18 Feb 2012 21:38:33 +0800 Subject: [PATCH] Give Tabulated List mode its own Lisp manual node. * modes.texi (Tabulated List Mode): New node. (Basic Major Modes): Add xref to it. * processes.texi (Process Information): Mention Process Menu mode. --- doc/lispref/ChangeLog | 7 ++ doc/lispref/elisp.texi | 3 +- doc/lispref/modes.texi | 237 ++++++++++++++++++++++++++++--------- doc/lispref/processes.texi | 3 + doc/lispref/vol1.texi | 3 +- doc/lispref/vol2.texi | 3 +- 6 files changed, 195 insertions(+), 61 deletions(-) diff --git a/doc/lispref/ChangeLog b/doc/lispref/ChangeLog index 85e78abdc3..33aaa61ed9 100644 --- a/doc/lispref/ChangeLog +++ b/doc/lispref/ChangeLog @@ -1,3 +1,10 @@ +2012-02-18 Chong Yidong + + * modes.texi (Tabulated List Mode): New node. + (Basic Major Modes): Add xref to it. + + * processes.texi (Process Information): Mention Process Menu mode. + 2012-02-17 Chong Yidong * syntax.texi (Motion via Parsing): Doc fix for scan-lists. diff --git a/doc/lispref/elisp.texi b/doc/lispref/elisp.texi index 9efbcfb4b8..efd250c06f 100644 --- a/doc/lispref/elisp.texi +++ b/doc/lispref/elisp.texi @@ -781,9 +781,10 @@ Major Modes * Derived Modes:: Defining a new major mode based on another major mode. * Basic Major Modes:: Modes that other modes are often derived from. +* Mode Hooks:: Hooks run at the end of major mode functions. +* Tabulated List Mode:: Parent mode for buffers containing tabulated data. * 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. * Example Major Modes:: Text mode and Lisp modes. Minor Modes diff --git a/doc/lispref/modes.texi b/doc/lispref/modes.texi index 3c5fbfb22c..ad0010adf3 100644 --- a/doc/lispref/modes.texi +++ b/doc/lispref/modes.texi @@ -284,9 +284,10 @@ buffer is put in Fundamental mode (@pxref{Major Mode Conventions}). * Derived Modes:: Defining a new major mode based on another major mode. * Basic Major Modes:: Modes that other modes are often derived from. +* Mode Hooks:: Hooks run at the end of major mode commands. +* Tabulated List Mode:: Parent mode for buffers containing tabulated data. * 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 commands. * Example Major Modes:: Text mode and Lisp modes. @end menu @@ -893,9 +894,9 @@ Prog mode binds @code{parse-sexp-ignore-comments} to @code{t} @deffn Command special-mode Special mode is a basic major mode for buffers containing text that is -produced specially by Emacs, rather than from a file. Major modes -derived from Special mode are given a @code{mode-class} property of -@code{special} (@pxref{Major Mode Conventions}). +produced specially by Emacs, rather than directly from a file. Major +modes derived from Special mode are given a @code{mode-class} property +of @code{special} (@pxref{Major Mode Conventions}). Special mode sets the buffer to read-only. Its keymap defines several common bindings, including @kbd{q} for @code{quit-window}, @kbd{z} for @@ -907,60 +908,9 @@ mode, which is used by the @samp{*Buffer List*} buffer. @xref{List Buffers,,Listing Existing Buffers, emacs, The GNU Emacs Manual}. @end deffn -@cindex tables of data -@deffn Command tabulated-list-mode -Tabulated List mode is another mode that derives from Special mode. It -displays tabulated data, i.e. a series of rows and columns, where each -row represents a particular entry, whose properties are displayed in the -various columns. It provides a general mechanism for sorting on -columns. You can use Tabulated List mode as the basis for other modes -that need to display lists. For example, the @samp{*Packages*} buffer -uses this (@pxref{Packages,,, emacs, The GNU Emacs Manual}). The -documentation of the @code{tabulated-list-mode} function explains what -you need to do to use it. At a minimum, specify the column format via -the @code{tabulated-list-format} variable. -@end deffn - -@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. To define a generic mode, use the -macro @code{define-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 -This macro defines a generic mode command named @var{mode} (a symbol, -not quoted). The optional argument @var{docstring} is the -documentation for the mode command. If you do not supply it, -@code{define-generic-mode} generates one by default. - -The argument @var{comment-list} is a list in which each element is -either a character, a string of one or two characters, or a cons cell. -A character or a string is set up in the mode's syntax table as a -``comment starter.'' If the entry is a cons cell, the @sc{car} is set -up as a ``comment starter'' and the @sc{cdr} as a ``comment ender.'' -(Use @code{nil} for the latter if you want comments to end at the end -of the line.) Note that the syntax table mechanism has limitations -about what comment starters and enders are actually possible. -@xref{Syntax Tables}. - -The argument @var{keyword-list} is a list of keywords to highlight -with @code{font-lock-keyword-face}. Each keyword should be a string. -Meanwhile, @var{font-lock-list} is a list of additional expressions to -highlight. Each element of this list should have the same form as an -element of @code{font-lock-keywords}. @xref{Search-based -Fontification}. - -The argument @var{auto-mode-list} is a list of regular expressions to -add to the variable @code{auto-mode-alist}. They are added by the execution -of the @code{define-generic-mode} form, not by expanding the macro call. - -Finally, @var{function-list} is a list of functions for the mode -command to call for additional setup. It calls these functions just -before it runs the mode hook variable @code{@var{mode}-hook}. -@end defmac + In addition, modes for buffers of tabulated data can inherit from +Tabulated List mode, which is in turn derived from Special mode. +@xref{Tabulated List Mode}. @node Mode Hooks @subsection Mode Hooks @@ -1021,6 +971,177 @@ This is a normal hook run by @code{run-mode-hooks}. It is run at the very end of every properly-written major mode command. @end defvar +@node Tabulated List Mode +@subsection Tabulated List mode +@cindex Tabulated List mode + + Tabulated List mode is a major mode for displaying tabulated data, +i.e.@: data consisting of @dfn{entries}, each entry occupying one row of +text with its contents divided into columns. Tabulated List mode +provides facilities for pretty-printing rows and columns, and sorting +the rows according to the values in each column. It is derived from +Special mode (@pxref{Basic Major Modes}). + + Tabulated List mode is intended to be used as a parent mode by a more +specialized major mode. Examples include Process Menu mode +(@pxref{Process Information}) and Package Menu mode (@pxref{Package +Menu,,, emacs, The GNU Emacs Manual}). + +@findex tabulated-list-mode + Such a derived mode should use @code{define-derived-mode} in the usual +way, specifying @code{tabulated-list-mode} as the second argument +(@pxref{Derived Modes}). The body of the @code{define-derived-mode} +form should specify the format of the tabulated data, by assigning +values to the variables documented below; then, it should call the +function @code{tabulated-list-init-header} to initialize the header +line. + + The derived mode should also define a @dfn{listing command}. This, +not the mode command, is what the user calls (e.g.@: @kbd{M-x +list-processes}). The listing command should create or switch to a +buffer, turn on the derived mode, specify the tabulated data, and +finally call @code{tabulated-list-print} to populate the buffer. + +@defvar tabulated-list-format +This buffer-local variable specifies the format of the Tabulated List +data. Its value should be a vector. Each element of the vector +represents a data column, and should be a list @code{(@var{name} +@var{width} @var{sort})}, where + +@itemize +@item +@var{name} is the column's name (a string). + +@item +@var{width} is the width to reserve for the column (an integer). This +is meaningless for the last column, which runs to the end of each line. + +@item +@var{sort} specifies how to sort entries by the column. If @code{nil}, +the column cannot be used for sorting. If @code{t}, the column is +sorted by comparing string values. Otherwise, this should be a +predicate function for @code{sort} (@pxref{Rearrangement}), which +accepts two arguments with the same form as the elements of +@code{tabulated-list-entries} (see below). +@end itemize +@end defvar + +@defvar tabulated-list-entries +This buffer-local variable specifies the entries displayed in the +Tabulated List buffer. Its value should be either a list, or a +function. + +If the value is a list, each list element corresponds to one entry, and +should have the form @w{@code{(@var{id} @var{contents})}}, where + +@itemize +@item +@var{id} is either @code{nil}, or a Lisp object that identifies the +entry. If the latter, the cursor stays on the ``same'' entry when +re-sorting entries. Comparison is done with @code{equal}. + +@item +@var{contents} is a vector with the same number of elements as +@code{tabulated-list-format}. Each vector element is either a string, +which is inserted into the buffer as-is, or a list @code{(@var{label} +. @var{properties})}, which means to insert a text button by calling +@code{insert-text-button} with @var{label} and @var{properties} as +arguments (@pxref{Making Buttons}). + +There should be no newlines in any of these strings. +@end itemize + +Otherwise, the value should be a function which returns a list of the +above form when called with no arguments. +@end defvar + +@defvar tabulated-list-revert-hook +This normal hook is run prior to reverting a Tabulated List buffer. A +derived mode can add a function to this hook to recompute +@code{tabulated-list-entries}. +@end defvar + +@defvar tabulated-list-printer +The value of this variable is the function called to insert an entry at +point, including its terminating newline. The function should accept +two arguments, @var{id} and @var{contents}, having the same meanings as +in @code{tabulated-list-entries}. The default value is a function which +inserts an entry in a straightforward way; a mode which uses Tabulated +List mode in a more complex way can specify another function. +@end defvar + +@defvar tabulated-list-sort-key +The value of this variable specifies the current sort key for the +Tabulated List buffer. If it is @code{nil}, no sorting is done. +Otherwise, it should have the form @code{(@var{name} . @var{flip})}, +where @var{name} is a string matching one of the column names in +@code{tabulated-list-format}, and @var{flip}, if non-@code{nil}, means +to invert the sort order. +@end defvar + +@defun tabulated-list-init-header +This function computes and sets @code{header-line-format} for the +Tabulated List buffer (@pxref{Header Lines}), and assigns a keymap to +the header line to allow sort entries by clicking on column headers. + +Modes derived from Tabulated List mode should call this after setting +the above variables (in particular, only after setting +@code{tabulated-list-format}). +@end defun + +@defun tabulated-list-print &optional remember-pos +This function populates the current buffer with entries. It should be +called by the listing command. It erases the buffer, sorts the entries +specified by @code{tabulated-list-entries} according to +@code{tabulated-list-sort-key}, then calls the function specified by +@code{tabulated-list-printer} to insert each entry. + +If the optional argument @var{remember-pos} is non-@code{nil}, this +function looks for the @var{id} element on the current line, if any, and +tries to move to that entry after all the entries are (re)inserted. +@end defun + +@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. To define a generic mode, use the +macro @code{define-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 +This macro defines a generic mode command named @var{mode} (a symbol, +not quoted). The optional argument @var{docstring} is the +documentation for the mode command. If you do not supply it, +@code{define-generic-mode} generates one by default. + +The argument @var{comment-list} is a list in which each element is +either a character, a string of one or two characters, or a cons cell. +A character or a string is set up in the mode's syntax table as a +``comment starter.'' If the entry is a cons cell, the @sc{car} is set +up as a ``comment starter'' and the @sc{cdr} as a ``comment ender.'' +(Use @code{nil} for the latter if you want comments to end at the end +of the line.) Note that the syntax table mechanism has limitations +about what comment starters and enders are actually possible. +@xref{Syntax Tables}. + +The argument @var{keyword-list} is a list of keywords to highlight +with @code{font-lock-keyword-face}. Each keyword should be a string. +Meanwhile, @var{font-lock-list} is a list of additional expressions to +highlight. Each element of this list should have the same form as an +element of @code{font-lock-keywords}. @xref{Search-based +Fontification}. + +The argument @var{auto-mode-list} is a list of regular expressions to +add to the variable @code{auto-mode-alist}. They are added by the execution +of the @code{define-generic-mode} form, not by expanding the macro call. + +Finally, @var{function-list} is a list of functions for the mode +command to call for additional setup. It calls these functions just +before it runs the mode hook variable @code{@var{mode}-hook}. +@end defmac + @node Example Major Modes @subsection Major Mode Examples diff --git a/doc/lispref/processes.texi b/doc/lispref/processes.texi index d91800fcb8..8b25868cfe 100644 --- a/doc/lispref/processes.texi +++ b/doc/lispref/processes.texi @@ -714,6 +714,9 @@ This command displays a listing of all living processes. In addition, it finally deletes any process whose status was @samp{Exited} or @samp{Signaled}. It returns @code{nil}. +The processes are shown in a buffer named @samp{*Process List*}, whose +major mode is named Process Menu mode. + If @var{query-only} is non-@code{nil} then it lists only processes whose query flag is non-@code{nil}. @xref{Query Before Exit}. @end deffn diff --git a/doc/lispref/vol1.texi b/doc/lispref/vol1.texi index e8ef4f0768..703ade3aac 100644 --- a/doc/lispref/vol1.texi +++ b/doc/lispref/vol1.texi @@ -802,9 +802,10 @@ Major Modes * Derived Modes:: Defining a new major mode based on another major mode. * Basic Major Modes:: Modes that other modes are often derived from. +* Mode Hooks:: Hooks run at the end of major mode commands. +* Tabulated List Mode:: Parent mode for buffers containing tabulated data. * 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 commands. * Example Major Modes:: Text mode and Lisp modes. Minor Modes diff --git a/doc/lispref/vol2.texi b/doc/lispref/vol2.texi index b271deec8b..7c1e2adbf8 100644 --- a/doc/lispref/vol2.texi +++ b/doc/lispref/vol2.texi @@ -801,9 +801,10 @@ Major Modes * Derived Modes:: Defining a new major mode based on another major mode. * Basic Major Modes:: Modes that other modes are often derived from. +* Mode Hooks:: Hooks run at the end of major mode commands. +* Tabulated List Mode:: Parent mode for buffers containing tabulated data. * 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 commands. * Example Major Modes:: Text mode and Lisp modes. Minor Modes -- 2.20.1