bug#36448: 26.2; doc string of `highlight-lines-matching-regexp'

bug#36448: 26.2; doc string of `highlight-lines-matching-regexp'

[Drew Adams]

This part of the doc string is not so good:

  Set face of all lines containing a match of REGEXP to FACE.

That's not what happens - "set" is the wrong verb here (face attributes
are set, but not the displayed face as a whole).

For example, if `font-lock-mode' is enabled and the command highlights a
line that contains text already highlighted by font-lock (e.g. with a
face foreground attribute) then the `highlight-lines-matching-regexp'
highlighting adds its face to the `face' spec for that already
highlighted text.  It does not replace face attributes that are already
set there.

The doc string should just say something similar to what (elisp)
`Highlight Interactively' says:

  Highlight entire lines containing a match for REGEXP, using face
  FACE ('highlight-lines-matching-regexp').

Highlighting "using" FACE is less definitive (more vague) than "setting"
the face to FACE.

If the doc string wants to go into more detail then it can say that FACE
is _added_ to faces already present, or that its attributes are added
merged with those already present.




In GNU Emacs 26.2 (build 1, x86_64-w64-mingw32)
 of 2019-04-13
Repository revision: fd1b34bfba8f3f6298df47c8e10b61530426f749
Windowing system distributor `Microsoft Corp.', version 10.0.17134
Configured using:
 `configure --without-dbus --host=x86_64-w64-mingw32
 --without-compress-install 'CFLAGS=-O2 -static -g3''

bug#36448: 26.2; doc string of `highlight-lines-matching-regexp'

[Eli Zaretskii]

> Date: Sun, 30 Jun 2019 13:40:10 -0700 (PDT)
> From: Drew Adams <drew.adams@oracle.com>
> 
> This part of the doc string is not so good:
> 
>   Set face of all lines containing a match of REGEXP to FACE.
> 
> That's not what happens - "set" is the wrong verb here (face attributes
> are set, but not the displayed face as a whole).

Thanks, fixed.