[groff] 09/09: groff_man_style(7): Add more man.local advice.

[G. Branden Robinson]

gbranden pushed a commit to branch master
in repository groff.

commit 499b9f21efd10eb57903cd0a1ea229ef7da23834
Author: G. Branden Robinson <g.branden.robinson@gmail.com>
AuthorDate: Thu Aug 20 23:45:44 2020 +1000

    groff_man_style(7): Add more man.local advice.
    
    * tmac/groff_man.7.man.in (Files) <man.local> [style]: Add suggestion
      for management of man page rendering preferences on a user-specific,
      rather than site-specific, basis.  Just an example because there are
      some impediments to implementation.
    
      (1) It'd be nice if we had a variant of .so that did not warn on
          failure to open a file if the error is ENOENT.
      (2) man-db's man(1) would need to have its sandbox to allow
          $HOME/.man.local (or the equivalent) to be opened.
---
 tmac/groff_man.7.man.in | 34 +++++++++++++++++++++++++++++++++-
 1 file changed, 33 insertions(+), 1 deletion(-)

diff --git a/tmac/groff_man.7.man.in b/tmac/groff_man.7.man.in
index 6c281b9..360b952 100644
--- a/tmac/groff_man.7.man.in
+++ b/tmac/groff_man.7.man.in
@@ -3158,7 +3158,7 @@ implementations that may give up their scan for indexing 
material early.
 .
 .
 .TP
-.I \%@LOCALMACRODIR@/\:man.local
+.I \%@LOCALMACRODIR@/\:\%man.local
 Put local changes and customizations into this file.
 _ifstyle()dnl
 .
@@ -3178,6 +3178,38 @@ _ifstyle()dnl
 .RE
 .
 .
+.IP
+On multi-user systems,
+it is more considerate to users whose preferences may differ from the
+administrator's to be less aggressive with such settings,
+or to permit their override with a user-specific
+.I man.local
+file.
+.
+One way to achieve the latter is by placing the following at the end of
+.IR @LOCALMACRODIR@/\:\%.man.local .
+.
+.RS
+.RS
+.EX
+\&.so \eV[HOME]/.man.local
+.EE
+.RE
+.
+Note that the above request will produce a warning if
+.RI \%$HOME /\:\%man.local
+does not exist;
+you may wish to `include' one in
+.I \%/\:\%etc/\:\%skel
+or an equivalent account configuration system.
+.
+Furthermore,
+a security-sandboxed
+.IR man (1) \" such as man-db 2.8.5
+program may lack permission to open the file.
+.RE
+.
+.
 .\" ====================================================================
 .SH Notes
 .\" ====================================================================