add details on em and en dash usage to syntax and style guides
- Dominant language
- Python
- Stars
- 58
- Forks
- 160
- Avg merge
- 5d 11h
- Merged PRs (30d)
- 12
Description
`--` (two hyphens) is auto converted by Sphinx to en-dash
and
`---` (three hyphens) is auto converted to em-dash
en-dashes should be used for ranges and connecting
```
0--60
1776--1976
the Bigg--Dealio wedding
```
em dashes should be used for in-sentence separation
```
One problem with em dashes --- and there are many --- is that they are hard to distinguish in fixed-width fonts.
```
Em-dashes should be set-off with spaces.
(This is a debated style, but I think it reads better.)
Em-dashes should also be used sparingly. Their use tends toward conversational, multi-nested, complex sentences. This is fine in some explanatory content, but can be confusing in procedural writing.
Also, avoid using em-dashes as a stand-in for definition lists.
```
BAD
- Item --- Explanation of item.
- Item --- Explanation of item.
```
Contributor guide
Research direction
Locate the syntax and style guides in the Sphinx documentation source and review the existing guidance around dashes. Done means documenting en-dash ranges and connections, spaced em-dash usage and cautions, and the definition-list example, with the supplied examples represented appropriately.
Written by the indexing model from the issue text.
Assessment
- Domain
- documentation
- Issue type
- Documentation
- Difficulty
- 2/5
- Estimated time
- 1-3 hours
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 38/100