xemacs-beta: man/lispref/text.texi comparison

comparison man/lispref/text.texi @ 444:576fb035e263 r21-2-37

Import from CVS: tag r21-2-37

author	cvs
date	Mon, 13 Aug 2007 11:36:19 +0200
parents	9d177e8d4150
children	1ccc32a20af4

comparison

equal deleted inserted replaced

-:a8296e22da4e
+:576fb035e263
 @c -*-texinfo-*-
 @c This is part of the XEmacs Lisp Reference Manual.
 @c Copyright (C) 1990, 1991, 1992, 1993, 1994 Free Software Foundation, Inc.
 @c See the file lispref.texi for copying conditions.
 @setfilename ../../info/text.info
 @node Text, Searching and Matching, Markers, Top
 @chapter Text
 @cindex text
 function is chiefly useful if you want to insert a string in
 a buffer other than the current one (otherwise you could just
 use @code{insert}).
 @end defun
-@defun insert-char character count &optional buffer
+@defun insert-char character &optional count ignored buffer
 This function inserts @var{count} instances of @var{character} into
 @var{buffer} before point.  @var{count} must be a number, and
-@var{character} must be a character.  The value is @code{nil}.  If
+@var{character} must be a character.
-optional argument @var{buffer} is @code{nil}, the current buffer is
-assumed. (In FSF Emacs, the third argument is called @var{inherit}
+If optional argument @var{buffer} is @code{nil}, the current buffer is
-and refers to text properties.)
+assumed. (In FSF Emacs, the third argument is called @var{inherit} and
+refers to text properties.  In XEmacs, it is always ignored.)
+This function always returns @code{nil}.
 @end defun
 @defun insert-buffer-substring from-buffer-or-name &optional start end
 This function inserts a portion of buffer @var{from-buffer-or-name}
 (which must already exist) into the current buffer before point.  The
 This is also responsible for calling @code{blink-paren-function} when
 the inserted character has close parenthesis syntax (@pxref{Blinking}).
 @end deffn
-@deffn Command newline &optional number-of-newlines
+@deffn Command newline &optional count
 This command inserts newlines into the current buffer before point.
-If @var{number-of-newlines} is supplied, that many newline characters
+If @var{count} is supplied, that many newline characters
 are inserted.
 @cindex newline and Auto Fill mode
 This function calls @code{auto-fill-function} if the current column
 number is greater than the value of @code{fill-column} and
-@var{number-of-newlines} is @code{nil}.  Typically what
+@var{count} is @code{nil}.  Typically what
 @code{auto-fill-function} does is insert a newline; thus, the overall
 result in this case is to insert two newlines at different places: one
 at point, and another earlier in the line.  @code{newline} does not
-auto-fill if @var{number-of-newlines} is non-@code{nil}.
+auto-fill if @var{count} is non-@code{nil}.
 This command indents to the left margin if that is not zero.
 @xref{Margins}.
 The value returned is @code{nil}.  In an interactive call, @var{count}
 cases.
 All of the deletion functions operate on the current buffer, and all
 return a value of @code{nil}.
-@defun erase-buffer &optional buffer
+@deffn Command erase-buffer &optional buffer
 This function deletes the entire text of @var{buffer}, leaving it
 empty.  If the buffer is read-only, it signals a @code{buffer-read-only}
 error.  Otherwise, it deletes the text without asking for any
 confirmation.  It returns @code{nil}.  @var{buffer} defaults to the
 current buffer if omitted.
 Normally, deleting a large amount of text from a buffer inhibits further
 auto-saving of that buffer ``because it has shrunk''.  However,
 @code{erase-buffer} does not do this, the idea being that the future
 text is not really related to the former text, and its size should not
 be compared with that of the former text.
-@end defun
+@end deffn
 @deffn Command delete-region start end &optional buffer
 This command deletes the text in @var{buffer} in the region defined by
 @var{start} and @var{end}.  The value is @code{nil}.  If optional
 argument @var{buffer} is @code{nil}, the current buffer is assumed.
 ---------- Buffer: foo ----------
 @end group
 @end example
 @end deffn
 @deffn Command delete-indentation &optional join-following-p
 This function joins the line point is on to the previous line, deleting
 any whitespace at the join and in some cases replacing it with one
 space.  If @var{join-following-p} is non-@code{nil},
 @code{delete-indentation} joins this line to the following line
 instead.  The value is @code{nil}.
 After the lines are joined, the function @code{fixup-whitespace} is
 responsible for deciding whether to leave a space at the junction.
 @end deffn
-@defun fixup-whitespace
+@deffn Command fixup-whitespace
 This function replaces all the white space surrounding point with either
 one space or no space, according to the context.  It returns @code{nil}.
 At the beginning or end of a line, the appropriate amount of space is
 none.  Before a character with close parenthesis syntax, or after a
 This has too many spaces
 This has too many spaces at the start of (this list)
 ---------- Buffer: foo ----------
 @end group
 @end smallexample
-@end defun
+@end deffn
 @deffn Command just-one-space
 @comment !!SourceFile simple.el
 This command replaces any spaces and tabs around point with a single
 space.  It returns @code{nil}.
 newly killed text in a new element at the beginning of the kill ring or
 adds it to the most recent element.  It uses the @code{last-command}
 variable to determine whether the previous command was a kill command,
 and if so appends the killed text to the most recent entry.
-@deffn Command kill-region start end
+@deffn Command kill-region start end &optional verbose
 This function kills the text in the region defined by @var{start} and
 @var{end}.  The text is deleted but saved in the kill ring, along with
 its text properties.  The value is always @code{nil}.
 In an interactive call, @var{start} and @var{end} are point and
 These functions and variables provide access to the kill ring at a lower
 level, but still convenient for use in Lisp programs.  They take care of
 interaction with X Window selections.  They do not exist in Emacs
 version 18.
-@defun current-kill n &optional do-not-move
+@defun current-kill count &optional do-not-move
 The function @code{current-kill} rotates the yanking pointer which
-designates the ``front'' of the kill ring by @var{n} places (from newer
+designates the ``front'' of the kill ring by @var{count} places (from newer
 kills to older ones), and returns the text at that place in the ring.
 If the optional second argument @var{do-not-move} is non-@code{nil},
 then @code{current-kill} doesn't alter the yanking pointer; it just
-returns the @var{n}th kill, counting from the current yanking pointer.
+returns the @var{count}th kill, counting from the current yanking pointer.
-If @var{n} is zero, indicating a request for the latest kill,
+If @var{count} is zero, indicating a request for the latest kill,
 @code{current-kill} calls the value of
 @code{interprogram-paste-function} (documented below) before consulting
 the kill ring.
 @end defun
-@defun kill-new string
+@defun kill-new string &optional replace
-This function puts the text @var{string} into the kill ring as a new
+This function makes the text @var{string} the latest entry in the kill
-entry at the front of the ring.  It discards the oldest entry if
+ring, and sets @code{kill-ring-yank-pointer} to point to it.
-appropriate.  It also invokes the value of
-@code{interprogram-cut-function} (see below).
+Normally, @var{string} is added to the front of the kill ring as a new
+entry.  However, if optional argument @var{replace} is non-@code{nil},
+the entry previously at the front of the kill ring is discarded, and
+@var{string} replaces it.
+This function runs the functions on @code{kill-hooks}, and also invokes
+the value of @code{interprogram-cut-function} (see below).
 @end defun
 @defun kill-append string before-p
 This function appends the text @var{string} to the first entry in the
 kill ring.  Normally @var{string} goes at the end of the entry, but if
 @node Internals of Kill Ring
 @subsection Internals of the Kill Ring
 The variable @code{kill-ring} holds the kill ring contents, in the
 form of a list of strings.  The most recent kill is always at the front
 of the list.
 The @code{kill-ring-yank-pointer} variable points to a link in the
 kill ring list, whose @sc{car} is the text to yank next.  We say it
 identifies the ``front'' of the ring.  Moving
 @code{kill-ring-yank-pointer} to a different link is called
 set this variable to the value of @code{kill-ring}.  The effect is to
 rotate the ring so that the newly killed text is at the front.
 Here is a diagram that shows the variable @code{kill-ring-yank-pointer}
 pointing to the second entry in the kill ring @code{("some text" "a
 different piece of text" "yet older text")}.
 @example
 @group
 kill-ring       kill-ring-yank-pointer
 |               |
 |     ___ ___    --->  ___ ___      ___ ___
 --> |___|___|------> |___|___|--> |___|___|--> nil
 |                |            |
 |                |            |
 |                |             -->"yet older text"
 |                |
 |                 --> "a different piece of text"
 |
 --> "some text"
 @end group
 @end example
 @item @var{integer}
 This kind of element records a previous value of point.  Ordinary cursor
 motion does not get any sort of undo record, but deletion commands use
 these entries to record where point was before the command.
-@item (@var{beg} . @var{end})
+@item (@var{start} . @var{end})
 This kind of element indicates how to delete text that was inserted.
-Upon insertion, the text occupied the range @var{beg}--@var{end} in the
+Upon insertion, the text occupied the range @var{start}--@var{end} in the
 buffer.
 @item (@var{text} . @var{position})
 This kind of element indicates how to reinsert text that was deleted.
 The deleted text itself is the string @var{text}.  The place to
 recording 16 bits of the visited file's modification time as of when it
 was previously visited or saved.  @code{primitive-undo} uses those
 values to determine whether to mark the buffer as unmodified once again;
 it does so only if the file's modification time matches those numbers.
-@item (nil @var{property} @var{value} @var{beg} . @var{end})
+@item (nil @var{property} @var{value} @var{start} . @var{end})
 This kind of element records a change in a text property.
 Here's how you might undo the change:
 @example
-(put-text-property @var{beg} @var{end} @var{property} @var{value})
+(put-text-property @var{start} @var{end} @var{property} @var{value})
 @end example
 @item @var{position}
 This element indicates where point was at an earlier time.  Undoing this
 element sets point to @var{position}.  Deletion normally creates an
 In an interactive call, @var{buffer-or-name} is the current buffer.
 You cannot specify any other buffer.
 @end deffn
-@defun buffer-disable-undo &optional buffer
+@deffn Command buffer-disable-undo &optional buffer
-@defunx buffer-flush-undo &optional buffer
+@deffnx Command buffer-flush-undo &optional buffer
 @cindex disable undo
 This function discards the undo list of @var{buffer}, and disables
 further recording of undo information.  As a result, it is no longer
 possible to undo either previous changes or any subsequent changes.  If
 the undo list of @var{buffer} is already disabled, this function
 This function returns @code{nil}.  It cannot be called interactively.
 The name @code{buffer-flush-undo} is not considered obsolete, but the
 preferred name @code{buffer-disable-undo} is new as of Emacs versions
 19.
-@end defun
+@end deffn
 As editing continues, undo lists get longer and longer.  To prevent
 them from using up all available memory space, garbage collection trims
 them back to size limits you can set.  (For this purpose, the ``size''
 of an undo list measures the cons cells that make up the list, plus the
 If @var{force} is non-@code{nil}, that says to fix the line's
 indentation if that doesn't match the left margin value.
 @end deffn
-@defun delete-to-left-margin from to
+@defun delete-to-left-margin &optional from to
 This function removes left margin indentation from the text
 between @var{from} and @var{to}.  The amount of indentation
 to delete is determined by calling @code{current-left-margin}.
 In no case does this function delete non-whitespace.
+The arguments @var{from} and @var{to} are optional; the default is the
+whole buffer.
 @end defun
 @defun indent-to-left-margin
 This is the default @code{indent-line-function}, used in Fundamental
 mode, Text mode, etc.  Its effect is to adjust the indentation at the
 @example
 @group
 ;; @r{Note that the first two lines of doc string}
 ;; @r{are effectively one line when viewed by a user.}
-(defun sort-lines (reverse beg end)
+(defun sort-lines (reverse start end)
 "Sort lines in region alphabetically.
 Called from a program, there are three arguments:
 @end group
 @group
 REVERSE (non-nil means reverse order),
-and BEG and END (the region to sort)."
+and START and END (the region to sort)."
 (interactive "P\nr")
 (save-restriction
-(narrow-to-region beg end)
+(narrow-to-region start end)
 (goto-char (point-min))
 (sort-subr reverse
 'forward-line
 'end-of-line)))
 @end group
 its @code{sort-subr} call looks like this:
 @example
 @group
 (sort-subr reverse
 (function
 (lambda ()
 (skip-chars-forward "\n \t\f")))
 'forward-paragraph)
 @end group
 @end example
 @end defun
 1.  If @var{field} is negative, sorting is by the
 @w{@minus{}@var{field}th} field from the end of the line.  This command
 is useful for sorting tables.
 @end deffn
-@deffn Command sort-columns reverse &optional beg end
+@deffn Command sort-columns reverse &optional start end
-This command sorts the lines in the region between @var{beg} and
+This command sorts the lines in the region between @var{start} and
 @var{end}, comparing them alphabetically by a certain range of columns.
-The column positions of @var{beg} and @var{end} bound the range of
+The column positions of @var{start} and @var{end} bound the range of
 columns to sort on.
 If @var{reverse} is non-@code{nil}, the sort is in reverse order.
 One unusual thing about this command is that the entire line
-containing position @var{beg}, and the entire line containing position
+containing position @var{start}, and the entire line containing position
 @var{end}, are included in the region sorted.
 Note that @code{sort-columns} uses the @code{sort} utility program,
 and so cannot work properly on text containing tab characters.  Use
 @kbd{M-x @code{untabify}} to convert tabs to spaces before sorting.
 Column number computations ignore the width of the window and the
 amount of horizontal scrolling.  Consequently, a column value can be
 arbitrarily high.  The first (or leftmost) column is numbered 0.
-@defun current-column
+@defun current-column &optional buffer
 This function returns the horizontal position of point, measured in
-columns, counting from 0 at the left margin.  The column position is the
+columns, counting from 0 at the left margin.
-sum of the widths of all the displayed representations of the characters
-between the start of the current line and point.
+This is calculated by adding together the widths of all the displayed
+representations of the character between the start of the previous line
+and point. (e.g. control characters will have a width of 2 or 4, tabs
+will have a variable width.)
+Ignores the finite width of frame displaying the buffer, which means
+that this function may return values greater than
+@code{(frame-width)}.
+Whether the line is visible (if @code{selective-display} is t) has no effect;
+however, ^M is treated as end of line when @code{selective-display} is t.
+If @var{buffer} is nil, the current buffer is assumed.
 For an example of using @code{current-column}, see the description of
 @code{count-lines} in @ref{Text Lines}.
 @end defun
-@defun move-to-column column &optional force
+@defun move-to-column column &optional force buffer
 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.
 converts the tab into spaces so that it can move precisely to column
 @var{column}.  Other multicolumn characters can cause anomalies despite
 @var{force}, since there is no way to split them.
 The argument @var{force} also has an effect if the line isn't long
-enough to reach column @var{column}; in that case, it says to add
+enough to reach column @var{column}; in that case, unless the value of
+@var{force} is the special value @code{coerce}, it says to add
 whitespace at the end of the line to reach that column.
-If @var{column} is not an integer, an error is signaled.
+If @var{column} is not a non-negative integer, an error is signaled.
 The return value is the column number actually moved to.
 @end defun
 @node Indentation
 This section describes the primitive functions used to count and
 insert indentation.  The functions in the following sections use these
 primitives.
-@defun current-indentation
+@defun current-indentation &optional buffer
 @comment !!Type Primitive Function
 @comment !!SourceFile indent.c
 This function returns the indentation of the current line, which is
 the horizontal position of the first nonblank character.  If the
 contents are entirely blank, then this is the horizontal position of the
 end of the line.
 @end defun
-@deffn Command indent-to column &optional minimum
+@deffn Command indent-to column &optional minimum buffer
 @comment !!Type Primitive Function
 @comment !!SourceFile indent.c
 This function indents from point with tabs and spaces until @var{column}
 is reached.  If @var{minimum} is specified and non-@code{nil}, then at
 least that many spaces are inserted even if this requires going beyond
 @var{column}.  Otherwise the function does nothing if point is already
 beyond @var{column}.  The value is the column at which the inserted
-indentation ends.
+indentation ends.  If @var{buffer} is @code{nil}, the current buffer is assumed.
 @end deffn
 @defopt indent-tabs-mode
 @comment !!SourceFile indent.c
 If this variable is non-@code{nil}, indentation functions can insert
 @deffn Command indent-according-to-mode
 This command calls the function in @code{indent-line-function} to
 indent the current line in a way appropriate for the current major mode.
 @end deffn
-@deffn Command indent-for-tab-command
+@deffn Command indent-for-tab-command &optional prefix-arg
 This command calls the function in @code{indent-line-function} to indent
 the current line; except that if that function is
 @code{indent-to-left-margin}, it calls @code{insert-tab} instead.  (That
 is a trivial command that inserts a tab character.)
 @end deffn
 In Mail mode, @kbd{C-c C-y} (@code{mail-yank-original}) uses
 @code{indent-rigidly} to indent the text copied from the message being
 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
 This section describes two commands that indent the current line
 @subsection Indentation-Based Motion Commands
 These commands, primarily for interactive use, act based on the
 indentation in the text.
 @deffn Command back-to-indentation
 @comment !!SourceFile simple.el
 This command moves point to the first non-whitespace character in the
 current line (which is the line in which point is located).  It returns
 @code{nil}.
 @end deffn
 The case change commands described here work on text in the current
 buffer.  @xref{Character Case}, for case conversion commands that work
 on strings and characters.  @xref{Case Tables}, for how to customize
 which characters are upper or lower case and how to convert them.
-@deffn Command capitalize-region start end
+@deffn Command capitalize-region start end &optional buffer
 This function capitalizes all words in the region defined by
 @var{start} and @var{end}.  To capitalize means to convert each word's
 first character to upper case and convert the rest of each word to lower
 case.  The function returns @code{nil}.
 ---------- Buffer: foo ----------
 @end group
 @end example
 @end deffn
-@deffn Command downcase-region start end
+@deffn Command downcase-region start end &optional buffer
 This function converts all of the letters in the region defined by
 @var{start} and @var{end} to lower case.  The function returns
 @code{nil}.
 When @code{downcase-region} is called interactively, @var{start} and
 @var{end} are point and the mark, with the smallest first.
 @end deffn
-@deffn Command upcase-region start end
+@deffn Command upcase-region start end &optional buffer
 This function converts all of the letters in the region defined by
 @var{start} and @var{end} to upper case.  The function returns
 @code{nil}.
 When @code{upcase-region} is called interactively, @var{start} and
 @var{end} are point and the mark, with the smallest first.
 @end deffn
-@deffn Command capitalize-word count
+@deffn Command capitalize-word count &optional buffer
 This function capitalizes @var{count} words after point, moving point
 over as it does.  To capitalize means to convert each word's first
 character to upper case and convert the rest of each word to lower case.
 If @var{count} is negative, the function capitalizes the
 @minus{}@var{count} previous words but does not move point.  The value
 When @code{capitalize-word} is called interactively, @var{count} is
 set to the numeric prefix argument.
 @end deffn
-@deffn Command downcase-word count
+@deffn Command downcase-word count &optional buffer
 This function converts the @var{count} words after point to all lower
 case, moving point over as it does.  If @var{count} is negative, it
 converts the @minus{}@var{count} previous words but does not move point.
 The value is @code{nil}.
 When @code{downcase-word} is called interactively, @var{count} is set
 to the numeric prefix argument.
 @end deffn
-@deffn Command upcase-word count
+@deffn Command upcase-word count &optional buffer
 This function converts the @var{count} words after point to all upper
 case, moving point over as it does.  If @var{count} is negative, it
 converts the @minus{}@var{count} previous words but does not move point.
 The value is @code{nil}.
 These functions handle both strings and buffers.  (Keep in mind that
 positions in a string start from 0, whereas positions in a buffer start
 from 1.)
-@defun get-text-property pos prop &optional object
+@defun get-text-property pos prop &optional object at-flag
 This function returns the value of the @var{prop} property of the
 character after position @var{pos} in @var{object} (a buffer or string).
 The argument @var{object} is optional and defaults to the current
 buffer.
 @ignore @c Bogus as hell!
 has a category that is a symbol, then @code{get-text-property} returns
 the @var{prop} property of that symbol.
 @end ignore
 @end defun
-@defun get-char-property pos prop &optional object
+@defun get-char-property pos prop &optional object at-flag
 This function is like @code{get-text-property}, except that it checks
 all extents, not just text-property extents.
 @ignore Does not apply in XEmacs
 The argument @var{object} may be a string, a buffer, or a window.  If it
 returns the position of the first character beyond @var{pos} whose
 properties are not identical to those of the character just after
 @var{pos}.
 If @var{limit} is non-@code{nil}, then the scan ends at position
 @var{limit}.  If there is no property change before that point,
 @code{next-property-change} returns @var{limit}.
 The value is @code{nil} if the properties remain unchanged all the way
 to the end of @var{object} and @var{limit} is @code{nil}.  If the value
 is non-@code{nil}, it is a position greater than or equal to @var{pos}.
 returns the position of the first character beyond @var{pos} whose
 @var{prop} property differs from that of the character just after
 @var{pos}.
 If @var{limit} is non-@code{nil}, then the scan ends at position
 @var{limit}.  If there is no property change before that point,
 @code{next-single-property-change} returns @var{limit}.
 The value is @code{nil} if the property remains unchanged all the way to
 the end of @var{object} and @var{limit} is @code{nil}.  If the value is
 non-@code{nil}, it is a position greater than or equal to @var{pos}; it
 equals @var{pos} only if @var{limit} equals @var{pos}.
 @end defun
 @defun previous-property-change pos &optional object limit
-This is like @code{next-property-change}, but scans back from @var{pos}
+This is like @code{next-property-change}, but scans backward from @var{pos}
 instead of forward.  If the value is non-@code{nil}, it is a position
 less than or equal to @var{pos}; it equals @var{pos} only if @var{limit}
 equals @var{pos}.
 @end defun
 @defun previous-single-property-change pos prop &optional object limit
-This is like @code{next-single-property-change}, but scans back from
+This is like @code{next-single-property-change}, but scans backward from
 @var{pos} instead of forward.  If the value is non-@code{nil}, it is a
 position less than or equal to @var{pos}; it equals @var{pos} only if
 @var{limit} equals @var{pos}.
 @end defun
 @subsection Saving Text Properties in Files
 @cindex text properties in files
 @cindex saving text properties
 You can save text properties in files, and restore text properties
 when inserting the files, using these two hooks:
 @defvar write-region-annotate-functions
 This variable's value is a list of functions for @code{write-region} to
 run to encode text properties in some fashion as annotations to the text
 being written in the file.  @xref{Writing to Files}.
 uses may be possible.
 @end defvar
 We invite users to write Lisp programs to store and retrieve text
 properties in files, using these hooks, and thus to experiment with
 various data formats and find good ones.  Eventually we hope users
 will produce good, general extensions we can install in Emacs.
 We suggest not trying to handle arbitrary Lisp objects as property
 names or property values---because a program that general is probably
 difficult to write, and slow.  Instead, choose a set of possible data
 @defun translate-region start end table
 This function applies a translation table to the characters in the
 buffer between positions @var{start} and @var{end}.  The translation
 table @var{table} can be either a string, a vector, or a char-table.
 If @var{table} is a string, its @var{n}th element is the mapping for the
 character with code @var{n}.
 If @var{table} is a vector, its @var{n}th element is the mapping for
 character with code @var{n}.  Legal mappings are characters, strings, or
 @code{nil} (meaning don't replace.)
 representing the register contents.  A string represents text stored in
 the register.  A marker represents a position.  A list represents a
 rectangle; its elements are strings, one per line of the rectangle.
 @end defvar
-@defun get-register reg
+@defun get-register register
 This function returns the contents of the register
-@var{reg}, or @code{nil} if it has no contents.
+@var{register}, or @code{nil} if it has no contents.
 @end defun
-@defun set-register reg value
+@defun set-register register value
-This function sets the contents of register @var{reg} to @var{value}.
+This function sets the contents of register @var{register} to @var{value}.
 A register can be set to any value, but the other register functions
 expect only certain data types.  The return value is @var{value}.
 @end defun
-@deffn Command view-register reg
+@deffn Command view-register register
-This command displays what is contained in register @var{reg}.
+This command displays what is contained in register @var{register}.
 @end deffn
 @ignore
-@deffn Command point-to-register reg
+@deffn Command point-to-register register
 This command stores both the current location of point and the current
-buffer in register @var{reg} as a marker.
+buffer in register @var{register} as a marker.
 @end deffn
-@deffn Command jump-to-register reg
+@deffn Command jump-to-register register
-@deffnx Command register-to-point reg
+@deffnx Command register-to-point register
 @comment !!SourceFile register.el
-This command restores the status recorded in register @var{reg}.
+This command restores the status recorded in register @var{register}.
-If @var{reg} contains a marker, it moves point to the position stored in
+If @var{register} contains a marker, it moves point to the position
-the marker.  Since both the buffer and the location within the buffer
+stored in the marker.  Since both the buffer and the location within the
-are stored by the @code{point-to-register} function, this command can
+buffer are stored by the @code{point-to-register} function, this command
-switch you to another buffer.
+can switch you to another buffer.
-If @var{reg} contains a window configuration or a frame configuration.
+If @var{register} 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
+@deffn Command insert-register register &optional beforep
-This command inserts contents of register @var{reg} into the current
+This command inserts contents of register @var{register} into the current
 buffer.
 Normally, this command puts point before the inserted text, and the
 mark after it.  However, if the optional second argument @var{beforep}
 is non-@code{nil}, it puts the mark before and point after.
 a rectangle (a list), currently useless things happen.  This may be
 changed in the future.
 @end deffn
 @ignore
-@deffn Command copy-to-register reg start end &optional delete-flag
+@deffn Command copy-to-register register 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
+register @var{register}.  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
+@deffn Command prepend-to-register register 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
+register @var{register}.  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
+@deffn Command append-to-register register 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
+text already in register @var{register}.  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
+@deffn Command copy-rectangle-to-register register 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
+into register @var{register}.  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
+@deffn Command window-configuration-to-register register
 This function stores the window configuration of the selected frame in
-register @var{reg}.
+register @var{register}.
 @end deffn
-@deffn Command frame-configuration-to-register reg
+@deffn Command frame-configuration-to-register register
 This function stores the current frame configuration in register
-@var{reg}.
+@var{register}.
 @end deffn
 @end ignore
 @node Transposition
 @section Transposition of Text
 the same MD5 digest, or to produce a message having a prespecified
 target digest.  MD5 is used heavily by various authentication schemes.
 Emacs Lisp interface to MD5 consists of a single function @code{md5}:
-@defun md5 object &optional start end
+@defun md5 object &optional start end coding noerror
 This function returns the MD5 message digest of @var{object}, a buffer
 or string.
 Optional arguments @var{start} and @var{end} denote positions for
 computing the digest of a portion of @var{object}.
-Some examples of usage:
+The optional @var{coding} argument specifies the coding system the text
+is to be represented in while computing the digest.  If unspecified, it
+defaults to the current format of the data, or is guessed.
+If @var{noerror} is non-@code{nil}, silently assume binary coding if the
+guesswork fails.  Normally, an error is signaled in such case.
+@var{coding} and @var{noerror} arguments are meaningful only in XEmacsen
+with file-coding or Mule support.  Otherwise, they are ignored.  Some
+examples of usage:
 @example
 @group
 ;; @r{Calculate the digest of the entire buffer}
 (md5 (current-buffer))
 of US-ASCII, as described in rfc2045.  Base64 is used by MIME to encode
 binary bodies, and to encode binary characters in message headers.
 The Lisp interface to base64 consists of four functions:
-@defun base64-encode-region beg end &optional no-line-break
+@deffn Command base64-encode-region start end &optional no-line-break
-This function encodes the region between @var{beg} and @var{end} of the
+This function encodes the region between @var{start} and @var{end} of the
 current buffer to base64 format.  This means that the original region is
 deleted, and replaced with its base64 equivalent.
 Normally, encoded base64 output is multi-line, with 76-character lines.
 If @var{no-line-break} is non-@code{nil}, newlines will not be inserted,
 resulting in single-line output.
 Mule note: you should make sure that you convert the multibyte
 characters (those that do not fit into 0--255 range) to something else,
 because they cannot be meaningfully converted to base64.  If the
 @end group
 @end example
 The function can also be used interactively, in which case it works on
 the currently active region.
-@end defun
+@end deffn
-@defun base64-encode-string string
+@defun base64-encode-string string &optional no-line-break
 This function encodes @var{string} to base64, and returns the encoded
 string.
+Normally, encoded base64 output is multi-line, with 76-character lines.
+If @var{no-line-break} is non-@code{nil}, newlines will not be inserted,
+resulting in single-line output.
 For Mule, the same considerations apply as for
 @code{base64-encode-region}.
 @example
 @group
 @result{} "ZnViYXI="
 @end group
 @end example
 @end defun
-@defun base64-decode-region beg end
+@deffn Command base64-decode-region start end
-This function decodes the region between @var{beg} and @var{end} of the
+This function decodes the region between @var{start} and @var{end} of the
 current buffer.  The region should be in base64 encoding.
 If the region was decoded correctly, @code{base64-decode-region} returns
 the length of the decoded region.  If the decoding failed, @code{nil} is
 returned.
 @example
 @group
 ;; @r{Decode a base64 buffer, and replace it with the decoded version}
 (base64-decode-region (point-min) (point-max))
 @end group
 @end example
-@end defun
+@end deffn
 @defun base64-decode-string string
 This function decodes @var{string} to base64, and returns the decoded
 string.  @var{string} should be valid base64-encoded text.

Mercurial > hg > xemacs-beta

comparison man/lispref/text.texi @ 444:576fb035e263 r21-2-37