Information for new users

Yeah, code text can get pretty mangled if pasted “out of context” into the message body. It gets gruesome if fenced in a code block afterward.

Since so many members here are primarily or exclusively using mailing list mode, it seems like a good idea to survey the UX side effects for online and mailing list users. @steven.daprano, would you care to share your experience with code pasted directly into in the message body?

(I’d also like to know if my efforts to create certain layout features are creating unintended effects, but that’s not the topic here,)

Academic but informative point: the header triggers if there is a space after the hash sign.

(Use of top-level header should be discouraged, or scale them both down to a less “shouty” size.)

1 Like

I’m not Steven, but I am one of those luddites who interacts
entirely in “mailing list mode.” What I’ve observed is that code
pasted straight into the post without any preformatting indicators
primarily seems to lose its indentation, though also some of its
line breaks (subsequent lines getting flowed into the previous
because they’re treated as part of the same “paragraph”).

It’s worth noting that even inline preformatting is suboptimal for
people used to exchanging complex code samples over mailing lists,
since proper E-mail can include them as MIME attachments and even
declare specific content types and file names, so that the examples
can be saved and run directly rather than requiring ham-fisted cut
and paste operations which may pick up extra whitespace or fight
with autoindenting in editors.

Note that my experiences may be further colored because I not only
rely on Discourse’s “mailing list mode,” but do so with a plaintext
console-based MUA rather than some fancy graphical HTML-rendering
client. I see that the messages I receive are multipart/alternative
including both a text/plain and text/html version, so wouldn’t be
surprised if people using HTML-based mail clients see an entirely
different representation that I do.

Thanks for sharing, @fungi.

also some of its line breaks (subsequent lines getting flowed into the previous
because they’re treated as part of the same “paragraph”)

I’ve noticed this consistently when pasting code as plain body text into VS Code. I’ll get an impressive one-liner that, if it ran, would win a trophy from the Rainbow Magazine One-Liner column. (Speaking of nostalgic days with my TRS-80 Color Computer.)

While we’re on the subject, does this code sample seem humorous or patronizing? (I should survey new users on it instead of those of us who are all too familiar with the pains of “body code” but we’re on the topic at the moment.)



So fence your posted code like this:

```
<paste or type code here>
```

It will make the code look like this:

volunteers = 0
print("Posting with a reader-friendly code format...")
volunteers += 1
print(f"...will probably encourage at least {volunteers} person to help me.")
while True:
    volunteers += 1
    print(f"or maybe {volunteers} people...")

The sample doesn’t seem patronizing at all to me, no.

It’s worth noting that in the text/plain representation I received
of that message, I do get all the Markdown included (the underscores
for your separator, the leading greater-than marks for the
blockquoted lines, backslashes escaping the backticks you wanted
displayed, and so on). For me, it seems like a fine compromise
though, as I don’t have trouble reading Markdown (I may have a
strong preference for reStructuredText, but this is still plenty
accessible).

1 Like

I guess the post unpins automatically for you. Maybe after certain time or after achieving certain “trust level”.

I think pinned posts are good just for a small part of users which really pay attention to various details of the forum.

I am sorry that I did not notice your earlier post. At this moment I cannot imagine a better way how to teach the new users how to post code. I think we should try to use the plug-in here. I can imagine that after fine-tuning the message being shown to the users it can work very well.

Should we @ notify administrators about the plug-in? I am guessing none of them really feels the troubles in helping the newcomers with their code.

Other ideas I have (not sure if they are possible in Discourse without too much effort):

  • Have reply templates to easily insert suggestions in replies to newcomers - like: code formatting, preparing minimal runnable code, including outputs and error messages…
  • Allow users of certain “trust level” and higher to edit beginner’s posts in a limited way - just to change formatting. - IMHO this is controversial and it will not help much.

My thanks to all who are supporting this – I think that moving this Forum forward in a positive way will be key to its success.

To be clear on the ‘Pinned Post’ to which I was referring, it’s this one…

… which I saw for some time, when I first joined, but I don’t recall if I dismissed it (having first read it and leaving it be for some period of time) or if it kind of becomes unstuck, so to speak, after some period of time – I think it’s former.

Said post is still pinned, for anyone viewing the Users Forum without being logged in.

Ah. Yes, I think that post unpins after you read it, maybe on a date.day() or a topics_originated.count() basis. With a bold headline and a short, easily digested instant toolkit for posting code the auto-unpin would be perfect.

When users are disciplined about posting formatted code, then we can use that awesome copy-code shortcut that appears in the top right corner of the code block!

Carol’s “Discourse Help” post

is not very helpful here. It says nothing about formatting code.

It starts with a link to About Discussions, or specifically the Python Discussions rather than the software itself. This is harmless but not really useful for new users.

There is a misnamed link to the Code of Conduct, which believe me, is in no way, shape or form a FAQ.

Then there are a bunch of UI hints, which are useful but irrelevant to the question of formatting posts properly or asking good questions.

There’s also confusion over the name: Discuss, Discussions or Discourse? Which is correct?

The answer about searching is poor:

“Discourse is perfectly searchable using Google”

Yeah okay, but how do I use Google to search Discourse? (Or Discuss, or whatever it is called. Not to be confused with Discord, which is completely different software.)

Although I have zero expectation that people will read it before posting, it would be nice to have a proper set of instructions for asking good questions, starting with right at the top how to format code. At least we could link to it when newbies post without reading it.

Moderators already have the ability to edit people’s posts. I hate hate hate that (anti-)feature. My words are my words, and are not for other people to change without my permission.

There is a fundamental problem with giving users the ability to edit their posts: you break the integrity of the question:answer format. There is a game people sometimes play on Reddit where they do this deliberately for humour, but to a lesser extent that happens any time people make significant edits to their posts.

Hypothetical example:

Homer asks “What’s wrong with my code? mylist = [45, 2, 6]; x = mylist.sorted() but x isn’t sorted in order.”

Bart replies: “Sorry, your code isn’t working for me, I get an AttributeError. If I fix it to use sort it works fine.”

Homer then silently edits his question instead of replying, changing the code to mylist = ['45', '2', '6']; x = sorted(mylist). Then Lisa gives him the answer to the edited question, and looks like a helpful and clever fellow, and poor Bart looks incompetent.

In a perfect world we could trust people to only edit their posts to fix minor typos and other inconsequential mistakes, and not to change the semantics of their posts.

Its not a great tragedy when this happens, but it is quite frustrating and annoying.

2 Likes

I do much the same as Cameron, even down to using mutt :slight_smile:

So I also see correctly indented code in the text part of the emails sent out by Discuss. But there are other issues.

At times, Discuss seems to insert blank lines between every line. Other times, it seems to put extraneous ^M characters (carriage returns). On occassions it has mysteriously truncated my posts.

(It seems to truncate posts just before a line containing more than two dashes in a row, even if it is protected by code fences or indented, although I cannot reliably reproduce that. It also truncates at Markdown horizontal rules, which is a line of dashes on its own.)

I have seen the curly quotes thing, but I don’t remember the circumstances. Generally they seem to be okay.

I think that posting from the web interface converts straight quotes to curly quotes, but posting from email does not.

Here is an experiment, from email:

Straight quotes, no code fences.

a = ‘Hello world.’
b = “Elvis has left the building.”

Straight quotes, indented code block:

c = 'Spam spam spam and eggs with grated spam.'
d = "Ethel the aardvark goes quantity surveying."

Straight quotes, code fences:

e = 'a b c d'
f = "e f g h"

And inline: g = 'a' + "b".

If somebody cares enough to do the same sort of thing from the web UI, we might be able to determine what is actually happening.

(If I can remember my login details, I may do so myself.)

Even from email, the straight quotes were converted to curly quotes (single: U+2018 and U+2019, double: U+201C and U+201D) when not protected by code fences or indent.

It seems likely that the same will happen from the web UI, but we might as well confirm it with a test.

Straight quotes, no code fences.

a = ‘Hello world.’
b = “Elvis has left the building.”

Straight quotes, indented code block:

c = 'Spam spam spam and eggs with grated spam.'
d = "Ethel the aardvark goes quantity surveying."

Straight quotes, code fences:

e = 'a b c d'
f = "e f g h"

And inline: g = 'a' + "b".

I’m not sure there’s a singular authoritative source specifying it as canon, but referring to it as the “Python Discourse [instance]” (or just Discourse for short, within the implied context of it being the Python Discourse instance as opposed to some other one) is, as far as I’m aware, the widely accepted and used name, following the same pattern as, e.g., the Python Discord [server], the Python GitHub [org], the Python IRC [channel], etc. That is also the name I’ve used in the normative PEP 1 and PyPA process documents.

discuss.python.org is just the URL, which perhaps somewhat unfortunately isn’t discourse.python.org, but calling it “Discuss” or “Discussions” is much too generic as opposed to referring to the specific platform, as it could refer to Python discussions in general or on any other platform, and the former is also not a noun, while the latter is neither in the URL, in common use or displayed anywhere prominent.

I’m not sure why they even recommend that at all, when Discourse’s built-in search feature is perfectly functional, as far as I’m aware.

While most other forums have this feature for moderators, I strongly agree that its use should be strictly limited to fixing post formatting only, even by moderators/admins. However, unlike most other forums I’m aware of, I don’t think I’ve ever actually seen it used even once by any admins, moderators, or TL4s.

And unlike most other forums, it is most certainly not silent—a fairly prominent orange edited icon with a count of edits is placed in the top right of any edited post, and clicking on it displays the full history of edits with the diffs of every change and their author and timestamp, which is visible publicly by all. Therefore, if a user does change their OP (and new users have to be TL1, AFAIK, to edit their posts, and they can only do so in a very limited window of time), a quick check of the edit history will show what happened.

Furthermore, there is full transparency as to exactly whether, what and who made changes to any post. If the feature is ever used inappropriately, this will be visible to everyone, and that user/moderator will face appropriate consequences, ranging from TL demotion and being prevented from using that feature again, to being banned.

To further reduce the risk of abuse while increasing the usefulness for the specific purpose of fixing new users’ formatting, if it is possible, TL4 users could be allowed to edit users’ posts up to TL2, TL3 users up to TL1, and TL2 only TL0, such that only mods/admins could edit TL3+, and only the hand-promoted/demoted TL4 (which can currently edit all posts, AFAIK) can edit TL2 users (i.e. most semi-regular users, including you).

This would be a dandy way to help new Discourse users (and ourslves) with their code formatting. The curly quotes would still be in the body text, but a quick drop into an editor and search-replace would handle it. A utility to automatically search and replace the left and right double and single quotes in a plaintext file could also be whipped up quickly.

The email discussion informs us of how big an issue the code formatting is for the mailing list users, so can be regarded as on-topic. Even the post editing analysis, though I’d say it invokes thoughts of “topic scope creep”. :wink:

Deconstructing Carol’s post must be declared a separate, subsequent point of discussion if for no other reason than to keep this topic narrow enough to mine for nuggets and design a solution, if a decision is made to move forward.

And here’s my own contribution to the “creep”:
I use discuss.python.org (code formatted to suppress the linking) because discuss.python.org == 'Python Discourse instance' although technically URL(discuss.python.org) 'Python Discourse instance'

Now back to our regularly-scheduled program…
Regarding viewing a post in plaintext, I just learned about a great tool:
Replace the /t/ in the post URL with /raw/ and strip out the permalink
https://discuss.python.org/t/how-can-i-add-one-value-on-inside-python-file/11704
https://discuss.python.org/raw/11704

…to go from THIS to THIS. It preserves the quotes, indents, contiguous spaces, everything (as far as I can tell). We had a post with a bunch of  # comments (with space) that blew into pieces from the huge headers. It was a hot mess and could have benefited greatly from this /raw/ technique. Perhaps Discourse.org would add a button to launch with the /raw URL. I’ll ask. For that matter, it may already be an option and is simply disabled.

3 Likes

Is there a way to check who is which trust level? I am a “regular”, but I don’t know which level that is. Is this level 4?

A

Here are the trust levels described:

Here are the detailed permissions:

This is really great. Having a button for this would be really useful.

Thanks for the links, it seems one can be a level 4 user only by manual promotion, so for a small forum such as this I’m not really sure of the benefits of using the level versus just using the moderator role.

A

My biggest concern is actually the code formatting rather than the typographic quotes, the former being a lot quicker to fix but can drastically affect the readability and semantics of the code users post. I would need to drop into an editor/IDE to actually run the code anyway, where the quote chars matter, so its quick to find/replace them there if needed.

Yeah, sorry—I was one of the people who brought that up to begin with, though technically even Carol’s post falls under the title “Information for New Users”.

I dub it @steven.daprano Mode :laughing:

That’s a great find, thanks. It does mean no syntax highlighting (which can make errors easier to spot) and one-click copyability, though it still works in a pinch for extreme cases like that.

That’s TL3. IIRC its “New user”, “Basic user”, “Member”, “Regular”, “Leader”

It adds a bunch of extra permissions like deleting threads, modifying other users’ roles, banning people, etc. that aren’t all that necessary or appropriate for users like us, beyond just the much more useful for this TL4 ones (editing, better flagging, no edit limit, splitting/merging duplicate or unrelated questions by the same user, adding a note to posts, etc). You could also make them a category moderator in Users/Python Help, though I’m not sure if that’s really better for this.

Update: This function was apparently created to add a Raw button the the edit history. Right now, you can only access this button if the post has been edited (not likely with a brand new user) and the orange pencil shows because there’s a history to display.

Edit History Header from meta.discourse.com. Click on any post’s edit history link to view the real thing.

expertcoder14 May 13, '21   [ ]HTML [ ][ ]HTMLRaw

By fungi via Discussions on Python.org at 25Jun2022 11:58:

I’m not Steven, but I am one of those luddites who interacts
entirely in “mailing list mode.” What I’ve observed is that code
pasted straight into the post without any preformatting indicators
primarily seems to lose its indentation, though also some of its
line breaks (subsequent lines getting flowed into the previous
because they’re treated as part of the same “paragraph”).

The email side sends multipart/alternative with tex/plain and
text/html parts. The text/plain seems to be the source MarkDown, so
the indentation is apparent. If your mailer’s viewing the HTML it will
be rendering stuff, and the indentation will vanish as you observe.

Steven and I are using mutt (a mail reader which runs in a terminal) and
generally see the text/plain version by default.

It’s worth noting that even inline preformatting is suboptimal for
people used to exchanging complex code samples over mailing lists,
since proper E-mail can include them as MIME attachments and even
declare specific content types and file names, so that the examples
can be saved and run directly rather than requiring ham-fisted cut
and paste operations which may pick up extra whitespace or fight
with autoindenting in editors.

Aye, though the python-list and friends tend to discard “non plain
text” attachments :slight_smile:

Note that my experiences may be further colored because I not only
rely on Discourse’s “mailing list mode,” but do so with a plaintext
console-based MUA rather than some fancy graphical HTML-rendering
client. I see that the messages I receive are multipart/alternative
including both a text/plain and text/html version, so wouldn’t be
surprised if people using HTML-based mail clients see an entirely
different representation that I do.

Ah, so my comments above are superfluous.

Cheers,
Cameron Simpson cs@cskk.id.au

Yes, I’m also relying on mutt and have it set up to prioritize
text/plain versions in multipart messages, though I do have my
.mailcap set up to pipe text/html through a console-based browser
for cases where there is no text/plain. It’s possible the messages I
saw with pasted code missing indentation or even line breaks was
simply pasted that way by its authors, since so many already
struggle to figure out how to copy and paste text at all, instead
resorting to attaching screen captures or, worse, snapshotting their
screens with cellphones.

This thread seems to have died, but in case the points being made here (which are many, and diverge to some extent from the topic) are under consideration, I’d like to add to this a ‘Code of Conduct’ to which members can be pointed, should they act in a way that is disrespectful to others.

I understand that this is somewhat subjective, but right now it just seems to be a free-for-all, to behave in whatever manner one chooses. I’m not going to name names, as that would, in and of itself, be disrespectful. The temporary banning of one new member was good to see, as he deserved it and from that I do know that the actions of members is being monitored, which is no bad thing, but a posted ‘Code of Conduct’ would be, at the very least, a point of reference.