Re: master 11f44ec6dda: Enable DND handlers to receive more than one URI at a time

[Po Lu]

Visuwesh <visuweshm@gmail.com> writes:

> I find the new text is quite hard to understand, how about saying
>
>     Each handler function is called with the URL that matched it and one
                                                        -------

When was this matched?  You have excluded the text that indicates the
event where this comparison takes place.

>     of the symbols @code{copy}, @code{move}, @code{link}, @code{private}
>     or @code{ask} identifying the action to be taken.
>
>     @cindex dnd-multiple-handler, a symbol property
>     If the handler function is a symbol whose property
>     @code{dnd-multiple-handler} is non-@code{nil} (@pxref{Symbol
>     Properties}), then it is given a list of every URL that matches its
>     regexp as the first argument instead.

I want to place emphasis on the new behavior, so it must come first in
that paragraph.  But if there's anything else which you find ambiguous,
please say so.

I've come to recognize that documentation should generally avoid words
or collocations that betray indecision or uncertainty on the part of the
writer (consider "by default" or "instead").  The replacement for "by
default" is to mention the general behavior first, followed by an
account of each exception to it.  Words such as "instead" should be
removed, since they are inserted to clarify the subject of a
qualification, and become redundant once such qualifications are
directly placed after their subjects.  The documentation produced is
pither and less prey to interpretation.