* Present what the document author needs to know before what the source diver needs to know. * Favor active voice over passive. * (doc/groff.texi.in): Add references. --- doc/groff.texi.in | 67 +++++++++++++++++++++++++++++-------------- tmac/groff_ms.7.man | 70 +++++++++++++++++++++++++++------------------ 2 files changed, 88 insertions(+), 49 deletions(-)
diff --git a/doc/groff.texi.in b/doc/groff.texi.in
index f2cd91695..3509a47dc 100644
--- a/doc/groff.texi.in
+++ b/doc/groff.texi.in
@@ -464,7 +464,7 @@
@title groff
@subtitle The GNU implementation of @code{troff}
@subtitle version @VERSION@
-@subtitle June 2025
+@subtitle July 2025
@author Trent@tie{}A.@: Fisher
@author Werner Lemberg
@author G.@tie{}Branden Robinson
@@ -5025,11 +5025,45 @@ @node ms Naming Conventions
@cindex naming conventions, @file{ms} macros
The following conventions are used for names of macros, strings, and
-registers. External names available to documents that use the
-@code{groff} @file{ms} macros contain only uppercase letters and digits.
+registers.
+External names available to documents that use the
+@code{groff} @file{ms}
+macros contain only uppercase letters and digits.
+The package reserves the following identifiers for internal use.
-Internally, the macros are divided into modules. Conventions for
-identifier names are as follows.
+@itemize @bullet
+@item
+those containing the characters
+@code{*},
+@code{@@},
+and@tie{}@code{:};
+and
+
+@item
+those containing only uppercase letters and digits.
+@end itemize
+
+When selecting a name for your document's own macros,
+strings,
+and
+registers,
+avoid those reserved by
+@code{groff} @file{ms}
+and those defined by
+GNU
+@command{troff} @c GNU
+see
+@ref{Macro Index},
+@ref{String Index},
+and
+@ref{Register Index},
+or
+@cite{groff_char@r{(7)}}
+for complete lists thereof.
+
+@code{groff} @file{ms}
+organizes most of its internal names into modules.
+The naming convenion is as follows.
@itemize @bullet
@item
@@ -5042,29 +5076,20 @@ @node ms Naming Conventions
@item
Names associated with a particular environment are of the form
-@var{environment}@code{:}@var{name}; these are used only within the
-@code{par} module.
+@var{environment}@code{:}@var{name};
+these are used only within the
+@code{par}
+module.
@item
-@var{name} does not have a module prefix.
+@var{name}
+does not have a module prefix.
@item
-Constructed names used to implement arrays are of the form
+Names constructed to implement arrays are of the form
@var{array}@code{!}@var{index}.
@end itemize
-Thus the @code{groff} @file{ms} macros reserve the following
-identifiers:
-
-@itemize @bullet
-@item
-those containing the characters @code{*}, @code{@@}, and@tie{}@code{:},
-and
-
-@item
-those containing only uppercase letters and digits.
-@end itemize
-
@c =====================================================================
@c =====================================================================
diff --git a/tmac/groff_ms.7.man b/tmac/groff_ms.7.man
index 096e237fa..717a3e4e3 100644
--- a/tmac/groff_ms.7.man
+++ b/tmac/groff_ms.7.man
@@ -10,7 +10,7 @@ .SH Name
.\" Legal Terms
.\" ====================================================================
.\"
-.\" Copyright (C) 1989-2024 Free Software Foundation, Inc.
+.\" Copyright (C) 1989-2025 Free Software Foundation, Inc.
.\"
.\" Permission is granted to make and distribute verbatim copies of this
.\" manual provided the copyright notice and this permission notice are
@@ -2770,31 +2770,60 @@ .SS "Berkeley \f[I]ms\f[] accent mark and glyph strings"
.SH "Naming conventions"
.\" ====================================================================
.
-The following conventions are used for names of macros,
-strings,
-and registers.
-.
External names available to documents that use the
-.I groff ms
+.I "groff ms"
macros contain only uppercase letters and digits.
.
+The package reserves for internal use the following identifiers:
.
-.LP
-Internally,
-the macros are divided into modules.
.
-Conventions for identifier names are as follows.
+.IP \[bu] 3n
+those containing the characters
+.BR * ,
+.BR @ ,
+and\~\c
+.BR : ;
+and
+.
+.
+.IP \[bu]
+those containing only uppercase letters and digits.
+.
+.
+.P
+When selecting a name for your document's own macros,
+strings,
+and
+registers,
+avoid those reserved by
+.I "groff ms"
+and those defined by
+GNU
+.IR troff ;\" GNU
+see
+.MR groff @MAN7EXT@
+for complete lists thereof.
+.
+.
+.P
+.I "groff ms"
+organizes most of its internal names into modules.
+.
+The naming convenion is as follows.
+.
.
.IP \[bu] 3n
Names used only within one module are of the form
.IB \%module * name\c
\&.
.
+.
.IP \[bu]
Names used outside the module in which they are defined are of the form
.IB \%module @ name\c
\&.
.
+.
.IP \[bu]
Names associated with a particular environment are of the form
.IB \%environment : name\c
@@ -2803,33 +2832,18 @@ .SH "Naming conventions"
.B par
module.
.
+.
.IP \[bu]
.I name
does not have a module prefix.
.
+.
.IP \[bu]
-Constructed names used to implement arrays are of the form
+Names constructed to implement arrays are of the form
.IB \%array ! index\c
\&.
.
.
-.PP
-Thus the
-.I groff ms
-macros reserve the following identifiers:
-.
-.IP \[bu] 3n
-those containing the characters
-.BR * ,
-.BR @ ,
-and\~\c
-.BR : ,
-and
-.
-.IP \[bu]
-those containing only uppercase letters and digits.
-.
-.
.\" ====================================================================
.SH Files
.\" ====================================================================
--
2.30.2
signature.asc
Description: PGP signature
_______________________________________________ groff-commit mailing list groff-commit@gnu.org https://lists.gnu.org/mailman/listinfo/groff-commit
