How many people here think that CommonMark is plain-text readable?

rokejulianlockhart · March 12, 2025, 12:45pm

Yes
No
Sometimes

0 voters

Context

I’ve used Markdown dialects for a few years across Discourse, GitHub, GitLab, Plume, WriteFreely, and Bugzilla, et cetera. However, solely as a markup language designed to be rendered.

Although I’ve never heard of its syntax being a problem in Discourse wikis, where the generally non-technical appear to be able to participate (and, consequently, read) without problem, I was recently told that some BRs that I considered to be very readable in plain-text format:

Example

SUMMARY
-------

Providing an HTTP[S] URI serving a `.flatpak` file to the `--local-filename` flag of `plasma-discover-6.3.2-1.fc41.x86_64` results in an error, despite it functioning with a `file:///` URI pointing to the same file (when stored locally). Considering that `flatpak-1.16.0-1.fc41.x86_64`, OSTW's `zypper`, and FC41's `dnf5-5.2.10.0-2.fc41.x86_64` all support HTTP URIs as arguments to their installation parameters, Discover should support this.

STEPS TO REPRODUCE
------------------

1. Install `plasma-discover-6.3.2-1.fc41.x86_64`.
2. Provide an HTTP[S] URI serving a `.flatpak` file to its `--local-filename`.

OBSERVED RESULT
---------------

If accessed via `firefox-136.0-2.fc41.x86_64`, I see a valid response:

> ~~~HTTP
> HTTP/2 200 
> content-type: application/octet-stream
> last-modified: Mon, 11 Mar 2024 04:36:49 GMT
> etag: "0x8DC4184DE4008CC"
> server: Windows-Azure-Blob/1.0 Microsoft-HTTPAPI/2.0
> x-ms-request-id: 5af19293-b01e-003f-0239-9129f6000000
> x-ms-version: 2025-01-05
> x-ms-creation-time: Mon, 11 Mar 2024 04:36:49 GMT
> x-ms-blob-content-md5: zmnaghRa6M/tXsmxRbDXBg==
> x-ms-lease-status: unlocked
> x-ms-lease-state: available
> x-ms-blob-type: BlockBlob
> content-disposition: attachment; filename=naps2-7.4.0-linux-x64.flatpak
> x-ms-server-encrypted: true
> via: 1.1 varnish, 1.1 varnish
> fastly-restarts: 1
> accept-ranges: bytes
> date: Sun, 09 Mar 2025 21:31:56 GMT
> age: 328
> x-served-by: cache-iad-kcgs7200031-IAD, cache-lon420123-LON
> x-cache: MISS, HIT
> x-cache-hits: 0, 1
> x-timer: S1741555917.611357,VS0,VE1
> content-length: 20338640
> X-Firefox-Spdy: h2
> ~~~

However, if provided as an argument to the `--local-filename` flag, it errors:

> ~~~QML
> org.kde.plasma.libdiscover: OdrsReviewsBackend: Fetch ratings: false
> adding empty sources model QStandardItemModel(0x56493d02af10)
> qrc:/qt/qml/org/kde/discover/qml/LoadingPage.qml:3:1: QML LoadingPage: Created graphical object was not placed in the graphics scene.
> qrc:/qt/qml/org/kde/discover/qml/BrowsingPage.qml:17:1: QML BrowsingPage: Created graphical object was not placed in the graphics scene.
> KNSCore::ResultsStream(0x56493eeb82e0) Finishing KNSCore::StaticXmlProvider(0x7f735c014ad0) 0
> ~~~

EXPECTED RESULT
---------------

It should the same as it would if the file had been supplied via a `file://` URI.

SOFTWARE/OS VERSIONS
--------------------

1.	~~~sh
	#!/usr/bin/env sh
	kinfo
	~~~

2.	> ~~~YAML
	> Operating System: Fedora Linux 41
	> KDE Plasma Version: 6.3.2
	> KDE Frameworks Version: 6.11.0
	> Qt Version: 6.8.2
	> Kernel Version: 6.13.5-200.fc41.x86_64 (64-bit)
	> Graphics Platform: Wayland
	> Processors: 12 × AMD Ryzen 5 7600X 6-Core Processor
	> Memory: 30.4 GiB of RAM
	> Graphics Processor 1: AMD Radeon RX 5700
	> Graphics Processor 2: AMD Radeon Graphics
	> ~~~

ADDITIONAL INFORMATION
----------------------

I expect that this isn't a matter of locality versus externality, since `file://` URIs support hostnames other than `localhost` (the default for `file:///`). Rather, it merely isn't yet designed to support alternative schemas. Considering that Dolphin utilises KIO to support myriad methods of acquiring content via HTTP[S], FTP[S], and WebDav, et cetera, Dolphin should be able to without reinventing much.

I've reported this to the PK backend, because I believe that this affects RPM files, too.

^[1]

…were, in fact, not (at least, to some): ^[2]

I’m closing this bug report now because it’s practically unreadable due to the unnecessary formatting that isn’t rendered by Bugzilla. Writing bug reports this way makes them extremely taxing to read; please open new bug reports using human-readable formatting.

^[3]

Query

Ignoring the specifics of that situation (unless they’re exceptional in a way that I’ve not recognised, which appears improbable, considering I merely utilised > and `):

How many of the participants here actively utilise Markdown for plain text communication (presumably, in places where there is no markup syntax available)?
How many (who do utilise it for either) consider it to be plain-text readable?

I ask because it’ll help me decide when to.

notriddle · March 12, 2025, 4:07pm

unless they’re exceptional in a way that I’ve not recognised

I think they might be. Here’s a screenshot where Bugzilla did something bad:

I notice that Bugzilla performed richtext formatting on the QML sample, but not the sh or YAML samples that were written in the numbered list. Inconsistent formatting is a lot more annoying than just having none. Bugzilla has also used a variable-width font, so the header underlines aren’t the right length.

In short, Bugzilla has its own text formatting rules, and you should learn and follow them.

which appears improbable, considering I merely utilised > and `

You also used an itemized list. I think this was your biggest mistake, firstly because you wrote 1. on both lines. Markdown allows that, but if you expect other people to read the un-HTML-ified text form of the document, you should count them.

I don’t actually understand why you used an itemized list at all. The “SOFTWARE/OS VERSIONS” section is a single query and response cycle. I would have written it like this, regardless of where I was posting it, because it’s a lot less verbose than the itemized list with two code spans, one of them nested in a block quote.
```
 $ kinfo
 Operating System: Fedora Linux 41
 KDE Plasma Version: 6.3.2
 KDE Frameworks Version: 6.11.0
 Qt Version: 6.8.2
 Kernel Version: 6.13.5-200.fc41.x86_64 (64-bit)
 Graphics Platform: Wayland
 Processors: 12 × AMD Ryzen 5 7600X 6-Core Processor
 Memory: 30.4 GiB of RAM
 Graphics Processor 1: AMD Radeon RX 5700
 Graphics Processor 2: AMD Radeon Graphics
```
The use of blockquotes doesn’t really make sense, either. It makes copying and pasting an annoyance, and it’s redundant with the code fences.
You also used underlined headers, which were messed up by Bugzilla’s use of a variable-width font.

rokejulianlockhart · March 12, 2025, 4:28pm

@notriddle, thank you. That’s comprehensive.

Regarding “Inconsistent formatting is a lot more annoying than just having none”, how so?

I would usually auto-number them in markdown, but in *that case, I merely pressed the wrong key there. I’d remediated it in my duplicate in /1:

rokejulianlockhart:

Example

SOFTWARE/OS VERSIONS
--------------------

1.	~~~sh
	#!/usr/bin/env sh
	kinfo
	~~~

2.	> ~~~YAML
	> Operating System: Fedora Linux 41
	> KDE Plasma Version: 6.3.2
	> KDE Frameworks Version: 6.11.0
	> Qt Version: 6.8.2
	> Kernel Version: 6.13.5-200.fc41.x86_64 (64-bit)
	> Graphics Platform: Wayland
	> Processors: 12 × AMD Ryzen 5 7600X 6-Core Processor
	> Memory: 30.4 GiB of RAM
	> Graphics Processor 1: AMD Radeon RX 5700
	> Graphics Processor 2: AMD Radeon Graphics
	> ~~~

That kind of formatting breaks down when there’s a more complex command and output, and has in the past lead to someone adhering to my reproduction instructions incorrectly. Do you believe that the undermentioned would be an improvement? If not, please advise.

~~~sh
kinfo
~~~

> ~~~YAML
> Operating System: Fedora Linux 41
> KDE Plasma Version: 6.3.2
> KDE Frameworks Version: 6.11.0
> Qt Version: 6.8.2
> Kernel Version: 6.13.5-200.fc41.x86_64 (64-bit)
> Graphics Platform: Wayland
> Processors: 12 × AMD Ryzen 5 7600X 6-Core Processor
> Memory: 30.4 GiB of RAM
> Graphics Processor 1: AMD Radeon RX 5700
> Graphics Processor 2: AMD Radeon Graphics
> ~~~

In that case, the BQs demonstrate that it’s the output of the previous command.

notriddle:

Bugzilla has also used a variable-width font, so the header underlines aren’t the right length.
notriddle:

You also used underlined headers, which were messed up by Bugzilla’s use of a variable-width font.

Is this the crux of it? I’ve been using a monospaced font for a long time, and honestly had completely forgotten that some things wouldn’t render the same in vriable width fonts.

notriddle · March 12, 2025, 5:07pm

Regarding “Inconsistent formatting is a lot more annoying than just having
none”, how so?

I don’t know how to say it any other way. If you expect something to be there,
and it’s not, it’s disorienting. In this case, the grey box that bugzilla puts
around blockquotes is missing on the ones wrapped in lists.

That kind of formatting breaks down when there’s a more complex command and
output, and has in the past lead to someone adhering to my reproduction
instructions incorrectly.

But, in this context, you aren’t dealing with a more complex command
and output. You just ran kinfo and posted what it said. The “undermentioned”
form is better because it can be copy and pasted from bugzilla without
having to strip formatting characters off of it.

More generally, it’s a bad idea to rely on people picking up on subtle
formatting to understand what you mean. If you’re truly worried about
people misunderstanding it, then the best solution is always to
use your words:

SOFTWARE/OS VERSIONS

I ran kinfo, and it gave this output:

Operating System: Fedora Linux 41
KDE Plasma Version: 6.3.2
KDE Frameworks Version: 6.11.0
Qt Version: 6.8.2
Kernel Version: 6.13.5-200.fc41.x86_64 (64-bit)
Graphics Platform: Wayland
Processors: 12 × AMD Ryzen 5 7600X 6-Core Processor
Memory: 30.4 GiB of RAM
Graphics Processor 1: AMD Radeon RX 5700
Graphics Processor 2: AMD Radeon Graphics

Is this the crux of it?

No, the crux of it is:

Some of the best writing on earth is written using nothing but sentences and paragraph breaks. Follow the KISS principle.
When you’re trying to get along with an established, existing community, you should try to learn their specific language and conventions. If nothing else, it’s a show of respect.

rokejulianlockhart · March 13, 2025, 12:02am

I’ve put your recommendations into practice, and they’ve worked well. Thank you.

vas · March 13, 2025, 12:45am

I think Markdown is very readable, but it only makes sense where you also have the goal of machine readability, i.e. so that it can be re-rendered or processed. That’s clearly not the case for Bugzilla comments.

I would never use ATX headings, > blockquotes, fences with info strings, etc when the content will ONLY ever be read by a human. Certainly not the link format. I might use Setext headings and the list format, but only because those are so natural people used them long before Markdown. I’d probably use caps for emphasis as I just did for “only”, as opposed to * as I did for “never”. Caps emphasis isn’t machine readable, because the machine won’t know which letters to change back to lower case when converting to italics. But for a humans-only audience, THIS is better than *this*.

rokejulianlockhart · March 13, 2025, 4:36pm

@vas, I did encounter pagure.io/fedora-kde/SIG/issue/582 today:

[ ] Set default background to Fedora background

[ ] Have codecs available on install or first update

[ ] Put maui-mauikit-index-fm as default in comps group

[ ] Fix aarch64 install image

[ ] ... other minor bugs

Those aren’t being converted into semantic HTML checkboxes:

<ul>
<li>[ ] Set default background to Fedora background</li>
<li>[ ] Have codecs available on install or first update</li>
<li>[ ] Put maui-mauikit-index-fm as default in comps group</li>
<li>[ ] Fix aarch64 install image </li>
<li>[ ] ... other minor bugs</li>
</ul>

…but are readable Markdown, and were written in Markdown markup (what Pagure uses).

I’m somewhat surprised by that. Didn’t such syntax exist long before Markdown, as mere convention? I’m not really old enough to know, but frequently see it utilised by those unfamiliar with markup syntax in plain-text environments.