bug#7151: `set-marker' narrowing and proposed feature `buffer-narrowed-p'

[MON KEY]

`set-marker' can not be set beyond value of `point-max'
This is documented here:

,---- (info "(elisp)Moving Marker Positions")
|
| If POSITION is less than 1, `set-marker' moves MARKER to the
| beginning of the buffer.  If POSITION is greater than the size of
| the buffer, `set-marker' moves marker to the end of the buffer.
| If POSITION is `nil' or a marker that points nowhere, then MARKER
| is set to point nowhere.
|
`----

Some mention in the above section should be made of `buffer-size' so users can
now how to check if the buffer is narrowed.

Likewise, docstrings of `>', `<', `<=', `>=', all indicate their arguments:

,----
|
| Both must be numbers or markers.
|
`----

There is a discrepancy here in that the following signals an error:

(let ((mk-mrk (make-marker)))
  (set-marker mk-mrk nil)
  (> mk-mrk (point-max)))
;=> (error "Marker does not point anywhere")

Moreover, as the docstring of `set-marker' doesn't indicate that its range is
bounded by the current values of `point-max' and `point-min' simple arithmetic
checks for a markers value against some arbitrary buffer position can lead to
confusing return values:

(let ((mk-mrk (make-marker)))
  (progn (narrow-to-region (+ (point-min) 10) (- (point-max) 10))
         (set-marker mk-mrk (1+ (point-max)))
         (widen))
  `(,(= mk-mrk (point-max))
    ,(>= mk-mrk (point-max))
    ,(< mk-mrk (point-max))
    ,(marker-position mk-mrk)
    ,(point-max)))
;=> (nil nil t <PSN> <PSN>)


(let ((mk-mrk (make-marker)))
  (set-marker mk-mrk (1+ (point-max)))
  (> mk-mrk (point-max)))
;=> nil

(let ((mk-mrk (make-marker)))
  (set-marker mk-mrk 12000)
  (> mk-mrk (point-max)))
;=> nil

(let ((mk-mrk (make-marker)))
  (set-marker mk-mrk 12000)
  (= (marker-position mk-mrk) 12000))
;=> nil

(let ((mk-mrk (make-marker)))
  (set-marker mk-mrk (1+ (point-max)))
  (> mk-mrk (1- (point-max))))
;=> t

I think some mention of these anomalies should be made in the respective docs in
addition to the scattered lisp service provided by the manual.

I would also like to propose addition of a new function `buffer-narrowed-p'.
rgrep'ing buffer-narrowed-p  in "lisp/" did not return any results...

(defun buffer-narrowed-p (&optional buffer-or-name)
  "Test if buffer narrowing is in effect.
When optional arg BUFFER-OR-NAME is non-nil check for narrowing in that buffer
instead. Default is `current-buffer'.\n
:EXAMPLE\n\n\(prog2
    \(narrow-to-region \(line-beginning-position\) \(line-end-position\)\)
    \(buffer-narrowed-p \"*Help*\"\)
  \(widen\)\)\n"
  (let ((chk-bffr (if buffer-or-name
                      (or (get-buffer buffer-or-name)
                          (error  "Optional arg BUFFER-OR-NAME does
not find buffer: `%S'"))
                    (current-buffer))))
    (with-current-buffer chk-bffr
      (or (> (point-min) 1)
          (/= (buffer-size) (1- (point-max)))
          (/= (- (point-max) (point-min)) (buffer-size))))))

--
/s_P\