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

Add "semantic line break" support (alternative to proseWrap: always) #16189

Draft
wants to merge 4 commits into
base: main
Choose a base branch
from

Conversation

benjie
Copy link

@benjie benjie commented Apr 2, 2024

Description

Hello, I am aware of the "no new options" philosophy and thus understand that you might wish to reject this PR, as such I have only invested an hour into stubbing it out. Please, however, hear me out.

I use prettier heavily in my day to day work, across many languages. I think it's a fantastic piece of software, so much so that I spearheaded the work to format the GraphQL Specification using prettier and the work required for the underlying tool, spec-md, to support prettier's flavour of Markdown formatting. This enabled us to spend less time concerned with the formatting of someone's spec pull request since it was already enforced, and the line wrapping (proseWrap: always) was essential for this.

However, small changes in specification text can cause significant re-wrapping, which makes review harder. For example, here's a recent pull request where I italicised some keywords (selection set -> _selection set_) and in may places that has caused entire paragraphs to re-wrap, causing reviewers to have to check the changes more carefully:

image

As previously mentioned, wrapping prose is essential to us for line-length reasons; however this re-wrapping is problematic.

This issue isn't limited to the GraphQL specification of course, anyone who writes large amounts of prose in Markdown will likely have felt this pain - documentation website and READMEs in particular are heavily hit by it.

I recently became aware of the Semantic Line Breaks Specification (SemBr) and thought that this would make a good alternative to proseWrap: always. This PR is a "proof of concept" to explore this idea and see if it's something that you might consider adding to Prettier. Arguably it's not a new option, it's just an alternative value for an existing option 😉

In Semantic Line Break mode, the rewrapping of the text is limited to the sentence (or parts thereof), rather than the paragraph, thus the above diff would have looked like:

-Since the result of evaluating a selection set is ordered,
+Since the result of evaluating a _selection set_ is ordered,
 the serialized Map of results should preserve this order by writing the map
 entries in the same order as those fields were requested as defined by
 selection set execution.
 Producing a serialized response where fields are represented in the same order
 in which they appear in the request improves human readability during debugging
 and enables more efficient parsing of responses if the order of properties can
 be anticipated.

This is a draft PR, so I have not yet added documentation or changelog changes. There's no point doing so if you are not interested in the option.

Checklist

  • I’ve added tests to confirm my change works.
  • (If changing the API or CLI) I’ve documented the changes I’ve made (in the docs/ directory).
  • (If the change is user-facing) I’ve added my changes to changelog_unreleased/*/XXXX.md file following changelog_unreleased/TEMPLATE.md.
  • I’ve read the contributing guidelines.

Try the playground for this PR

@benjie
Copy link
Author

benjie commented Apr 2, 2024

The main issue that I saw whilst writing this is that adding newlines after commas can lead to text like:

I use prettier daily to format my markdown,
TypeScript,
JavaScript,
JSON,
HTML,
CSS,
yaml,
and other file formats that I work with.
I particularly like how prettier supports "languages within languages",
whereby my markdown can contain JavaScript,
which can in turn contain GraphQL,
and yet all of the different languages are formatted how I would expect.
Prettier is amazing!
:sparkles: 

Note how each list item is on it's own line. Thinking about it, this seems like a feature rather than a bug, for example adding "GraphQL," to that list between JSON and HTML would not
require any re-wrapping. Note that SemBr does not require newlines after commas (even the recommendation is a little subtle), so if this became a blocker I'd be happy to remove it and
limit semantic linebreaks to sentences (., ! and ?) - that would still be a significant improvement over the status quo.

Perhaps you'd consider adding ., !, and ? forced linebreaks to the default proseWrap: always, then we wouldn't need the sembr setting at all?

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

Successfully merging this pull request may close these issues.

None yet

1 participant