[X2Go-Commits] [x2goserver] 50/99: x2goserver/lib/x2goupdateoptionsstring: better document end-of-options terminator and highlight its importance.

[git-admin at x2go.org]

This is an automated email from the git hooks/post-receive script.

x2go pushed a commit to branch master
in repository x2goserver.

commit 85599d36afb19aed34ed580ba3fa8ab171c17913
Author: Mihai Moldovan <ionic at ionic.de>
Date:   Thu Nov 12 11:35:32 2020 +0100

    x2goserver/lib/x2goupdateoptionsstring: better document end-of-options terminator and highlight its importance.
---
 debian/changelog                       |  2 ++
 x2goserver/bin/x2goupdateoptionsstring | 26 +++++++++++++++++++++-----
 2 files changed, 23 insertions(+), 5 deletions(-)

diff --git a/debian/changelog b/debian/changelog
index 2a7201ba..9e2f2ed5 100644
--- a/debian/changelog
+++ b/debian/changelog
@@ -281,6 +281,8 @@ x2goserver (4.1.0.4-0x2go1.2) UNRELEASED; urgency=medium
       needed (and if not, it shouldn't have any side effects anyway).
     - x2goserver/lib/x2goupdateoptionsstring: add space between link and
       punctuation character for easier copying.
+    - x2goserver/lib/x2goupdateoptionsstring: better document end-of-options
+      terminator and highlight its importance.
   * debian/control:
     + Build-depend upon lsb-release for distro version detection.
   * debian/x2goserver.manpages:
diff --git a/x2goserver/bin/x2goupdateoptionsstring b/x2goserver/bin/x2goupdateoptionsstring
index 582a33d2..4e4f0993 100755
--- a/x2goserver/bin/x2goupdateoptionsstring
+++ b/x2goserver/bin/x2goupdateoptionsstring
@@ -372,11 +372,8 @@ B<->I<key>B<=>I<value>.
 Use the B<--compact> option to minimize the original options string, removing
 duplicated and empty entries.
 
-You can terminate program options parsing via a standard double-dash (B<-->)
-pseudo-option.
-It is recommended to always do so if you pass removal transformation
-operations, even if no actual options are used to avoid misinterpreting such
-transformation options as options/flags to the program.
+Refer to the L<OPTIONS PARSING section|/OPTIONS PARSING> for a description of
+when and how to terminate options passed to this program.
 
 =head1 OPTIONS
 
@@ -401,6 +398,25 @@ The order of arguments is preserved in a first-seen fashion.
 
 =back
 
+=head2 OPTIONS PARSING
+
+You can terminate program options parsing via a standard double-dash (B<-->)
+pseudo-option.
+It is B<highly recommended> to always do so.
+
+If you pass removal transformation operations, passing the options terminator
+is B<mandatory>, even if no actual options are used.
+Otherwise, transformation operations will be interpreted as options to the
+program, which will almost certainly lead to an error.
+
+For example, passing C<-clipboard> as a transformation operation without a
+previous options terminator will be interpreted as the option C<-c>, with the
+rest of the string modified into C<-lipboard>.
+Since this program does not accept an option called C<-l>, it will terminate
+with an error.
+Even then, this is certainly not what the original transformation operation
+was supposed to represent.
+
 =head1 EXAMPLES
 
 For an options string such as

--
Alioth's /home/x2go-admin/maintenancescripts/git/hooks/post-receive-email on /srv/git/code.x2go.org/x2goserver.git