Format Application Service schema

[V02460]

Minor formatting of the Application Service schema files. This PR

• removes spurious line breaks in the descriptions by switching from literal strip (|-) to folded strip (>-) YAML string representation (https://yaml-multiline.info/)
• Keeps a line length of 80+10% characters (similar to how black does it)
• Ensures trailing newlines

Pull Request Checklist

• Pull request includes a changelog file
• Pull request includes a sign off
• Pull request is classified as 'other changes'

[zecakeh]

removes spurious line breaks in the descriptions by switching from literal strip (|-) to folded strip (>-) YAML string representation (https://yaml-multiline.info/)

The descriptions are written using Markdown (just like most of the spec) so we don't really care about "spurious" line breaks, they should be removed by the Markdown parser.

In my opinion, switching to the folded strip is worse, because the text does not behave as Markdown. For example we need to put 2 empty lines between paragraphs.

[anoadragon453]

element-hq/synapse#17892 (comment) is relevant to this discussion. I expect whatever solution we end up using there, can be useful here.

[richvdh]

sorry, I've read the thread at element-hq/synapse#17892 (comment) and am still not really clear why this is an improvement.

That thread appears to cite "tools handling the descriptions as plaintext" as a reason to prefer the >- style (complete with triple-linebreaks), but what tools do we have that do so? The thread includes a screenshot of "literal style with additional line breaks" which does indeed look awful, but where would that actually appear?

In this instance: our primary tooling is the spec, and https://playground.matrix.org, both of which treat the description as markdown. https://swagger.io/specification/#rich-text-formatting again says that the description is markdown.

So, could someone explain like I'm 5: what exactly goes wrong if we use |- style here?

/cc @anoadragon453 @V02460

[V02460]

Hey, sorry to have caused such confusion 😅 I hope this explanation will clear things up.

Take as a motivational example the editing of a registration file in VS Code. Additional IDE support is available when providing its schema file. Hovering over a key will give you a popup with its description string rendered in plain text. You can see that the flow of the text is borked because of the additional newline in the description.

To support both Markdown and plain text descriptions in tools, I propose restricting the description texts to a subset of Markdown: Markdown, but without any newlines in paragraphs.

Up to this point, nothing is specific to the different ways YAML can express one and the same string – but of course we have to choose one of them in the end. Here is the same description string expressed in three different YAML format styles:

styles:
    quote: "The first paragraph without any linebreaks inside.\n\nThe second paragraph that is separated by two linebreaks from the first."
    literal: |-
        The first paragraph \
        without any \
        linebreaks inside.

        The second paragraph \
        that is separated by \
        two linebreaks from \
        the first.
    folded: >-
        The first paragraph
        without any
        linebreaks inside.


        The second paragraph
        that is separated by
        two linebreaks from
        the first.

Quoted style is just a very long line without any formatting, but with noisy escape characters. Literal style gets either very long lines or these annoying backslashes (when requiring no linebreaks in paragraphs). Folded style gets the additional line break between paragraphs.

[richvdh]

Right, I see; thanks for the explanation.

My feeling is that having to remember to use triple-linebreaks for paragraph breaks is a high price to pay for compatibility with VSCode, and I'm reluctant.

FWIW, I tried the same things in a JetBrains IDE, and it copes fine with |- with linebreaks.

Maybe we could make an exception in cases where we think it is particularly likely that we think people will be hand-writing YAML using the schema, but that seems unlikely for all the API endpoints.

So, -0.5 from me. If other SCT members and regular contributors are strongly in favour, I'll not insist.

[clokep]

I'm in agreement with @richvdh.

[anoadragon453]

Changes LGTM, other than the outstanding discussion at https://github.com/matrix-org/matrix-spec/pull/2131/files#r2038004161