[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] /srv/bzr/emacs/trunk r107324: Give Tabulated List mode its
From: |
Chong Yidong |
Subject: |
[Emacs-diffs] /srv/bzr/emacs/trunk r107324: Give Tabulated List mode its own Lisp manual node. |
Date: |
Sat, 18 Feb 2012 21:38:33 +0800 |
User-agent: |
Bazaar (2.3.1) |
------------------------------------------------------------
revno: 107324
committer: Chong Yidong <address@hidden>
branch nick: trunk
timestamp: Sat 2012-02-18 21:38:33 +0800
message:
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.
modified:
doc/lispref/ChangeLog
doc/lispref/elisp.texi
doc/lispref/modes.texi
doc/lispref/processes.texi
doc/lispref/vol1.texi
doc/lispref/vol2.texi
=== modified file 'doc/lispref/ChangeLog'
--- a/doc/lispref/ChangeLog 2012-02-17 14:01:05 +0000
+++ b/doc/lispref/ChangeLog 2012-02-18 13:38:33 +0000
@@ -1,3 +1,10 @@
+2012-02-18 Chong Yidong <address@hidden>
+
+ * 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 <address@hidden>
* syntax.texi (Motion via Parsing): Doc fix for scan-lists.
=== modified file 'doc/lispref/elisp.texi'
--- a/doc/lispref/elisp.texi 2012-02-16 14:43:41 +0000
+++ b/doc/lispref/elisp.texi 2012-02-18 13:38:33 +0000
@@ -781,9 +781,10 @@
* 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
=== modified file 'doc/lispref/modes.texi'
--- a/doc/lispref/modes.texi 2012-02-16 14:43:41 +0000
+++ b/doc/lispref/modes.texi 2012-02-18 13:38:33 +0000
@@ -284,9 +284,10 @@
* 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 @@
@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
address@hidden (@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 @@
Buffers,,Listing Existing Buffers, emacs, The GNU Emacs Manual}.
@end deffn
address@hidden tables of data
address@hidden 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.
address@hidden deffn
-
address@hidden Generic Modes
address@hidden Generic Modes
address@hidden 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}.
-
address@hidden 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,
address@hidden 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.
address@hidden 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 @address@hidden
address@hidden defmac
+ In addition, modes for buffers of tabulated data can inherit from
+Tabulated List mode, which is in turn derived from Special mode.
address@hidden List Mode}.
@node Mode Hooks
@subsection Mode Hooks
@@ -1021,6 +971,177 @@
very end of every properly-written major mode command.
@end defvar
address@hidden Tabulated List Mode
address@hidden Tabulated List mode
address@hidden 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}).
+
address@hidden 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.
+
address@hidden 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}
address@hidden @var{sort})}, where
+
address@hidden
address@hidden
address@hidden is the column's name (a string).
+
address@hidden
address@hidden 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.
+
address@hidden
address@hidden 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
address@hidden (see below).
address@hidden itemize
address@hidden defvar
+
address@hidden 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 @address@hidden(@var{id} @var{contents})}}, where
+
address@hidden
address@hidden
address@hidden 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}.
+
address@hidden
address@hidden is a vector with the same number of elements as
address@hidden 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
address@hidden with @var{label} and @var{properties} as
+arguments (@pxref{Making Buttons}).
+
+There should be no newlines in any of these strings.
address@hidden itemize
+
+Otherwise, the value should be a function which returns a list of the
+above form when called with no arguments.
address@hidden defvar
+
address@hidden 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
address@hidden
address@hidden defvar
+
address@hidden 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.
address@hidden defvar
+
address@hidden 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
address@hidden, and @var{flip}, if address@hidden, means
+to invert the sort order.
address@hidden defvar
+
address@hidden 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
address@hidden).
address@hidden defun
+
address@hidden 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
address@hidden, then calls the function specified by
address@hidden to insert each entry.
+
+If the optional argument @var{remember-pos} is address@hidden, 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.
address@hidden defun
+
address@hidden Generic Modes
address@hidden Generic Modes
address@hidden 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}.
+
address@hidden 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,
address@hidden 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.
address@hidden 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 @address@hidden
address@hidden defmac
+
@node Example Major Modes
@subsection Major Mode Examples
=== modified file 'doc/lispref/processes.texi'
--- a/doc/lispref/processes.texi 2012-02-15 08:50:38 +0000
+++ b/doc/lispref/processes.texi 2012-02-18 13:38:33 +0000
@@ -714,6 +714,9 @@
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 address@hidden then it lists only processes
whose query flag is address@hidden @xref{Query Before Exit}.
@end deffn
=== modified file 'doc/lispref/vol1.texi'
--- a/doc/lispref/vol1.texi 2012-02-16 14:43:41 +0000
+++ b/doc/lispref/vol1.texi 2012-02-18 13:38:33 +0000
@@ -802,9 +802,10 @@
* 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
=== modified file 'doc/lispref/vol2.texi'
--- a/doc/lispref/vol2.texi 2012-02-16 14:43:41 +0000
+++ b/doc/lispref/vol2.texi 2012-02-18 13:38:33 +0000
@@ -801,9 +801,10 @@
* 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
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] /srv/bzr/emacs/trunk r107324: Give Tabulated List mode its own Lisp manual node.,
Chong Yidong <=