@defvar use-hard-newlines
If this variable is non-@code{nil}, the filling functions do not delete
newlines that have the @code{hard} text property. These ``hard
-newlines'' act as paragraph separators.
+newlines'' act as paragraph separators. @xref{Hard and Soft
+Newlines,, Hard and Soft Newlines, emacs, The GNU Emacs Manual}.
@end defvar
@node Margins
@cindex filling, automatic
@cindex Auto Fill mode
+@c FIXME: I don't think any of the variables below is a/an normal/abnormal hook.
Auto Fill mode is a minor mode that fills lines automatically as text
is inserted. This section describes the hook used by Auto Fill mode.
For a description of functions that you can call explicitly to fill and
@group
(sort-subr reverse
(function
- (lambda ()
- (while (and (not (eobp))
- (looking-at paragraph-separate))
- (forward-line 1))))
+ (lambda ()
+ (while (and (not (eobp))
+ (looking-at paragraph-separate))
+ (forward-line 1))))
'forward-paragraph)
@end group
@end example
When called interactively, @var{column} is the value of prefix numeric
argument. If @var{column} is not an integer, an error is signaled.
+@c This behavior used to be documented until 2013/08.
+@ignore
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.
+@end ignore
If it is impossible to move to column @var{column} because that is in
the middle of a multicolumn character such as a tab, point moves to the
For example, if @var{count} is 3, this command adds 3 columns of
indentation to each of the lines beginning in the region specified.
+@c FIXME: I suggest using message-indent-citation as the example, or
+@c just remove this paragraph. --xfq
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 group
@group
-(capitalize-region 1 44)
+(capitalize-region 1 37)
@result{} nil
---------- Buffer: foo ----------
@end defun
@defun add-face-text-property start end face &optional appendp object
-@code{face} text attributes can be combined. If you want to make a
-section both italic and green, you can either define a new face that
-have those attributes, or you can add both these attributes separately
-to text:
+This function acts on the text between @var{start} and @var{end},
+adding the face @var{face} to the @code{face} text property.
+@var{face} should be a valid value for the @code{face} property
+(@pxref{Special Properties}), such as a face name or an anonymous face
+(@pxref{Faces}).
+
+If any text in the region already has a non-nil @code{face} property,
+those face(s) are retained. This function sets the @code{face}
+property to a list of faces, with @var{face} as the first element (by
+default) and the pre-existing faces as the remaining elements. If the
+optional argument @var{append} is non-@code{nil}, @var{face} is
+appended to the end of the list instead. Note that in a face list,
+the first occurring value for each attribute takes precedence.
+
+For example, the following code would assign a italicized green face
+to the text between @var{start} and @var{end}:
@example
(add-face-text-property @var{start} @var{end} 'italic)
-(add-face-text-property @var{start} @var{end} '(:foreground "#00ff00"))
+(add-face-text-property @var{start} @var{end} '(:foreground "red"))
+(add-face-text-property @var{start} @var{end} '(:foreground "green"))
@end example
-The attribute is (by default) prepended to the list of face
-attributes, and the first attribute of the same type takes
-precedence. So if you have two @code{:foreground} specifications, the
-first one will take effect.
-
-If you pass in @var{appendp}, the attribute will be appended instead
-of prepended, which means that it will have no effect if there is
-already an attribute of the same type.
-
+The optional argument @var{object}, if non-@code{nil}, specifies a
+buffer or string to act on, rather than the current buffer. If
+@var{object} is a string, then @var{start} and @var{end} are
+zero-based indices into the string.
@end defun
- The easiest way to make a string with text properties
-is with @code{propertize}:
+ The easiest way to make a string with text properties is with
+@code{propertize}:
@defun propertize string &rest properties
This function returns a copy of @var{string} which has the text
dynamically updating the @code{face} property of characters based on
the context.
+The @code{add-face-text-property} function provides a convenient way
+to set this text property. @xref{Changing Properties}.
+
@item font-lock-face
@kindex font-lock-face @r{(text property)}
This property specifies a value for the @code{face} property that Font
Insertion of text at the border between intervals also raises
questions that have no satisfactory answer.
- However, it is easy to arrange for editing to behave consistently for
-questions of the form, ``What are the properties of this character?''
-So we have decided these are the only questions that make sense; we have
-not implemented asking questions about where intervals start or end.
+ However, it is easy to arrange for editing to behave consistently
+for questions of the form, ``What are the properties of text at this
+buffer or string position?'' So we have decided these are the only
+questions that make sense; we have not implemented asking questions
+about where intervals start or end.
In practice, you can usually use the text property search functions in
place of explicit interval boundaries. You can think of them as finding
This represents a window configuration to restore in one frame, and a
position to jump to in the current buffer.
+@c FIXME: Mention frameset here.
@item @code{(@var{frame-configuration} @var{position})}
This represents a frame configuration to restore, and a position
to jump to in the current buffer.