From 306263da43dd20e22f48027b9032e39f1f2f9492 Mon Sep 17 00:00:00 2001
From: nnposter <nnposter@e0a8ed71-7df4-0310-8962-fdc924857419>
Date: Tue, 2 Dec 2025 22:48:31 +0000
Subject: [PATCH] Explain the effect of arguments that are not script-specific.
 Close #3223, close #3221, fix #3211

---
 docs/refguide.xml | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/docs/refguide.xml b/docs/refguide.xml
index d0d6ae09a..884b23638 100644
--- a/docs/refguide.xml
+++ b/docs/refguide.xml
@@ -2480,9 +2480,20 @@ escapes a quote. A backslash is only used to escape quotation marks in this
 special case; in all other cases a backslash is interpreted literally. Values
 may also be tables enclosed in <literal>{}</literal>, just as in Lua. A table
 may contain simple string values or more name-value pairs, including nested
-tables.  Many scripts qualify their arguments with the script name, as in <literal>xmpp-info.server_name</literal>.  You may use that full qualified version to affect just the specified script, or you may pass the unqualified version (<literal>server_name</literal> in this case) to affect all scripts using that argument name.  A script will first check for its fully qualified argument name (the name specified in its documentation) before it accepts an unqualified argument name.  A complex example of script arguments is
-<option>--script-args 'user=foo,pass=",{}=bar",whois={whodb=nofollow+ripe},xmpp-info.server_name=localhost'</option>.  The online NSE Documentation Portal at <ulink url="https://nmap.org/nsedoc/"/>
-lists the arguments that each script accepts.
+tables.  A complex example of script arguments is
+<option>--script-args 'user=foo,pass=",{}=bar",whois={whodb=nofollow+ripe},xmpp-info.server_name=localhost'</option>.
+Many scripts qualify their arguments with the script name, as in
+<literal>xmpp-info.server_name</literal>.  A script will first check for its
+fully qualified argument name (the name specified in its documentation) before
+it accepts an unqualified argument name (<literal>server_name</literal> in this
+case).  Some arguments are not specific to one script. They typically effect
+behavior of a library and therefore potentially all the scripts that use the
+library.  (One such example is <literal>http.useragent</literal>, which sets
+the default HTTP User-Agent header for every web request, regardless which
+script sends it.)  It is not possible for the exact same argument to be given
+different values for diferent scripts.  The online NSE Documentation Portal at
+<ulink url="https://nmap.org/nsedoc/"/> lists the arguments that each script
+accepts.
 </para>
 </listitem>
 </varlistentry>