Re: Interactive hat. (Patch)

[Eli Zaretskii <eliz@gnu.org>]

> Date: Tue, 14 Apr 2009 20:15:38 +0000
> Cc: lekktu@gmail.com, monnier@iro.umontreal.ca, emacs-devel@gnu.org
> From: Alan Mackenzie <acm@muc.de>
> 
> That was some impressive proof-reading.  Thank you very much indeed!

Thank _you_ for working on this in the first place.

> > 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"

That's good.  Yes, `texinfo-make-menu' is known for adding gratuitous
whitespace.

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

There was no "not" in the text I suggested.

> 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?

Nothing's wrong; you are looking at the result of info.el's attempt to
beautify the Info cross-reference syntax, and failing spectacularly
when it spans more than a single line.  Please visit the produced Info
file literally, and you will see that the text produced by makeinfo is
perfectly okay.

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

Well, this is related to Miles's comments.  Maybe if we find a better
term for this, the index entry could use that.

> > 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."?

Wasn't your motivation primarily portability to versions of Emacs that
don't support some of the newer characters?  If so, why not say that?

> "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)
> ....
> 
> "?

That's a very good idea, IMO.