Use of markdown in snap metadata (summary / description)


#42

We are already here. Removing this functionality would degrade the presentation of snaps on snapcraft.io.

It has not been argued that a web page’s worth of content should be presented in a description. Indeed, being able to link off to other pages keeps the description focused on the app’s merits.

Code blocks are useful to demonstrate the utility of your application through examples. Countless manpages and the success of tldr evidence this. Developers like Andrzej wouldn’t be using this if they didn’t think it would help people understand and be motivated to install their app.

It is also worth noting that code blocks are helpful in outlining post-install instructions. You can find many cases in the store walking the end user through connecting needed interfaces or placing assets in the right directory.


#43

I believe the events were:

  1. Someone designed a specific format to ensure it would look good on the terminal
  2. The proposition was presented, and agreed to as a good start
  3. Something else was implemented instead
  4. People used the new formatting
  5. It now looks awful on the terminal

So, the pain was self-inflicted, and we need to fix it.

The suggested corrective action is:

  1. Fix the formatting ASAP, as already requested above, to ensure we don’t derail further
  2. Fix the formattings that are broken in the web to ensure they conform

We can then discuss further improvements to the formatting, but anything is pointless if we don’t follow through on our agreements. It’s also important to understand their rationale.

I think it’s fine to handle four-space indented blocks as mono-spaced code blocks. That will also look good on the terminal. I would suggest using the same logic as Discourse: needs to be indented by 3 spaces or more, and with an empty line above and one below.


#44

I had assumed (in absence of being able to do actual links inside a terminal) you would render inline links in a style similar to the shortcut reference links. Is that acceptable in a text renderer or does that transform the text too much? From an editors point of view the inline links are easier to write and manage.


#45

I do not think we should rush into this.

  1. Taking features away from people sets a bad precedent.
  2. At some point we must accept that requiring presentation in all other clients match what’s possible in the terminal severely limits our ability to create a compelling experience in these richer environments.

#46

We are not rushing. The syntax proposed here is from September of 2017, and the awful presentation in the terminal is real, as anticipated.

Let’s please address this as a matter of urgency so we stop the improper syntax from being used and so that we can fix the terminal presentation for those already using it.


#47

FWIW we have updated snapcraft.io in a demo URL with the following list:

  • Lists (* Foo)
  • Italics (foo)
  • Bold (foo)
  • Paragraph merging (consecutive lines are joined)
  • Auto-linking of literal URLs
  • No titled URLs
  • Code in sentence using single backtick (`)
  • No ``` backticks for code blocks
  • Support for code blocks with 3 spaces (for now) one line above and below the code block. We will add support for 3 or more spaces for code blocks shortly after.

You can check the changes in the following demo URL: https://snapcraft-io-canonical-websites-pr-1694.run.demo.haus/ , so we are ready on our side to release if everyone is happy.

Some example to look at:
https://snapcraft-io-canonical-websites-pr-1694.run.demo.haus/electron-mail
https://snapcraft-io-canonical-websites-pr-1694.run.demo.haus/fuzzy-repo-finder


#48

The syntax you proposed was in September 2017. There was further discussion through October and November, resulting in the proposal that included title URLs and code blocks. The feature went live at the end of January. Given that it’s been over a month and a half without a single end user complaint, perhaps this urgency is unwarranted.

We should first discuss and put ourselves on record accepting the implications of reverting, should that prove necessary. Removing title URLs and code blocks as backticks would break presentation for existing apps, create unanticipated work for the authors, and potentially leave an impression that future features may be taken away without notice.

I do not think we should treat that lightly.


#49

There was a very specific rationale used for the proposed syntax, which has proven correct in practice rather than in theory. I don’t know how to say that more emphatically: we don’t want to have rich syntax that turns the terminal interactions into a mess.

Can we please stop arguing to thread carefully, and fix the problem right now before it spreads further?