-File: lispref.info, Node: Filling, Next: Margins, Prev: Maintaining Undo, Up: Text
-
-Filling
-=======
-
- "Filling" means adjusting the lengths of lines (by moving the line
-breaks) so that they are nearly (but no greater than) a specified
-maximum width. Additionally, lines can be "justified", which means
-inserting spaces to make the left and/or right margins line up
-precisely. The width is controlled by the variable `fill-column'. For
-ease of reading, lines should be no longer than 70 or so columns.
-
- You can use Auto Fill mode (*note Auto Filling::.) to fill text
-automatically as you insert it, but changes to existing text may leave
-it improperly filled. Then you must fill the text explicitly.
-
- Most of the commands in this section return values that are not
-meaningful. All the functions that do filling take note of the current
-left margin, current right margin, and current justification style
-(*note Margins::.). If the current justification style is `none', the
-filling functions don't actually do anything.
-
- Several of the filling functions have an argument JUSTIFY. If it is
-non-`nil', that requests some kind of justification. It can be `left',
-`right', `full', or `center', to request a specific style of
-justification. If it is `t', that means to use the current
-justification style for this part of the text (see
-`current-justification', below).
-
- When you call the filling functions interactively, using a prefix
-argument implies the value `full' for JUSTIFY.
-
- - Command: fill-paragraph JUSTIFY
- This command fills the paragraph at or after point. If JUSTIFY is
- non-`nil', each line is justified as well. It uses the ordinary
- paragraph motion commands to find paragraph boundaries. *Note
- Paragraphs: (xemacs)Paragraphs.
-
- - Command: fill-region START END &optional JUSTIFY
- This command fills each of the paragraphs in the region from START
- to END. It justifies as well if JUSTIFY is non-`nil'.
-
- The variable `paragraph-separate' controls how to distinguish
- paragraphs. *Note Standard Regexps::.
-
- - Command: fill-individual-paragraphs START END &optional JUSTIFY
- MAIL-FLAG
- This command fills each paragraph in the region according to its
- individual fill prefix. Thus, if the lines of a paragraph were
- indented with spaces, the filled paragraph will remain indented in
- the same fashion.
-
- The first two arguments, START and END, are the beginning and end
- of the region to be filled. The third and fourth arguments,
- JUSTIFY and MAIL-FLAG, are optional. If JUSTIFY is non-`nil', the
- paragraphs are justified as well as filled. If MAIL-FLAG is
- non-`nil', it means the function is operating on a mail message
- and therefore should not fill the header lines.
-
- Ordinarily, `fill-individual-paragraphs' regards each change in
- indentation as starting a new paragraph. If
- `fill-individual-varying-indent' is non-`nil', then only separator
- lines separate paragraphs. That mode can handle indented
- paragraphs with additional indentation on the first line.
-
- - User Option: fill-individual-varying-indent
- This variable alters the action of `fill-individual-paragraphs' as
- described above.
-
- - Command: fill-region-as-paragraph START END &optional JUSTIFY
- This command considers a region of text as a paragraph and fills
- it. If the region was made up of many paragraphs, the blank lines
- between paragraphs are removed. This function justifies as well
- as filling when JUSTIFY is non-`nil'.
-
- In an interactive call, any prefix argument requests justification.
-
- In Adaptive Fill mode, which is enabled by default,
- `fill-region-as-paragraph' on an indented paragraph when there is
- no fill prefix uses the indentation of the second line of the
- paragraph as the fill prefix.
-
- - Command: justify-current-line HOW EOP NOSQUEEZE
- This command inserts spaces between the words of the current line
- so that the line ends exactly at `fill-column'. It returns `nil'.
-
- The argument HOW, if non-`nil' specifies explicitly the style of
- justification. It can be `left', `right', `full', `center', or
- `none'. If it is `t', that means to do follow specified
- justification style (see `current-justification', below). `nil'
- means to do full justification.
-
- If EOP is non-`nil', that means do left-justification when
- `current-justification' specifies full justification. This is used
- for the last line of a paragraph; even if the paragraph as a whole
- is fully justified, the last line should not be.
-
- If NOSQUEEZE is non-`nil', that means do not change interior
- whitespace.
-
- - User Option: default-justification
- This variable's value specifies the style of justification to use
- for text that doesn't specify a style with a text property. The
- possible values are `left', `right', `full', `center', or `none'.
- The default value is `left'.
-
- - Function: current-justification
- This function returns the proper justification style to use for
- filling the text around point.
-
- - Variable: fill-paragraph-function
- This variable provides a way for major modes to override the
- filling of paragraphs. If the value is non-`nil',
- `fill-paragraph' calls this function to do the work. If the
- function returns a non-`nil' value, `fill-paragraph' assumes the
- job is done, and immediately returns that value.
-
- The usual use of this feature is to fill comments in programming
- language modes. If the function needs to fill a paragraph in the
- usual way, it can do so as follows:
-
- (let ((fill-paragraph-function nil))
- (fill-paragraph arg))
-
- - Variable: use-hard-newlines
- If this variable is non-`nil', the filling functions do not delete
- newlines that have the `hard' text property. These "hard
- newlines" act as paragraph separators.
+File: lispref.info, Node: The Mark, Next: The Region, Prev: Changing Markers, Up: Markers
+
+The Mark
+========
+
+ One special marker in each buffer is designated "the mark". It
+records a position for the user for the sake of commands such as `C-w'
+and `C-x <TAB>'. Lisp programs should set the mark only to values that
+have a potential use to the user, and never for their own internal
+purposes. For example, the `replace-regexp' command sets the mark to
+the value of point before doing any replacements, because this enables
+the user to move back there conveniently after the replace is finished.
+
+ Once the mark "exists" in a buffer, it normally never ceases to
+exist. However, it may become "inactive", and usually does so after
+each command (other than simple motion commands and some commands that
+explicitly activate the mark). When the mark is active, the region
+between point and the mark is called the "active region" and is
+highlighted specially.
+
+ Many commands are designed so that when called interactively they
+operate on the text between point and the mark. Such commands work
+only when an active region exists, i.e. when the mark is active. (The
+reason for this is to prevent you from accidentally deleting or
+changing large chunks of your text.) If you are writing such a command,
+don't examine the mark directly; instead, use `interactive' with the
+`r' specification. This provides the values of point and the mark as
+arguments to the command in an interactive call, but permits other Lisp
+programs to specify arguments explicitly, and automatically signals an
+error if the command is called interactively when no active region
+exists. *Note Interactive Codes::.
+
+ Each buffer has its own value of the mark that is independent of the
+value of the mark in other buffers. (When a buffer is created, the mark
+exists but does not point anywhere. We consider this state as "the
+absence of a mark in that buffer.") However, only one active region can
+exist at a time. Activating the mark in one buffer automatically
+deactivates an active mark in any other buffer. Note that the user can
+explicitly activate a mark at any time by using the command
+`activate-region' (normally bound to `M-C-z') or by using the command
+`exchange-point-and-mark' (normally bound to `C-x C-x'), which has the
+side effect of activating the mark.
+
+ Some people do not like active regions, so they disable this behavior
+by setting the variable `zmacs-regions' to `nil'. This makes the mark
+always active (except when a buffer is just created and the mark points
+nowhere), and turns off the highlighting of the region between point
+and the mark. Commands that explicitly retrieve the value of the mark
+should make sure that they behave correctly and consistently
+irrespective of the setting of `zmacs-regions'; some primitives are
+provided to ensure this behavior.
+
+ In addition to the mark, each buffer has a "mark ring" which is a
+list of markers containing previous values of the mark. When editing
+commands change the mark, they should normally save the old value of the
+mark on the mark ring. The variable `mark-ring-max' specifies the
+maximum number of entries in the mark ring; once the list becomes this
+long, adding a new element deletes the last element.
+
+ - Function: mark &optional force buffer
+ This function returns BUFFER's mark position as an integer.
+ BUFFER defaults to the current buffer if omitted.
+
+ If the mark is inactive, `mark' normally returns `nil'. However,
+ if FORCE is non-`nil', then `mark' returns the mark position
+ anyway--or `nil', if the mark is not yet set for the buffer.
+
+ (Remember that if ZMACS-REGIONS is `nil', the mark is always
+ active as long as it exists, and the FORCE argument will have no
+ effect.)
+
+ If you are using this in an editing command, you are most likely
+ making a mistake; see the documentation of `set-mark' below.
+
+ - Function: mark-marker &optional force buffer
+ This function returns BUFFER's mark. BUFFER defaults to the
+ current buffer if omitted. This is the very marker that records
+ the mark location inside XEmacs, not a copy. Therefore, changing
+ this marker's position will directly affect the position of the
+ mark. Don't do it unless that is the effect you want.
+
+ If the mark is inactive, `mark-marker' normally returns `nil'.
+ However, if FORCE is non-`nil', then `mark-marker' returns the
+ mark anyway.
+ (setq m (mark-marker))
+ => #<marker at 3420 in markers.texi>
+ (set-marker m 100)
+ => #<marker at 100 in markers.texi>
+ (mark-marker)
+ => #<marker at 100 in markers.texi>
+
+ Like any marker, this marker can be set to point at any buffer you
+ like. We don't recommend that you make it point at any buffer
+ other than the one of which it is the mark. If you do, it will
+ yield perfectly consistent, but rather odd, results.
+
+ - Function: set-mark position &optional buffer
+ This function sets `buffer''s mark to POSITION, and activates the
+ mark. BUFFER defaults to the current buffer if omitted. The old
+ value of the mark is _not_ pushed onto the mark ring.
+
+ *Please note:* Use this function only if you want the user to see
+ that the mark has moved, and you want the previous mark position to
+ be lost. Normally, when a new mark is set, the old one should go
+ on the `mark-ring'. For this reason, most applications should use
+ `push-mark' and `pop-mark', not `set-mark'.
+
+ Novice XEmacs Lisp programmers often try to use the mark for the
+ wrong purposes. The mark saves a location for the user's
+ convenience. An editing command should not alter the mark unless
+ altering the mark is part of the user-level functionality of the
+ command. (And, in that case, this effect should be documented.)
+ To remember a location for internal use in the Lisp program, store
+ it in a Lisp variable. For example:
+
+ (let ((start (point)))
+ (forward-line 1)
+ (delete-region start (point))).
+
+ - Command: exchange-point-and-mark &optional dont-activate-region
+ This function exchanges the positions of point and the mark. It
+ is intended for interactive use. The mark is also activated
+ unless DONT-ACTIVATE-REGION is non-`nil'.
+
+ - Function: push-mark &optional position nomsg activate buffer
+ This function sets BUFFER's mark to POSITION, and pushes a copy of
+ the previous mark onto `mark-ring'. BUFFER defaults to the
+ current buffer if omitted. If POSITION is `nil', then the value
+ of point is used. `push-mark' returns `nil'.
+
+ If the last global mark pushed was not in BUFFER, also push
+ POSITION on the global mark ring (see below).
+
+ The function `push-mark' normally _does not_ activate the mark.
+ To do that, specify `t' for the argument ACTIVATE.
+
+ A `Mark set' message is displayed unless NOMSG is non-`nil'.
+
+ - Function: pop-mark
+ This function pops off the top element of `mark-ring' and makes
+ that mark become the buffer's actual mark. This does not move
+ point in the buffer, and it does nothing if `mark-ring' is empty.
+ It deactivates the mark.
+
+ The return value is not meaningful.
+
+ - Variable: mark-ring
+ The value of this buffer-local variable is the list of saved former
+ marks of the current buffer, most recent first.
+
+ mark-ring
+ => (#<marker at 11050 in markers.texi>
+ #<marker at 10832 in markers.texi>
+ ...)
+
+ - User Option: mark-ring-max
+ The value of this variable is the maximum size of `mark-ring'. If
+ more marks than this are pushed onto the `mark-ring', `push-mark'
+ discards an old mark when it adds a new one.
+
+ In additional to a per-buffer mark ring, there is a "global mark
+ring". Marks are pushed onto the global mark ring the first time you
+set a mark after switching buffers.
+
+ - Variable: global-mark-ring
+ The value of this variable is the list of saved former global
+ marks, most recent first.
+
+ - User Option: mark-ring-max
+ The value of this variable is the maximum size of
+ `global-mark-ring'. If more marks than this are pushed onto the
+ `global-mark-ring', `push-mark' discards an old mark when it adds
+ a new one.
+
+ - Command: pop-global-mark
+ This function pops a mark off the global mark ring and jumps to
+ that location.