DOCS: Improve docs related to text exclusion

docs/use.md

@@ -3,6 +3,36 @@
 This section describes major ways to use and control `sphinx-copybutton`'s behavior.
 
 (configure-copy-text)=
+
+## Automatic exclusion of prompts from the copies
+
+The Sphinx code highlighter, Pygments, tags the prompts (`>>>`, `...`,
+`In [1]:`, `$`) of console sessions.
+Sphinx by default excludes prompts from being selectable.
+However, by default `sphinx-copybutton` will copy these prompts (for backwards compatibility with the other "manually-selectable exclude" options).
+
+To make `sphinx-copybutton` skip all prompt characters generated by pygments, use the following setting:
+
+```{code-block} python
+copybutton_exclude = '.linenos, .gp'
+```
+
+To **skip all console outputs**, add `.go` to the string above.
+
+For automatic exclusion, make sure to use the right highlight language.
+For example: `pythonconsole` instead of `python`, `console` instead of `bash`,
+`ipythonconsole` instead of `ipython`, etc.
+
+This setting can also be used to exclude arbitrary css classes from
+being copied.  By default `.linenos` are excluded.  `.linenos` is the
+Sphinx default for line numbers, `.gp` is the Pygments class for the
+prompts, and `.go` is the class for console outputs.
+
+This setting conflicts with most of pattern-based copy-selection
+settings below, so should not be used with them.  This will hopefully
+be improved in the future.
+
+
 ## Strip and configure input prompts for code cells
 
 By default, `sphinx-copybutton` will copy the entire contents of a code
@@ -366,22 +396,3 @@ button.copybtn {
 See the [Sphinx documentation on custom CSS for more information](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-html_static_path).
 
 [regex101]: https://regex101.com
-
-
-## Exclude text from being copied
-
-You may exclude elements matching CSS selectors from being copied by
-specifying the `copybutton_exclude` option in ``conf.py``.  For
-example, a viewer usually doesn't want to copy the line numbers, and
-CSS provides a way to exclude this.  This option implements that
-option for sphinx-copybutton as well.
-
-
-```{code-block} python
-copybutton_exclude = '.exclude_me'
-```
-By default `.linenos, .gp` are excluded. If you specify the
-`copybutton_exclude` option it will replace the default.  `.linenos`
-is the Sphinx default for line numbers, and `.gp` is Pygments (the
-default highlighter of Sphinx) for "prompt", e.g. `$` in a
-shell-session. `.gp` is excluded in upstream Sphinx by default.