Subject: Re: bug#67621: [PATCH] documentation for ert-font-lock

From: Michael Albinus <[email-masked]>
Date: Mon, 04 Dec 2023 14:01:40 +0100

Vladimir Kazanov <[email-masked]> writes:

> Hi team,

Hi Vladimir,

> As (reasonably) requested in emacs-devel@ [1], sending a patch that
> adds ert-font-lock to NEWS and expands the ERT manual.

Thanks. Just some few comments.

> --- a/doc/misc/ert.texi
> +++ b/doc/misc/ert.texi
> @@ -526,6 +526,7 @@ How to Write Tests
>  * Tests and Their Environment:: Don't depend on customizations; no side effects.
>  * Useful Techniques::           Some examples.
>  * erts files::                  Files containing many buffer tests.
> +* Syntax Highlighting Tests:: Tests for face assignment.
>  @end menu

Align the entries. "Tests" must be at the same position as "Files".

> +Syntax highlighting is normally provided by the Font Lock minor mode
> +that assigns face properties to parts of the buffer. The

Use two spaces at sentence end. This is for everything in ert.texi and
NEWS.

> +Test assertion parser extracts tests from comment-only lines. Every
> +comment assertion line starts either with a caret ('^') or an arrow
> +('<-'). A caret/arrow should be followed immedately by the name of a
> +face to be checked.

Use @samp here, like (@samp{^}) and (@samp{<-}) .

> +i.e. @code{:tag} and @code{:expected-result}.

Please write i.e.,

> --- a/etc/NEWS
> +++ b/etc/NEWS
> +** ERT
> +
> ++++
> +*** Syntax highlighting unit testing support

This needs a trailing period.

> +An ERT extension ('ert-font-lock') now provides support for face
> +assignment unit testing.

Since it doesn't tell details, you might refer to the manual. like

--8<---------------cut here---------------start------------->8---
An ERT extension ('ert-font-lock') now provides support for face
assignment unit testing.  For more information, see the "(ert) Syntax
Highlighting Tests" node in the ERT manual.
--8<---------------cut here---------------end--------------->8---

> Regards,
> Vladimir Kazanov

Best regards, Michael.