getodk / getodk/docs

add details on em and en dash usage to syntax and style guides

Open
#495 0 comments 0 reactions 0 assignees View on GitHub
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

Open the contributing 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

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.