In many topics on this forum, users are posting code as mere text. On both the Discourse web interface and email notifications, this mangles the indentation. Steven D’Aprano, Cameron Simpson, I and others find ourselves explaining how to use the Markdown-like syntax (with three backticks) somewhat often.
There are also some (rarer) users who post screenshots of code.
This post looks like the three-backticks trick is not so easy to understand at first. Indeed, the web interface inserts single backticks for inline code when clicking the “preformatted text” button in the course of a paragraph, and in a new paragraph, it says “indent preformatted text by 4 spaces”, which seems less practical for copy-pasting.
Could we put this information somewhere? The pinned post on the Users category looks like a good place. Currently, this reads:
About the Users category
General discussion forum for the Python programming language. All welcome.
Maybe expand to something like:
General discussion forum for the Python programming language. All welcome.
When posting code samples and error tracebacks, please paste the content in-between triple backticks, as in this example:
```
[Someone please insert a mini-code-example based on
some Monty Python sketch here...]
```
In many topics on this forum, users are posting code as mere text. On
both the Discourse web interface and email notifications, this mangles
the indentation. Steven D’Aprano, Cameron Simpson, I and others find
ourselves explaining how to use the Markdown-like syntax (with three
backticks) somewhat often.
There is also the “indent with four spaces” syntax. Markdown again, and
far more natural, if the poster can indent their paste. I post from
email using a real editor, so this is easy for me. I don’t think that is
easy in the web interface.
There are also some (rarer) users who post screenshots of code.
Yah. I sometimes try to push back against that, politely.
Could we put this information somewhere? The pinned post on the Users
category looks like a good place. Currently, this reads:
About the Users category
General discussion forum for the Python programming language. All welcome.
Maybe expand to something like:
General discussion forum for the Python programming language. All welcome.
When posting code samples and error tracebacks, please paste the content in-between triple backticks, as in this example:
Did you want those four backticks?
[Someone please insert a mini-code-example based on
some Monty Python sketch here...]
There is also the “indent with four spaces” syntax. Markdown again, and
far more natural, if the poster can indent their paste. I post from
email using a real editor, so this is easy for me. I don’t think that is
easy in the web interface.
Yeah, the difficulty of doing this in the web interface is what incited me to suggest the three backticks.
Did you want those four backticks?
Well, what do you see exactly? What I wrote is exactly:
[four backticks]
[three backticks]
[Someone please …]
[three backticks]
[four backticks]
That was in order to make the code show up surrounded by three backticks in a code block (so four backticks were needed to surround the whole thing because three would have caused confusion, as does a string delimiter inside of a string).
Well, what do you see exactly? What I wrote is exactly:
[four backticks]
[three backticks]
[Someone please …]
[three backticks]
[four backticks]
That was in order to make the code show up surrounded by three backticks in a code block (so four backticks were needed to surround the whole thing because three would have caused confusion, as does a string delimiter inside of a string).
Maybe expand to something like:
> General discussion forum for the Python programming language. All welcome.
>
> *When posting code samples and error tracebacks, please paste the content in-between triple backticks, as in this example:*
>
> ````text
> ```
> [Someone please insert a mini-code-example based on
> some Monty Python sketch here...]
> ```
which is exactly what is in the text/plain version of the forum email.
The text/html part contains this:
<p style=3D"margin-top:0; border: 0;">Maybe expand to something like:</p>=
=0D
<blockquote style=3D"border-left: 5px solid #e9e9e9; background-color: #f=
8f8f8; margin: 0;">=0D
<p style=3D"padding: 1em;; margin-top:0; border: 0;">General discussion f=
orum for the Python programming language. All welcome.</p>=0D
<p style=3D"padding: 1em;; margin-top:0; border: 0;"><em>When posting cod=
e samples and error tracebacks, please paste the content in-between tripl=
e backticks, as in this example:</em></p>=0D
<pre style=3D"word-wrap: break-word; max-width: 694px;"><code style=3D"di=
splay: block; background-color: #f1f1ff; padding: 5px;; background-color:=
#f1f1ff; padding: 2px 5px;">```=0D
[Someone please insert a mini-code-example based on=0D
some Monty Python sketch here...]=0D
```</code></pre>=0D
</blockquote></div>=0D
It does look better in the forum. And I see my query about the four
backticks in the forum… does not show the four backticks
Worth noting that you can also use <pre><code> tags to wrap source, which is useful when you want to embed other HTML markup inside it. I often do that…
if bold_line in [my, many, immediate, desires, include, a, bold_line]:
print("Code wrapped in HTML tags")
(There are <b></b> tags wrapped around the second line, of course.) Can’t do that with backticks or indented blocks.
You can also use <code>…</code> inline as a substitute for single-backtick fencing, which normally has similar effect. That’s more useful on, say, Github, where <var></var> inside <code></code> will italicize a variable name. Discourse for some reason doesn’t respect either <var> or <em> to italicize inside inline <code> tags, so it’s kind of pointless here. (The seventh word should be in → italics ← .)
That doesn’t get formatted as a code block, though — which means it’s not monospaced, it’ll be subject to word-wrapping, and other differences. It’s not an equivalent representation. But it does come in handy at times, agreed.
By FeRD (Frank Dana) via Discussions on Python.org at 23Aug2022 23:05:
That doesn’t get formatted as a code block, though — which means it’s
not monospaced, it’ll be subject to word-wrapping, and other
differences. It’s not an equivalent representation. But it does come in
handy at times, agreed.
Aye, that was his point I thought.
If it can’t be turned off, it’s not a feature. - Karl Heuer
