python-tooling
python-tooling copied to clipboard
UCL-ARC
Feature suggestion: Automating wrapping markdown one-sentence-per-line
Is Your Feature Request Related to a Problem? Please Describe
Add an automated way to wrap markdown files at 80 (@dstansby: maybe a bit more??) characters.
Suggested by @paddyroddy in https://github.com/UCL-ARC/python-tooling/pull/335#discussion_r1537991316.
Describe the Solution You'd Like
An automated way to wrap markdown files in the pre-commit config.
Describe Alternatives You've Considered
No response
Additional Context
No response
Identified in https://github.com/UCL-ARC/python-tooling/issues/361 proseWrap broke things due to https://github.com/prettier/prettier/issues/9232. This might be fixable by a different markdown parser, or not using the RST-like hyperlink format.
I'd vote against autowrapping Markdown. From my perspective:
- It can make minor changes lead to unnecessarily large diffs.
- It adds extra faff while editing - either you try to manually reflow text to keep to line length limit or have to apply a reformatter after making edits.
- Markdown unlike source code is generally naturally reflowable by soft wrapping as indentation is (mostly) not used to indicate structure.
It can make minor changes lead to unnecessarily large diffs.
I actually wholeheartedly disagree with this bit. When markdown is not wrapped and someone changes a few words in a paragraph, it can be very long.
I wrap markdown for my own stuff. But just because I quite like to cat flibble.md and read it in a terminal.
No strong opinion other than: if we do decide a policy of wrapping it should be linter-ed.
I wrap markdown for my own stuff. But just because I quite like to
cat flibble.mdand read it in a terminal.
You may already know but in case it's helpful: as an alternative to cat flibble.md, fmt flibble.md will display word wrapped content of flibble.md without touching file.
I'm also -1 on wrapping Markdown at a fixed number of characters, and agree with reasons in https://github.com/UCL-ARC/python-tooling/issues/337#issuecomment-2165251499. Generally I try and do one-sentence-per-line, for reasons outlined here: https://nick.groenen.me/notes/one-sentence-per-line/, which I think addresses https://github.com/UCL-ARC/python-tooling/issues/337#issuecomment-2165291128 too, so perhaps we could look for a linter that wraps whole sentences, or just leave this as is with no automatic markdown wrapping?
I'm also -1 on wrapping Markdown at a fixed number of characters, and agree with reasons in #337 (comment). Generally I try and do one-sentence-per-line, for reasons outlined here: nick.groenen.me/notes/one-sentence-per-line, which I think addresses #337 (comment) too, so perhaps we could look for a linter that wraps whole sentences, or just leave this as is with no automatic markdown wrapping?
@p-j-smith found some one-sentence-per-line linter, but it was impractically slow
Generally I try and do one-sentence-per-line, for reasons outlined here: https://nick.groenen.me/notes/one-sentence-per-line/, which I think addresses #337 (comment) too, so perhaps we could look for a linter that wraps whole sentences, or just leave this as is with no automatic markdown wrapping?
One sentence per line seems a good recommendation to me - if nothing else it'll make me notice, and hopefully be more likely to fix, my tendency towards overly long sentences (this one being a case in point 😅).
Is consensus here that we
- would like to wrap markdown at one sentence per line, but there's no technical solution we can find at the moment
- don't want to wrap at a hard character limit
? If so I'll edit the title of the issue and we can keep on the lookout for a one-sentence-per-line linter
Not sure if it helps us in the quest for one-sentence-per-line but..
- https://sembr.org/
Is a thing.
Was this what Paul found? https://github.com/JoshuaKGoldberg/sentences-per-line
Looks to be a markdownlint rule that we could test.
Was this what Paul found? JoshuaKGoldberg/sentences-per-line
Looks to be a
markdownlintrule that we could test.
Just trying to find what it was
Found it! Yes it was that one, see discussion here https://github.com/UCL-MIRSG/MIRSG/issues/191 (screenshot, as you might not have access)
I ended up using Prose Wrap from prettier