5.3.3 The Complete beginning-of-buffer

Here is the complete text of the beginning-of-buffer function:

     (defun beginning-of-buffer (&optional arg)
       "Move point to the beginning of the buffer;
     leave mark at previous position.
     With \\[universal-argument] prefix,
     do not set mark at previous position.
     With numeric arg N,
     put point N/10 of the way from the beginning.
     
     If the buffer is narrowed,
     this command uses the beginning and size
     of the accessible part of the buffer.
     
     Don't use this command in Lisp programs!
     \(goto-char (point-min)) is faster
     and avoids clobbering the mark."
       (interactive "P")
       (or (consp arg)
           (and transient-mark-mode mark-active)
           (push-mark))
       (let ((size (- (point-max) (point-min))))
         (goto-char (if (and arg (not (consp arg)))
                        (+ (point-min)
                           (if (> size 10000)
                               ;; Avoid overflow for large buffer sizes!
                               (* (prefix-numeric-value arg)
                                  (/ size 10))
                             (/ (+ 10 (* size (prefix-numeric-value arg)))
                                10)))
                      (point-min))))
       (if arg (forward-line 1)))

Except for two small points, the previous discussion shows how this function works. The first point deals with a detail in the documentation string, and the second point concerns the last line of the function.

In the documentation string, there is reference to an expression:

     \\[universal-argument]

A ‘\\’ is used before the first square bracket of this expression. This ‘\\’ tells the Lisp interpreter to substitute whatever key is currently bound to the ‘[...]’. In the case of universal-argument, that is usually C-u, but it might be different. (See Tips for Documentation Strings, for more information.)

Finally, the last line of the beginning-of-buffer command says to move point to the beginning of the next line if the command is invoked with an argument:

     (if arg (forward-line 1)))

This puts the cursor at the beginning of the first line after the appropriate tenths position in the buffer. This is a flourish that means that the cursor is always located at least the requested tenths of the way through the buffer, which is a nicety that is, perhaps, not necessary, but which, if it did not occur, would be sure to draw complaints.

On the other hand, it also means that if you specify the command with a C-u, but without a number, that is to say, if the `raw prefix argument' is simply a cons cell, then the command puts you at the beginning of the second line ... I don't know whether this is intended or whether no one has dealt with the code to avoid this happening.