Mercurial > emacs

--- a/doc/lispref/ChangeLog	Wed May 20 02:35:45 2009 +0000
+++ b/doc/lispref/ChangeLog	Wed May 20 02:56:33 2009 +0000
@@ -1,3 +1,53 @@
+2009-05-20  Chong Yidong  <cyd@stupidchicken.com>
+
+	* syntax.texi (Position Parse): Document rationale for ignored
+	arguments to syntax-ppss-flush-cache.
+
+	* processes.texi (Input to Processes): Mark PROCESS arg to
+	process-running-child-p as optional.
+	(Network Options): Document NO-ERROR arg to
+	set-network-process-option.
+
+	* buffers.texi (Indirect Buffers): Mark clone-indirect-buffer as a
+	command.
+
+	* searching.texi (POSIX Regexps): Mark posix-search-forward and
+	posix-search-backward as commands.
+
+	* os.texi (Killing Emacs): Mark kill-emacs as a command.
+	(Suspending Emacs): Mark suspend-emacs as a command.
+	(Processor Run Time): Mark emacs-uptime and emacs-init-time as
+	commands.
+	(Terminal Output): Remove obsolete function baud-rate.  Document
+	TERMINAL arg for send-string-to-terminal.
+
+	* nonascii.texi (Terminal I/O Encoding): Document TERMINAL arg for
+	terminal-coding-system and set-terminal-coding-system.
+	(Explicit Encoding): Mark DESTINATION arg of decode-coding-region
+	as optional.
+	(Character Sets): Document RESTRICTION arg of char-charset.
+	(Character Codes): Mark POS argument to get-byte as optional.
+
+	* minibuf.texi (Minibuffer Misc): Document ARGS arg for
+	minibuffer-message.
+
+	* files.texi (Create/Delete Dirs): Mark make-directory and
+	delete-directory as commands.
+
+	* abbrevs.texi (Abbrev Tables): Fix arglist for make-abbrev-table.
+
+	* text.texi (Base 64): Mark base64-decode-string and
+	base64-encode-string as commands.
+	(Columns): Mark move-to-column as a command.
+	(Mode-Specific Indent): Document RIGID arg to
+	indent-for-tab-command.
+	(Region Indent): Mark TO-COLUMN arg to indent-region as optional.
+	Mark indent-code-rigidly as a command.
+	(Substitution): Mark translate-region as a command.
+
+	* frames.texi (Size and Position): Remove obsolete functions
+	screen-height and screen-width.
+
 2009-05-19  Chong Yidong  <cyd@stupidchicken.com>

 	* windows.texi (Cyclic Window Ordering, Cyclic Window Ordering)
--- a/doc/lispref/abbrevs.texi	Wed May 20 02:35:45 2009 +0000
+++ b/doc/lispref/abbrevs.texi	Wed May 20 02:56:33 2009 +0000
@@ -82,7 +82,7 @@

   This section describes how to create and manipulate abbrev tables.

-@defun make-abbrev-table &rest props
+@defun make-abbrev-table &optional props
 This function creates and returns a new, empty abbrev table---an
 obarray containing no symbols.  It is a vector filled with zeros.
 @var{props} is a property list that is applied to the new table
--- a/doc/lispref/buffers.texi	Wed May 20 02:35:45 2009 +0000
+++ b/doc/lispref/buffers.texi	Wed May 20 02:56:33 2009 +0000
@@ -1135,7 +1135,7 @@
 buffer, not from @var{base-buffer}.
 @end deffn

-@defun clone-indirect-buffer newname display-flag &optional norecord
+@deffn clone-indirect-buffer newname display-flag &optional norecord
 This function creates and returns a new indirect buffer that shares
 the current buffer's base buffer and copies the rest of the current
 buffer's attributes.  (If the current buffer is not indirect, it is
@@ -1145,7 +1145,7 @@
 buffer by calling @code{pop-to-buffer}.  If @var{norecord} is
 non-@code{nil}, that means not to put the new buffer to the front of
 the buffer list.
-@end defun
+@end deffn

 @defun buffer-base-buffer &optional buffer
 This function returns the base buffer of @var{buffer}, which defaults
--- a/doc/lispref/files.texi	Wed May 20 02:35:45 2009 +0000
+++ b/doc/lispref/files.texi	Wed May 20 02:56:33 2009 +0000
@@ -2492,24 +2492,24 @@
 delete directories.

 @findex mkdir
-@defun make-directory dirname &optional parents
-This function creates a directory named @var{dirname}.
-If @var{parents} is non-@code{nil}, as is always the case in an
+@deffn Command make-directory dirname &optional parents
+This command creates a directory named @var{dirname}.  If
+@var{parents} is non-@code{nil}, as is always the case in an
 interactive call, that means to create the parent directories first,
 if they don't already exist.

-@code{mkdir} is an alias for this fuction.
-@end defun
-
-@defun delete-directory dirname
-This function deletes the directory named @var{dirname}.  The function
+@code{mkdir} is an alias for this.
+@end deffn
+
+@deffn Command delete-directory dirname
+This command deletes the directory named @var{dirname}.  The function
 @code{delete-file} does not work for files that are directories; you
 must use @code{delete-directory} for them.  If the directory contains
 any files, @code{delete-directory} signals an error.

-This function only follows symbolic links at the level of parent
-directories.
-@end defun
+@code{delete-directory} only follows symbolic links at the level of
+parent directories.
+@end deffn

 @node Magic File Names
 @section Making Certain File Names ``Magic''
--- a/doc/lispref/frames.texi	Wed May 20 02:35:45 2009 +0000
+++ b/doc/lispref/frames.texi	Wed May 20 02:56:33 2009 +0000
@@ -968,13 +968,6 @@
 selected frame.
 @end defun

-@defun screen-height
-@defunx screen-width
-These functions are old aliases for @code{frame-height} and
-@code{frame-width}.  When you are using a non-window terminal, the size
-of the frame is normally the same as the size of the terminal screen.
-@end defun
-
 @defun frame-pixel-height &optional frame
 @defunx frame-pixel-width &optional frame
 These functions return the height and width of the main display area
--- a/doc/lispref/minibuf.texi	Wed May 20 02:35:45 2009 +0000
+++ b/doc/lispref/minibuf.texi	Wed May 20 02:56:33 2009 +0000
@@ -2125,10 +2125,12 @@
 frame.  If an integer, it specifies a number of lines.
 @end defopt

-@defun minibuffer-message string
+@defun minibuffer-message string &rest args
 This function displays @var{string} temporarily at the end of the
 minibuffer text, for two seconds, or until the next input event
-arrives, whichever comes first.
+arrives, whichever comes first.  If @var{args} is non-@code{nil}, the
+actual message is obtained by passing @var{string} and @var{args}
+through @code{format}.  @xref{Formatting Strings}.
 @end defun

 @ignore
--- a/doc/lispref/nonascii.texi	Wed May 20 02:35:45 2009 +0000
+++ b/doc/lispref/nonascii.texi	Wed May 20 02:56:33 2009 +0000
@@ -328,7 +328,7 @@
 @end example
 @end defun

-@defun get-byte pos &optional string
+@defun get-byte &optional pos string
 This function returns the byte at character position @var{pos} in the
 current buffer.  If the current buffer is unibyte, this is literally
 the byte at that position.  If the buffer is multibyte, byte values of
@@ -573,10 +573,15 @@
 This function makes @var{charsets} the highest priority character sets.
 @end defun

-@defun char-charset character
+@defun char-charset character &optional restriction
 This function returns the name of the character set of highest
 priority that @var{character} belongs to.  @acronym{ASCII} characters
 are an exception: for them, this function always returns @code{ascii}.
+
+If @var{restriction} is non-@code{nil}, it should be a list of
+charsets to search.  Alternatively, it can be a coding system, in
+which case the returned charset must be supported by that coding
+system (@pxref{Coding Systems}).
 @end defun

 @defun charset-plist charset
@@ -1621,7 +1626,7 @@
 operation is trivial.  The result of encoding is a unibyte string.
 @end defun

-@deffn Command decode-coding-region start end coding-system destination
+@deffn Command decode-coding-region start end coding-system &optional destination
 This command decodes the text from @var{start} to @var{end} according
 to coding system @var{coding-system}.  To make explicit decoding
 useful, the text before decoding ought to be a sequence of byte
@@ -1706,15 +1711,20 @@
 terminal.  @xref{Multiple Terminals}.
 @end deffn

-@defun terminal-coding-system
+@defun terminal-coding-system &optional terminal
 This function returns the coding system that is in use for encoding
-terminal output---or @code{nil} for no encoding.
+terminal output from @var{terminal}---or @code{nil} if the output is
+not encoded.  If @var{terminal} is a frame, it means that frame's
+terminal; if it is @code{nil}, that means the currently selected
+frame's terminal.
 @end defun

-@deffn Command set-terminal-coding-system coding-system
+@deffn Command set-terminal-coding-system coding-system &optional terminal
 This command specifies @var{coding-system} as the coding system to use
-for encoding terminal output.  If @var{coding-system} is @code{nil},
-that means do not encode terminal output.
+for encoding terminal output from @var{terminal}.  If
+@var{coding-system} is @code{nil}, terminal output is not encoded.  If
+@var{terminal} is a frame, it means that frame's terminal; if it is
+@code{nil}, that means the currently selected frame's terminal.
 @end deffn

 @node MS-DOS File Types
--- a/doc/lispref/os.texi	Wed May 20 02:35:45 2009 +0000
+++ b/doc/lispref/os.texi	Wed May 20 02:56:33 2009 +0000
@@ -539,8 +539,8 @@
 parent process normally resumes control.  The low-level primitive for
 killing Emacs is @code{kill-emacs}.

-@defun kill-emacs &optional exit-data
-This function exits the Emacs process and kills it.
+@deffn Command kill-emacs &optional exit-data
+This command exits the Emacs process and kills it.

 If @var{exit-data} is an integer, then it is used as the exit status
 of the Emacs process.  (This is useful primarily in batch operation; see
@@ -549,7 +549,7 @@
 If @var{exit-data} is a string, its contents are stuffed into the
 terminal input buffer so that the shell (or whatever program next reads
 input) can read them.
-@end defun
+@end deffn

   All the information in the Emacs process, aside from files that have
 been saved, is lost when the Emacs process is killed.  Because killing
@@ -605,7 +605,7 @@
 systems, ``suspension'' actually creates a new shell temporarily as a
 subprocess of Emacs.  Then you would exit the shell to return to Emacs.

-@defun suspend-emacs &optional string
+@deffn Command suspend-emacs &optional string
 This function stops Emacs and returns control to the superior process.
 If and when the superior process resumes Emacs, @code{suspend-emacs}
 returns @code{nil} to its caller in Lisp.
@@ -676,7 +676,7 @@
 Resumed!
 @end group
 @end smallexample
-@end defun
+@end deffn

 @defvar suspend-hook
 This variable is a normal hook that Emacs runs before suspending.
@@ -830,7 +830,7 @@
 Emacs was dumped.  @xref{Building Emacs}.)
 @end defvar

-@deffn Command getenv var
+@deffn Command getenv var &optional frame
 @cindex environment variable access
 This function returns the value of the environment variable @var{var},
 as a string.  @var{var} should be a string.  If @var{var} is undefined
@@ -1473,7 +1473,7 @@
   Emacs provides several functions and primitives that return time,
 both elapsed and processor time, used by the Emacs process.

-@defun emacs-uptime &optional format
+@deffn Command emacs-uptime &optional format
 This function returns a string representing the Emacs
 @dfn{uptime}---the elapsed wall-clock time this instance of Emacs is
 running.  The string is formatted by @code{format-seconds} according
@@ -1481,7 +1481,9 @@
 descriptors, see @ref{Time Parsing, format-seconds}.  If @var{format}
 is @code{nil} or omitted, it defaults to @code{"%Y, %D, %H, %M,
 %z%S"}.
-@end defun
+
+When called interactively, it prints the uptime in the echo area.
+@end deffn

 @defun get-internal-run-time
 This function returns the processor run time used by Emacs as a list
@@ -1508,10 +1510,11 @@
 @code{current-time}.
 @end defun

-@defun emacs-init-time
+@deffn Command emacs-init-time
 This function returns the duration of the Emacs initialization
-(@pxref{Startup Summary}) in seconds, as a string.
-@end defun
+(@pxref{Startup Summary}) in seconds, as a string.  When called
+interactively, it prints the duration in the echo area.
+@end deffn

 @node Time Calculations
 @section Time Calculations
@@ -1946,15 +1949,12 @@
 not.  If Emacs has the wrong value, it makes decisions that are less
 than optimal.  To fix the problem, set @code{baud-rate}.

-@defun baud-rate
-This obsolete function returns the value of the variable
-@code{baud-rate}.
-@end defun
-
-@defun send-string-to-terminal string
-This function sends @var{string} to the terminal without alteration.
+@defun send-string-to-terminal string &optional terminal
+This function sends @var{string} to @var{terminal} without alteration.
 Control characters in @var{string} have terminal-dependent effects.
-This function operates only on text terminals.
+This function operates only on text terminals.  @var{terminal} may be
+a terminal object, a frame, or @code{nil} for the selected frame's
+terminal.

 One use of this function is to define function keys on terminals that
 have downloadable function key definitions.  For example, this is how (on
--- a/doc/lispref/processes.texi	Wed May 20 02:35:45 2009 +0000
+++ b/doc/lispref/processes.texi	Wed May 20 02:56:33 2009 +0000
@@ -979,8 +979,8 @@
 @end smallexample
 @end defun

-@defun process-running-child-p process
-This function will tell you whether a subprocess has given control of
+@defun process-running-child-p &optional process
+This function will tell you whether a @var{process} has given control of
 its terminal to its own child process.  The value is @code{t} if this is
 true, or if Emacs cannot tell; it is @code{nil} if Emacs can be certain
 that this is not so.
@@ -1074,7 +1074,6 @@
 stopped previously.
 @end defun

-@c Emacs 19 feature
 @defun signal-process process signal
 This function sends a signal to process @var{process}.  The argument
 @var{signal} specifies which signal to send; it should be an integer.
@@ -2240,10 +2239,13 @@
 that port.
 @end table

-@defun set-network-process-option process option value
+@defun set-network-process-option process option value &optional no-error
 This function sets or modifies a network option for network process
 @var{process}.  See @code{make-network-process} for details of options
-@var{option} and their corresponding values @var{value}.
+@var{option} and their corresponding values @var{value}.  If
+@var{no-error} is non-@code{nil}, this function returns @code{nil}
+instead of signaling an error if @var{option} is not a supported
+option.  If the function successfully completes, it returns @code{t}.

 The current setting of an option is available via the
 @code{process-contact} function.
--- a/doc/lispref/searching.texi	Wed May 20 02:35:45 2009 +0000
+++ b/doc/lispref/searching.texi	Wed May 20 02:56:33 2009 +0000
@@ -1182,17 +1182,17 @@
 This is because POSIX backtracking conflicts with the semantics of
 non-greedy repetition.

-@defun posix-search-forward regexp &optional limit noerror repeat
+@deffn Command posix-search-forward regexp &optional limit noerror repeat
 This is like @code{re-search-forward} except that it performs the full
 backtracking specified by the POSIX standard for regular expression
 matching.
-@end defun
+@end deffn

-@defun posix-search-backward regexp &optional limit noerror repeat
+@deffn Command posix-search-backward regexp &optional limit noerror repeat
 This is like @code{re-search-backward} except that it performs the full
 backtracking specified by the POSIX standard for regular expression
 matching.
-@end defun
+@end deffn

 @defun posix-looking-at regexp
 This is like @code{looking-at} except that it performs the full
--- a/doc/lispref/syntax.texi	Wed May 20 02:35:45 2009 +0000
+++ b/doc/lispref/syntax.texi	Wed May 20 02:56:33 2009 +0000
@@ -728,9 +728,12 @@
 @code{inhibit-modification-hooks}.  For this reason, it is sometimes
 necessary to flush the cache manually.

-@defun syntax-ppss-flush-cache beg
-This function flushes the cache used by @code{syntax-ppss}, starting at
-position @var{beg}.
+@defun syntax-ppss-flush-cache beg &rest ignored-args
+This function flushes the cache used by @code{syntax-ppss}, starting
+at position @var{beg}.  The remaining arguments, @var{ignored-args},
+are ignored; this function accepts them so that it can be directly
+used on hooks such as @code{before-change-functions} (@pxref{Change
+Hooks}).
 @end defun

   Major modes can make @code{syntax-ppss} run faster by specifying
--- a/doc/lispref/text.texi	Wed May 20 02:35:45 2009 +0000
+++ b/doc/lispref/text.texi	Wed May 20 02:56:33 2009 +0000
@@ -2129,14 +2129,17 @@
 @code{count-lines} in @ref{Text Lines}.
 @end defun

-@defun move-to-column column &optional force
+@deffn Command move-to-column column &optional force
 This function moves point to @var{column} in the current line.  The
 calculation of @var{column} takes into account the widths of the
 displayed representations of the characters between the start of the
 line and point.

-If column @var{column} is beyond the end of the line, point moves to the
-end of the line.  If @var{column} is negative, point moves to the
+When called interactively, @var{column} is the value of prefix numeric
+argument.  If @var{column} is not an integer, an error is signaled.
+
+If column @var{column} is beyond the end of the line, point moves to
+the end of the line.  If @var{column} is negative, point moves to the
 beginning of the line.

 If it is impossible to move to column @var{column} because that is in
@@ -2151,10 +2154,8 @@
 enough to reach column @var{column}; if it is @code{t}, that means to
 add whitespace at the end of the line to reach that column.

-If @var{column} is not an integer, an error is signaled.
-
 The return value is the column number actually moved to.
-@end defun
+@end deffn

 @node Indentation
 @section Indentation
@@ -2235,15 +2236,17 @@
 indent the current line in a way appropriate for the current major mode.
 @end deffn

-@deffn Command indent-for-tab-command
-This command calls the function in @code{indent-line-function} to indent
-the current line; however, if that function is
-@code{indent-to-left-margin}, @code{insert-tab} is called instead.  (That
-is a trivial command that inserts a tab character.)
+@deffn Command indent-for-tab-command &optional rigid
+This command calls the function in @code{indent-line-function} to
+indent the current line; however, if that function is
+@code{indent-to-left-margin}, @code{insert-tab} is called instead.
+(That is a trivial command that inserts a tab character.)  If
+@var{rigid} is non-@code{nil}, this function also rigidly indents the
+entire balanced expression that starts at the beginning of the current
+line, to reflect change in indentation of the current line.
 @end deffn

 @deffn Command newline-and-indent
-@comment !!SourceFile simple.el
 This function inserts a newline, then indents the new line (the one
 following the newline just inserted) according to the major mode.

@@ -2274,7 +2277,7 @@
   This section describes commands that indent all the lines in the
 region.  They return unpredictable values.

-@deffn Command indent-region start end to-column
+@deffn Command indent-region start end &optional to-column
 This command indents each nonblank line starting between @var{start}
 (inclusive) and @var{end} (exclusive).  If @var{to-column} is
 @code{nil}, @code{indent-region} indents each nonblank line by calling
@@ -2312,7 +2315,6 @@
 @end defvar

 @deffn Command indent-rigidly start end count
-@comment !!SourceFile indent.el
 This command indents all lines starting between @var{start}
 (inclusive) and @var{end} (exclusive) sideways by @var{count} columns.
 This ``preserves the shape'' of the affected region, moving it as a
@@ -2328,13 +2330,13 @@
 replied to.
 @end deffn

-@defun indent-code-rigidly start end columns &optional nochange-regexp
+@deffn Command indent-code-rigidly start end columns &optional nochange-regexp
 This is like @code{indent-rigidly}, except that it doesn't alter lines
 that start within strings or comments.

 In addition, it doesn't alter a line if @var{nochange-regexp} matches at
 the beginning of the line (if @var{nochange-regexp} is non-@code{nil}).
-@end defun
+@end deffn

 @node Relative Indent
 @subsection Indentation Relative to Previous Lines
@@ -3867,7 +3869,7 @@
 @end example
 @end defun

-@defun translate-region start end table
+@deffn Command translate-region start end table
 This function applies a translation table to the characters in the
 buffer between positions @var{start} and @var{end}.

@@ -3881,7 +3883,7 @@
 characters that were actually changed by the translation.  This does
 not count characters that were mapped into themselves in the
 translation table.
-@end defun
+@end deffn

 @node Registers
 @section Registers
@@ -3956,27 +3958,6 @@
 This command displays what is contained in register @var{reg}.
 @end deffn

-@ignore
-@deffn Command point-to-register reg
-This command stores both the current location of point and the current
-buffer in register @var{reg} as a marker.
-@end deffn
-
-@deffn Command jump-to-register reg
-@deffnx Command register-to-point reg
-@comment !!SourceFile register.el
-This command restores the status recorded in register @var{reg}.
-
-If @var{reg} contains a marker, it moves point to the position stored in
-the marker.  Since both the buffer and the location within the buffer
-are stored by the @code{point-to-register} function, this command can
-switch you to another buffer.
-
-If @var{reg} contains a window configuration or a frame configuration.
-@code{jump-to-register} restores that configuration.
-@end deffn
-@end ignore
-
 @deffn Command insert-register reg &optional beforep
 This command inserts contents of register @var{reg} into the current
 buffer.
@@ -3996,43 +3977,6 @@
 changed in the future.
 @end deffn

-@ignore
-@deffn Command copy-to-register reg start end &optional delete-flag
-This command copies the region from @var{start} to @var{end} into
-register @var{reg}.  If @var{delete-flag} is non-@code{nil}, it deletes
-the region from the buffer after copying it into the register.
-@end deffn
-
-@deffn Command prepend-to-register reg start end &optional delete-flag
-This command prepends the region from @var{start} to @var{end} into
-register @var{reg}.  If @var{delete-flag} is non-@code{nil}, it deletes
-the region from the buffer after copying it to the register.
-@end deffn
-
-@deffn Command append-to-register reg start end &optional delete-flag
-This command appends the region from @var{start} to @var{end} to the
-text already in register @var{reg}.  If @var{delete-flag} is
-non-@code{nil}, it deletes the region from the buffer after copying it
-to the register.
-@end deffn
-
-@deffn Command copy-rectangle-to-register reg start end &optional delete-flag
-This command copies a rectangular region from @var{start} to @var{end}
-into register @var{reg}.  If @var{delete-flag} is non-@code{nil}, it
-deletes the region from the buffer after copying it to the register.
-@end deffn
-
-@deffn Command window-configuration-to-register reg
-This function stores the window configuration of the selected frame in
-register @var{reg}.
-@end deffn
-
-@deffn Command frame-configuration-to-register reg
-This function stores the current frame configuration in register
-@var{reg}.
-@end deffn
-@end ignore
-
 @node Transposition
 @section Transposition of Text

@@ -4067,7 +4011,7 @@
 }2045.  This section describes the functions for
 converting to and from this code.

-@defun base64-encode-region beg end &optional no-line-break
+@deffn Command base64-encode-region beg end &optional no-line-break
 This function converts the region from @var{beg} to @var{end} into base
 64 code.  It returns the length of the encoded text.  An error is
 signaled if a character in the region is multibyte, i.e.@: in a
@@ -4079,9 +4023,9 @@
 text, to avoid overlong lines.  However, if the optional argument
 @var{no-line-break} is non-@code{nil}, these newlines are not added, so
 the output is just one long line.
-@end defun
-
-@defun base64-encode-string string &optional no-line-break
+@end deffn
+
+@deffn Command base64-encode-string string &optional no-line-break
 This function converts the string @var{string} into base 64 code.  It
 returns a string containing the encoded text.  As for
 @code{base64-encode-region}, an error is signaled if a character in the
@@ -4091,7 +4035,7 @@
 text, to avoid overlong lines.  However, if the optional argument
 @var{no-line-break} is non-@code{nil}, these newlines are not added, so
 the result string is just one long line.
-@end defun
+@end deffn

 @defun base64-decode-region beg end
 This function converts the region from @var{beg} to @var{end} from base