docs: rewrite, fix and improve CLI tutorial

docs-requirements.txt

@@ -1,6 +1,7 @@
 sphinx >=4.0.0
 furo ==2022.09.15
 myst-parser >=0.18.0
+sphinx-design >=0.3.0
 versioningit >=2.0.0, <3
 
 docutils-stubs

docs/cli/tutorial.rst

@@ -1,40 +1,53 @@
 Tutorial
---------
+========
+
+Introduction
+------------
 
 Streamlink is a command-line application, which means that the commands described
-here should be typed into a terminal. On Windows, you have to open either the
+here should be typed into a terminal, or to be more precise, into a command-line shell.
-`Command Prompt`_, `PowerShell`_ or `Windows Terminal`_, on macOS open the `Terminal <macOS-Terminal>`_ app,
+
-and if you're on Linux or BSD you probably already know the drill.
+On Windows, you have to open either the `Windows Terminal`_ (recommended), `PowerShell`_ or `Command Prompt`_ (discouraged).
+On macOS, open the `Terminal <macOS Terminal_>`_ app, and if you're on Linux or BSD,
+the terminal emulator depends on your desktop environment and its configuration.
 
 The way Streamlink works is that it's only a means to extract and transport
 the streams, and the playback is done by an external video player. Streamlink
 works best with `VLC`_ or `mpv`_, which are also cross-platform, but other players
 may be compatible too, see the :ref:`Players <players:Players>` page for a complete overview.
 
+
+Getting started
+---------------
+
 Now to get into actually using Streamlink, let's say you want to watch the
-stream located on twitch.tv/day9tv, you start off by telling Streamlink
+stream located on ``https://www.twitch.tv/nasa``, you start off by telling Streamlink
-where to attempt to extract streams from. This is done by giving the URL to the
+where to attempt to extract streams from. This is done by setting the URL as the
-command :command:`streamlink` as the first argument:
+first argument on the :command:`streamlink` command:
 
 .. code-block:: console
 
-    $ streamlink twitch.tv/day9tv
+    $ streamlink twitch.tv/nasa
-    [cli][info] Found matching plugin twitch for URL twitch.tv/day9tv
+    [cli][info] Found matching plugin twitch for URL twitch.tv/nasa
-    Available streams: audio, high, low, medium, mobile (worst), source (best)
+    Available streams: audio_only, 160p (worst), 360p, 480p, 720p60, 1080p60 (best)
-
 
 .. note::
     You don't need to include the protocol when dealing with HTTP(s) URLs,
-    e.g. just ``twitch.tv/day9tv`` is enough and quicker to type.
+    e.g. just ``twitch.tv/nasa`` is enough and quicker to type.
+
+.. caution::
+
+    Depending on the command-line shell in use, any kind of command argument like the input URL for example
+    may need to get quoted or escaped. See the `Shell syntax`_ section down below.
 
 
 This command will tell Streamlink to attempt to extract streams from the URL
-specified, and if it's successful, print out a list of available streams to choose
+specified via its :ref:`plugins system <plugins:Plugins>` which is responsible for resolving streams from specific
-from.
+streaming services. If it's successful, Streamlink will print out a list of available streams to choose from.
 
-In some cases (see :ref:`cli/protocols:Supported streaming protocols`), local files are supported
+In addition to Streamlink's plugins system, direct stream URLs can be played via the
-using the ``file://`` protocol, for example a local HLS playlist can be played.
+:ref:`supported streaming protocols <cli/protocols:Streaming protocols>`, which also support playback of local files
-Relative file paths and absolute paths are supported. All path separators are ``/``,
+using the ``file://`` protocol. Relative file paths and absolute paths are supported. All path separators are ``/``,
 even on Windows.
 
 .. code-block:: console
@@ -47,14 +60,13 @@ even on Windows.
 To select a stream and start playback, simply add the stream name as a second
 argument to the :command:`streamlink` command:
 
-.. sourcecode:: console
+.. code-block:: console
 
-    $ streamlink twitch.tv/day9tv 1080p60
+    $ streamlink twitch.tv/nasa 1080p60
-    [cli][info] Found matching plugin twitch for URL twitch.tv/day9tv
+    [cli][info] Found matching plugin twitch for URL twitch.tv/nasa
     [cli][info] Opening stream: 1080p60 (hls)
     [cli][info] Starting player: vlc
 
-
 The stream you chose should now be playing in the player. It's a common use case
 to just want to start the highest quality stream and not be bothered with what it's
 named. To do this, just specify ``best`` as the stream name and Streamlink will
@@ -76,3 +88,76 @@ into customizing it to your own needs, such as:
 .. _macOS Terminal: https://support.apple.com/guide/terminal/welcome/mac
 .. _VLC: https://videolan.org/
 .. _mpv: https://mpv.io/
+
+
+Shell syntax
+------------
+
+Depending on your used command-line shell and how you've entered the command,
+input strings like the URL or other command arguments may need to get `escaped <escape-character_>`_ or quoted,
+because command-line shells interpret and treat certain characters as special symbols which can alter the shell's behavior,
+like characters for substituting/expanding strings, delimiting commands, path/file globbing, etc.
+
+The most relevant characters (among others) for input URLs that can cause unexpected results are
+
+- ``&``, ``;`` (command delimiting)
+- ``$``, ``%`` (variable substitution)
+- ``?``, ``*`` (path globbing)
+
+The quoting and escaping behavior varies wildly between each shell and its configuration,
+so please take a look at your shell's documentation about all the details, if you're unsure.
+
+**Quoting and character escaping examples:**
+
+URL: ``https://example/path?a=$one&b=%two%&c=*three*;&``
+
+.. tab-set::
+
+    .. tab-item:: POSIX compliant
+
+        - `BASH manual <bash_>`_
+        - `ZSH manual <zsh_>`_
+
+        .. code-block:: sh
+
+            streamlink 'https://example/path?a=$one&b=%two%&c=*three*;&'
+            streamlink "https://example/path?a=\$one&b=%two%&c=*three*;&"
+            streamlink https://example/path?a=\$one\&b=%two%\&c=*three*\;\&
+
+    .. tab-item:: FISH
+
+        - `FISH language documentation <fish_>`_
+
+        .. code-block:: fish
+
+            streamlink 'https://example/path?a=$one&b=%two%&c=*three*;&'
+            streamlink "https://example/path?a=\$one&b=%two%&c=*three*;&"
+            streamlink https://example/path\?a=\$one&b=%two%&c=\*three\*\;\&
+
+    .. tab-item:: PowerShell
+
+        - `PowerShell language specification <pwsh_>`_
+
+        .. code-block:: pwsh
+
+            streamlink 'https://example/path?a=$one&b=%two%&c=*three*;&'
+            streamlink "https://example/path?a=`$one&b=%two%&c=*three*;&"
+            streamlink https://example/path?a=`$one`&b=%two%`&c=*three*`;`&
+
+    .. tab-item:: Windows Batch
+
+        - `Escape characters, delimiters and quotes <batch-ss64_>`_
+        - `Percent sign escaping <batch-so_>`_
+
+        .. code-block:: bat
+
+            streamlink "https://example/path?a=$one&b="%"two"%"&c=*three*;&"
+            streamlink https://example/path?a=$one^&b=^%two^%^&c=*three*^;^&
+
+.. _escape-character: https://en.wikipedia.org/wiki/Escape_character
+.. _bash: https://www.gnu.org/software/bash/manual/bash.html
+.. _zsh: https://zsh.sourceforge.io/Doc/Release/zsh_toc.html
+.. _fish: https://fishshell.com/docs/current/language.html
+.. _pwsh: https://learn.microsoft.com/en-us/powershell/scripting/lang-spec/chapter-02
+.. _batch-ss64: https://ss64.com/nt/syntax-esc.html
+.. _batch-so: https://stackoverflow.com/a/31420292

docs/conf.py

@@ -26,6 +26,7 @@ extensions = [
     'ext_plugins',
     'ext_releaseref',
     'myst_parser',
+    'sphinx_design',
 ]
 
 autosectionlabel_prefix_document = True