Snap multi-line descriptions need newline trim on store import

All snap multi-line descriptions which are automatically transferred to the online store need a newline trim on import.

Example: https://snapcraft.io/inkscape

Notice all the excess newlines.

This seems to apply to all snaps which have not been manually corrected/edited via the web interface.

The example you give is an accurate rendering of the description that is present in the snapcraft.yaml - as per http://yaml-multiline.info/ Inkscape probably wants to use > instead of | for their multi-line description.

I have created a merge request upstream to fix it.

I just want to point out that it seems many/most snaps have not used ‘>’ for their descriptions. If you browse the snap store you will see that every second snap or so suffers from this.

That won’t actually fix it though, surely? The store description pasted into the webUI takes priority over any updated yaml? (at least that used to be the case)

Ah, this is a very topical question @popey - did you see Update store metadata ? This describes how one can update metadata from a snap upload and resolve conflicts from the store UI.

Yes, and I hope that my merge request will help the publishers of those snaps understand how to fix their snapcraft.yaml to address this issue.

We should not munge descriptions in the store, new-lines in the description should be respected so that publishers can format their description (within the limits of the YAML)

Perhaps update all snapcraft doc examples to use ‘>’ instead of ‘|’ to make people avoid repeating this mistake:

2 Likes

I did not, thanks!

Let’s please not use or encourage people to use “>” in snapcraft.yaml. The resulting string is modified in a non-obvious way, and corrupts the original intention of the author, which is surprising and will present bad results in the terminal, and probably in the web as well.

For example:

>>> yaml.load(""">                                                                                                                                                       
...   Foo                                                                                                                                                                
...   Bar                                                                                                                                                                
...                                                                                                                                                                      
...   Baz                                                                                                                                                                
...                                                                                                                                                                      
...                                                                                                                                                                      
...   Bam                                                                                                                                                                
... """)                                                                                                                                                                 
'Foo Bar\nBaz\n\nBam\n'                                                                                                                                                  
>>> print _                                                                                                                                                              
Foo Bar                                                                                                                                                                  
Baz

Bam

What rules does markdown have wrt newlines?

I ask because it’s mentioned elsewhere that we’ll be moving to support a limited subset of markdown, so it’d make sense to make it as friction-free as possible

1 Like

From https://daringfireball.net/projects/markdown/syntax#p

PARAGRAPHS AND LINE BREAKS
A paragraph is simply one or more consecutive lines of text, separated by one or more blank lines. (A blank line is any line that looks like a blank line — a line containing nothing but spaces or tabs is considered blank.) Normal paragraphs should not be indented with spaces or tabs.

The implication of the “one or more consecutive lines of text” rule is that Markdown supports “hard-wrapped” text paragraphs. This differs significantly from most other text-to-HTML formatters (including Movable Type’s “Convert Line Breaks” option) which translate every line break character in a paragraph into a <br /> tag.

When you do want to insert a <br /> break tag using Markdown, you end a line with two or more spaces, then type return.

Yes, this takes a tad more effort to create a <br />, but a simplistic “every line break is a <br />” rule wouldn’t work for Markdown. Markdown’s email-style blockquoting and multi-paragraph list items work best — and look better — when you format them with hard breaks.

(testing with common mark shows this still holds true there).

Interestingly, github-flavoured markdown doesn’t do that.

1 Like

In general markdown does (or tries to do) the right thing one would expect when looking at the pure text, which partly explains its popularity. That said, the double space at the end is a major mistake that we shouldn’t repeat or depend on. The right thing for breaking paragraphs on our end is just having an empty line, which will also do the right thing on markdown per the first paragraph in the explanation.

1 Like

Correct, and markdown does that. The two spaces at the end thing is for line breaks, not paragraph breaks.

For things
like poetry
y’know?

1 Like

@chipaca The person who invented that semantics should be locked up in a room with an invisible key somewhere inside it.

@chipaca’s table of people that hate markdown, and why

why who
just hate poetry @niemeyer
1 Like