Docs for &optional and &rest arguments together

[Arthur Miller <arthur.miller@live.com>]

I like 'with-*' idiom in Lisp, and I have written a smal macro for
myself to work with files, based on with-temp-file macro.

The Manual says I can have both optional and rest arguments togheter,
which we can: 

(required-vars…
 [&optional [optional-vars…]]
 [&rest [rest-var]])

But when I use it, I still have to pass a nil for the "optional"
argument, which I think is also not so strange either, otherwise how
will Emacs now where "optional" argument list ends and where "rest"
argument list starts? No?

When I read the manual:

"A call to the function requires one actual argument for each of the
required-vars. There may be actual arguments for zero or more of the
optional-vars, and there cannot be any actual arguments beyond that
unless the lambda list uses &rest. In that case, there may be any number
of extra actual arguments.

If actual arguments for the optional and rest variables are omitted,
then they always default to nil."

https://www.gnu.org/software/emacs/manual/html_node/elisp/Argument-List.html

I get the impression that I actually can omit the optional argument(s)
even when followed by the &rest keyword. It is probably only the case
when optional arguments *are not* followed by the &rest keyword. I don't
see that captured by the documentation, at least not very clearly.

After the experience with add-to-list I am not offering any patches for
the docs. I am just pointing it out how I perceive it. If I am wrong
about, I would be actually happy to see how to use both &optional and
&rest and not have to specify the "optional" argument when I call the macro.

For the illustration of what I describe above, here is the macro:

(defmacro with-file (file &optional operation &rest body)
  (declare (indent 1) (debug t))
  `(let ((op ,operation)
         (buffer (get-buffer-create ,file)))
     (unless op
       (setq op 'append))
     (unwind-protect
         (prog1 
             (with-current-buffer buffer
                   (cond ((equal op 'apend)
                          (goto-char (point-min))
                          (insert-file-contents ,file)
                          (goto-char (point-max))
                          ,@body)
                         ((equal op 'prepend)
                          ,@body
                          (goto-char (point-max))
                          (insert-file-contents ,file))
                         (t ;; overwrite file
                          ,@body)))
	   (with-current-buffer buffer
	     (write-region nil nil ,file nil 0)))
       (and (buffer-name buffer)
            (kill-buffer buffer)))))

And when calling, there is no way to omit the "optional" nil:

(with-file "some-test" nil
           (insert "hello world"))

(with-file "some-test" 'prepend
           (insert "I am before Hello world!")
           (newline))

(with-file "some-test" 'apend
           (newline)
           (insert "I am after Hello world!"))