forward-paragraph in GNU Emacs

Question

I'm reading "An Introduction to Programming in Emacs Lisp" by Robert J. Chassell. And I have a question. In the node "fwd-para while" (explanation of the while loop of forward-paragraph), it says:

Interestingly, the loop count is not decremented until we leave the space between paragraphs, unless we come to the end of buffer or stop seeing the local value of the paragraph separator.

I can't understand it, can somebody explain it for me? Thanks.

The while loop looks like this:

;; going forwards and not at the end of the buffer
(while (and (> arg 0) (not (eobp)))

  ;; between paragraphs
  ;; Move forward over separator lines...
  (while (and (not (eobp))
              (progn (move-to-left-margin) (not (eobp)))
              (looking-at parsep))
    (forward-line 1))
  ;;  This decrements the loop
  (unless (eobp) (setq arg (1- arg)))
  ;; ... and one more line.
  (forward-line 1)

  (if fill-prefix-regexp
      ;; There is a fill prefix; it overrides parstart;
      ;; we go forward line by line
      (while (and (not (eobp))
                  (progn (move-to-left-margin) (not (eobp)))
                  (not (looking-at parsep))
                  (looking-at fill-prefix-regexp))
        (forward-line 1))

    ;; There is no fill prefix;
    ;; we go forward character by character
    (while (and (re-search-forward sp-parstart nil 1)
                (progn (setq start (match-beginning 0))
                       (goto-char start)
                       (not (eobp)))
                (progn (move-to-left-margin)
                       (not (looking-at parsep)))
                (or (not (looking-at parstart))
                    (and use-hard-newlines
                         (not (get-text-property (1- start) 'hard)))))
      (forward-char 1))

    ;; and if there is no fill prefix and if we are not at the end,
    ;;     go to whatever was found in the regular expression search
    ;;     for sp-parstart
    (if (< (point) (point-max))
        (goto-char start))))

Thanks for editing and answering. I have another three questions about forward-paragraph:

1. What is the meaning of (progn (move-to-left-margin) (not (eobp)))? If (not (eobp)) is true, shouldn't (progn (move-to-left-margin) (not (eobp))) always be true?

2. About this line:

   ;; ... and one more line.
   (forward-line 1)
   

   Why forwarding one more line?

3. About this paragraph:

   This while loop has us searching forward for `sp-parstart', which is the combination of possible whitespace with a the local value of the start of a paragraph or of a paragraph separator.

   Why does the local value of the start of a paragraph or of a paragraph separator? As far as I'm concerned, the condition of the paragraph separator has already been processed in the first while loop of the while.

Answer 1

It's not that interesting! If you look at the docstring for forward-paragraph you'll see that it:

Returns the count of paragraphs left to move.

That means that if you are one paragraph from the end of the buffer, and evaluate (forward-paragraph 3), it will return 2, meaning that it stepped forward by one paragraph, but the remaining two steps that you requested could not be taken.

In order to return the number of steps not taken, forward-paragraph returns (just after the block of code you've quoted) the value arg. So arg must only be decremented when forward-paragraph actually steps forward by a paragraph. I'm sure you can figure out the rest.

(If you're wondering where the return value is used, it's in fill-paragraph to avoid filling a non-existent paragraph at the end of the buffer.)

ETA: I see that you've added three new questions. Instead of answering them, I'll tell you how you might try to answer them for yourself by using the Emacs Lisp debugger to step through the code for forward-paragraph and see what it is actually doing.

1. Find the source code for forward-paragraph by typing C-h C-f forward-paragraph RET and then clicking on the link in the *Help* buffer.

2. Recompile forward-paragraph for debugging by running the command eval-defun, for example by typing C-M-x.

3. Turn on debugging for forward-paragraph by typing M-x debug-on-entry RET forward-paragraph RET.

4. Go to a suitable buffer and run forward-paragraph, for example by typing M-}.

5. Now you're in the debugger, which shows you the call stack and the current form being evaluated. You can type d to step into that form and see the evaluation of its subforms, or c to completely evaluate the form and see its result, and q to exit the debugger. (See the documentation for more debugger commands.)

6. Step through the execution of forward-paragraph until you understand what it is doing.