bug#78021: 30.1; Unclear sentence in (emacs)Matching

[Drew Adams]

> > Not clear enough:
> > "with only white space between the delimiters".
> > Only whitespace between which delimiters?  There are
> > presumably at least 3 delimiters in this scenario, one
> > opening and two closing.
> 
> The scenario is like this: "some text (     ) more text", and the user
> types ")" somewhere between the pair of parens.  If you can think of a
> clearer way of describing this just as briefly, I would be grateful (Eli
> requested that the node should not become much longer).
> 
> > Not clear enough:
> > "to after the closing delimiter".
> > Which closing delimiter?
> 
> The one in the text scenario given above, which is the only actual
> closing delimiter character in the text -- the "other closing delimiter"
> is still just the key being typed, but the character is not inserted (as
> the description says).  Here, too, I would welcome a clearer but just as
> brief description.
> 
> >                           Immediately after it?
> > If not, where after it?
> 
> Yes, immediately or directly after it.  Perhaps adding one of those
> words would be acceptable.

Quite complicated.  Maybe should include an illustration.

  However, if you try to insert a closing delimiter between
  a matching pair of the same type, which are not separated
  or are separated only by whitespace, then there's no
  insertion and point is moved immediately after the closing
  delimiter.  For example, if you try to insert `)' at | then
  for `(|)' the result is `()|', and for `(    |  )' the
  result is `(      )|'.

Or maybe:

  However, if only whitespace (or nothing) is delimited, and
  you try to insert a closing delimiter of the same type
  between the delimiters, it's not inserted.  Instead, point
  is put immediately after the closing delimiter.  For example... 

But a reasonable question is why?  Why is that the chosen
behavior?  And why is delimited whitespace special here?
Explaining _why_ would itself take readers a long way toward
understanding _what_ the behavior is.  IOW, start by saying
what the problem is that this behavior tries to solve.

> > And please change the name of the node (the name
> > used by `g' etc.) from just "Matching" to something
> > else, preferably something that indicates it's
> > about matching delimiters.  That too is part of
> > this bug/enhancement request.
> 
> Making such a change is the maintainers' prerogative; the (cogent)
> argument against such a change is that, being a long-standing node name,
> changing it could well break references in external info files or other
> formats derived from them, like web pages.

If that's a concern then the old node name could presumably
still be respected for a while, as an (unadvertised) alias.

But yes, it would have been better to think more about the
node name at the outset.  The key terms in this are "paired"
and "delimiters".

There can be different ways that a pair of delimiters match
each other.  What's important is that there's some way that
they're defined as a matching _pair_.

And an ordered pair, at that.  `(' matches `)' that follows
it, but it doesn't match `)' that precedes it, etc.  (Dunno
what the case is for bidirectional text.)

Matching isn't even a great term to introduce for this, IMO.
In one sense `)' matches `)'; in another sense `)' matches `('.

> > Thanks for working on this.  And thank you for
> > providing the proposed text (for the part concerning
> > this bug).  When reviewing doc changes we shouldn't
> > have to decipher a diff or apply it.
> 
> Since dealing with diffs is standard fare here, and they are generally
> required by those who decide whether to accept the changes, and those
> who install the changes to the source repository, I don't think it's
> unduly burdensome on other interested participants to expect them to be
> able to deal with them too.

I do think so.  Ordinary users of all stripes are encouraged
to file bug reports and enhancement requests.  They shouldn't
need to access texi sources or be familiar with diffs or
patches.  Especially for doc changes.  Just tossing them a
patch discourages such participation.

I write technical docs.  There's no way we would expect our
reviewers to fiddle with source input (XML) to the doc process
or diffs/patches, even though they're all competent software
people.  Reviewing doc is about reading text, and preferably
doing so in context.

Think about this: Surely you didn't _write_ your improved
text in the form of a diff.  You wrote it as ordinary text,
and you probably did so reading the surrounding context as
ordinary text.  And even if you didn't, mere mortals would.