From f03d98649788243d4f47b340858a08e8f0d0dc8c Mon Sep 17 00:00:00 2001
From: "Kelvin M. Klann" <kmk3.code@protonmail.com>
Date: Thu, 3 Nov 2022 13:04:45 -0300
Subject: docs: clarify that --appimage should appear before --profile

And fix the argument order in the examples to reflect that.

Background: The order in which these options appeared in the
documentation was inconsistent.  src/man/firejail.txt used --appimage
before --profile and src/man/firejail-profile.txt used --profile before
--appimage.  Then commit 44fefcac0 ("Make appimage examples consistent
with --appimage option short description", 2022-10-05) / PR #5402 was
made, which standardized on --profile before --appimage in both places.

But as mentioned by @rusty-snake[1], --appimage has be specified before
--profile in order for any `?HAS_APPIMAGE` conditionals inside of the
profile to evaluate to true.

So change the documentation to use and recommend the latter form.

Also, add --quiet to one example to make it clear that --appimage does
not have to be the first option (nor the last option before --profile).

[1] https://github.com/netblue30/firejail/pull/5402#issuecomment-1274889618
---
 src/man/firejail-profile.txt |  9 +++++++--
 src/man/firejail.txt         | 17 ++++++++++++-----
 2 files changed, 19 insertions(+), 7 deletions(-)

(limited to 'src/man')

diff --git a/src/man/firejail-profile.txt b/src/man/firejail-profile.txt
index 138aae8af..7fa677ae5 100644
--- a/src/man/firejail-profile.txt
+++ b/src/man/firejail-profile.txt
@@ -14,7 +14,7 @@ Using a specific profile:
 .br
 Example:
 .br
-$ firejail --profile=/etc/firejail/kdenlive.profile --appimage kdenlive.appimage
+$ firejail --appimage --profile=/etc/firejail/kdenlive.profile kdenlive.appimage
 .br
 
 .br
@@ -25,7 +25,7 @@ $ firejail --profile=/etc/firejail/kdenlive.profile --appimage kdenlive.appimage
 .br
 Example:
 .br
-$ firejail --profile=kdenlive --appimage kdenlive.appimage
+$ firejail --appimage --profile=kdenlive kdenlive.appimage
 .br
 
 .br
@@ -179,6 +179,11 @@ can be enabled or disabled globally in Firejail's configuration file.
 
 The profile line may be any profile line that you would normally use in a profile \fBexcept\fR for "quiet" and "include" lines.
 
+Note: When using one or more conditionals and \fB--profile\fR, it is
+recommended that the relevant option(s) (such as \fB--appimage\fR) be specified
+before \fB--profile\fR, so that their respective conditional(s) (such as
+\fB?HAS_APPIMAGE\fR) inside of the profile evaluate to true.
+
 .TP
 \fBinclude other.profile
 Include other.profile file.
diff --git a/src/man/firejail.txt b/src/man/firejail.txt
index b4be1cd62..39c81312c 100644
--- a/src/man/firejail.txt
+++ b/src/man/firejail.txt
@@ -11,7 +11,7 @@ firejail [OPTIONS] [program and arguments]
 Start an AppImage program:
 .PP
 .RS
-firejail [OPTIONS] --appimage [appimage-file and arguments]
+firejail [OPTIONS] --appimage [OPTIONS] [appimage-file and arguments]
 .RE
 .PP
 #ifdef HAVE_FILE_TRANSFER
@@ -164,15 +164,22 @@ private-bin and private-lib are disabled by default when running appimages.
 .br
 Example:
 .br
-$ firejail --profile=krita --appimage krita-3.0-x86_64.appimage
+$ firejail --appimage --profile=krita krita-3.0-x86_64.appimage
 .br
-$ firejail --private --profile=krita --appimage krita-3.0-x86_64.appimage
+$ firejail --quiet --appimage --private --profile=krita krita-3.0-x86_64.appimage
 .br
 #ifdef HAVE_X11
-$ firejail --net=none --x11 --profile=krita --appimage krita-3.0-x86_64.appimage
+$ firejail --appimage --net=none --x11 --profile=krita krita-3.0-x86_64.appimage
 #endif
-.TP
+.br
+
+.br
+Note: When using both \fB--appimage\fR and \fB--profile\fR, it is recommended
+to always specify the former before the latter, so that any \fB?HAS_APPIMAGE\fR
+conditionals inside of the profile evaluate to true (see \fB?CONDITIONAL\fR in
+firejail-profile(5)).
 #ifdef HAVE_NETWORK
+.TP
 \fB\-\-bandwidth=name|pid
 Set bandwidth limits for the sandbox identified by name or PID, see \fBTRAFFIC SHAPING\fR section for more details.
 #endif
-- 
cgit v1.2.3-54-g00ecf