git: 237cc7b408dd - main - style.Makefile: document the style for lists

The branch main has been updated by obrien:

URL: https://cgit.FreeBSD.org/src/commit/?id=237cc7b408dd8d0c6eb4af6ab796b8d4b750c9ba

commit 237cc7b408dd8d0c6eb4af6ab796b8d4b750c9ba
Author:     David E. O'Brien <obrien@FreeBSD.org>
AuthorDate: 2025-10-29 07:59:18 +0000
Commit:     David E. O'Brien <obrien@FreeBSD.org>
CommitDate: 2025-10-30 03:41:59 +0000

    style.Makefile: document the style for lists
    
    Reviewed by:    sjg
    Differential Revision:  https://reviews.freebsd.org/D53429
---
 share/man/man5/style.Makefile.5 | 24 +++++++++++++++++++-----
 1 file changed, 19 insertions(+), 5 deletions(-)

diff --git a/share/man/man5/style.Makefile.5 b/share/man/man5/style.Makefile.5
index fe8754924575..9a2f1b069d99 100644
--- a/share/man/man5/style.Makefile.5
+++ b/share/man/man5/style.Makefile.5
@@ -1,7 +1,7 @@
 .\"
 .\" SPDX-License-Identifier: BSD-3-Clause
 .\"
-.\" Copyright (c) 2002-2003, 2023 David O'Brien <obrien@FreeBSD.org>
+.\" Copyright (c) 2002-2003, 2023, 2025 David O'Brien <deo@NUXI.org>
 .\" All rights reserved.
 .\"
 .\" Redistribution and use in source and binary forms, with or without
@@ -28,7 +28,7 @@
 .\" OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
 .\" SUCH DAMAGE.
 .\"
-.Dd July 17, 2023
+.Dd October 29, 2025
 .Dt STYLE.MAKEFILE 5
 .Os
 .Sh NAME
@@ -179,6 +179,21 @@ settings between the
 and
 .Fl I Ns 's.
 .It
+Lists that span more than one line should be formatted as follows:
+.Bd -literal -offset indent
+SRCS+=<SP>\\
+<TAB>main.c<SP>\\
+<TAB>trace.c<SP>\\
+<TAB>zoo.c \\
+\&
+.Ed
+Specifically, the last item in the list should have a trailing '\\'.
+This is to avoid causing a "false diff" or "false blame" when
+a new item is appended at the end.
+In general the list should be English language alphabetized.
+A list of libraries or header inclusion paths are notable exceptions
+if needed for proper building.
+.It
 Do not use GCCisms (such as
 .Fl g
 and
@@ -233,9 +248,6 @@ For variables that are only checked with
 .Fn defined ,
 do not provide any fake value.
 .El
-.Pp
-The desire to express a logical grouping often means not obeying some of the
-above.
 .Sh EXAMPLES
 The simplest program
 .Pa Makefile
@@ -270,5 +282,7 @@ manual page and first appeared in
 .An David O'Brien Aq deo@NUXI.org
 .Sh BUGS
 There are few hard and fast style rules here.
+The desire to express a logical grouping sometimes means not obeying some of the
+above.
 The style of many things is too dependent on the context of the whole makefile,
 or the lines surrounding it.