doc: enable the furo theme

Author: davvid

share/doc/git-cola/git-cola.rst

@@ -133,15 +133,15 @@ If defined, the first of these variables is used:
 The `*VISUAL` variables are consulted before the `*EDITOR` variables so that you can
 configure a graphical editor independently of the editor used by the Git CLI.
 
-*ProTip*: Configuring your editor to `gvim -f -p` will open multiple tabs
+*Pro Tip*: Configuring your editor to `gvim -f -p` will open multiple tabs
 when editing files.  `gvim -f -o` uses splits.
 
 `git cola` is {vim, emacs, textpad, notepad++}-aware.
 When you select a line in the diff or grep screens and press any of
 `Enter`, `Ctrl-e`, or the `Edit` button, you are taken to that exact line.
 
 The editor preference is saved in the `gui.editor` variable using
-`git config <http://git-scm.com/docs/git-config>`_.
+`git config <https://git-scm.com/docs/git-config>`_.
 
 The following are some recommend editor configurations.
 
@@ -170,7 +170,7 @@ KEYBOARD SHORTCUTS
 ==================
 `git cola` has many useful keyboard shortcuts.
 
-Many of `git cola`'s editors understand vim-style hotkeys, eg. `{h,j,k,l}`
+Many of `git cola`'s editors understand vim-style hotkeys, e.g. `{h,j,k,l}`
 for navigating in the diff, status, grep, and file browser widgets.
 
 `{d,u}` move down/up one half page at a time (similar to vim's `ctrl-{d,u}`).
@@ -211,42 +211,41 @@ A hidden tool can be re-opened using the `Tools` menu or
 the `Shift+Control-{1, 2, 3, ...}` shortcut keys.
 
 The Diff editor can be focused with `Ctrl-j`.
-the Status tool can be focused with `Ctrl-k`.
-the Commit tool can be focused with `Ctrl-l`.
+The Status tool can be focused with `Ctrl-k`.
+The Commit tool can be focused with `Ctrl-l`.
 
 
 .. _status:
 
 STATUS
 ======
 The `Status` tool provides a visual analog to the
-`git status <http://git-scm.com/docs/git-status>`_ command.
+`git status <https://git-scm.com/docs/git-status>`_ command.
 
 `Status` displays files that are `modified` relative to the staging area,
 `staged` for the next commit, `unmerged` files from an in-progress merge,
 and files that are `untracked` to git.
 
 These are the same categories one sees when running
-`git status <http://git-scm.com/docs/git-status>`_
+`git status <https://git-scm.com/docs/git-status>`_
 on the command line.
 
 You can navigate through the list of files using keyboard arrows as well
-as the ergonomical and vim-like `j` and `k` shortcut keys.
+as the ergonomic and vim-like `j` and `k` shortcut keys.
 
 There are several convenient ways to interact with files in the `Status` tool.
 
 Selecting a file displays its diff in the `Diff` viewer.
-Double-clicking a file stages its contents, as does the
-the `Ctrl-s` shortcut key.
+Double-clicking a file stages its contents, as does the `Ctrl-s` shortcut key.
 
 `Ctrl-e` opens selected files in the configured editor, and
-`Ctrl-d` opens selected files using `git difftool <http://git-scm.com/docs/git-difftool>`_
+`Ctrl-d` opens selected files using `git difftool <https://git-scm.com/docs/git-difftool>`_
 
 Additional actions can be performed using the right-click context menu.
 
 Drag and Drop
 -------------
-Files can be dragged from the the `Status` tool onto other applications.
+Files can be dragged from the `Status` tool onto other applications.
 
 Some terminals will treat a drag with multiple files by separating them with newlines,
 which is less amenable for pasting command-line arguments.
@@ -273,7 +272,7 @@ Different actions are available depending a file's status.
 
 Stage Selected
 ~~~~~~~~~~~~~~
-Add to the staging area using `git add <http://git-scm.com/docs/git-add>`_
+Add to the staging area using `git add <https://git-scm.com/docs/git-add>`_
 Marks unmerged files as resolved.
 
 Launch Editor
@@ -296,11 +295,11 @@ Throws away uncommitted edits
 Unstage Selected
 ~~~~~~~~~~~~~~~~
 Remove from the index/staging area with
-`git reset <http://git-scm.com/docs/git-reset>`_
+`git reset <https://git-scm.com/docs/git-reset>`_
 
 Launch Merge Tool
 ~~~~~~~~~~~~~~~~~
-Resolve conflicts using `git mergetool <http://git-scm.com/docs/git-mergetool>`_.
+Resolve conflicts using `git mergetool <https://git-scm.com/docs/git-mergetool>`_.
 
 Delete File(s)
 ~~~~~~~~~~~~~~
@@ -370,19 +369,21 @@ staged content.
 
 Sign Off
 --------
-The `Sign Off` button adds a standard::
+The `Sign Off` button adds a sign-off to the bottom of the commit message::
 
     Signed-off-by: A. U. Thor <a.u.thor@example.com>
 
-line to the bottom of the commit message.
-
 Invoking this action is equivalent to passing the ``-s`` option
-to `git commit <http://git-scm.com/docs/git-commit>`_.
+to `git commit <https://git-scm.com/docs/git-commit>`_.
+
+Signing-off on commits is a common practice in projects that use
+`Developer Certificate of Origin <https://developercertificate.org/>`_
+attestations in their contribution process.
 
 Commit
 ------
 The commit button runs
-`git commit <http://git-scm.com/docs/git-commit>`_.
+`git commit <https://git-scm.com/docs/git-commit>`_.
 The contents of the commit message editor is provided as the commit message.
 
 Only staged files are included in the commit -- this is the same behavior
@@ -405,7 +406,7 @@ Red indicates that the line is running up against the standard
 80-column limit for commit messages.
 
 Keeping commit messages less than 76-characters wide is encouraged.
-`git log <http://git-scm.com/docs/git-log>`_
+`git log <https://git-scm.com/docs/git-log>`_
 is a great tool but long lines mess up its formatting for everyone else,
 so please be mindful when writing commit messages.
 
@@ -422,8 +423,8 @@ Create Signed Commit
 Tell `git commit` and `git merge` to sign commits using GPG.
 
 Using this option is equivalent to passing the ``--gpg-sign`` option to
-`git commit <http://git-scm.com/docs/git-commit>`_ and
-`git merge <http://git-scm.com/docs/git-merge>`_.
+`git commit <https://git-scm.com/docs/git-commit>`_ and
+`git merge <https://git-scm.com/docs/git-merge>`_.
 
 This option's default value can be configured using the `cola.signcommits`
 configuration variable.
@@ -447,37 +448,39 @@ across all repositories.
 
 BRANCHES
 ========
-The `Branches` tool provides a visual tree to navigate through the branches.
-The tree has three main nodes `Local Branch`, `Remote Branch` and `Tags`.
-Branches are grouped by their name divided by the character '/'.Ex::
+The `Branches` tool provides a visual tree to navigate branches.
+The tree has three main sections: `Local Branches`, `Remote Branches` and `Tags`.
+Branches are grouped by their name divided by the character ``/``.
+For example, in a repo with the following list of branches::
 
     branch/feature/foo
     branch/feature/bar
     branch/doe
 
-Will produce::
+The branches widget will display the following hierarchy::
 
     branch
         - doe
         + feature
             - bar
             - foo
 
-Current branch will display a star icon. If current branch has commits
-ahead/behind it will display an up/down arrow with its number.
+The current branch is decorated with a star icon.
+If the current branch has commits ahead or behind the remote then an up or down
+arrow will be displayed alongside a number showing the number of commits.
 
 Actions
 -------
 Various actions are available through the right-click context menu.
-Different actions are available depending of selected branch status.
+Different actions are available depending on the selected branch's status.
 
 Checkout
 ~~~~~~~~
 The checkout action runs
 `git checkout [<branchname>] <https://git-scm.com/docs/git-checkout>`_.
 
-Merge in current branch
-~~~~~~~~~~~~~~~~~~~~~~~
+Merge into current branch
+~~~~~~~~~~~~~~~~~~~~~~~~~
 The merge action runs
 `git merge --no-commit [<branchname>] <https://git-scm.com/docs/git-merge>`_.
 
@@ -513,7 +516,7 @@ Use the ``File -> Apply Patches`` menu item to begin applying patches.
 
 Dragging and dropping patches onto the `git cola` interface
 adds the patches to the list of patches to apply using
-`git am <http://git-scm.com/docs/git-am>`_.
+`git am <https://git-scm.com/docs/git-am>`_.
 
 You can drag either a set of patches or a directory containing patches.
 Patches can be sorted using in the interface and are applied in the
@@ -523,7 +526,7 @@ When a directory is dropped `git cola` walks the directory
 tree in search of patches.  `git cola` sorts the list of
 patches after they have all been found.  This allows you
 to control the order in which patches are applied by placing
-patchsets into alphanumerically-sorted directories.
+patch sets into alphanumerically-sorted directories.
 
 
 CUSTOM WINDOW SETTINGS
@@ -532,7 +535,7 @@ CUSTOM WINDOW SETTINGS
 of tools within the `git cola` interface.  Changes are saved
 and restored at application shutdown/startup.
 
-`git cola` can be configured to not save custom layouts by unsetting
+`git cola` can be configured to not save custom layouts by disabling
 the `Save Window Settings` option in the `git cola` preferences.
 
 
@@ -639,7 +642,7 @@ cola.blockcursor
 ----------------
 Whether to use a "block" cursor in diff editors. The block cursor is easier to
 see compared to a line cursor. Set to `false` to use a thin "line" cursor.
-Defauls to `true`.
+Defaults to `true`.
 
 cola.browserdockable
 --------------------
@@ -695,7 +698,7 @@ and applying diffs.
 
 A `.gitattributes` file can set the ``binary`` attribute in order to force
 specific untracked paths to be treated as binary files when diffing.
-Binary files are displayed using a hexdump display.
+Binary files are displayed using a hex-dump display.
 
 .. sourcecode:: sh
 
@@ -781,8 +784,8 @@ remember is controlled by `cola.maxrecent` and defaults to `8`.
 cola.mousezoom
 --------------
 Controls whether zooming text using Ctrl + MouseWheel scroll is enabled.
-Set to `false to disable scrolling with the mouse wheel.
-Defauls to `true`.
+Set to ``false`` to disable scrolling with the mouse wheel.
+Defaults to ``true``.
 
 cola.dragencoding
 -----------------
@@ -879,7 +882,7 @@ whereas ``gnome-terminal -- git difftool`` does not.
 
 You should not need to set this variable for the built-in terminals
 cola knows about -- it will behave correctly without configuration.
-For example, when unconfigured, cola already knows that xfce4-terminal
+For example, when not configured, cola already knows that xfce4-terminal
 requires shell quoting.
 
 This configuration variable is for custom terminals outside of the builtin set.
@@ -1033,7 +1036,7 @@ gui.editor
 ----------
 The default text editor to use is defined in `gui.editor`.
 The config variable overrides the VISUAL environment variable.
-e.g. `gvim -f -p`.
+Defaults to `gvim -f -p`.
 
 gui.historybrowser
 ------------------
@@ -1082,7 +1085,7 @@ GIT_COLA_SCALE
     for more details.
 
 `git cola` can be made to scale its interface for HiDPI displays.
-When defined, `git cola` will scale icons, radioboxes, and checkboxes
+When defined, `git cola` will scale icons, radio buttons, and checkboxes
 according to the scale factor.  The default value is `1`.
 A good value is `2` for high-resolution displays.
 
@@ -1139,13 +1142,13 @@ selected file as FILENAME, and the name of the current branch as CUR_BRANCH
 (if the head is detached, CUR_BRANCH is empty).
 
 If ``<name>`` contains slashes (``/``) then the leading part of the name,
-up until the final slash, is treated like a path of submenus under which the
+up until the final slash, is treated like a path of sub-menus under which the
 actions will be created.
 
 For example, configuring ``guitool.Commands/Util/echo.cmd`` creates a
 ``Commands`` menu inside the top-level ``Actions`` menu, a ``Util`` menu
 inside the ``Commands`` menu and an ``echo`` action inside the ``Commands``
-submenu.
+sub-menu.
 
 guitool.<name>.background
 -------------------------
@@ -1187,7 +1190,7 @@ and can be used together with it.
 
 guitool.<name>.revunmerged
 --------------------------
-Show only unmerged branches in the revprompt subdialog. This is useful for
+Show only unmerged branches in the revprompt sub-dialog. This is useful for
 tools similar to merge or rebase, but not for things like checkout or reset.
 
 guitool.<name>.title
@@ -1206,7 +1209,7 @@ guitool.<name>.shortcut
 Specifies a keyboard shortcut for the custom tool.
 
 The value must be a valid string understood by the `QAction::setShortcut()` API.
-See http://qt-project.org/doc/qt-4.8/qkeysequence.html#QKeySequence-2
+See https://doc.qt.io/qt-6/qkeysequence.html#toString
 for more details about the supported values.
 
 Avoid creating shortcuts that conflict with existing built-in `git cola`
@@ -1313,7 +1316,7 @@ Git Installation
 If Git is installed in a custom location, e.g. not installed in `C:/Git` or
 Program Files, then the path to Git must be configured by creating a file in
 your home directory `~/.config/git-cola/git-bindir` that points to your git
-installation.  e.g.::
+installation, e.g.::
 
     C:/Tools/Git/bin
 
@@ -1332,7 +1335,7 @@ https://stackoverflow.com/questions/18683092/how-to-run-ssh-add-on-windows
 FIPS SECURITY MODE
 ==================
 
-`FIPS Security Mode <https://developer.mozilla.org/en-US/docs/Mozilla/Projects/NSS/FIPS_Mode_-_an_explanation>`_
+`FIPS Security Mode <https://github.com/python/cpython/issues/53462>`_
 is available in newer versions of Python. These include Python 3.9+ and the
 patched Python 3.6 used by CentOS8/RHEL8 (and possibly others).