Use of markdown in snap metadata (summary / description)

snapd
33

@niemeyer @chipaca @evan

I know that we just discussed removing support for code blocks and titled URLs but based on the previous replies. Would it be acceptable to…

  • Remove support of titled-URLs [title](link)?
  • Remove support of ``` for code blocks?
  • Remove support of (`) for code in the middle of a sentence?
  • Support code blocks using indentation instead?

So going back to the original list, we will have:

  • Lists (* Foo)
  • Italics (_foo_)
  • Bold (**foo**)
  • Paragraph merging (consecutive lines are joined)
  • Auto-linking of literal URLs
  • Code block by indentation (4 spaces)

Let me know your thoughts.

1 Like
34

From a terminal POV, single `s are ok.

35

Why is snapd CLI attempting to render anything in the description? I humbly suggest that just showing the raw not-really-markdown is just fine.

I stand by my comment above in Use of markdown in snap metadata (summary / description) - we simply need to show publishers how it will look, and let them make their own decisions about what to include or not include.

4 Likes
36

the snapd CLI is not trying to render anything for the description. The last requested changes have been about making sure that that description looks alright unrendered, while still supporting what more rendery frontends need to not scare away their users. That had been the intent all along, but it got a little lost along the way.

I might, at some point, look into rendering what’s possible to render on the terminal. Because it’s fun, and it involves widths of things on the terminal :slight_smile: but that’s a 20% / weekends kind of thing, that I don’t expect to come to fruition this year.

1 Like
37

I still think this is problematic. We have snaps in the Store which make good use [1, 2] of titled URLs. We have snaps which are using ``` code blocks to give usage instructions today [1, 2].

Apologies John, but I find this confusing. Can you please explain how single ` is okay, but ``` is not?

1 Like
38

Ah, thank you for those examples!

electron-mail is actually a very good example of why this should never have gone live as is: it is very messy, almost unreadable towards the end, on the terminal:

  ElectronMail is an [Electron](https://electronjs.org)-based unofficial desktop client for
  [ProtonMail](https://protonmail.com/) and [Tutanota](https://tutanota.com/) end-to-end encrypted
  email providers. The app aims to provide enhanced desktop user experience enabling features that
  are not supported by the official in-browser web clients.
  It is written in [TypeScript](http://www.typescriptlang.org) and uses
  [Angular](https://angular.io).


  **Features**
  - **Cross platform**, Linux/OSX/Windows.
  - **Multi email providers** support.
  - **Multi accounts** support per each email provider. Individual entry point domain selection is
  [enabled](https://github.com/vladimiry/ElectronMail/issues/29).
  - **Automatic login into the app** with remembered master password using
  [keytar](https://github.com/atom/node-keytar) module ("Keep me signed in" feature).
  - **Automatic login into the email accounts**, including filling [2FA
  tokens](https://github.com/vladimiry/ElectronMail/issues/10).
  - **Encrypted settings storage** with switchable predefined key derivation and encryption presets.
  Argon2 is used as the default key derivation function.
  - **Native notifications** for individual accounts clicking on which focuses the app window and
  selects respective account in the accounts list.
  - **System tray icon** with a total number of unread messages shown on top of it. Enabling [local
  messages store](https://github.com/vladimiry/ElectronMail/issues/32) improves this feature ([how
  to enable](https://github.com/vladimiry/ElectronMail/releases/tag/v2.0.0-beta.1)), see respective
  [issue](https://github.com/vladimiry/ElectronMail/issues/30).
  - **Switchable view layouts** (full, tabs and dropdown). See details
  [here](https://github.com/vladimiry/ElectronMail/issues/36) and screenshots in
  [images](https://github.com/vladimiry/electronmail/tree/master/images) folder.
  - **Batch emails export** to EML files. Feature released with
  [v2.0.0-beta.4](https://github.com/vladimiry/ElectronMail/releases/tag/v2.0.0-beta.4) version,
  requires `local messages store` feature to be enabled ([how to
  enable](https://github.com/vladimiry/ElectronMail/releases/tag/v2.0.0-beta.1)).
  - **Full-text search**. Enabled with
  [v2.2.0](https://github.com/vladimiry/ElectronMail/releases/tag/v2.2.0) release.
  - Option to use a **built-in/prepackaged web client** instead of loading the online page. The
  built-in web clients are built from source code, see respective official
  [Protonmail](https://github.com/ProtonMail/WebClient) and
  [Tutanota](https://github.com/tutao/tutanota) repositories. See
  [original](https://github.com/vladimiry/ElectronMail/issues/79) issue for details.
  - Start **minimized to tray**.
  - **Close to tray**.

  **NOTE:** To use the __Keep me signed in__ feature please enable the password manager service by
  either running the following command in the terminal or by clicking on the "Permissions" button:

   ```
  sudo snap connect electron-mail:password-manager-service
  ```

  This is required to connect the snap with the system's default keyring to save and access
  encrypted passwords securely.

tqdm shows you why ``` isn’t a good fit for the terminal also, and also why `s are ok (granted their use of "s wrapping `s looks a little bit weird, but note how `tqdm` looks fine)

  https://tqdm.github.io

  `tqdm` means "progress" in Arabic (taqadum, تقدّم) and is an
  abbreviation for "I love you so much" in Spanish (te quiero demasiado).

  Instantly make your loops show a smart progress meter and stats - just replace any pipe "`|`" with
  "`| tqdm |`", and you're done!

  ```sh
  $ seq 9999999 | tqdm --bytes | wc -l
  75.2MB [00:00, 217MB/s]
  9999999
  $ 7z a -bd -r backup.7z docs/ | grep Compressing | \
      tqdm --total $(find docs/ -type f | wc -l) --unit files >> backup.log
  100%|███████████████████████████████▉| 8014/8014 [01:37<00:00, 82.29files/s]
  ```

  Overhead is low -- about 60ns per iteration.

  In addition to its low overhead, `tqdm` uses smart algorithms to predict
  the remaining time and to skip unnecessary iteration displays, which
  allows for a negligible overhead in most cases.

  `tqdm` works on any platform (Linux, Windows, Mac, FreeBSD, NetBSD,
  Solaris/SunOS), in any console or in a GUI, and is also friendly with
  IPython/Jupyter notebooks.

  `tqdm` does not require any dependencies, just
  an environment supporting `carriage return \r` and
  `line feed \n` control characters.

those ```'s are just line noise, especially given that an indented block would achieve the same thing.

cavestory suffers from a lesser case of electron-mail's problem with the links getting in the way of reading. altair fares better.

To explain the ``` vs ` thing in words: the triple backticks go on a line of their own, and seem to be line noise to a user unfamiliar with, or not expecting, markdown. Single backticks work as quotes, which are part of the language.

39

If you’re technical enough to be using the terminal, are you really going to be surprised by Markdown?

40

you can be technical enough for a lot of things, and yet not want to see ugly…

However, there are several developers that have already started using this, and I can see how it could be inconvenient and a hassle (and losing cred) to go back to them and say “akshully, herp derp”. On the other hand, I hope you appreciate how ugly descriptions have become when unrendered thanks to this work.

While I’ve gone on about ```s being ugly, the real problem is with links making paragraphs unreadable. I think if we absolutely need titled links, as opposed to autolinks, and the feedback I’ve heard is that we do (but I don’t get to decide this), then I propose we support shortcut reference links instead:

Rather than

ElectronMail is an [Electron](https://electronjs.org)-based unofficial
desktop client for [ProtonMail](https://protonmail.com/) and
[Tutanota](https://tutanota.com/) end-to-end encrypted email providers. The
app aims to provide enhanced desktop user experience enabling features that
are not supported by the official in-browser web clients.  It is written in
[TypeScript](http://www.typescriptlang.org) and uses
[Angular](https://angular.io).

it would be

ElectronMail is an [Electron]-based unofficial desktop client for [ProtonMail]
and [Tutanota] end-to-end encrypted email providers. The app aims to provide
enhanced desktop user experience enabling features that are not supported by
the official in-browser web clients.  It is written in [TypeScript] and uses
[Angular].

[Electron]: https://electronjs.org
[ProtonMail]: https://protonmail.com/
[Tutanota]: https://tutanota.com/
[TypeScript]: http://www.typescriptlang.org
[Angular]: https://angular.io

As you can see, it degrades a lot better.

@niemeyer would you agree to have indented blocks for literals, and shortcut reference links, supported in the web (and eventually our GUI clients)?

If we do agree on this, we could

  • make the web editor stop talking about ``` pairs, and [foo](bar) links, and instead talks about indented blocks and shortcut reference links.
  • continue to support ``` blocks and [foo](bar) links on the web, for rendering only
  • reach out to people using the old features, explain that because they render so poorly on the terminal and offer assistance
  • in a couple of months, drop support for the old

WDYT?

1 Like
41

Can we please go back to supporting the minimum that was defined and supposedly agreed a long time ago, before we try to be more inventive?

This is a description for the software… it’s not the software’s web page, and I’d prefer to avoid structure that would encourage people to consider it as such and render the information less valuable as an actual 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.

1 Like
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.
1 Like
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

1 Like
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?

1 Like
50

Hi,

It’s been a while, and since the last response, snapcraft.io has been working as agreed here.

Is there any possibility to consider expanding the capabilities as some people suggested here?

As a maintainer of snapcraft.io, I would love to stick to a standard like CommonMark, some of the work done previously has caused issues for users:

For comparison, we use CommonMark on charmhub.io on all the charms details pages and libraries, and we never had any issues with it.

Could we consider using a Markdown standard on snapcraft.io?

3 Likes
51

Another advantage of using a standard markdown is that you can reuse an existing library for the implementation and therefore be building on the back of someone else’s work instead of reinventing the wheel. This will reduce the burden on the snapcraft.io maintainers and allow for security coverage to be managed much easier.

2 Likes
52

This is a really bad take in my opinion. A lot of software on the store is difficult to understand how to use it, or there are required steps to follow before you can use it. This is not about replicating a webpage but to explain to users how to use our software. Yes there is a descriptive property, but there is also the requirement to inform users about how to use the app - I’d argue instructions are also description because it helps the user understand the requirements BEFORE they install the software so can make an informed decision on whether they want to do so. Without the abilities we’ve discussed here, particularly fenced code blocks and named hyperlinks, users will install complex apps and immediately uninstall or complain to the developer (or this forum) because they can’t drive it without the instructions.

Sure you could ignore that premise and people won’t use the store for apps that need instructional material to get going. Instead either the developer will ignore the snap store for being too difficult or they’ll ignore the description field entirely and not provide anything useful at all beyond a duplication of what they put in their summary.

One of the biggest marketing efforts of the Snap ecosystem has historically promoting the ease of developer experience. This discussion and the decision to restrict the description in these ways flies in the face of that messaging.

Also: named hyperlinks are an accessibility thing. With a plain hyperlink (URL only) people, visually impaired and otherwise, are unable to understand the purpose of the link.

1 Like