saforem2
commented
9 months ago from #317:
Yeah so really my main thought was to try and enforce at most one sentence per line, similar to writing LaTeX, e.g.
Rationale: Extremely long lines can be difficult to work with in some editors. More information: https://cirosantilli.com/markdown-style-guide#line-wrapping.
By starting a new line at the end of each sentence, and splitting sentences themselves at natural breaks between clauses, a text file becomes far easier to edit and version control.
but it really is just a personal / stylistic preference at the end of the day 🤷🏻♂️
A good argument for one sentence per line can be found in the Motivation section from mdslw:
If we want to use a linter (e.g. markdownlint) or or a pre-commit hook, most style guidelines suggest 80 character limits on line length, e.g.
theres also a good discussion on this issue at:
sentences-per-line- style: sentence per line
- Markdown: should we require one sentence per line? #2
- Initial version / proposal of the Markdown style guide #1
- [VOTE] code-styling/markdown: Max line length #2
I personally am of the opinion that enforcing one sentence per line is advantageous.
This forces clean line differences when changing the source text and makes it easier to review changes. Additionally, it ensures that a changed line corresponds to changing (at most) a single sentence.
This makes it easier as a group to see what changed between commits and to point to specific lines where content has changed in the source.
See #317 and https://github.com/argonne-lcf/user-guides/pull/317#issuecomment-1901443879. Related to #69. Doesn't need to be strictly enforced, but could be just noted as recommended style in the README.
The current
.mdsource appears to be a mix of files with hard/semantic line wraps (e.g. 1 sentence per line) like https://github.com/argonne-lcf/user-guides/blob/main/docs/polaris/data-science-workflows/python.md, or mostly no line wraps like https://github.com/argonne-lcf/user-guides/blob/main/docs/polaris/running-jobs.md, or files that switch between conventions internally https://github.com/argonne-lcf/user-guides/blob/main/docs/aurora/data-management/daos/daos-overview.md .It is mostly a matter of style; the biggest issue with mixed convention is that it pollutes the git history when a file changes conventions due to someone's personal preferences or IDE's auto-formatting.
If we want consistent hard line wraps, would need to decide on a character limit, or a semantic limit. My preference is for soft line wrapping, which seems to be most of the current source, or semantic wrapping.