# Explaining users how to format their code examples

**URL:** <https://discuss.python.org/t/explaining-users-how-to-format-their-code-examples/7431>\
**Category:** Python Help\
**Created:** [February 28, 2021, 7:15pm UTC](https://discuss.python.org/t/explaining-users-how-to-format-their-code-examples/7431 "2021-02-28T19:15:25Z")\
**Posts on this page:** 11\
**Page:** 1

<div class="post-metadata">

**Author:** ![jeanas](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/jeanas/32/8115_2.png) [@jeanas](https://discuss.python.org/u/jeanas)\
**Post date:** [February 28, 2021, 7:15pm UTC](https://discuss.python.org/t/explaining-users-how-to-format-their-code-examples/7431/1 "2021-02-28T19:15:25Z")

</div>

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](https://discuss.python.org/t/orbiting-turtles-around-a-stationary-circle/7414) 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:_
> 
> ````plaintext
> ```
> [Someone please insert a mini-code-example based on
> some Monty Python sketch here...]
> ```
> ````

---

<div class="post-metadata">

**Author:** ![cameron](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/cameron/32/2658_2.png) [@cameron](https://discuss.python.org/u/cameron)\
**Post date:** [March 1, 2021, 12:03am UTC](https://discuss.python.org/t/explaining-users-how-to-format-their-code-examples/7431/2 "2021-03-01T00:03:19Z")

</div>

> 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:_
> > 
> > ```plaintext
> > 
> > ```

Did you want those four backticks?

> > ```auto
> > [Someone please insert a mini-code-example based on
> > some Monty Python sketch here...]
> > 
> > ```

Otherwise, seconded.

Cheers,  
Cameron Simpson [cs@cskk.id.au](mailto:cs@cskk.id.au)

---

<div class="post-metadata">

**Author:** ![jeanas](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/jeanas/32/8115_2.png) [@jeanas](https://discuss.python.org/u/jeanas)\
**Post date:** [March 1, 2021, 7:17pm UTC](https://discuss.python.org/t/explaining-users-how-to-format-their-code-examples/7431/3 "2021-03-01T19:17:05Z")

</div>

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

I suppose your mail client does not render that properly? Here is how it shows up on Discourse: [https://discuss.python.org/t/explaining-users-how-to-format-their-code-examples/](https://discuss.python.org/t/explaining-users-how-to-format-their-code-examples/)

> Otherwise, seconded.

Nice! I’ll let a day pass in case someone has further comments, then ping forum administrators.

---

<div class="post-metadata">

**Author:** ![cameron](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/cameron/32/2658_2.png) [@cameron](https://discuss.python.org/u/cameron)\
**Post date:** [March 1, 2021, 9:45pm UTC](https://discuss.python.org/t/explaining-users-how-to-format-their-code-examples/7431/4 "2021-03-01T21:45:09Z")

</div>

> > 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).
> 
> I suppose your mail client does not render that properly? Here is how it shows up on Discourse: [https://discuss.python.org/t/explaining-users-how-to-format-their-code-examples/](https://discuss.python.org/t/explaining-users-how-to-format-their-code-examples/)

I saw this:

`````
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 🙂

Cheers,  
Cameron Simpson [cs@cskk.id.au](mailto:cs@cskk.id.au)

---

<div class="post-metadata">

**Author:** ![jeanas](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/jeanas/32/8115_2.png) [@jeanas](https://discuss.python.org/u/jeanas)\
**Post date:** [March 3, 2021, 10:13pm UTC](https://discuss.python.org/t/explaining-users-how-to-format-their-code-examples/7431/5 "2021-03-03T22:13:32Z")

</div>

Okay, @ambv, could you take a minute to edit the pinned post? Thanks in advance!

As to the code example, maybe as simple as

```auto
import spam

```

in order not to distract the reader 🙂

---

<div class="post-metadata">

**Author:** ![ambv](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/ambv/32/25884_2.png) [@ambv](https://discuss.python.org/u/ambv)\
**Post date:** [March 3, 2021, 11:08pm UTC](https://discuss.python.org/t/explaining-users-how-to-format-their-code-examples/7431/6 "2021-03-03T23:08:46Z")

</div>

Something like this?

> [@About the Python Help category](https://discuss.python.org/t/about-the-users-category/42):
>
> General help/discussion forum for the Python programming language. All welcome. Please format your pasted code using Markdown backticks like this: ```python # YOUR CODE GOES HERE if me.is_hungry: me.bake("bagel") ``` This will look like this: # YOUR CODE GOES HERE if me.is\_hungry: me.bake("bagel") That’s nicely colored and keeps indentation intact! sunglasses If you make a mistake, don’t worry: you can always edit your post later to fix it.

---

<div class="post-metadata">

**Author:** ![jeanas](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/jeanas/32/8115_2.png) [@jeanas](https://discuss.python.org/u/jeanas)\
**Post date:** [March 4, 2021, 6:04am UTC](https://discuss.python.org/t/explaining-users-how-to-format-their-code-examples/7431/7 "2021-03-04T06:04:33Z")

</div>

Looks excellent, thanks!

---

<div class="post-metadata">

**Author:** ![ferdnyc](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/ferdnyc/32/6325_2.png) [@ferdnyc](https://discuss.python.org/u/ferdnyc)\
**Post date:** [March 10, 2021, 12:59am UTC](https://discuss.python.org/t/explaining-users-how-to-format-their-code-examples/7431/8 "2021-03-10T00:59:05Z")

</div>

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 ← `.)

---

<div class="post-metadata">

**Author:** ![mlgtechuser](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/mlgtechuser/32/7310_2.png) [@mlgtechuser](https://discuss.python.org/u/mlgtechuser)\
**Post date:** [May 30, 2022, 3:46pm UTC](https://discuss.python.org/t/explaining-users-how-to-format-their-code-examples/7431/9 "2022-05-30T15:46:34Z")

</div>

You can escape the markdown control characters with backslash:

**```python  
\<code here\>  
```**

The raw text looks like this:  
\```python  
\<code here\>  
\```

> [@jeanas](#):
>
> 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).

---

<div class="post-metadata">

**Author:** ![ferdnyc](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/ferdnyc/32/6325_2.png) [@ferdnyc](https://discuss.python.org/u/ferdnyc)\
**Post date:** [August 23, 2022, 10:54pm UTC](https://discuss.python.org/t/explaining-users-how-to-format-their-code-examples/7431/10 "2022-08-23T22:54:54Z")

</div>

> [@mlgtechuser](#):
>
> You can escape the markdown control characters with backslash:
> 
> **```python  
> \<code here\>  
> ```**

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.

---

<div class="post-metadata">

**Author:** ![cameron](https://sea2.discourse-cdn.com/flex002/user_avatar/discuss.python.org/cameron/32/2658_2.png) [@cameron](https://discuss.python.org/u/cameron)\
**Post date:** [August 24, 2022, 2:02am UTC](https://discuss.python.org/t/explaining-users-how-to-format-their-code-examples/7431/11 "2022-08-24T02:02:37Z")

</div>

By FeRD (Frank Dana) via Discussions on [Python.org](http://Python.org) at 23Aug2022 23:05:

> > [@mlgtechuser](#):
> >
> > You can escape the markdown control characters with backslash:
> > 
> > **```python  
> > \<code here\>  
> > ```**
> 
> 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

Cheers,  
Cameron Simpson [cs@cskk.id.au](mailto:cs@cskk.id.au)
