Unclear meaning block.

[renintw]

Found when reviewing #447.
There's a code block with unclear meaning.
Example: http://localhost:8895/reference/classes/wp_query/#standard-loop

[renintw]

Some findings:

1. It can be fixed by removing <pre class="notranslate"> in the shortcode.
2. It also can be fixed by adding an extra <pre> tag around the %2$s here.
3. Once there's <pre></pre> inside the shortcode, there'd be an extra <p> + <code> as shown in the PR description.

You can test with the following content in a new post.

<!-- wp:shortcode -->
[php]
<span class="pl-ent">&lt;?php</span>
<pre class="notranslate"><span class="pl-c">// The Query.</span>
<span class="pl-s1"><span class="pl-c1">$</span>the_query</span> = <span class="pl-k">new</span> <span class="pl-v">WP_Query</span>( <span class="pl-s1"><span class="pl-c1">$</span>args</span> );

<span class="pl-c">// The Loop.</span>
<span class="pl-k">if</span> ( <span class="pl-s1"><span class="pl-c1">$</span>the_query</span>-&gt;<span class="pl-en">have_posts</span>() ) {
	<span class="pl-k">echo</span> <span class="pl-s">'&lt;ul&gt;'</span>;
	<span class="pl-k">while</span> ( <span class="pl-s1"><span class="pl-c1">$</span>the_query</span>-&gt;<span class="pl-en">have_posts</span>() ) {
		<span class="pl-s1"><span class="pl-c1">$</span>the_query</span>-&gt;<span class="pl-en">the_post</span>();
		<span class="pl-k">echo</span> <span class="pl-s">'&lt;li&gt;'</span> . esc_html( get_the_title() ) . <span class="pl-s">'&lt;/li&gt;'</span>;
	}
	<span class="pl-k">echo</span> <span class="pl-s">'&lt;/ul&gt;'</span>;
} <span class="pl-k">else</span> {
	esc_html_e( <span class="pl-s">'Sorry, no posts matched your criteria.'</span> );
}
<span class="pl-c">// Restore original Post Data.</span>
wp_reset_postdata();</pre>
[/php]
<!-- /wp:shortcode -->

Before diving further into this:

1. After the fix from #447, the block will be invisible. However, it still occupies space. Visually, it looks like bottom padding. Ideally, it would be better to remove it, but if the method of removal is complicated or tricky, perhaps it's okay to leave it for now?
2. Is anyone familiar with the reason here - why in the shortcode, the addition of the pre tag comes with an extra <p> tag. Is this intentional?

cc @ryelle @adamwoodnz

[ryelle]

I think all the HTML in the shortcode is legacy or maybe carried over from copy-paste, since the syntax-highlighting is done by prism.js now. I imagine the parsing that prism.js causes the extra nested code.

Is this an issue on more than one page? Do we need a code solution, or could we just update the content in the explanation here?