emacs-devel
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Interactive hat. (Patch V2)


From: Alan Mackenzie
Subject: Re: Interactive hat. (Patch V2)
Date: Mon, 27 Apr 2009 11:46:20 +0000
User-agent: Mutt/1.5.9i

Hello, Eli,

Thanks, once again, for the proof reading.  I'll be correcting the
mistakes you've pointed out.  But in the meantime, allow me the
indulgence of a rant:

On Fri, Apr 24, 2009 at 04:38:52PM +0300, Eli Zaretskii wrote:

> > + @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.  

I don't think so; at least, not if makeinfo does what its manual says.
@itemx is defined to be identical to @item, except for not inserting a
blank line.  (See page "itemx" in the manual).

> (All that just to save a blank line?...)

Ten blank lines, actually.

[ .... ]

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

> Doesn't the second line need indentation?

Yes, it does.  Thanks!

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

Because @example inserts silly whitespace, of which there is already too
much.

makeinfo is a fascist program, one which seems to think that there is no
documention whatsoever that cannot be improved by inserting an infinite
number of blank lines (despite what the Texinfo manual says) or indenting
otherwise innocent example source code to an arbitrarily far right
column.

The manual's description of these topics is of "note to self" quality
rather than having the rigor one would expect of a GNU manual.  (What
hacker would interpret "the text is not indented" to mean "the text is
indented to column 10"?)

I think I've wasted more time trying to get a good, reasonably compact
layout on the page I've written than it took me to write the material,
and it's been almost as much fun as coding in Cobol.  I've now joined
that body of hackers who hold Texinfo to be unsuitable for writing
manuals in, though it's still much better than most of the competition.

Yes, I should really submit a proper bug report to bug-texinfo, but I can
see myself having to follow up with a set of patches, and I really,
really don't want to spend time on this - I just can't be bothered.  I
need to get out more.

Don't worry, I'll get over it.

-- 
Alan Mackenzie (Nuremberg, Germany).




reply via email to

[Prev in Thread] Current Thread [Next in Thread]