Re: Interactive hat. (Patch V2)

[Eli Zaretskii]

> Date: Thu, 23 Apr 2009 20:50:30 +0000
> Cc: address@hidden, address@hidden, address@hidden
> From: Alan Mackenzie <address@hidden>
> 
> > > ! The @samp{*} checks that the buffer is writable, signaling an error if
> 
> > "buffer is writable" sounds strange.  How about
> 
> >   The @samp{*} checks that the buffer is read-only, and signals an
> >   error if so.
> 
> > or simply
> 
> >   The @samp{*} signals an error if the buffer is read-only.
> 
> I cut the sentence down to "The `*' checks that the buffer is writable.".

But we don't use ``writable buffer'' anywhere else.  A file can be
writable, but a buffer?

Why didn't you like one of my suggestions, or some variation thereof?

> ! @itemize @minus
> ! @item
> ! Zero or more of the ``special'' code characters @samp{*}, @samp{@@},
> ! @samp{^}, which direct Emacs to perform auxiliary functions
> ! (@pxref{Interactive Codes}) before getting the command's arguments.
> ! They are processed in the order they appear.
> ! @item
> ! a sequence of elements separated by newlines, one for each

The first @item's text is capitalized, but the second one's isn't.

> + @subsection Non-string Equivalents of Interactive Code Characters
> + @cindex Non-string interactive code

I suggest "@cindex non-string interactive spec".  Note that all index
entries begin with a lower-case letter, to avoid dependency on sort
order in the index, and also for uniformity.

> + @table @asis
> + @item @samp{*}: @code{(barf-if-buffer-readonly)}
> + @itemx @samp{d}: @code{(point)}
> + @itemx @samp{i}: @code{nil}
> + @itemx @samp{m}: @code{(mark)}
> + @itemx @samp{n}: @code{(read-number)}
> + @itemx @samp{P}: @code{current-prefix-arg}
> + @itemx @samp{r}: @code{(region-beginning)} and @code{(region-end)}
> + @itemx @samp{v}: @code{(read-variable)}
> + @itemx @samp{x}: @code{(read-minibuffer)}
> + @itemx @samp{X}: @code{(eval-minibuffer)}
> + @itemx @samp{z}: @code{(read-coding-system)}
> + @end table

That's an unusual use of @itemx.  Beware: it could do something you
didn't intend in some future version of Texinfo.  (All that just to
save a blank line?...)

> + @code{(read-file-name @var{prompt} nil default-directory t nil
> + 'file-directory-p)}

Doesn't the second line need indentation?

> + @verbatim
> + (interactive
> +  (let ((events (this-command-keys-vector))
> +        e w
> +        (i 0))
> +    (while (and (< i (length events))
> +                (not (consp (setq e (aref events i)))))
> +      (setq i (1+ i)))
> +    (when (consp e)
> +      (setq w (car (cadr e)))
> +      (if (windowp w)
> +          (if (and (window-minibuffer-p w)
> +                   (> (minibuffer-depth) 0))
> +              (error
> +               "Attempt to select inactive minibuffer window")))
> +      (run-hooks mouse-leave-buffer-hook)
> +      (select-window w))
> +    nil))
> + @end verbatim

This @verbatim is not enough, I think: the typeface used by this
example will be different from every other example in the manual,
right?  You need to force the same typeface as in @example, somehow.

Btw, why didn't @example fit the bill?

> + @item @samp{K} - key sequence (no case conversion)
> + @verbatim
> + (interactive
> +  (let ((prompt "Key binding: ")
> +        (ks) last-event)
> +    (put-text-property 0 (length prompt) 'face
> +                       'minibuffer-prompt prompt)
> +    (setq ks (read-key-sequence prompt nil t)
> +          last-event (aref ks (1- (length ks))))
> +    (if (consp last-event) (setq last-event (car last-event)))
> +    (setq my-up-event
> +          (and (symbolp last-event)
> +               (memq 'down
> +                     (get last-event 'event-symbol-elements))
> +               (vector (read-event))))
> +    (list ks)))
> + @end verbatim
> + Note how @code{my-up-event} gets set to the mouse up event, if any.
> + You can use this for the @samp{U} equivalent (see below).

?? Copy-paste mistake?  The "Note" seems to be copied verbatim from
the previous example.