From: Paul Fox <pgf@foxharp.boston.ma.us>
Date: Tue, 22 Apr 2014 16:23:01 +0000 (-0400)
Subject: man pages: clarify how profiles entries are searched
X-Git-Url: https://diplodocus.org/git/nmh/commitdiff_plain/34b792b0953b6104cc21eb88c2e34f3cc53f71b6?ds=inline

man pages: clarify how profiles entries are searched

(cherry picked from commit d7b59eb68168ead6a81ca40cf8aa5cccbf86c649)
---

diff --git a/man/mh-profile.man b/man/mh-profile.man
index cb85747f..f34ac4ba 100644
--- a/man/mh-profile.man
+++ b/man/mh-profile.man
@@ -671,6 +671,27 @@ This is the program used by
 .B whatnow
 to determine to whom a message would be sent.
 .RE
+.SS "Profile Lookup"
+Some
+.B nmh
+programs will look in more than just the user's 
+.I \&.mh\(ruprofile
+for profile entries.  In particular, 
+.BR mhbuild ,
+.BR mhshow ,
+.BR mhstore ,
+and
+.BR mhn 
+will also all look in a file specified by a program-specific
+environment variable (see below), and after that in 
+the system-installed profile (%etcdir%/mhn.defaults).  (The
+.B mhfixmsg
+program is similar, but doesn't consult an environment variable.)
+The first match found for a particular component will be used,
+allowing user-supplied entries to override those that are system-supplied.
+A profile component with a blank value field will "hide" any later
+occurrences of the component, and will make the entry appear to be
+absent.
 .SS "Environment Variables"
 The operation of
 .B nmh
diff --git a/man/mhbuild.man b/man/mhbuild.man
index dd5f11c8..4a0e8730 100644
--- a/man/mhbuild.man
+++ b/man/mhbuild.man
@@ -644,15 +644,17 @@ definitions useful for that machine.
 .PP
 Finally,
 .B mhbuild
-will attempt to consult a global
-.B mhbuild
-user profile, e.g.,
+will attempt to consult
 .PP
 .RS 5
 %etcdir%/mhn.defaults
 .RE
 .PP
 if it exists.
+.PP
+See "Profile Lookup" in
+.IR mh-profile (5)
+for the profile search order, and for how duplicate entries are treated.
 .SS "Syntax of Composition Files"
 The following is the formal syntax of a
 .B mhbuild
diff --git a/man/mhshow.man b/man/mhshow.man
index abfcc227..d2209143 100644
--- a/man/mhshow.man
+++ b/man/mhshow.man
@@ -584,8 +584,7 @@ mhshow-show-<type>
 .PP
 need be present in this additional profile. Finally,
 .B mhshow
-will attempt to consult one other additional user profile,
-e.g.,
+will attempt to consult
 .PP
 .RS 5
 %etcdir%/mhn.defaults
@@ -595,6 +594,9 @@ which is created automatically during
 .B nmh
 installation.
 .PP
+See "Profile Lookup" in
+.IR mh-profile (5)
+for the profile search order, and for how duplicate entries are treated.
 .SS Content\-Type Marker
 If
 .B mhshow
diff --git a/man/mhstore.man b/man/mhstore.man
index 6fb6008b..abb6881b 100644
--- a/man/mhstore.man
+++ b/man/mhstore.man
@@ -519,8 +519,7 @@ particular machine, this environment variable should be set to
 refer to a file containing definitions useful for that machine.
 Finally,
 .B mhstore
-will attempt to consult one other additional
-user profile, e.g.,
+will attempt to consult
 .PP
 .RS 5
 %etcdir%/mhn.defaults
@@ -529,6 +528,10 @@ user profile, e.g.,
 which is created automatically during
 .B nmh
 installation.
+.PP
+See "Profile Lookup" in
+.IR mh-profile (5)
+for the profile search order, and for how duplicate entries are treated.
 .SH FILES
 .B mhstore
 looks for additional profile files in multiple locations: absolute