Timeline for When should code formatting be used for non-code text?
Current License: CC BY-SA 4.0
128 events
when toggle format | what | by | license | comment | |
---|---|---|---|---|---|
Jul 22 at 8:01 | comment | added | Cerbrus | @wjandrea stop trying to cover every single edge case. The more specificity you add, the more edge cases you're gonna miss. | |
Jul 21 at 21:59 | comment | added | wjandrea | @Cerbrus Maybe instead we could expand the "code" bullet to say "Micro-snippets of code and text that looks like code" | |
Jul 21 at 21:52 | comment | added | wjandrea |
@Cerbrus But it's not intended to be code at all, and no Python dev would interpret it as code (except maybe a beginner). It's an object representation; it represents an object (a lambda function) that can't be represented using valid Python (as opposed to something like [0] , a list containing an integer). It's not code any more than a stack trace is.
|
|
Jul 21 at 21:37 | comment | added | wjandrea | @philipxy Quote block, not code block. That said, I prefer inline code formatting myself, so that any special characters are handled automatically. TylerH and I discussed this on Mar 28. | |
Jul 21 at 19:45 | comment | added | Cerbrus | @wjandrea syntactically invalid code is still code. We don't need a separate entry for that. | |
Jul 21 at 19:23 | comment | added | philipxy | "(Also consider using quote blocks instead, especially for long single-line error messages.)" No, use inline for that so it wraps. | |
Jul 21 at 16:44 | comment | added | wjandrea |
@Cerbrus Why do you say "That's just code."? What I wrote, <function <lambda> at 0x7f7563ceda60> , is output from Python but it's not syntactically valid Python itself.
|
|
Jul 21 at 16:42 | history | edited | Cerbrus | CC BY-SA 4.0 |
That's just code.
|
Jul 21 at 16:41 | history | rollback | Cerbrus |
Rollback to Revision 48
|
|
Jul 21 at 16:41 | history | edited | Cerbrus | CC BY-SA 4.0 |
That's just code.
|
Jul 21 at 16:38 | history | edited | wjandrea | CC BY-SA 4.0 |
Add short errors and short output.
|
Jul 21 at 16:17 | history | edited | wjandrea | CC BY-SA 4.0 |
This answer doesn't cover the syntax, so the pun doesn't make sense, isn't relevant, and without context, it's rude to use the name of a serious illness.
|
Jul 21 at 15:06 | history | edited | Anerdw | CC BY-SA 4.0 |
Make this easier to find for people coming from "How do I make a good edit?"
|
Mar 28 at 22:01 | comment | added | wjandrea | @TylerH On second thought, I'm going to drop the blockquote/inline debate. Code block is the better option overall IMHO, and this answer recommends it first, so w/e. I would only use inline as a last resort. | |
Mar 28 at 21:30 | comment | added | wjandrea | @TylerH BTW, this is relevant: Add format for logs/warnings/error messages which allows word-wrapping and preserves newlines - MSE | |
Mar 28 at 21:28 | comment | added | wjandrea | @TylerH "no one is making an edit in 2017 based on this guidance" - Well yeah, but there are posts from 2017 out there that still have tables formatted as code. The reason I mentioned it is so that editors are aware of it and don't feel obliged to reformat old tables, I mean, as long as they're perfectly readable of course. | |
Mar 28 at 21:19 | comment | added | wjandrea | @TylerH "That users make mistakes is not a process issue." - True, but it's an easy mistake to make, for example if you have a word in angle brackets, it'll go missing and you might not notice from a quick glance. While for inline code formatting, the only special characters you need to worry about are backticks, which affect the result in an obvious way. | |
Mar 28 at 20:52 | comment | added | TylerH | @wjandrea While a CW, the post above is not necessarily a place for users to place their personal preferences. There's no issue with using block quotes, for example, with error messages (in fact it is the ideal format). That users make mistakes is not a process issue. I also don't see a need to point out that markdown table support was added in 2020. All edits are made in present time no matter what time (or year) that is; no one is making an edit in 2017 based on this guidance. | |
Mar 28 at 20:51 | comment | added | wjandrea | @TylerH Why'd you rollback? | |
Mar 28 at 20:50 | history | rollback | TylerH |
Rollback to Revision 42
|
|
Mar 28 at 20:47 | history | edited | wjandrea | CC BY-SA 4.0 |
I've seen too many error messages mangled by quote formatting to recommend it. Inline code formatting works instead for long single lines.
|
Mar 28 at 19:34 | history | edited | wjandrea | CC BY-SA 4.0 |
Add back the caveats about tables. These are considerations for editors to take into account.
|
Mar 28 at 19:23 | history | edited | wjandrea | CC BY-SA 4.0 |
Add back the first paragraph that directly answered the question and move in the point that these words don't require special formatting at all. Then below we can focus on things that *do* require special formatting. Use emphasis "sparingly" ;)
|
Mar 24 at 21:55 | comment | added | Cerbrus | Let's grumpily shake hands on a job well done, then @MarkAmery. The header was quite important to me, as that's a big signpost stating "Hey, we have formatting documentation" :D | |
Mar 24 at 21:52 | comment | added | Mark Amery | @Cerbrus I see your latest edit - looks good to me. I think we've grumpily haggled our way into producing something significantly better than what either of us originally wanted, so, thank you! (I am still not a big fan of the giant heading but I can live with it and many of the other changes you've either made or nudged me into along the way are big improvements on my first draft from earlier today.) | |
Mar 24 at 21:47 | history | edited | Cerbrus | CC BY-SA 4.0 |
Added big fat "use more suitable formatting" back in, formatted list.
|
Mar 24 at 21:42 | history | edited | Mark Amery | CC BY-SA 4.0 |
edited body
|
Mar 24 at 21:42 | comment | added | Cerbrus | Okay, I'll have a look @MarkAmery. | |
Mar 24 at 21:42 | history | edited | Mark Amery | CC BY-SA 4.0 |
A proposal!
|
Mar 24 at 21:41 | comment | added | Mark Amery | @Cerbrus Yes - actually very similar to something I already had in my editor. I'm gonna hit save, but feel free to take a look and decide what to keep from each version. I'd be able to live with yours if you entirely prefer it! | |
Mar 24 at 21:40 | comment | added | Cerbrus | @MarkAmery how is this, is that an okay compromise? | |
Mar 24 at 21:40 | history | edited | Cerbrus | CC BY-SA 4.0 |
added 286 characters in body
|
Mar 24 at 21:34 | comment | added | Mark Amery | Personally, I think adding my two data examples in would be too pedantic; we don't need to list every unusual use case of code formatting that the community has ever decided it's okay with. It makes much more sense to me to explicitly highlight common misuses of code formatting and say not to do them - it was after all the misuses that this very question was originally about! | |
Mar 24 at 21:33 | comment | added | Cerbrus | Just... Please don't edit the tables example back into it. It's been used as a hack in the past, and it was only ever added into this answer because that other user completely misinterpreted my comment. | |
Mar 24 at 21:31 | comment | added | Cerbrus | Data is a fine example to add under code. Sample form inputs, (verbatim data), just as well... Or just add a category "Test / example data". Again, I'm absolutely fine with listing proper uses. @MarkAmery (I keep forgetting the mention) | |
Mar 24 at 21:29 | comment | added | Mark Amery | @Cerbrus I am sure there are several more. Off the top of my head: 1. Indicating something to be typed verbatim (but which is nonetheless not exactly code), like a default username or password. 2. Indicating that a series of characters represents string data that an algorithm will operate on (but perhaps not as code per se - such data might not be written as a string literal with quotes, especially in a language-agnostic algorithm question). I've seen code formatting used for both of these and consider it appropriate for both. | |
Mar 24 at 21:26 | history | edited | Cerbrus | CC BY-SA 4.0 |
deleted 17 characters in body
|
Mar 24 at 21:24 | comment | added | Cerbrus | Those 3 categories are exhaustive. Unless you can think of another one. The lists under them are just examples. Actually, 4 categories now, but IMO, shell commands are just code. Not a hill to die on though. | |
Mar 24 at 21:21 | comment | added | Cerbrus | shell is code. @MarkAmery, if you'd edit a shell command example, by itself, into those list, I'd be absolutely okay with that. I'm fine with listing okay examples of code blocks / inline code. Just don't list bad uses. | |
Mar 24 at 21:20 | history | edited | Cerbrus | CC BY-SA 4.0 |
Again, we don't want to list every single instance of bad use of code formatting. That list can _never_ be complete, and just saying "don't use code formatting outside of these examples" is enough.
|
Mar 24 at 21:17 | comment | added | Mark Amery |
@Cerbrus But it's not a fix, because it's genuinely not an exhaustive list! As just one example, names of shell commands like git or cp are commonly backticked and that's fine and correct, but they don't appear in the old list (and you've twice reverted my attempts to add that common use case to the list...) On the one hand you don't want to make the list actually be exhaustive, but on the other you want people to reason that backticks are inappropriate in some scenarios because those scenarios aren't on the (non-exhaustive) list; it doesn't make sense.
|
|
Mar 24 at 21:13 | history | edited | Mark Amery | CC BY-SA 4.0 |
Go for an *even more succinct* version of my earlier edits
|
Mar 24 at 21:12 | comment | added | Cerbrus | There, fixed it, @MarkAmery. Those 3 top categories are and always have been well-defined. | |
Mar 24 at 21:12 | history | edited | Cerbrus | CC BY-SA 4.0 |
deleted 13 characters in body
|
Mar 24 at 21:11 | comment | added | Mark Amery | ""iOS" is not a code snippet, filename, or URL, so shouldn't be code. How does this not answer that @MarkAmery?" - because the bulleted list that includes code snippets, filenames, and URLs is not an exhaustive list of all the things it's appropriate to use code formatting for, and even has a disclaimer above it (that indeed you keep restoring!) explicitly noting that it's not a definitive list! We're directly saying before we even get into the list that there is additional stuff it's appropriate to use code formatting for that we haven't listed. | |
Mar 24 at 21:08 | comment | added | Cerbrus |
"iOS" is not a code snippet, filename, or URL, so shouldn't be code. How does this not answer that @MarkAmery? The link points to other options for formatting... For other cases where code formatting clearly isn't okay, as it's not a code snippet, filename, or URL. You're looking way too much into this. IT's an extremely simple list fo 3 items for inline code, and 2 for code blocks. Other than that, don't use code formatting. Don't overcomplicate this.
|
|
Mar 24 at 21:06 | comment | added | Mark Amery | @Cerbrus "That footer already more than covers that" - how? I don't think that footer really has much meaning at all, and don't understand what purpose you think it serves. Possibly you take it to convey that all uses of code formatting besides those listed in the answer are inappropriate... but it doesn't clearly say that, and it shouldn't, since that's untrue and contradicts the bit earlier in the post about the list of places to use code formatting not being definitive. It's in effect not saying much more than "Some other kinds of formatting exist, and here are some docs about them". | |
Mar 24 at 20:59 | comment | added | Mark Amery |
@Cerbrus If the FAQ doesn't indicate whether common abuses of code formatting are right or wrong, it simply doesn't provide a useful answer to the question asked. Even the original question body asked specifically about the constantly recurring topic of whether words like iOS should be backticked - the very thing you insist we shouldn't answer! Again, if all we're gonna do is provide a non-exhaustive list of fairly obviously okay uses of backticks and leave it at that, what's the point of this FAQ?
|
|
Mar 24 at 20:47 | comment | added | Cerbrus | Oh, I overlooked that. Still, I'm not interested in repeating this entire discussion in these comments again, @MarkAmery, these FAQ entries shouldn't list every single thing you shouldn't do. That footer already more than covers that. The more extensive you make that list, the more you give people to point out edge-cases not covered by that list. "But it doesn't say I can't use code formatting for city names!" | |
Mar 24 at 20:44 | comment | added | Mark Amery | @Cerbrus "an even more serious reason I reverted those edit is that they state tables are okay to use code blocks for" - huh? They explicitly said it's better to use proper Markdown tables, and to edit old posts that used code blocks for tables to convert them to use proper tables instead. I double-checked the edit history to see if I made some terrible typo, but no, the edits you reverted definitely said the exact opposite of what you're saying they said. I can make the instruction not to use code blocks for this even more clear if you think it's somehow open to misinterpretation... | |
Mar 24 at 20:33 | comment | added | Mark Amery | @Cerbrus I'd appreciate it if you were to @-notify me when rolling back my edits or making changes I'm likely to disagree with; I've done you that courtesy! | |
Mar 24 at 20:02 | comment | added | Cerbrus | We shouldn't be duplicating information out of the help center. FAQ exists to fill the gaps. And an even more serious reason I reverted those edit is that they state tables are okay to use code blocks for. That's blatantly incorrect. The whole reason tables were added, is because wjandrea misinterpreted a comment from me explaining tables should never be code blocks. | |
Mar 24 at 19:58 | history | rollback | Cerbrus |
Rollback to Revision 29
|
|
Mar 24 at 19:52 | history | edited | Mark Amery | CC BY-SA 4.0 |
further shorten prose
|
Mar 24 at 19:48 | comment | added | Mark Amery | Like, literally what's the point of having an FAQ entry for this and using it as a dupe target if we're just gonna provide a partial answer, shrug and decide it's long enough, and roll back attempts to make it more exhaustive? It'd literally be more useful for this entire Q&A to not exist if we approach it like that, since at least then it wouldn't be used as a basis for closing other questions! We need to be able to document the answers to recurring policy questions somewhere. | |
Mar 24 at 19:45 | history | edited | Mark Amery | CC BY-SA 4.0 |
Shorten prose a bit
|
Mar 24 at 19:43 | history | rollback | Mark Amery |
Rollback to Revision 27 - I think the edits just rolled back were useful and should stay, for reasons outlined in the comments.
|
|
Mar 24 at 19:41 | comment | added | Mark Amery | @Cerbrus I don't agree. It's not clear if that large notice is meant to mean that literally any other use of backticks is inappropriate, and either way is problematic. If it does mean that, it's wrong, since other accepted uses exist (one of which you just edited out!). If it doesn't, this post simply doesn't answer whether backticking technology and language names is appropriate, despite having been used as a dupe target multiple times for that precise question. Yes, it's an FAQ entry, and for that reason it should exhaustively cover at least the things that are frequently asked about! | |
Mar 24 at 19:27 | history | edited | Cerbrus | CC BY-SA 4.0 |
deleted 32 characters in body
|
Mar 24 at 19:25 | comment | added | Cerbrus | This is a FAQ entry. It should be simple to read and to the point. It should not be bloated with all kinds of examples of what not to do. As I stated more than once already in the comments here, the large notice at the bottom of the post now more than covers the "other" formatting cases. | |
Mar 24 at 19:22 | history | rollback | Cerbrus |
Rollback to Revision 22
|
|
Mar 24 at 19:13 | history | edited | Mark Amery | CC BY-SA 4.0 |
added 9 characters in body
|
Mar 24 at 19:12 | comment | added | Mark Amery |
I've tweaked this post a bit, including adding a section about common abuses of code formatting to avoid. I've primarily done this because I want a source I can cite when rejecting the endless stream of suggested edits that use backticks for emphasis or stick them around technology-related proper nouns like iPhone and C# ; prior to the edit, the answer didn't definitively say that using backticks for such words is wrong. @Cerbrus, given the distaste you've voiced for showing examples of the wrong formatting, I've taken care to only gives examples of correct formatting in those cases.
|
|
Mar 24 at 19:03 | history | edited | Mark Amery | CC BY-SA 4.0 |
Added more good examples; added a section on common abuses that I can cite in my rejection reason when rejecting backticking edits; removed the "I think" given this answer is now a heavily edited community wiki
|
Mar 24 at 18:45 | history | edited | Mark Amery | CC BY-SA 4.0 |
Tweaked section about errors and logs to: 1) make clear code formatting is not the ONLY reasonable option here; 2) remove the outermost bulleted list, which only had one element so didn't really make sense!
|
Feb 22 at 16:50 | history | edited | wjandrea | CC BY-SA 4.0 |
Add link about syntax highlighting.
|
Feb 22 at 16:44 | history | edited | wjandrea | CC BY-SA 4.0 |
Add back the two misuses we see often since keyboard keys aren't covered on the linked page and tables are tricky. Other minor improvements to readability/formatting.
|
Jan 22 at 13:45 | history | edited | Cerbrus | CC BY-SA 4.0 |
added 101 characters in body
|
Jan 21 at 12:15 | history | edited | Cerbrus | CC BY-SA 4.0 |
Looking back at it a week later, adding a "code formatting isn't suitable for..." list is just stupid. We don't need to list every single example of misuse.
|
Jan 11 at 18:27 | history | edited | wjandrea | CC BY-SA 4.0 |
Add link about HTML tags
|
Jan 8 at 23:13 | history | edited | wjandrea | CC BY-SA 4.0 |
grammar
|
Jan 8 at 22:45 | comment | added | wjandrea | @Cerbrus "The one from 2022 isn't even a table" - Oh yeah, I should have clarified, it's an attempt at a table, but it's misaligned. "That code block is Markdown syntax for a table." - Oh, you didn't read the whole thing! Look under "Pre-November 2020". | |
Jan 8 at 22:41 | comment | added | Cerbrus | But we're not getting anywhere with this back and forth. Let's end this. | |
Jan 8 at 22:41 | comment | added | Cerbrus | The one from 2022 isn't even a table... And even if it was, That's one example. You're using that meta question as an example of a table in a code block. Implying that it should've been formatted as a table, instead. That code block is Markdown syntax for a table. That has nothing to do with this question. | |
Jan 8 at 22:36 | comment | added | wjandrea | @Cerbrus "those are old examples" - One of them's from 2022, but regardless, why does their age matter? Like I said, I'm thinking of direction to editors, including about old posts. "examples that show command output" - The first two are not, or if they are, IDK what commands they would be from. "If anything, that meta question invalidates the need to mention tables here." - In what way? If editors are looking for guidance about code formatting, how is that going to lead them to a question about tables? | |
Jan 8 at 22:35 | comment | added | wjandrea | @Cerbrus Oh, I changed my position, was that not clear? I'm now saying "Don't do it, but if you see it, you don't need to bother fixing it." (Whereas for emphasis, it should always be fixed.) | |
Jan 8 at 22:33 | comment | added | Kevin B | 🚽You could also wrap them in emojis, but you probably shouldn't.🧻 | |
Jan 8 at 22:18 | comment | added | Cerbrus | @wjandrea your argument can be summarized to "I'm not saying not to do it, I'm saying you can do it, but there's a better option." That just flips my argument. I'm stating you shouldn't. Your answer is "you can"... That's not a good answer / justification. | |
Jan 8 at 22:16 | comment | added | Cerbrus | @wjandrea those are old examples, examples that show command output, not tables, and that Meta question with the "table formatted as code" is explaining how markdown tables work. None of them are examples of people using code blocks to render tabled. If anything, that meta question invalidates the need to mention tables here. | |
Jan 8 at 22:15 | comment | added | wjandrea | @Cerbrus Also, bad_coder doesn't represent me. I still respect you even if I totally disagree with you, so the fact that you think my points are basically "No you're wrong" is really disappointing. | |
Jan 8 at 22:12 | comment | added | wjandrea | @Cerbrus Here are some examples I found from a quick look: Bash parameter expansions, Python operator precedence, git command timetables. And here's a Meta question from before 2020 where the answer has a table formatted as code, which suggests there are a lot more out there. | |
Jan 8 at 22:00 | comment | added | bad_coder | @Cerbrus yeah, you just spammed the comment section 6 times making the same argument - we heard you already. I'm of the same opinion as wjandrea, the linked examples (especially the kbd) advert the most common mistakes and deserve mention. | |
Jan 8 at 21:52 | comment | added | Cerbrus | You're just shoehorning those examples in there. The only reason that mentions tables is because I brought them up as an extremely bad example. I've hardly ever seen people use code blocks for tables on SO. | |
Jan 8 at 21:49 | comment | added | wjandrea | @Cerbrus No offense, but did you read the edit you just rolled back? It basically said "also, don't do this ...". | |
Jan 8 at 21:49 | history | rollback | bad_coder |
Rollback to Revision 16
|
|
Jan 8 at 21:48 | comment | added | Cerbrus | Dude. If you add a recommendation and then immediately invalidate that recommendation, you shouldn't add that recommendation. Especially not if the better alternative is off-topic. | |
Jan 8 at 21:47 | history | rollback | Cerbrus |
Rollback to Revision 12
|
|
Jan 8 at 21:46 | history | edited | wjandrea | CC BY-SA 4.0 |
Weaken the recommendation - not mistakes per se. Also fix typo.
|
Jan 8 at 21:39 | history | edited | bad_coder | CC BY-SA 4.0 |
Fixed link.
|
Jan 8 at 21:38 | comment | added | wjandrea | @TylerH oh, I thought you were replying to my other comment. I'm still not following you though, and I'm not sure what made you think of headers. | |
Jan 8 at 21:31 | history | edited | bad_coder | CC BY-SA 4.0 |
Added reference.
|
Jan 8 at 21:26 | comment | added | TylerH | @wjandrea You were, it seemed. See meta.stackoverflow.com/questions/254990/… But maybe your comment was not very clear. | |
Jan 8 at 21:21 | comment | added | wjandrea | @bad_coder Done. I added a section about other cases where code formatting ideally shouldn't be used on non-code. No link though cause I couldn't find anything specific enough from a quick look. | |
Jan 8 at 21:20 | history | edited | wjandrea | CC BY-SA 4.0 |
Add back keyboard keys, but explicitly recommending against. Also add tables.
|
Jan 8 at 21:17 | comment | added | wjandrea | @TylerH Who's talking about headers? Regarding emphasis, the answer explicitly recommends against it. I'm sorry, I'm not following you at all. | |
Jan 8 at 19:59 | comment | added | Cerbrus | This answer is not about fromatting non-code as something other than code, so that shouldn't be added in here. | |
Jan 8 at 16:58 | comment | added | TylerH | @wjandrea Headers or emphasis are not code or code-adjacent, so are irrelevant to this post and thus should not be included. | |
Jan 8 at 16:32 | comment | added | wjandrea | @TylerH Sorry, what? This question is about formatting non-code as code and this answer includes filenames and URLs. | |
Jan 8 at 16:25 | comment | added | bad_coder |
@TylerH I agree with wjandrea that the mall-formatted code span instead of <kdb> is a common enough problem. A compromise solution is including a link to a relevant post at the end of this canonical that explains its use. After editing hundreds if not thousands of such cases I have to agree it warrants a reference.
|
|
Jan 8 at 16:11 | comment | added | TylerH | @wjandrea This post is about code formatting, so it should not contain any suggestions about formatting things that are not code. | |
Jan 8 at 16:09 | comment | added | wjandrea | @Cerbrus Who's saying it's bad practice? | |
Jan 8 at 14:06 | comment | added | Cerbrus |
I don't know how I can make this any simpler @wjandrea: Do not suggest bad practices, especially if that's just a stepping stone to a different off-topic suggestion. <kbd> is irrelevant here, so don't suggest a bad practice to suggest <kbd> .
|
|
Jan 8 at 2:28 | comment | added | wjandrea |
I'm considering filling in some details but I'm not sure everyone would agree. LMK: 1) Why not: It's not any clearer. The formatting is just a distraction. 2) What to use instead: Bold or italics can be used to add emphasis if necessary. In the edit OP's referring to, it's not. I see a lot of edits like this where people add code formatting to key terms (I guess), but 90% of the time, they don't need emphasis. Sometimes, BTW, terms can be confused with code, like if you write "iterator " in a Python question, could you be referring to collections.abc.Iterator ?
|
|
Jan 8 at 2:05 | comment | added | wjandrea | @Cerbrus What I meant to say is, it's about code formatting, but not strictly about formatting code, you know? Anyway, I'm not saying not to do it, I'm saying you can do it, but there's a better option. What I had in mind was direction to editors, like to say "always remove code formatting used for emphasis, but if it's used for keyboard keys, you can leave it". And I would say the same exact thing for tables. For one thing, there are a lot of old posts from before we had proper tables that are still fine. Unless their text overflows, I don't bother changing them. | |
Jan 8 at 1:54 | history | edited | wjandrea | CC BY-SA 4.0 |
Add filename that would get mangled
|
Jan 7 at 21:05 | comment | added | Cerbrus |
... It is about code formatting ... Don't suggest things people shouldn't do. By your logic you could also add "You can use a code block to display a table, but you should use markdown tables, instead."
|
|
Jan 7 at 20:38 | history | edited | wjandrea | CC BY-SA 4.0 |
Split block formatting into its own section since the question is focused on inline. Add spacing error example. Add link to relevant question.
|
Jan 7 at 20:24 | comment | added | wjandrea |
@Cerbrus I see your point, but it's specifically not about code formatting, it's about formatting non-code as if it were code. It'd be clearer if I wrote "For keyboard keys, it's fine, but it's better to use the <kbd> tag". How would you feel about that?
|
|
Jan 7 at 20:07 | comment | added | Cerbrus | @wjandrea don't suggest keyboard keys here. This answer is about code formatting, not about keyboard key formatting. | |
Jan 7 at 20:06 | history | rollback | Cerbrus |
Rollback to Revision 8
|
|
Jan 7 at 19:56 | history | edited | wjandrea | CC BY-SA 4.0 |
boldly adding keyboard keys vs <kbd>
|
Jan 7 at 19:44 | comment | added | wjandrea |
@Lance Why monospaced though? I use bold, personally. That lets me do things like give the name of a VSCode command and its ID clearly, like "Tasks: Run Task (workbench.action.tasks.runTask )".
|
|
Dec 25, 2023 at 19:44 | comment | added | Karl Knechtel |
A couple specific ideas for Python: 1) use backticks for the name of a third-party package or tool as it would appear in the source code, such as in an import statement; or on a command line: "run pip install -e . ". Use normal formatting for a package or tool as it would appear in documentation: "use Pip to install the package". 2) use backticks for the word "class" when specifically referring to the relevant code: "since Example was defined as a class , ..." / "since Example was defined using the class keyword, ..." Use plain text more generally: "since Example is a class, ...".
|
|
Apr 1, 2022 at 21:36 | comment | added | Lance U. Matthews |
The style I've settled on for writing documentation/instructions is to use monospace text to indicate UI elements or other text the user might encounter (e.g. "Click the OK button to close the Preferences dialog"), and I've carried that over to Stack Overflow/Exchange. Care must be taken and context must be given to adequately separate it from actual code so it's not mistaken as such, but I think monospace makes more sense for that purpose than using "quotes" and especially bold or italics.
|
|
Jan 17, 2021 at 4:21 | comment | added | HABO |
I find it's a good way to indicate search strings without confusion about punctutation marks, e.g.: Have you tried using <your favorite search engine> to look for wombat query vms ? Searches for bacon levitation and "bacon levitation" tend to be quite different.
|
|
Jan 16, 2021 at 0:58 | history | edited | Cody GrayMod | CC BY-SA 4.0 |
fix indentation broken during CommonMark migration
|
Jan 16, 2021 at 0:57 | comment | added | Cody Gray Mod | @M.Justin Already covered in the answer by "Micro-snippets of code". Let me move that item up to the top of the list, though. Also, the indentation here was apparently broken by the CommonMark migration, so I've fixed that, too. | |
Jan 15, 2021 at 23:41 | comment | added | M. Justin | The error code example is about code blocks, but everything else, including the question, appears to be discussing inline code spans. Should that really be included in this answer (and/or should a single-line example be chosen)? | |
Jan 15, 2021 at 23:37 | history | edited | M. Justin | CC BY-SA 4.0 |
Prefer code fence to pre HTML tag
|
Jan 15, 2021 at 22:11 | comment | added | M. Justin | Also, you know, actual code. | |
Jul 25, 2019 at 18:39 | history | edited | BSMP | CC BY-SA 4.0 |
Added error code as code that should get code formatting: https://meta.stackoverflow.com/questions/286706/how-should-compiler-errors-linker-errors-and-logs-be-formatted, along with an example of an error code that needs a monospaced font
|
Jun 15, 2019 at 0:51 | history | made wiki | Post Made Community Wiki by user3956566 | ||
Aug 14, 2014 at 5:36 | history | edited | AstroCB | CC BY-SA 3.0 |
deleted 1 character in body
|
May 16, 2014 at 17:00 | vote | accept | kviiri | ||
May 16, 2014 at 13:34 | history | edited | Fish Below the Ice | CC BY-SA 3.0 |
added 177 characters in body
|
May 16, 2014 at 13:10 | history | edited | Fish Below the Ice | CC BY-SA 3.0 |
deleted 203 characters in body
|
May 15, 2014 at 12:57 | history | edited | Fish Below the Ice | CC BY-SA 3.0 |
added 210 characters in body
|
May 15, 2014 at 12:34 | history | answered | Fish Below the Ice | CC BY-SA 3.0 |