docs/use: Improve docs about copybutton_exclude

- As in #185, document the current sate of copybutton_exclude and saw
  how to turn it on (since the default just got turned off for
  backwards compat).
- Review: worth a read to make sure it isn't too confusing.

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, and sphinx by default excludes
+prompts from being selectable.  Sphinx-copybutton can follows this
+default with the following setting.  This setting is not the default,
+because it conflicts with the backwards compatibility of the other
+following manually-selectable exclude options:
+```{code-block} python
+copybutton_exclude = '.linenos, .gp'
+```
+
+Add `.go` to the excludes and you will not copy console output,
+either.
+
+For automatic exclusion, use the right highlight language:
+`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.