Function: org-fill-element

org-fill-element is a byte-compiled function defined in org.el.gz.

Signature

(org-fill-element &optional JUSTIFY)

Documentation

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.

Source Code

;; Defined in /usr/src/emacs/lisp/org/org.el.gz
(defun org-fill-element (&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."
  (with-syntax-table org-mode-transpose-word-syntax-table
    ;; Move to end of line in order to get the first paragraph within
    ;; a plain list or a footnote definition.
    (let ((element (save-excursion (end-of-line) (org-element-at-point))))
      ;; First check if point is in a blank line at the beginning of
      ;; the buffer.  In that case, ignore filling.
      (cl-case (org-element-type element)
	;; Use major mode filling function is source blocks.
        (src-block
         (let ((regionp (region-active-p)))
           (org-babel-do-in-edit-buffer
            ;; `org-babel-do-in-edit-buffer' will preserve region if it
            ;; is within src block contents.  Otherwise, the region
            ;; crosses src block boundaries.  We re-fill the whole src
            ;; block in such scenario.
            (when (and regionp (not (region-active-p)))
              (push-mark (point-min))
              (goto-char (point-max))
              (setq mark-active t))
            (funcall-interactively #'fill-paragraph justify 'region))))
	;; Align Org tables, leave table.el tables as-is.
	(table-row (org-table-align) t)
	(table
	 (when (eq (org-element-property :type element) 'org)
	   (save-excursion
	     (goto-char (org-element-post-affiliated element))
	     (org-table-align)))
	 t)
	(paragraph
	 ;; Paragraphs may contain `line-break' type objects.
	 (let ((beg (max (point-min)
			 (org-element-contents-begin element)))
	       (end (min (point-max)
			 (org-element-contents-end element))))
	   ;; Do nothing if point is at an affiliated keyword.
	   (if (< (line-end-position) beg) t
	     ;; Fill paragraph, taking line breaks into account.
	     (save-excursion
	       (goto-char beg)
	       (let ((cuts (list beg)))
		 (while (re-search-forward "\\\\\\\\[ \t]*\n" end t)
		   (when (org-element-type-p
			  (save-excursion (backward-char)
					  (org-element-context))
                          'line-break)
		     (push (point) cuts)))
		 (dolist (c (delq end cuts))
		   (fill-region-as-paragraph c end justify)
		   (setq end c))))
	     t)))
	;; Contents of `comment-block' type elements should be
	;; filled as plain text, but only if point is within block
	;; markers.
	(comment-block
	 (let* ((case-fold-search t)
		(beg (save-excursion
		       (goto-char (org-element-begin element))
		       (re-search-forward "^[ \t]*#\\+begin_comment" nil t)
		       (forward-line)
		       (point)))
		(end (save-excursion
		       (goto-char (org-element-end element))
		       (re-search-backward "^[ \t]*#\\+end_comment" nil t)
		       (line-beginning-position))))
	   (if (or (< (point) beg) (> (point) end)) t
	     (fill-region-as-paragraph
	      (save-excursion (end-of-line)
			      (re-search-backward "^[ \t]*$" beg 'move)
			      (line-beginning-position))
	      (save-excursion (forward-line 0)
			      (re-search-forward "^[ \t]*$" end 'move)
			      (line-beginning-position))
	      justify))))
	;; Fill comments.
	(comment
	 (let ((begin (org-element-post-affiliated element))
	       (end (org-element-end element)))
	   (when (and (>= (point) begin) (<= (point) end))
	     (let ((begin (save-excursion
			    (end-of-line)
			    (if (re-search-backward "^[ \t]*#[ \t]*$" begin t)
				(progn (forward-line) (point))
			      begin)))
		   (end (save-excursion
			  (end-of-line)
			  (if (re-search-forward "^[ \t]*#[ \t]*$" end 'move)
			      (1- (line-beginning-position))
			    (skip-chars-backward " \r\t\n")
			    (line-end-position)))))
	       ;; Do not fill comments when at a blank line.
	       (when (> end begin)
		 (let ((fill-prefix
			(save-excursion
			  (forward-line 0)
			  (looking-at "[ \t]*#")
			  (let ((comment-prefix (match-string 0)))
			    (goto-char (match-end 0))
			    (if (looking-at adaptive-fill-regexp)
				(concat comment-prefix (match-string 0))
			      (concat comment-prefix " "))))))
		   (save-excursion
		     (fill-region-as-paragraph begin end justify))))))
	   t))
	;; Ignore every other element.
	(otherwise t)))))