FillParagraph

Last edit

Summary: Update bullet list advice

Added:

>

Added:

>

Changed:

< ;; The original value is ""\f\\|[ ]*$", add to it bullet (*) and (-).

to

> ;; The original value is "\f\\|[ ]*$", so we add the bullets (-), (+), and (*).

Changed:

< (setq paragraph-start "\f\\|[ \t]*$\\|[-*] +.+$"

to

> (setq paragraph-start "\f\\|[ \t]*$\\|[ \t]*[-+*] ")
> To cover other cases, such as numbered lists, it may be helpful to copy from the settings in MarkdownMode (or simply use it for plain text).
> In older Emacs (prior to 20.7), it may be necessary to use something closer to this:
> (setq paragraph-start "\f\\|[ \t]*$\\|[ \t]*[-+*]
+.+$"

Deleted:

< <i>Note: The handling of these two variables was broken in Emacs 20.7, so the above example might not work for you. I applied the following patch to my Emacs 20.7, so it works now.</i>
< From: StefanMonnier
< Subject: Re: adaptive fill question
< To: AlexSchroeder
< Date: 02 Mar 2001 16:43:40 -0500
< Could you try the trivial patch below to textmodes/fill.el ? I believe it's a bug, but it's old code and there are so many different possible situations that it's hard to tell whether the code is the way it is just by happenstance or if it is due to a particular problem.
< The patch fixes the problem for me, but please try it in other cases as well, to see if it introduces unexpected problems.
< Stefan
< Index: fill.el
< ===================================================================
< RCS file: /cvs/emacs/lisp/textmodes/fill.el,v
< retrieving revision 1.126
< diff -u -u -b -r1.126 fill.el
< --- fill.el 2001/02/22 20:08:33 1.126
< +++ fill.el 2001/03/02 21:38:28
< @@ -225,7 +235,7 @@
< (move-to-left-margin)
< (setq start (point))
< (setq first-line-prefix
< - (cond ((looking-at paragraph-start) nil)
< + (cond ;; ((looking-at paragraph-start) nil)
< ((and adaptive-fill-regexp (looking-at adaptive-fill-regexp))
< (buffer-substring-no-properties start (match-end 0)))
< (adaptive-fill-function (funcall adaptive-fill-function))))


In text-mode, lines end when you tell Emacs to end them. RET is bound to newline. This will insert a line break. If you don’t hit RET, your current line will grow longer and longer. As you reach the right margin of your display, the line is wrapped for you.

Line Wrapping

Emacs displays a “\” character at the end of the line and your typing continues on the next line. Emacs doesn’t insert any linebreaks for you unless you say so. Therefore many people think this looks “ugly” since it doesn’t take word boundaries into account. Here is an example of how a long line might look on a small display:

    In text-mode, lines end when you te\|
    ll Emacs to end them.  RET is bound\|
    to newline.  This will insert a lin\|
    e break.                            |

Paragraph Filling / Word Wrapping

Instead of hitting RET when your typing approaches the right margin, you can type M-q or M-x fill-paragraph to fill the current paragraph. This will take the paragraph and fill all the words such that line breaks are removed from short lines and new line breaks are inserted before words that cross the right margin.

The right margin is determined by the variable fill-column. You can set it using C-x f or M-x set-fill-column using an explicit argument. Use C-u followed by a number to specify a column. Just C-u as argument means to use the current column. The default value for fill-column is 70. This can be set to 80 in the InitFile with the command

  (setq-default fill-column 80)

In the following example, I have set the fill-column to 35 by typing C-u 35 C-x f and then I used M-q to refill the paragraph. (See AutoFillMode if you want to reduce your M-q typing.)

    In text-mode, lines end when you    |
    tell Emacs to end them.  RET is     |
    bound to newline.  This will insert |
    a line break.                       |

You can also block-fill the text by using a prefix for the paragraph filling command. Using C-u M-q to fill the same text, I get this:

    In  text-mode, lines  end  when you |
    tell  Emacs to  end  them.  RET  is |
    bound to newline.  This will insert |
    a line break.                       |

The same block-fill is achieved by M-1 M-q which is faster to type.

Not Breaking

The ‘fill-nobreak-predicate’ hook lets you avoid line breaks at certain places. For example if you’re French, you might be used to typing a space in front of colons, question marks, exclamation marks, etc. [1] This might lead to the following problem:

   Where do we write the question marks |
   ? We use a space in front of them.   |

To avoid this, add ‘fill-french-nobreak-p’ to ‘fill-nobreak-predicate’.

Emacs comes with a ‘fill-single-word-nobreak-p’ to not dangle the first or last word of a sentence, and HtmlMode/SgmlMode? sets up ‘sgml-fill-nobreak’ to keep a tag and first attribute together. For more nobreaks see

Paragraph Boundaries

By default, text-mode assumes that empty lines separate paragraphs. The boundaries of paragraphs are determined by two variables. You might want to change these two variables if you are writing a new major mode for a programming language, or if you are unhappy with the defaults. Here is an example: If you write a bulleted list, you need to separate items by an empty line if you want to fill them using M-q:

    * One item
    
    * Another item
    
    * The last item

If you want to write this without empty lines, filling will fuse the items:

    * One item
    * Another item
    * The last item

turns into

    * One item Another item The last item

In order to prevent this, we need to tell Emacs that the bullet indicates the start of a new paragraph. Here is how:

    ;; The original value is "\f\\|[      ]*$", so we add the bullets (-), (+), and (*).
    ;; There is no need for "^" as the regexp is matched at the beginning of line.
    (setq paragraph-start "\f\\|[ \t]*$\\|[ \t]*[-+*] ")

To cover other cases, such as numbered lists, it may be helpful to copy from the settings in MarkdownMode (or simply use it for plain text).

In older Emacs (prior to 20.7), it may be necessary to use something closer to this:

    (setq paragraph-start "\f\\|[ \t]*$\\|[ \t]*[-+*] +.+$"
          paragraph-separate "$")

Problems

Setting the fill column seems not to work

If you see that C-u 100 C-x f M-q and C-u 20 C-x f M-q and others are doing exactly the same, for instance breaking the lines at column 70, then check the major mode you are in. If possible, change to text-mode (M-x text-mode) and try again there. Some modes (ex: lisp-interaction-mode, the one used in the scratch buffer) seem to overwrite the filling rules.


See also MarginMode and AutoFillMode. And UnfillParagraph.


CategoryFilling CategoryCode