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 cb85747..f34ac4b 100644 (file)
--- 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
 .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
 .SS "Environment Variables"
 The operation of
 .B nmh

diff --git a/man/mhbuild.man b/man/mhbuild.man
index dd5f11c..4a0e873 100644 (file)
--- a/man/mhbuild.man
+++ b/man/mhbuild.man
@@ -644,15 +644,17 @@ definitions useful for that machine.
 .PP
 Finally,
 .B mhbuild
 .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
 .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
 .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 abfcc22..d220914 100644 (file)
--- 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
 .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
 .PP
 .RS 5
 %etcdir%/mhn.defaults


@@ -595,6 +594,9 @@ which is created automatically during
 .B nmh
 installation.
 .PP
 .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
 .SS Content\-Type Marker
 If
 .B mhshow

diff --git a/man/mhstore.man b/man/mhstore.man
index 6fb6008..abb6881 100644 (file)
--- 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
 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
 .PP
 .RS 5
 %etcdir%/mhn.defaults


@@ -529,6 +528,10 @@ user profile, e.g.,
 which is created automatically during
 .B nmh
 installation.
 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
 .SH FILES
 .B mhstore
 looks for additional profile files in multiple locations: absolute