Repository: borgbackup/borg

Issue:
Rendering issue with docs, converting double-hyphen to en dash
<!--
Thank you for reporting an issue.

*IMPORTANT* -  *before* creating a new issue please look around:
 - Borgbackup documentation: http://borgbackup.readthedocs.io/en/stable/index.html
 - FAQ: https://borgbackup.readthedocs.io/en/stable/faq.html
 and
 - open issues in Github tracker: https://github.com/borgbackup/borg/issues
  
If you cannot find a similar problem, then create a new issue.

Please fill in as much of the template as possible.
-->

## Have you checked borgbackup docs, FAQ, and open Github issues?

Yes

## Is this a BUG / ISSUE report or a QUESTION?

Bug

## Describe the problem you're observing.

#### Can you reproduce the problem? If so, describe how. If not, describe troubleshooting steps you took before opening the issue.

https://borgbackup.readthedocs.io/en/1.2.0/changes.html#version-1-2-0-2022-02-22-22-02-22

The sample commands (`--repair`, `compact --cleanup-commits`) **should** include `--` (double ASCII hyphen):

https://github.com/borgbackup/borg/blame/master/docs/changes.rst#L240
https://github.com/borgbackup/borg/blame/master/docs/changes.rst#L246

> run `borg compact --cleanup-commits` to clean up a ton of 17 bytes long files in your repo caused by a borg 1.1 bug

Instead, when displayed on the page (and therefore when copy/pasted) they are rendered with the double hyphen becoming a single Unicode en dash:

> run `borg compact –cleanup-commits` to clean up a ton of 17 bytes long files in your repo caused by a borg 1.1 bug

#### Include any warning/errors/backtraces from the system logs

<!--

If this complaint relates to borg performance, please include CRUD benchmark
results and any steps you took to troubleshoot.
How to run benchmark: http://borgbackup.readthedocs.io/en/stable/usage/benchmark.html

*IMPORTANT* - Please mark logs and text output from terminal commands 
or else Github will not display them correctly. 
An example is provided below.

Example:
```
this is an example how log text should be marked (wrap it with ```)
```
-->



Discussion:
Yeah, that looks bad, it should keep `--` and not transform that.
https://www.sphinx-doc.org/en/master/usage/configuration.html?highlight=dash#confval-smartquotes
We currently have that in `docs/conf.py`:
```
# If true, SmartyPants will be used to convert quotes and dashes to
# typographically correct entities.
html_use_smartypants = True
```

The sphinx version running at RTD is 1.8.6.

https://github.com/borgbackup/borg/commit/b08064bb4ed4bbafcd17281c6b5c92a63cd8a79d

Hmm, is our markup for options wrong? Shall we rather use `smartquotes_action = 'qe'` to disable dashes to avoid such issues?

@enkore ^
Yes, because there are a lot of --option mentions all over the docs. Though we could also change the default role used for \`...\`, because rST thinks it's \<cite\> right now - hence the smartypants. That still wouldn't fix all other occurrences, so disabling this particular conversion seems the best way. (You can search for `–` without matching `-` in Firefox by checking "match diacritics", which does the opposite).

Resolving patch:
diff --git a/docs/conf.py b/docs/conf.py
--- a/docs/conf.py
+++ b/docs/conf.py
@@ -154,6 +154,7 @@ def setup(app):
 # If true, SmartyPants will be used to convert quotes and dashes to
 # typographically correct entities.
 html_use_smartypants = True
+smartquotes_action = 'qe'  # no D in there means "do not transform -- and ---"
 
 # Custom sidebar templates, maps document names to template names.
 html_sidebars = {


Test patch: