From 88f68e8afcfd3de40da9d1d077330cc0828aeb98 Mon Sep 17 00:00:00 2001
From: "Steffen (Daode) Nurpmeso" <steffen@sdaoden.eu>
Date: Sat, 19 Aug 2017 23:53:53 +0200
Subject: [PATCH] nail.1: fix `source' docu; mention `source' early!

---
 nail.1 | 41 +++++++++++++++++++++++++++--------------
 1 file changed, 27 insertions(+), 14 deletions(-)

diff --git a/nail.1 b/nail.1
index 2b768f44..c8a3da10 100644
--- a/nail.1
+++ b/nail.1
@@ -176,29 +176,32 @@ non-interactive scripting capabilities.
 .It Fl \&: Ar spec
 Explicitly control which of the
 .Sx "Resource files"
-shall be loaded: if the letter
+shall be
+.Ic source Ns
+d (loaded): if the letter
 .Ql s
 is (case-insensitively) part of the
 .Ar spec
 then the system wide
 .Pa \*(UR
-is loaded, likewise the letter
+is sourced, likewise the letter
 .Ql u
-controls loading of the user's personal
+controls sourcing of the user's personal
 .Pa \*(ur
 file, whereas the letters
 .Ql -
 and
 .Ql /
-explicitly forbid loading of any resource files.
-This option should be used by scripts: to avoid environmental noise they
-should
+explicitly forbid sourcing of any resource files.
+Scripts should use this option: to avoid environmental noise they should
 .Dq detach
-from any configuration files and create a script-local environment,
-explicitly setting any of the desired
+from any configuration and create a script-specific environment, setting
+any of the desired
 .Sx "INTERNAL VARIABLES"
 via
-.Fl S .
+.Fl S
+and running configurating commands via
+.Fl X .
 This option overrides
 .Fl n .
 .
@@ -795,11 +798,15 @@ to include the message that is being responded to when
 ing.
 .
 .Pp
-It should be remarked that the file mode creation mask can be
-explicitly managed via the variable
+Some random remarks.
+The file mode creation mask can be explicitly managed via the variable
 .Va umask .
-\*(UA will not follow symbolic links when opening files for writing,
-sufficient system support provided.
+Sufficient system support provided symbolic links will not be followed
+when files are opened for writing.
+Files and shell pipe output can be
+.Ic source Ns
+d for evaluation, also during startup from within the
+.Sx "Resource files" .
 .\" }}}
 .
 .\" .Ss "On sending mail, and non-interactive mode" {{{
@@ -6266,7 +6273,13 @@ If the given expanded argument ends with a vertical bar
 .Ql |
 then the argument will instead be interpreted as a shell command and
 \*(UA will read the output generated by it.
-Interpretation of commands read is stopped when an error is encountered.
+Dependent on the settings of
+.Va posix
+and
+.Va errexit ,
+and also dependent on whether the command modifier
+.Cm ignerr
+had been used, encountering errors will stop sourcing of the given input.
 \*(ID Note that
 .Ic \&\&source
 cannot be used from within macros that execute as
-- 
2.11.4.GIT