Subject: bug#28777: Clarifying the temporary documentation update marks in etc/NEWS

From: Phil Sainty <[email-masked]>
Date: Tue, 10 Oct 2017 23:16:16 +1300

On 10/10/17 04:32, Eli Zaretskii wrote:
>> +++
>
> This indication means the change is already described in the manual.
> But since the patch doesn't include any doc changes except NEWS, I
> presume you decided this shouldn't be mentioned in the manual (and
> I agree), so the indication should be "---" instead.

I conclude that I'm a little confused about the description of the
two marks.  I had intentionally used "+++" because "all necessary
documentation updates are complete" (but I can see now that this
could make "---" redundant, unless both marks were used together).

etc/NEWS says:

> +++ indicates that all necessary documentation updates are complete.
>     (This means all relevant manuals in doc/ AND lisp doc-strings.)
> --- means no change in the manuals is needed.

If I now understand correctly, "---" means that all relevant lisp doc
strings have been updated, and "+++" means the same thing and that
there have additionally been updates to the manual?

If so, then I think this text could be clarified:

> +++ indicates that all necessary documentation updates are complete.
>     (This means all relevant manuals in doc/ AND lisp doc-strings.)
> --- indicates that all lisp doc-string updates are complete and
>     that no change in the manuals is needed.

-Phil