doc: add section about directory history / stack

This PR also adds "See Also" section in the related commands.

doc_src/cmds/cd.rst

@@ -27,8 +27,6 @@ As a special case, ``cd .`` is equivalent to ``cd $PWD``, which is useful in cas
 Examples
 --------
 
-
-
 ::
 
     cd
@@ -37,8 +35,7 @@ Examples
     cd /usr/src/fish-shell
     # changes the working directory to /usr/src/fish-shell
 
-
 See Also
 --------
 
-See also the :ref:`cdh <cmd-cdh>` command for changing to a recently visited directory.
+Navigate directories using the :ref:`directory history <directory-history>` or the :ref:`directory stack <directory-stack>`

doc_src/cmds/cdh.rst

@@ -10,15 +10,16 @@ Synopsis
 
     cdh [ directory ]
 
-
 Description
 -----------
 
-``cdh`` with no arguments presents a list of recently visited directories. You can then select one of the entries by letter or number. You can also press :kbd:`Tab` to use the completion pager to select an item from the list. If you give it a single argument it is equivalent to ``cd directory``.
+``cdh`` with no arguments presents a list of :ref:`recently visited directories <directory-history>`. You can then select one of the entries by letter or number. You can also press :kbd:`Tab` to use the completion pager to select an item from the list. If you give it a single argument it is equivalent to ``cd directory``.
 
 Note that the ``cd`` command limits directory history to the 25 most recently visited directories. The history is stored in the ``$dirprev`` and ``$dirnext`` variables which this command manipulates. If you make those universal variables your ``cd`` history is shared among all fish instances.
 
 See Also
 --------
 
-See also the :ref:`prevd <cmd-prevd>` and :ref:`pushd <cmd-pushd>` commands which also work with the recent ``cd`` history and are provided for compatibility with other shells.
+- the :ref:`dirh <cmd-dirh>` command to print the directory history
+- the :ref:`prevd <cmd-prevd>` command to move backward
+- the :ref:`nextd <cmd-nextd>` command to move forward

doc_src/cmds/dirh.rst

@@ -13,8 +13,15 @@ Synopsis
 Description
 -----------
 
-``dirh`` prints the current directory history. The current position in the history is highlighted using the color defined in the ``fish_color_history_current`` environment variable.
+``dirh`` prints the current :ref:`directory history <directory-history>`. The current position in the history is highlighted using the color defined in the ``fish_color_history_current`` environment variable.
 
 ``dirh`` does not accept any parameters.
 
-Note that the ``cd`` command limits directory history to the 25 most recently visited directories. The history is stored in the ``$dirprev`` and ``$dirnext`` variables.
+Note that the :ref:`cd <cmd-cd>` command limits directory history to the 25 most recently visited directories. The history is stored in the ``$dirprev`` and ``$dirnext`` variables.
+
+See Also
+--------
+
+- the :ref:`cdh <cmd-cdh>` command to display a prompt to quickly navigate the history
+- the :ref:`prevd <cmd-prevd>` command to move backward
+- the :ref:`nextd <cmd-nextd>` command to move forward

doc_src/cmds/dirs.rst

@@ -14,8 +14,13 @@ Synopsis
 Description
 -----------
 
-``dirs`` prints the current directory stack, as created by :ref:`pushd <cmd-pushd>` and modified by :ref:`popd <cmd-popd>`.
+``dirs`` prints the current :ref:`directory stack <directory-stack>`, as created by :ref:`pushd <cmd-pushd>` and modified by :ref:`popd <cmd-popd>`.
 
 With "-c", it clears the directory stack instead.
 
 ``dirs`` does not accept any parameters.
+
+See Also
+--------
+
+- the :ref:`cdh <cmd-cdh>` command which provides a more intuitive way to navigate to recently visited directories.

doc_src/cmds/nextd.rst

@@ -10,23 +10,18 @@ Synopsis
 
     nextd [ -l | --list ] [POS]
 
-
 Description
 -----------
 
-``nextd`` moves forwards ``POS`` positions in the history of visited directories; if the end of the history has been hit, a warning is printed.
+``nextd`` moves forwards ``POS`` positions in the :ref:`history of visited directories <directory-history>`; if the end of the history has been hit, a warning is printed.
 
 If the ``-l`` or ``--list`` flag is specified, the current directory history is also displayed.
 
 Note that the ``cd`` command limits directory history to the 25 most recently visited directories. The history is stored in the ``$dirprev`` and ``$dirnext`` variables which this command manipulates.
 
-You may be interested in the :ref:`cdh <cmd-cdh>` command which provides a more intuitive way to navigate to recently visited directories.
-
 Example
 -------
 
-
-
 ::
 
     cd /usr/src
@@ -41,3 +36,9 @@ Example
     nextd
     # Working directory is now /usr/src/fish-shell
 
+See Also
+--------
+
+- the :ref:`cdh <cmd-cdh>` command to display a prompt to quickly navigate the history
+- the :ref:`dirh <cmd-dirh>` command to print the directory history
+- the :ref:`prevd <cmd-prevd>` command to move backward

doc_src/cmds/popd.rst

@@ -10,13 +10,10 @@ Synopsis
 
     popd
 
-
 Description
 -----------
 
-``popd`` removes the top directory from the directory stack and changes the working directory to the new top directory. Use :ref:`pushd <cmd-pushd>` to add directories to the stack or :ref:`dirs <cmd-dirs>` to print it.
-
-You may be interested in the :ref:`cdh <cmd-cdh>` command which provides a more intuitive way to navigate to recently visited directories.
+``popd`` removes the top directory from the :ref:`directory stack <directory-stack>` and changes the working directory to the new top directory. Use :ref:`pushd <cmd-pushd>` to add directories to the stack.
 
 Example
 -------
@@ -35,3 +32,8 @@ Example
     # Working directory is now /usr/src
     # Directory stack contains /usr/src
 
+See Also
+--------
+
+- the :ref:`dirs <cmd-dirs>` command to print the directory stack
+- the :ref:`cdh <cmd-cdh>` command which provides a more intuitive way to navigate to recently visited directories.

doc_src/cmds/prevd.rst

@@ -13,19 +13,15 @@ Synopsis
 Description
 -----------
 
-``prevd`` moves backwards ``POS`` positions in the history of visited directories; if the beginning of the history has been hit, a warning is printed.
+``prevd`` moves backwards ``POS`` positions in the :ref:`history of visited directories <directory-history>`; if the beginning of the history has been hit, a warning is printed.
 
 If the ``-l`` or ``--list`` flag is specified, the current history is also displayed.
 
 Note that the ``cd`` command limits directory history to the 25 most recently visited directories. The history is stored in the ``$dirprev`` and ``$dirnext`` variables which this command manipulates.
 
-You may be interested in the :ref:`cdh <cmd-cdh>` command which provides a more intuitive way to navigate to recently visited directories.
-
 Example
 -------
 
-
-
 ::
 
     cd /usr/src
@@ -40,3 +36,9 @@ Example
     nextd
     # Working directory is now /usr/src/fish-shell
 
+See Also
+--------
+
+- the :ref:`cdh <cmd-cdh>` command to display a prompt to quickly navigate the history
+- the :ref:`dirh <cmd-dirh>` command to print the directory history
+- the :ref:`nextd <cmd-nextd>` command to move forward

doc_src/cmds/pushd.rst

@@ -13,7 +13,7 @@ Synopsis
 Description
 -----------
 
-The ``pushd`` function adds ``DIRECTORY`` to the top of the directory stack and makes it the current working directory. :ref:`popd <cmd-popd>` will pop it off and return to the original directory.
+The ``pushd`` function adds ``DIRECTORY`` to the top of the :ref:`directory stack <directory-stack>` and makes it the current working directory. :ref:`popd <cmd-popd>` will pop it off and return to the original directory.
 
 Without arguments, it exchanges the top two directories in the stack.
 
@@ -21,10 +21,6 @@ Without arguments, it exchanges the top two directories in the stack.
 
 ``pushd -NUMBER`` rotates clockwise i.e. top to bottom.
 
-See also :ref:`dirs <cmd-dirs>` to print the stack and ``dirs -c`` to clear it.
-
-You may be interested in the :ref:`cdh <cmd-cdh>` command which provides a more intuitive way to navigate to recently visited directories.
-
 Example
 -------
 
@@ -49,3 +45,9 @@ Example
     popd
     # Working directory is now /usr/src/fish-shell
     # Directory stack contains /usr/src/fish-shell /tmp
+
+See Also
+--------
+
+- the :ref:`dirs <cmd-dirs>` command to print the directory stack
+- the :ref:`cdh <cmd-cdh>` command which provides a more intuitive way to navigate to recently visited directories.

doc_src/cmds/pwd.rst

@@ -21,3 +21,8 @@ The following options are available:
 - ``-L`` or ``--logical`` Output the logical working directory, without resolving symlinks (default behavior).
 
 - ``-P`` or ``--physical`` Output the physical working directory, with symlinks resolved.
+
+See Also
+--------
+
+Navigate directories using the :ref:`directory history <directory-history>` or the :ref:`directory stack <directory-stack>`

doc_src/index.rst

@@ -1477,10 +1477,25 @@ In addition, when pasting inside single quotes, pasted single quotes and backsla
 
 .. [#] These rely on external tools. Currently xsel, xclip, wl-copy/wl-paste and pbcopy/pbpaste are supported.
 
+.. _multiline:
+
+Multiline editing
+-----------------
+
+The fish commandline editor can be used to work on commands that are several lines long. There are three ways to make a command span more than a single line:
+
+- Pressing the :kbd:`Enter` key while a block of commands is unclosed, such as when one or more block commands such as ``for``, ``begin`` or ``if`` do not have a corresponding :ref:`end <cmd-end>` command.
+
+- Pressing :kbd:`Alt`\ +\ :kbd:`Enter` instead of pressing the :kbd:`Enter` key.
+
+- By inserting a backslash (``\``) character before pressing the :kbd:`Enter` key, escaping the newline.
+
+The fish commandline editor works exactly the same in single line mode and in multiline mode. To move between lines use the left and right arrow keys and other such keyboard shortcuts.
+
 .. _history-search:
 
-Searchable history
-------------------
+Searchable command history
+--------------------------
 
 After a command has been entered, it is inserted at the end of a history list. Any duplicate history items are automatically removed. By pressing the up and down keys, the user can search forwards and backwards in the history. If the current command line is not empty when starting a history search, only the commands containing the string entered into the command line are shown.
 
@@ -1503,21 +1518,35 @@ To search for previous entries containing the word 'make', type ``make`` in the
 
 If the commandline reads ``cd m``, place the cursor over the ``m`` character and press :kbd:`Alt`\ +\ :kbd:`↑` to search for previously typed words containing 'm'.
 
+Navigating directories
+======================
 
-.. _multiline:
+.. _directory-history:
 
-Multiline editing
+The current working directory can be displayed with the :ref:`pwd <cmd-pwd>` command.
+
+Directory history
 -----------------
 
-The fish commandline editor can be used to work on commands that are several lines long. There are three ways to make a command span more than a single line:
+Fish automatically keeps a trail of the recent visited directories with :ref:`cd <cmd-cd>` by storing this history in the ``dirprev`` and ``dirnext`` variables.
 
-- Pressing the :kbd:`Enter` key while a block of commands is unclosed, such as when one or more block commands such as ``for``, ``begin`` or ``if`` do not have a corresponding :ref:`end <cmd-end>` command.
+Several commands are provided to interact with this directory history:
 
-- Pressing :kbd:`Alt`\ +\ :kbd:`Enter` instead of pressing the :kbd:`Enter` key.
+- :ref:`dirh <cmd-dirh>` prints the history
+- :ref:`cdh <cmd-cdh>` displays a prompt to quickly navigate the history
+- :ref:`prevd <cmd-prevd>` moves backward through the history. It is bound to :kbd:`Alt`\ +\ :kbd:`←`
+- :ref:`nextd <cmd-nextd>` moves forward through the history. It is bound to :kbd:`Alt`\ +\ :kbd:`→`
 
-- By inserting a backslash (``\``) character before pressing the :kbd:`Enter` key, escaping the newline.
+.. _directory-stack:
 
-The fish commandline editor works exactly the same in single line mode and in multiline mode. To move between lines use the left and right arrow keys and other such keyboard shortcuts.
+Directory stack
+---------------
+
+Another set of commands, usually also available in other shells like bash, deal with the directory stack. Stack handling is not automatic and needs explicit calls of the following commands:
+
+- :ref:`dirs <cmd-dirs>` prints the stack
+- :ref:`pushd <cmd-pushd>` adds a directory on top of the stack and makes it the current working directory
+- :ref:`popd <cmd-popd>` removes the directory on top of the stack and changes the current working directory
 
 .. _job-control: