[groff] 14/21: troff(1): Revise.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 9d5a78631de107d08a83012ee00078530f42ee36
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Sun Jun 6 23:42:45 2021 +1000

    troff(1): Revise.
    
    * (Options) <-F, -m, -M, -U>: Revise descriptions for tightness and
      precision; remove duplication of details of font and macro search path
      issues.
    * (Environment): Add lead paragraph discussing path separator character
      portability issue.
      <GROFF_FONT_PATH, GROFF_TMAC_PATH>: Supply details.
      <GROFF_TYPESETTER>: Clarify.
---
 src/roff/troff/troff.1.man | 114 ++++++++++++++++++++++++++++-----------------
 1 file changed, 70 insertions(+), 44 deletions(-)

diff --git a/src/roff/troff/troff.1.man b/src/roff/troff/troff.1.man
index c549335..c44227f 100644
--- a/src/roff/troff/troff.1.man
+++ b/src/roff/troff/troff.1.man
@@ -203,19 +203,19 @@ Use
 .I fam
 as the default font family.
 .
+.
 .TP
 .BI \-F dir
-Search in directory (or directory path)
+Search in directory
 .I dir
-for subdirectories
-.IR dev name
-.RI ( name
-is the name of the device) and there for the
-.I DESC
-file and font files.
+for the selected output device's directory of device and font
+description files.
+.
+See the description of
+.I GROFF_FONT_PATH
+in section \[lq]Environment\[rq] below for the default search locations
+and ordering.
 .
-.I dir
-is scanned before all other font directories.
 .
 .TP
 .B \-i
@@ -264,31 +264,36 @@ file name.
 .
 .TP
 .BI \-m name
-Read in the file
-.RI name .tmac .
+Process
+.RI name .tmac
+before any input files.
 .
-If it isn't found, try
+If
+.RI name .tmac
+is not found,
 .IR tmac. name
-instead.
+is attempted.
 .
-It will be first searched for in directories given with the
-.B \-M
-command-line option, then in directories given in the
+.I name
+(in both arrangements)
+is presumed to be a macro file;
+see the description of
 .I GROFF_TMAC_PATH
-environment variable, then in the current directory (only if in unsafe
-mode), the home directory,
-.IR @SYSTEMMACRODIR@ ,
-.IR @LOCALMACRODIR@ ,
-and
-.IR @MACRODIR@ .
+in section \[lq]Environment\[rq] below for the default search locations
+and ordering.
+.
 .
 .TP
 .BI \-M dir
-Search directory (or directory path)
+Search directory
 .I dir
 for macro files.
 .
-This is scanned before all other macro directories.
+See the description of
+.I GROFF_TMAC_PATH
+in section \[lq]Environment\[rq] below for the default search locations
+and ordering.
+.
 .
 .TP
 .BI \-n num
@@ -356,8 +361,9 @@ for a more detailed description.
 .
 .TP
 .B \-U
-Unsafe mode;
-enables the
+Operate in
+.IR "unsafe mode" ;
+enabling the
 .BR .open ,
 .BR .opena ,
 .BR .pso ,
@@ -369,7 +375,7 @@ requests.
 For security reasons,
 these potentially dangerous requests are disabled otherwise.
 .
-It will also add the current directory to the macro search path;
+It also adds the current directory to the macro search path;
 see
 .B \-m
 above.
@@ -632,41 +638,61 @@ All warnings.
 .SH Environment
 .\" ====================================================================
 .
+.I GROFF_FONT_PATH
+and
+.I GROFF_TMAC_PATH
+each accept a search path of directories;
+that is,
+a list of directory names separated by the system's path component
+separator character.
+.
+On Unix systems,
+this character is a colon (:);
+on Windows systems,
+it is a semicolon (;).
+.
+.
 .TP
 .I GROFF_FONT_PATH
 A list of directories in which to seek the selected output device's
 directory of device and font description files.
 .
 .I \%@g@troff
-will scan directories given in the
+will scan directories given as arguments to any specified
 .B \-F
-option before these,
-and in standard directories
-.RI ( @LOCALFONTDIR@ ,
-.IR @FONTDIR@ ,
-.IR @LEGACYFONTDIR@ )
-after these.
+options before these,
+then in a site-specific directory
+.RI ( @LOCALFONTDIR@ ),
+a standard location
+.RI ( @FONTDIR@ ),
+and a compatibility directory
+.RI ( @LEGACYFONTDIR@ )
+after them.
 .
 .
 .TP
 .I GROFF_TMAC_PATH
-A colon separated list of directories in which to search for
-macro files.
+A list of directories in which to search for macro files.
 .
 .I \%@g@troff
-will scan directories given in the
+will scan directories given as arguments to any specified
 .B \-M
-option before these, and in standard directories (current directory if
-in unsafe mode, home directory,
-.IR @SYSTEMMACRODIR@ ,
-.IR @LOCALMACRODIR@ ,
-.IR @MACRODIR@ )
-after these.
+options before these,
+then the current directory
+(only if in unsafe mode),
+the user's home directory,
+a platform-specific directory
+.RI ( @SYSTEMMACRODIR@ ),
+a site-specific directory
+.RI ( @LOCALMACRODIR@ ),
+and a standard location
+.RI ( @MACRODIR@ )
+after them.
 .
 .
 .TP
 .I GROFF_TYPESETTER
-Default device.
+Default output device.
 .
 .
 .TP