Markdown: one sentence per line

simonrelet commented 6 years ago

# Options (if any):
--parser markdown

Input:

## Building and enforcing a style guide

By far the biggest reason for adopting Prettier is to stop all the on-going debates over styles. It is generally accepted that having a common style guide is valuable for a project and team but getting there is a very painful and unrewarding process. People get very emotional around particular ways of writing code and nobody likes spending time writing and receiving nits.

Output:

## Building and enforcing a style guide

By far the biggest reason for adopting Prettier is to stop all the on-going
debates over styles. It is generally accepted that having a common style guide
is valuable for a project and team but getting there is a very painful and
unrewarding process. People get very emotional around particular ways of writing
code and nobody likes spending time writing and receiving nits.

Expected behavior:

I would love an option to have the markdown formatting follow the one sentence per line technique. There's are good explanation in Asciidoctor's recommended practices.

## Building and enforcing a style guide

By far the biggest reason for adopting Prettier is to stop all the on-going debates over styles.
It is generally accepted that having a common style guide is valuable for a project and team but getting there is a very painful and unrewarding process.
People get very emotional around particular ways of writing code and nobody likes spending time writing and receiving nits.

ikatyang commented 6 years ago

Ref: previous discussion https://github.com/prettier/prettier/issues/3183#issuecomment-342644669 https://github.com/prettier/prettier/pull/3199#issuecomment-342664082

suchipi commented 6 years ago

I wrote a lot of markdown over the weekend and found myself wanting this option, too. But I do have concerns about detecting sentences properly.

tibdex commented 6 years ago

Hi all and thanks for this amazing tool,

I think the one sentence per line technique makes a lot of sense. For me, the It prevents reflows point of Asciidoctor is really important. Indeed, currently, if I change a sentence in a paragraph by removing/adding characters it will very likely lead to a diff impacting all the remaining lines/sentences of this paragraph. It obviously makes the diff harder to read as it's not immediate to pinpoint the actual small change. This problem would not happen with the one sentence per line technique.

https://github.com/prettier/prettier/pull/3199 added the --no-prose-wrap option but it still prevents having one sentence per line:

Input (manually writing one sentence per line):

By far the biggest reason for adopting Prettier is to stop all the on-going debates over styles.
It is generally accepted that having a common style guide is valuable for a project and team but getting there is a very painful and unrewarding process.
People get very emotional around particular ways of writing code and nobody likes spending time writing and receiving nits.

Default output:

By far the biggest reason for adopting Prettier is to stop all the on-going
debates over styles. It is generally accepted that having a common style guide
is valuable for a project and team but getting there is a very painful and
unrewarding process. People get very emotional around particular ways of writing
code and nobody likes spending time writing and receiving nits.

Output with `--no-prose-wrap`:

By far the biggest reason for adopting Prettier is to stop all the on-going debates over styles. It is generally accepted that having a common style guide is valuable for a project and team but getting there is a very painful and unrewarding process. People get very emotional around particular ways of writing code and nobody likes spending time writing and receiving nits.

Expected behavior:

The output is the same as the input: Prettier didn't put all the sentences of the paragraph into a single line.

Should we change the --no-prose-wrap so that it doesn't actually wrap prose in any way? Or should we change it to an option with three values (not sure about the naming):

proseWrap:
  'usePrintWidth' /* current default */
  | 'oneLinePerParagraph' /* same as --no-prose-wrap */
  | 'off' /* let the sentences where they are */

What do you think?

lydell commented 6 years ago

@tibdex The pros and cons of having all on one line vs. wrapping at 80 chars vs. wrapping after each sentences are known. And if sentence-wrapping is added, there will be three choices. The only missing pieces are:

How much demand is it for this feature? This will take some time to find out. So far this issue only has 1 :+1:
How should a sentence be defined?

tibdex commented 6 years ago

How should a sentence be defined?

That's the hard part of course.

I did some research and found that Prettier uses remark-parse which is a unified parser. So the integration with retext plugins should be doable. In particular, there is retext-english wrapping parse-english which is able to produce an AST with SentenceNode. For other latin-based languages there is parse-latin but it's not ideal according to https://github.com/wooorm/remark/issues/25.

So I guess adding robust support for one sentence per line auto-formatting in any language would require a huge amount of work and would maybe still lead to mediocre results.

Do we still want to try it? Maybe just for English or maybe with a disclaimer saying that it only works well with latin-based languages? Or do you think it's feature creep and that NLP shouldn't be baked inside Prettier? If it's not the role of Prettier to perform one sentence per line auto-formatting, then shouldn't we provide an option to completely disable prose wrapping like I suggested in my previous comment? It would allow people to use a dedicated tool for one sentence per line formatting without loosing all the other Markdown-formatting goodies provided by Prettier!

lydell commented 6 years ago

Nice research @tibdex! 👍

Also, thanks for pointing out your alternative proposal: Preserving the original wrapping of text. I missed that.

simonrelet commented 6 years ago

Preserving the original wrapping of the text is a good compromise.

jbe456 commented 6 years ago

So I guess adding robust support for one sentence per line auto-formatting in any language would require a huge amount of work and would maybe still lead to mediocre results.

What about considering a configuration with a sentence separator and a list of exceptions?

There would be no default since the configuration would heavily depend on the project. Choosing the option proseWrap: oneLinePerSentence would require to define two mandatory parameters: a sentence separator and a list of exceptions

For most project/languages it would look like:

sentence separator: .
exceptions: ["1.", "2.", ... "Mr.", "Mrs.", "Ms.", "Dr.", "Sr.", "Jr.", "b.c.", "a.m.", "A.M.", "p.m.", "P.M.", "i.e.", "etc.", "e.g.", "al." ...]

For Japanese:

sentence separator: 。
exceptions: ?

etc

It seems like it would make the development much cheaper while still being flexible enough to fulfill most, if not all, of the "one sentence per line" use case.

The big drawbacks I foresee is that:

it's an additional configuration, and I know this project does not like that :wink:
while running Prettier one would need to check the diff in order to make sure that you did not forget to add any exceptions... otherwise it might cut a sentence in half!

suchipi commented 6 years ago

Since prettier is an opinionated formatter, I don't think such an option will be making it in anytime soon. I also think there might be less friction in doing the line breaks by hand than to try to maintain a list of exceptions, which feels it would grow larger and larger as time went on. However, with --prose-wrap preserve, you could prettier in conjunction with an additional tool that wraps sentences if you wanted to.

azu commented 6 years ago

How should a sentence be defined?

FYI: https://github.com/diasks2/pragmatic_segmenter

prettier / prettier