9

I would like to fill (wrap) a long heading in org mode. I don't see mention of how to do so in the org manual.

If I manually wrap the line by inserting a newline, org mode does not recognize the wrapped text as a heading.

Is this possible?

Note: org-fill-paragraph does not do this:

(defun org-fill-paragraph (&optional justify)
  "Fill element at point, when applicable.

This function only applies to comment blocks, comments, example
blocks and paragraphs.  Also, as a special case, re-align table
when point is at one.

If JUSTIFY is non-nil (interactively, with prefix argument),
justify as well.  If `sentence-end-double-space' is non-nil, then
period followed by one space does not end a sentence, so don't
break a line there.  The variable `fill-column' controls the
width for filling.

For convenience, when point is at a plain list, an item or
a footnote definition, try to fill the first paragraph within."
  (interactive)
  ; ...
David J.
  • 1,809
  • 1
  • 13
  • 23

2 Answers2

11

The original poster is using the words fill and wrap interchangeably -- they are not the same.

See the variable org-startup-truncated:

Non-nil means entering Org-mode will set `truncate-lines'.
This is useful since some lines containing links can be very long and
uninteresting.  Also tables look terrible when wrapped.

The default is t. To change this, the user can put the following code into the .emacs file:

(setq org-startup-truncated nil)

org-mode needs a line-end to correctly identify a heading. To see an example of the regexp that org-mode uses for headings, the user can type (after an org-mode buffer has been loaded):

M-x describe-variable RET org-complex-heading-regexp RET

As can be seen, the ending is $ -- i.e., to the end of the line.

^\\(\\*+\\)\\(?: +\\(TODO\\|DONE\\)\\)?\\(?: +\\(\\[#.\\]\\)\\)?\\(?: +\\(.*?\\)\\)??\\(?:[     ]+\\(:[[:alnum:]_@#%:]+:\\)\\)?[    ]*$
lawlist
  • 18,826
  • 5
  • 37
  • 118
  • Thanks for clarifying filling vs. wrapping. That distinction is not clear from reading www.emacswiki.org/emacs/FillParagraph. Thanks for showing the underlying regular expression. As for take-aways, is this accurate?: Unless one modifies that regex, filling (inserting newlines) is not an option. Truncation will work, either using the way you show or with `M-x toggle-truncate-lines` (shown in my answer). – David J. Dec 21 '14 at 19:41
  • 1
    To disable truncation automatically, the variable `org-startup-truncated` is most appropriate because the initialization of `org-mode` checks the value of that variable and unless it is `nil`, the initialization process specifically sets `(setq truncate-lines t)`. To keep the default behavior and only toggle it manually, then `toggle-truncate-lines` is certainly appropriate. The underlying regex for headlings cannot be easily changed (in my opinion) because there are a million and one functions that rely on it -- e.g., `org-agenda-list`; `org-search-view`; `org-tags-view`, to name a few. – lawlist Dec 21 '14 at 20:06
  • 1
    You may also be interested in `visual-line-mode` which endeavors to keep whole words together when wrapping. For my own setup, I have modified the editing of todo entries as follows: editing automatically narrows the buffer to the task I'm editing; `visual-line-mode` is activated and I do my editing; when exiting the narrowed buffer, `visual-line-mode` is turned off; truncation remains the default when the buffer is *not* narrowed. I have a custom setup that keeps the un-narrowed buffer in a read-only state, which is made readable when editing, and then set to read-only when done. – lawlist Dec 21 '14 at 20:19
4

I don't see how to make filling work. So a work-around is to use M-x toggle-truncate-lines. This only affects the presentation of the heading. It does not insert newlines.

David J.
  • 1,809
  • 1
  • 13
  • 23