From 5d55dd98798a259dc5ccf02dec4fadc4d1794fe8 Mon Sep 17 00:00:00 2001
From: Fabian Boehm <FHomborg@gmail.com>
Date: Fri, 17 Jan 2025 20:27:36 +0100
Subject: [PATCH] docs/fish: Add invocation examples

---
 doc_src/cmds/fish.rst | 33 ++++++++++++++++++++++++++++++++-
 doc_src/language.rst  |  2 ++
 2 files changed, 34 insertions(+), 1 deletion(-)

diff --git a/doc_src/cmds/fish.rst b/doc_src/cmds/fish.rst
index 19889d964..500450219 100644
--- a/doc_src/cmds/fish.rst
+++ b/doc_src/cmds/fish.rst
@@ -24,7 +24,8 @@ The :ref:`tutorial <tutorial>` is available as HTML via ``help tutorial`` or in
 The following options are available:
 
 **-c** or **--command=COMMAND**
-    Evaluate the specified commands instead of reading from the commandline, passing additional positional arguments through ``$argv``.
+    Evaluate the specified commands instead of reading from the commandline.
+    Any additional positional arguments are used as ``$argv``.
 
 **-C** or **--init-command=COMMANDS**
     Evaluate specified commands after reading the configuration but before executing command specified by **-c** or reading interactive input.
@@ -106,3 +107,33 @@ These options can also be changed via the :envvar:`FISH_DEBUG` and :envvar:`FISH
 The categories enabled via **--debug** are *added* to the ones enabled by $FISH_DEBUG, so they can be disabled by prefixing them with **-** (**reader-*,-ast*** enables reader debugging and disables ast debugging).
 
 The file given in **--debug-output** takes precedence over the file in :envvar:`FISH_DEBUG_OUTPUT`.
+
+Examples
+--------
+
+To just start fish::
+
+  fish
+
+To run a file with fish::
+
+  fish /path/to/script.fish
+
+To run some commands with fish::
+
+  fish -c 'echo Hi there!'
+
+You can also pass arguments to those commands::
+
+  > fish -c 'printf %s\n $argv' "first line" "second line"
+  first line
+  second line
+
+To run a script, except read this other file first::
+
+  fish --init-cmd "source otherfile" script.fish
+
+To :ref:`profile <profiling>` fish's startup and find what takes the most time in your configuration::
+
+  fish --profile-startup /tmp/start.prof -ic exit
+  sort -nk2 /tmp/start.prof
diff --git a/doc_src/language.rst b/doc_src/language.rst
index 18ac97a63..1fde731e0 100644
--- a/doc_src/language.rst
+++ b/doc_src/language.rst
@@ -2130,6 +2130,8 @@ To start a debug session simply insert the :doc:`builtin command <cmds/breakpoin
 
 Another way to debug script issues is to set the :envvar:`fish_trace` variable, e.g. ``fish_trace=1 fish_prompt`` to see which commands fish executes when running the :doc:`fish_prompt <cmds/fish_prompt>` function.
 
+.. _profiling:
+
 Profiling fish scripts
 ^^^^^^^^^^^^^^^^^^^^^^