diff options
author | Simon McVittie <smcv@debian.org> | 2020-09-03 11:38:14 +0100 |
---|---|---|
committer | Simon McVittie <smcv@debian.org> | 2020-09-03 12:49:53 +0100 |
commit | 61389b21b9306a3fd5d8d45cda36ab029e33f094 (patch) | |
tree | 5996aa61f0099ffb2edadb3fd719d7b8c7266611 | |
parent | ea5c2a3f4161ac2ad66373028d5b9a73d589b292 (diff) | |
download | gnome-terminal-61389b21b9306a3fd5d8d45cda36ab029e33f094.tar.gz |
man: Document the various ways to run a command in a gnome-terminal
There are three ways to run a command in a gnome-terminal (using
"python -q" as my example because it illustrates how argument parsing
works), of which "-e" was previously the only one listed in the
man page:
* gnome-terminal [OPTIONS] -- python3 -q
* gnome-terminal [OPTIONS] -e "python3 -q" [MORE OPTIONS]
* gnome-terminal [OPTIONS] -x python3 -q
--command is a long form of -e, and --execute is a long form of -x.
Both the "-e" and "-x" forms are deprecated in favour of the "--" form,
but previously only the deprecated "-e" form was documented in the
man page.
Document the preferred form in the synopsis, and document -e and -x in
terms of their replacements with the preferred form.
Resolves: https://gitlab.gnome.org/GNOME/gnome-terminal/-/issues/296
-rw-r--r-- | man/gnome-terminal.xml | 52 |
1 files changed, 51 insertions, 1 deletions
diff --git a/man/gnome-terminal.xml b/man/gnome-terminal.xml index abdac002..94f3cc58 100644 --- a/man/gnome-terminal.xml +++ b/man/gnome-terminal.xml @@ -48,6 +48,8 @@ <refsynopsisdiv> <cmdsynopsis> <command>gnome-terminal</command> + <group rep="repeat"><replaceable>OPTION</replaceable></group> + <group>-- <replaceable>PROGRAM</replaceable> <group rep="repeat"><replaceable>ARG</replaceable></group></group> </cmdsynopsis> </refsynopsisdiv> @@ -180,7 +182,38 @@ <term><option>--command, -e=COMMAND</option></term> <listitem> <para> - Execute the argument to this option inside the terminal. + Split the argument to this option into a program and arguments + in the same way a shell would, and execute the resulting + command-line inside the terminal. + </para> + <para> + This option is deprecated. Instead, use <option>--</option> + to terminate the options, and put the program and arguments to + execute after it: for example, instead of + <userinput>gnome-terminal -e "python3 -q"</userinput>, prefer to use + <userinput>gnome-terminal -- python3 -q</userinput>. + </para> + <para> + Note that the <replaceable>COMMAND</replaceable> is not run via + a shell: it is split into words and executed as a program. If + shell syntax is required, use the form + <userinput>gnome-terminal -- sh -c '...'</userinput>. + </para> + </listitem> + </varlistentry> + <varlistentry> + <term><option>--execute PROGRAM [ARGS], -x PROGRAM [ARGS]</option></term> + <listitem> + <para> + Stop parsing options at this point, and interpret all + subsequent options as a program and arguments to execute + inside the terminal. + </para> + <para> + This option is deprecated: use <option>--</option> instead. + For example, instead of + <userinput>gnome-terminal -x python3 -q</userinput>, prefer to use + <userinput>gnome-terminal -- python3 -q</userinput>. </para> </listitem> </varlistentry> @@ -374,6 +407,23 @@ </refsect1> <refsect1> + <title>EXAMPLES</title> + <para> + To run a terminal containing an interactive Python prompt: + <literallayout> + gnome-terminal --title=Python -- python3 -q + </literallayout> + </para> + <para> + To interpret shell syntax in a terminal, either write it in a + separate shell script, or use <literal>sh -c</literal>: + <literallayout> + gnome-terminal -- sh -c 'if [ "$(id -u)" = 0 ]; then ...' + </literallayout> + </para> + </refsect1> + + <refsect1> <title>SEE ALSO</title> <para> For further information, visit the website |