emacs-diffs
[Top][All Lists]
Advanced

[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


reply via email to

[Prev in Thread] Current Thread [Next in Thread]