Repository: borgbackup/borg

Issue:
Disable smartquotes in the sphinx configuration
## Have you checked borgbackup docs, FAQ, and open Github issues?

Yes

## Is this a BUG / ISSUE report or a QUESTION?

QUESTION

## The Question

Regarding the sphinx documentation and it's configuration,
I was wondering if it wouldn't be a better idea to disable  
smart quoting mode (which is enabled by default).
The motivation behind my question/suggestion is that it might
improve the overall "copy-pasteability" of the documentation.
Currently there are various places in the rendered documentation
on readthedocs which prevent easy copy pasting of commands
due to the conversion of the double dashes to a unicode dash.

Wouldn't it be a better idea to disable the [smartquotes](https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-smartquotes) option
inside `conf.py` so people who are working on the documentation
don't have to escape each and every occurrence of a command-line
flag with two dashes?


Discussion:
Can you link to a place in the docs that can't be copy and pasted due to this?

And make a PR afterwards?

Sorry for my late reply,

https://borgbackup.readthedocs.io/en/master/quickstart.html#backup-compression contains
a blockquote with a command inside which was "victim" of a such conversion.

    $ borg create –compression zstd,N /path/to/repo::arch ~

I'm not quite sure yet if this is due to the smartquotes configuration or if the "en dash" character ended up like this due to an editor configuration. I'll try to dig a little bit further into this :)

EDIT: After building the docs with `smartquotes = False`, the mentioned line above is rendered
as expected, e.g. two single dashes instead of an "en dash".

Pull request located #4703
Yeah, this one example got rendered badly, when smartquotes are enabled. But the problem are not the smartquotes, but that the example is not made using the correct markup. In the fragment shown below, the first example is rendered badly (causing the c&p problem), the second example does not have this problem:

```
zstd is a modern compression algorithm and might be preferable over zlib and
lzma, except if you need compatibility to older borg versions (< 1.1.4) that
did not yet offer zstd.

    $ borg create --compression zstd,N /path/to/repo::arch ~

Other options are:

If you have a fast repo storage and you want minimum CPU usage, no compression::

    $ borg create --compression none /path/to/repo::arch ~
```

Note the `::` introducing the 2nd example, this should be used for the 1st one also.

So, I'ld rather prefer the markup being fixed (at all places) than the configuration being changed.
Good eye, I guess we can close this issue then :)
Thanks for looking into it!
Do you want to fix the markup instead? Needs a PR against master and 1.1-maint.

Resolving patch:
diff --git a/src/borg/archiver.py b/src/borg/archiver.py
--- a/src/borg/archiver.py
+++ b/src/borg/archiver.py
@@ -2633,9 +2633,9 @@ def define_archive_filters_group(subparser, *, sort_by=True, first_last=True):
 
         Make sure you have free space there, you'll need about 1GB each (+ overhead).
 
-        If your repository is encrypted and borg needs a passphrase to unlock the key, use:
+        If your repository is encrypted and borg needs a passphrase to unlock the key, use::
 
-        BORG_PASSPHRASE=mysecret borg benchmark crud REPO PATH
+            BORG_PASSPHRASE=mysecret borg benchmark crud REPO PATH
 
         Measurements are done with different input file sizes and counts.
         The file contents are very artificial (either all zero or all random),
@@ -4152,7 +4152,7 @@ def define_archive_filters_group(subparser, *, sort_by=True, first_last=True):
         Upgrade should be able to resume if interrupted, although it
         will still iterate over all segments. If you want to start
         from scratch, use `borg delete` over the copied repository to
-        make sure the cache files are also removed:
+        make sure the cache files are also removed::
 
             borg delete borg
 


Test patch: