Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Decide on line wraps: hard wraps, soft wraps, semantic wraps #330

Open
felker opened this issue Jan 30, 2024 · 1 comment
Open

Decide on line wraps: hard wraps, soft wraps, semantic wraps #330

felker opened this issue Jan 30, 2024 · 1 comment

Comments

@felker
Copy link
Member

felker commented Jan 30, 2024

See #317 and #317 (comment). Related to #69. Doesn't need to be strictly enforced, but could be just noted as recommended style in the README.

The current .md source 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.

@saforem2
Copy link
Member

saforem2 commented Jan 30, 2024

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.

-Semantic linefeeds:

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:

Motivation

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:

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.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

No branches or pull requests

2 participants