3

I keep finding things with the <code> tag or the <pre> tag instead of four spaces or inline code formatting. I want to find these and fix them, replacing them with the better code formatting of the um well formatting. I want to be able to search for this. How can I do this?

  • 1
    +1 For the question. I don't find the underlying intent really worthwhile though. – David Foerster Jul 28 '17 at 9:48
3

Instead of searching for posts with HTML code formatting just so you can make them use the (usually) nicer Markdown style, I recommend that you instead search for posts with HTML code formatting as a heuristic for finding posts by inexperienced users that might benefit from editing. Then fix anything that needs fixing--unclear wording, grammar, spelling, capitalization, details in comments that belong in the post, tagging, broken links, visible formatting problems, meaningless titles, poorly cited quotations, and so forth.

While you're at it, you should also--usually--change <pre><code> </code></pre> (and sometimes just <pre> </pre>) to indentation by four spaces and <code> </code> to ` `. When doing so, please be aware that they do not always have the same effects, so you must be careful.

You can also make other similar HTML-to-Markdown changes, for example by replacing <br/> tags by separating paragraphs with blank lines (people often really mean <p> </p>) or, though less often warranted, by two spaces at the end of a line. Similar caveats apply.

The Problem

If you choose to find and change numerous posts' formatting from using the <pre> and <code> tags to using Markdown, please be careful. Placing text between <pre><code> and </code></pre> does not always have the same effect as indenting every line by four spaces, due to the way HTML and Markdown markup interact with other HTML and Markdown markup. Similarly, <code> </code> does not always work the same as ` `. (See below for how this can be the case, and some examples to watch out for.)

Therefore, care--and, in a few cases, exceptional care--will be required if you are to perform a large number of these substitutions without causing harm.

  • Sometimes the difference is unintentional but would still need to be tended to in making the change. (For example, if you came upon a post with a code block formatted one way followed immediately by a code block formatted the other way, what would you do? Would you format them the same way with no additional change? See below.)
  • Sometimes the difference is intentional. Some kinds of formatting cannot be achieved without HTML tags, and this includes some uses of <pre><code> </code></pre> and <code> </code>. I have written a number of posts that use those tags because they really have to (as well as a few posts, when I just started out on the site, that use them unnecessarily).

The Solution

Three concerns have been raised, regarding the project of replacing HTML code formatting with Markdown:

  1. This has the potential to be really boring for you.

    I read Zanna's answer as expressing this concern, but in case that was not intended, we can just say that I am expressing it right now.

  2. The changes are invisible--if done right--except to editors, so the benefit is small. (See Zanna's answer and David Foerster's comment.)

    These may in effect be trivial edits of the sort that (a) are not worth pushing other posts down and off the front page, if done in large numbers and (b) some reviewers may consider not worth their time/effort and opt to reject.

  3. Without very carefully examining the context and reading the surrounding text and markup, as well as carefully checking the rendered result, it is easy to break formatting that works. This is the concern I am expressing in this post.

But I don't think you need to let any of these worries stop you, so long as you broaden your ambit to include fixing all the other problems with the post. I do not mean just fixing other problems you happen to notice while zeroing in on HTML code formatting. I mean, read through the whole post and fix everything that benefits from fixing.

In most cases, backticks and indentation are easier, faster, and less prone to error than writing <code> and <pre><code> tags manually. Experienced Ask Ubuntu users almost always prefer backticks and indentation (except in case where the effects are different and they want the effect provided by manual HTML tagging). For this reason, I hypothesize that searching for posts with manual HTML code formatting is a useful way to find posts that are likely to benefit from improvement in other ways.

I believe this one change to your mission, by itself, would be sufficient to fully address all those potential problems.

  1. Reading posts and fixing everything you can is more interesting than focusing on one narrow formatting issue, and this sort of editing is intrinsically rewarding because you (and other people throughout the world) can see the improvements in the rendered posts.

  2. You'll be making multiple improvements, so the benefits will often be significant. It will also take (at least a little) longer to edit the posts. In combination, these factors will make your edits more useful. It will be worth it to review these edits and to have the recently edited posts appear on the front page. I don't think you'll have to worry about limiting the number of edits you do.

    Occasionally you may find posts where the only thing "wrong" is the use of HTML formatting, and in this case, you could still go ahead and fix that (if you want to). But I doubt most posts will be like that.

  3. Because you'll be reading through the post and looking for other problems, you are far less likely to miss ways that your formatting changes could have unintended results.


But how?

Markdown is translated into HTML, so how can Markdown code formatting produce different text than the HTML equivalent?

Code formatting in Markdown does turn into HTML, but it doesn't always turn into the exact HTML one might think it does. For example, this question about how to make URLs in Markdown gives an example URL, written like this:

    <a href="abc.php">ABC</a>

It appears like this:

<a href="abc.php">ABC</a>

To see how this is achieved, view the raw HTML of the page. (Browsers usually call this View Source. In Firefox, View Page Source is an option in the contextual menu that appears when you right-click on a page.) This reveals that the actual HTML code on the page is:

<pre><code>&lt;a href="abc.php"&gt;ABC&lt;/a&gt; 
</code></pre>

This sort of thing is what the editing guide means by "escaped" when it says:

Indent four spaces to create an escaped <pre> <code> block

To see how some other constructions are formed in HTML, you can view the source of this page.

Examples

This is a summary of some ways Markdown and HTML code formatting produce different results, but it is not exhaustive. I do recommend you watch out for these things, though.

Embedded Formatting: Inline Code Spans

An inline code span can exist within formatted text, but what if one wants to apply formatting to just some text within it?

This Markdown is an unsuccessful attempt to create an inline code span with one word linkified and another italicized:

> You can use `[rm](http://manpages.ubuntu.com/manpages/xenial/en/man1/rm.1.html) -i *filename*`.

It produces:

You can use [rm](http://manpages.ubuntu.com/manpages/xenial/en/man1/rm.1.html) -i *filename*.

But it works if you use <code> </code> instead of ` `.

> You can use <code>[rm](http://manpages.ubuntu.com/manpages/xenial/en/man1/rm.1.html) -i *filename*</code>.

That produces:

You can use rm -i filename.

Embedded Formatting: Code Blocks

Similarly, for a code block, this Markdown doesn't work:

    sudo apt install [libc++-dev](https://packages.ubuntu.com/xenial/libc++-dev)
    usermod -a -G sambashare *username*

It produces:

sudo apt install [libc++-dev](https://packages.ubuntu.com/xenial/libc++-dev)
usermod -a -G sambashare *username*

Changing the formatting inside the code block is not sufficient by itself:

    sudo apt install <a href="https://packages.ubuntu.com/xenial/libc++-dev">libc++-dev</a>
    usermod -a -G sambashare <em>username</em>

Because that just produces:

sudo apt install <a href="https://packages.ubuntu.com/xenial/libc++-dev">libc++-dev</a>
usermod -a -G sambashare <em>username</em>

But it works if you also use <pre><code> </code></pre> instead of indentation:

<pre><code>sudo apt install <a href="https://packages.ubuntu.com/xenial/libc++-dev">libc++-dev</a>
usermod -a -G sambashare <em>username</em></code></pre>

That produces:

sudo apt install libc++-dev
usermod -a -G sambashare username

Note that, unlike with inline code spans where Markdown inside <code> </code> tags works, code blocks require not just that the block be started and ended with explicit HTML, but that the internal formatting is achieved with HTML as well.

Adjacent Code Blocks

Suppose I have two separate code blocks in Markdown, one right after the other:

    first block

    second block

Well, that didn't work! Even though there are no spaces in the middle line that is intended to separate the blocks, Markdown treats it as a single code block and it gets rendered like this:

first block

second block

If someone used <pre> and <code> instead then the problem does not appear. (They may have used it deliberately for this reason, or they may be entirely unaware of this issue.)

<pre><code>first block</code></pre>

<pre><code>second block</code></pre>

That produces this, which looks right:

first block
second block

It also works if only one of the blocks is formatted with <code> and <pre>. It is only adjacent Markdown-formatted code blocks that are merged.

Using those HTML tags explicitly is not the best way to separate adjacent code blocks, and I do recommend converting them to using the Markdown style (so long as there are no other reasons not to). But you have to insert something between them that is not displayed but prevents them from being interpreted as a single block. I suggest an empty HTML comment:

    first block

<!-- -->

    second block

That looks like this:

first block
second block

A similar situation occurs with HTML <blockquote> vs. Markdown > quote formatting (and the same HTML-comment solution works):

> ABC

<!-- -->

> DEF

This produces:

ABC

DEF

Character References

Sometimes people who don't know about ` ` formatting will use <code> </code>, which you could replace with backticks, but only if you replace the character references they included, such as writing < as &lt;. If only they'd known about ` `, they wouldn't have needed to write such things!

You may see this:

> <code>&lt;code&gt;</code> and <code>&lt;/code&gt;</code> make an inline code span.

That looks like this:

<code> and </code> make an inline code span.

Suppose you replace the code tags with backticks:

> `&lt;code&gt;` and `&lt;/code&gt;` make an inline code span.

Well, that's no good:

&lt;code&gt; and &lt;/code&gt; make an inline code span.

You will need to convert the character references into literal text as well:

> `<code>` and `</code>` make an inline code span.

That's better:

<code> and </code> make an inline code span.

Embedded Backticks

Backticks work fine in code blocks, but they can cause problems in inline code spans that are opened and closed by backticks. You might write:

> `$()` is preferable to ``` `` ``` in shell scripts. You can use `$(seq 1 10)` instead of `` `seq 1 10` ``.

As desired, this produces:

$() is preferable to `` in shell scripts. You can use $(seq 1 10) instead of `seq 1 10`.

But because it is not obvious how to write that using the `-based syntax, some people use <code> </code> blocks, sometimes with character references or backslash escapes, to try to render it. Here's one way you might see:

> `$()` is preferable to <code>&#96;&#96;</code> in shell scripts. You can use `$(seq 1 10)` instead of <code>&#96;seq 1 10&#96;</code>.

Suppose you were to just replace the <code> and </code> tags with `:

> `$()` is preferable to `&#96;&#96;` in shell scripts. You can use `$(seq 1 10)` instead of `&#96;seq 1 10&#96;`.

That produces:

$() is preferable to &#96;&#96; in shell scripts. You can use $(seq 1 10) instead of &#96;seq 1 10&#96;.

Another way you might see is:

> `$()` is preferable to <code>\`\`</code> in shell scripts. You can use `$(seq 1 10)` instead of <code>\`seq 1 10\`</code>.

If you replace <code> and </code> with `:

> `$()` is preferable to `\`\`` in shell scripts. You can use `$(seq 1 10)` instead of `\`seq 1 10\``.

Then you get this mess:

$() is preferable to \`` in shell scripts. You can use $(seq 1 10) instead of \seq 1 10``.

Further reading: How can the backtick character ` be included in code?

I assume there are other cases where replacing HTML code formatting with Markdown requires extra care. Those are just the ones I've seen.

  • 1
    Yes indeed, fix everything about the post (and thank you for the wonderful guide to code formatting). When I am editing to clean up like this, I also try to check all the posts on the page (if there are answers) for any issues so as so economize on bumping, and because otherwise I might never see the page again. – Zanna Jul 28 '17 at 21:07
3

I am not sure this is the best use of your time, but, it's your time...

However, since you have < 2k as yet, it's also reviewers' time, so feedback on this is needed from others. Personally, I reformat posts like that if I happen to be editing them for some other reason, but I don't regard it as high priority to fix.

Also, editing old posts to fix invisible formatting issues should be done (if at all) slowly so as not to overwhelm the front page with bumped posts.

Answering the question though, you can search for them using Stack Exchange Data Explorer (SEDE).

The database stores post body text as rendered HTML, so the Body schema contains <code> if the post contains anything that renders as <code>, meaning we can't use that schema to find out if the markdown text actually contains <code>. However, the PostHistory table stores revisions in markdown format, so I was able to devise a probably overcomplicated and poorly written query mostly copied from other people's queries for you, which others could surely simplify and improve, to find (hopefully) posts whose current version contains <code> and <pre> tags.

Warning: it returns 7482 posts.

  • Right. It is not the best use of my time. Lets get back to reviewing FP&LA instead... I'll just do it when i find it – fosslinux Jul 28 '17 at 21:45
  • 1
    @ubashu but Eliah Kagan argued persuasively that you should do this if you want to, and you accepted his answer, so I am surprised you say that. I didn't mean my answer to sound dismissive, and if it came across that way, I'm sorry. It's awesome of you to look for extra ways to improve the site. PS, you will definitely find <pre> and <code> tags reviewing FP&LA ;) – Zanna Jul 28 '17 at 22:06
  • yeah that's what I meant I'll do it when I find it. Yes, I will still do it, but as you stated there is a lot of them... – fosslinux Jul 29 '17 at 3:29
  • 1
    @ubashu in that case I guess I myself will use my query from time to time as Eliah Kagan suggested to you, since I have written it XD – Zanna Jul 29 '17 at 4:56

You must log in to answer this question.

Not the answer you're looking for? Browse other questions tagged .