Use of markdown in snap metadata (summary / description)

robert.ancell · January 31, 2019, 2:34am

Do we support nesting i.e. bold and italic? Bold/italic links?

chipaca · March 13, 2019, 10:15am

Can we please remove the support for triple-backticks and titled URLs, until we’ve been able to agree on them?

They both look very ugly on the terminal unless parsed and rendered in some way (links might not have a good way of dealing with them across all supported terminals, so they’d always look ugly).

Gustavo’s original proposal had the enormous advantage of not needing any work for things to look alright on the terminal. We could opportunistically add support for things, but didn’t have to. With the latest additions, unless we do something, it’s going to look ugly.

Please, let’s drop support for things we haven’t agreed to, until we’ve been able to discuss it more?

Thank you.

niemeyer · March 13, 2019, 11:31am

Yes, the original set was very much based on the fact it was properly formatted in the terminal, and it seems to have been lost in translation above without further agreement.

@pheurton @Lukewh Can we please fix that ASAP?

Lukewh · March 13, 2019, 12:05pm

Sure, we’ll get it updated and released ASAP

chipaca · March 13, 2019, 1:20pm

One thing, before it’s released, is there an easy way to alert / update descriptions that are already using the features we’re disabling? Maybe advocacy or store teams can help?

Lukewh · March 13, 2019, 1:22pm

Yeah we’ll be in conversation with them, as we were when we first released the subset

chipaca · March 13, 2019, 1:24pm

Thank you, good to know.

evan · March 13, 2019, 1:55pm

@chipaca would it be acceptable to just strip ``` when displayed in the terminal? Code blocks don’t need special formatting in the terminal, but they are particularly helpful in the web description:

chipaca · March 13, 2019, 2:02pm

not really (I mean, obviously yes, but I think it’s a bad idea, and it’d still take a few months to make it ‘out there’ during which people will be looking at nasty ```s)

However, I’d have 0 issues with us supporting code blocks via indentation.

evan · March 13, 2019, 2:05pm

Ah, okay. Can you elaborate on why it’s a bad idea to strip these out, and why it would take months to get that ‘out there’?

chipaca · March 13, 2019, 2:20pm

because it wouldn’t be markdown, and it wouldn’t be plain text, but something in between. We’d have to update documentation to say “it’s going to be markdown but just now we’re just stripping ```s”, which is rather lame.

And because moving to markdown wasn’t resourced, there is no timetable for when the actual thing is going to happen, so it’d easily be 2020+ before it’s done.

if I landed it in master today, it’d be in 2.39 which I don’t expect to be in stable for a couple of months.

pheurton · March 13, 2019, 4:20pm

@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.

chipaca · March 13, 2019, 4:28pm

From a terminal POV, single `s are ok.

sparkiegeek · March 14, 2019, 5:41pm

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.

chipaca · March 14, 2019, 5:52pm

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 but that’s a 20% / weekends kind of thing, that I don’t expect to come to fruition this year.

evan · March 15, 2019, 9:39am

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?

chipaca · March 15, 2019, 10:00am

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.

evan · March 15, 2019, 10:10am

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

chipaca · March 15, 2019, 3:10pm

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?

niemeyer · March 15, 2019, 3:15pm

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.