[groff] 15/21: [docs]: Revise discussion of unsafe mode.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 18acdc214a9473be8bee3d0bb57e7de4030003d4
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Mon Jun 7 00:30:33 2021 +1000

    [docs]: Revise discussion of unsafe mode.
    
    * doc/groff.texi (Groff Options):
    * src/roff/troff/troff.1.man (Options): Parallelize presentation of -U
      option.  Provide motivation in our Texinfo manual, and explain what
      the risk is instead of saying, vaguely, "potentially dangerous".
    
    * doc/groff_diff.7.man (Restricted requests): Add new section.
    
    Prompted by an observation by Dave Kemper.
---
 doc/groff.texi             |  8 ++++++--
 man/groff_diff.7.man       | 27 +++++++++++++++++++++++++--
 src/roff/troff/troff.1.man | 19 ++++++++++---------
 3 files changed, 41 insertions(+), 13 deletions(-)

diff --git a/doc/groff.texi b/doc/groff.texi
index 2d51f91..d45dc61 100644
--- a/doc/groff.texi
+++ b/doc/groff.texi
@@ -1294,8 +1294,12 @@ and Font Files}.)  This can be overridden with the 
@option{-X} option.
 @item -U
 @cindex mode, unsafe
 @cindex unsafe mode
-Unsafe mode.  This enables the @code{open}, @code{opena}, @code{pso},
-@code{sy}, and @code{pi} requests.
+Operate in @dfn{unsafe mode}, which enables the @code{open},
+@code{opena}, @code{pi}, @code{pso}, and @code{sy} requests.  These
+requests are disabled by default because they allow an untrusted input
+document to write to arbitrary file names and run arbitrary commands.
+This option also adds the current directory to the macro search path;
+see the @option{-m} option above.
 
 @item -w@var{name}
 Enable warning @var{name}.  Available warnings are described in
diff --git a/man/groff_diff.7.man b/man/groff_diff.7.man
index 35f0a46..f539b24 100644
--- a/man/groff_diff.7.man
+++ b/man/groff_diff.7.man
@@ -935,6 +935,26 @@ inter-word space when a line is adjusted.
 .
 .
 .\" ====================================================================
+.SS "Restricted requests"
+.\" ====================================================================
+.
+To mitigate risks from untrusted input documents,
+the
+.BR open ,
+.BR opena ,
+.BR pi ,
+.BR pso ,
+and
+.B sy
+requests are disabled by default.
+.
+.IR \%@g@troff (@MAN1EXT@)'s
+.B \-U
+option enables the formatter's \[lq]unsafe mode\[rq],
+restoring their function.
+.
+.
+.\" ====================================================================
 .SS "New requests"
 .\" ====================================================================
 .
@@ -3875,13 +3895,16 @@ Useful in conjunction with the
 .B \[rs]n[.ne]
 register.
 .
+.
 .TP
 .B \[rs]n[.U]
-Set to\~1 if in safer mode and to\~0 if in unsafe mode (as given with
-the
+Set to\~1 if in safer mode and to\~0 if in unsafe mode
+(as determined by
+.IR \%@g@troff 's
 .B \-U
 command-line option).
 .
+.
 .TP
 .B \[rs]n[.vpt]
 1\~if vertical position traps are enabled, 0\~otherwise.
diff --git a/src/roff/troff/troff.1.man b/src/roff/troff/troff.1.man
index c44227f..cd0ead4 100644
--- a/src/roff/troff/troff.1.man
+++ b/src/roff/troff/troff.1.man
@@ -362,23 +362,24 @@ for a more detailed description.
 .TP
 .B \-U
 Operate in
-.IR "unsafe mode" ;
-enabling the
+.IR "unsafe mode" ,
+which enables the
 .BR .open ,
 .BR .opena ,
+.BR .pi ,
 .BR .pso ,
-.BR .sy ,
 and
-.B .pi
+.B .sy
 requests.
 .
-For security reasons,
-these potentially dangerous requests are disabled otherwise.
+These requests are disabled by default because they allow an untrusted
+input document to write to arbitrary file names and run arbitrary
+commands.
 .
-It also adds the current directory to the macro search path;
-see
+This option also adds the current directory to the macro search path;
+see the
 .B \-m
-above.
+option above.
 .
 .
 .TP