Re: Interactive hat. (Patch)

[Alan Mackenzie]

Hi, Eli!

That was some impressive proof-reading.  Thank you very much indeed!

I've corrected most of the mistakes you pointed out, and incorporated
most of your suggestions which weren't about mistakes.  What remains is:

On Mon, Apr 13, 2009 at 11:47:03PM +0300, Eli Zaretskii wrote:
> > Date: Mon, 13 Apr 2009 19:32:55 +0000
> > From: Alan Mackenzie <address@hidden>
> > Cc: Juanma Barranquero <address@hidden>, address@hidden

> My $0.02 are below:

#########################################

> >   @menu
> > ! * Using Interactive::           General rules for @code{interactive}.
> > ! * Interactive Codes::           The standard letter-codes for reading 
> > arguments
> > !                                 in various ways.
> > ! * Non-string Interactive::      Non-string equivalents of the 
> > letter-codes.
> > ! * Interactive Examples::        Examples of how to read interactive 
> > arguments.
> >   @end menu

> Why did you add whitespace between the menu items and their
> descriptions? now the lines are too long, IMO.  Suggest to reduce the
> whitespace back.

I didn't add the whitespace, as such.  C-c C-u C-m `texinfo-make-menu'
did it for me, so I wasn't fully aware of it.  Anyhow, I've taken all but
one of the spaces out, to leave the minimum gap (1 space) between
"Interactive::" and "Non-string"

#########################################

> > ! 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.

It seems a bit negative.  "Writable" seems more positive than "not
read-only".  I'll think a bit more about this.

#########################################

> > ! @code{shift-select-mode}; @xref{Shift Selection,,, emacs, The GNU
> > ! Emacs Manual}. @footnote{Note that the code character @samp{^} was

> @footnote should come before the period that ends the previous
> sentence.  It is converted to a superscript n, so having it after the
> period looks incorrect.

I got some strange interactions between @footnote and the @xref near the
end of the paragraph.  makeinfo left ".)" on a line of its own at the
end, even though there was plenty of space on the line before.

In the end, I moved the footnote to near the start of the pargraph.  I'm
(still) getting trouble from makeinfo 4.7, though.  It generates this for
the end of that paragraph:

     Shift-translation is controlled on the user level by
     `shift-select-mode'; see Shift Selection(emacs)
     .  Special.

, with that oddly placed full stop.  The corresponding bit of .texi is:

Shift-translation is controlled on the user level by
@code{shift-select-mode}; @xref{Shift Selection,,, emacs, The GNU
Emacs Manual}.  Special.

Have you any idea what's going wrong?

#########################################

> > + @node Non-string Interactive
> > + @comment  node-name,  next,  previous,  up
> > + @subsection Non-string Equivalents of Interactive Code Characters

> It is usually a good idea to have one or more @cindex entries at the
> beginning of each section that gives the main subject of the section.
> Imagine yourself a year from now looking for this stuff, and ask
> yourself what phrases you'd think about -- these are the phrases you
> need to put in the @cindex entry for the section.  The name of the
> node, or some trivial transformation of it, is usually the first
> choice.

Hmm.  Difficult!  My first attempt was more like a sentence and was far
too long.  The best I can manage right now is:

    @cindex Non-string interactive code

#######################################

> > + the code characters into a non-string interactive form.  The semantics

> This rationale for the functionality doesn't really explain it.  In a
> nutshell, it says "You will want the non-string equivalents when you
> need the non-string interactive form."  That's a tautology.  Can you
> come up with a better rationale?

Very good point!  How about something like: "These should help you when
you need to combine the effect of a standard code character with lisp
code which is specific to your command."?

######################################

> > +              (error "Attempt to select silly inactive minibuffer 
> > window")))

> This line is too long, and will overflow the right margin in a printed
> manual.  Please break it into two lines.

The "silly" shouldn't have escaped from my test file :-).  I'll get all
the line lengths right before the next version of the patch.

#####################################

> > + 
> > + @item @samp{^} - shift-translation
> > + @lisp
> > + (interactive
> > +  (progn (if (fboundp 'handle-shift-selection)
> > +             (handle-shift-selection))
> > +         nil))
> > + @end lisp
> > + 
> > + @item @samp{a} - function name
> > + @lisp
> > + (interactive (list (completing-read "Function: " obarray 'fboundp t)))
> > + @end lisp
> > + 
> > + @item @samp{b} - existing buffer
> > + @lisp
> > + (interactive (list (read-buffer "Buffer: " (current-buffer) t)))
> > + @end lisp

> Do we _really_ need an example for _each_one_ of the codes?  Some of
> them are quite trivial, why put them in the manual?  A couple of
> trivial examples and a few more non-trivial ones, that's all that's
> needed to get the idea.

I've been mulling that over.  I think each code should be mentioned (the
whole idea is to save manual scanning effort for lazy elisp maintainers),
but perhaps not so bloatedly as I've done.  How about compacting the easy
ones into a compact list, and leaving the more difficult ones as they
are, something like:

"Many of the code characters are equivalent to a single Lisp function.
These are:

    `*` - `barf-if-readonly'
    `d' - `point'
    ....
    `z' - `read-coding-system'

The other code characters need more involved coding to emulate, for
example:

`K' - key sequence (no case conversion)
          (interactive
           (let ((prompt "Key binding: ")
                 (ks) last-event)
....

"?

-- 
Alan Mackenzie (Nuremberg, Germany).