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.
Someone designed a specific format to ensure it would look good on the terminal
The proposition was presented, and agreed to as a good start
Something else was implemented instead
People used the new formatting
It now looks awful on the terminal
So, the pain was self-inflicted, and we need to fix it.
The suggested corrective action is:
Fix the formatting ASAP, as already requested above, to ensure we don’t derail further
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.
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.
Taking features away from people sets a bad precedent.
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.
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.
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.
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.
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?
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.
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.
