Use semantic constructs for listing blocks

[ggrossetie]

This issue will be addressed as part of: https://github.com/asciidoctor/asciidoctor/issues/242

Preformatted text

Listing blocks display their rendered content exactly as they were entered by the user. The <pre> fits the description as it represents a block of preformatted text.

Some examples of cases where the pre element could be used [...] Including fragments of computer code, with structure indicated according to the conventions of that language. [...]

https://html.spec.whatwg.org/multipage/grouping-content.html#the-pre-element

Code

When a language is defined (source block), we should wrap the content in a <code> element. Please note that it only applies when no syntax highlighter is defined.

The language should be added on the <code> element as a data attribute: <code data-lang="ruby">. Not sure if we should also add the language as a class, something like: <code class="language-ruby" data-lang="ruby">...? Arguably, we don't need it because we can use data attribute as CSS selector:

/* Selects if the attribute has a particular value */
code[data-lang="ruby"] {
}

/* Selects if the attribute is present at all */
code[data-lang] {
}

But at the same it might be useful?

Figure

The figure element represents some flow content, optionally with a caption, that is self-contained (like a complete sentence) and is typically referenced as a single unit from the main flow of the document.

https://html.spec.whatwg.org/multipage/grouping-content.html#the-figure-element

MDN Web Docs as more or less the same definition:

The HTML

(Figure With Optional Caption) element represents self-contained content, potentially with an optional caption, which is specified using the

element. The figure, its caption, and its contents are referenced as a single unit.

https://developer.mozilla.org/en-US/docs/Web/HTML/Element/figure

Both put emphasis on the fact that content wrapped in a <figure> element can be moved to another part of the document or to an appendix without affecting the main flow. Therefore, authors are encouraged to consider using labels to refer to figures, rather than using relative position, e.g., "in the photograph above" or "as the next figure shows", so that the page can easily be restyled without affecting the page's meaning.

I guess it's a general writing guideline that can apply when writing in AsciiDoc.

Listing block:

<figure class="listing">
<pre>error: 1954 Forbidden search
absolutely fatal: operation lost in the dodecahedron of doom

Would you like to try again? y/n</pre>
</figure>

Listing block with title:

<figure class="listing">
<figcaption><span class="label">Listing 1.</span> Gemfile.lock</figcaption>
<pre>GEM
  remote: https://rubygems.org/
  specs:
    asciidoctor (2.0.12)

PLATFORMS
  ruby

DEPENDENCIES
  asciidoctor (~> 2.0.12)</pre>
</figure>

Source block with title and roles:

<figure id="ruby-code" class="listing ruby code">
<figcaption><span class="label">Listing 1.</span> Some Ruby code</figcaption>
<pre><code data-lang="ruby">require 'sinatra'

get '/hi' do
  "Hello World!"
end</code></pre>
</figure>

As you can see we are using a built-in role/class named "listing" to differentiate listing block and literal block:

<figure class="literal">
<pre>error: 1954 Forbidden search
absolutely fatal: operation lost in the dodecahedron of doom

Would you like to try again? y/n</pre>
</figure>

We are also using a <span> element on the caption label to be able to style it.

Figure caption position

The <figcaption element can be declared as the first or last child of a <figure>:

before

after

In theory we could use this capability to configure (via an attribute?) if we want to display the caption at the start or at the end of the listing block.

Having said that, we can also do that using CSS and I don't know if other non-HTML converters will be able to leverage this feature.

[redbow-kimee]

CommonMark (among other things uses <pre><code> for listings. It would also be neat to switch between <pre><code> and <pre><samp> depending on if the listing is code or data.

[mojavelinux]

In general, we use the literal block for data and the source block for code. I think we should stick to that. I'd be okay with <pre><samp> for listing blocks.

[ggrossetie]

I'd be okay with <pre><samp> for listing blocks.

Something like that?

listing

<figure class="listing">
<pre><samp>GEM
  remote: https://rubygems.org/
  specs:
    asciidoctor (2.0.12)

PLATFORMS
  ruby

DEPENDENCIES
  asciidoctor (~> 2.0.12)</samp></pre>
</figure>

source listing

<figure class="listing">
<pre><code data-lang="ruby">require 'sinatra'

get '/hi' do
  "Hello World!"
end</code></pre>
</figure>

literal

<figure class="literal">
<pre>error: 1954 Forbidden search
absolutely fatal: operation lost in the dodecahedron of doom

Would you like to try again? y/n</pre>
</figure>

[mojavelinux]

I'd be okay with <pre><samp> for listing blocks.

Shoot! I meant to say for literal blocks. So I meant it the other way around.

[ggrossetie]

listing

<figure class="listing">
<pre>GEM
  remote: https://rubygems.org/
  specs:
    asciidoctor (2.0.12)

PLATFORMS
  ruby

DEPENDENCIES
  asciidoctor (~> 2.0.12)</pre>
</figure>

source listing

<figure class="listing">
<pre><code data-lang="ruby">require 'sinatra'

get '/hi' do
  "Hello World!"
end</code></pre>
</figure>

literal (listing sample? 🤓)

<figure class="literal">
<pre><samp>error: 1954 Forbidden search
absolutely fatal: operation lost in the dodecahedron of doom

Would you like to try again? y/n</samp></pre>
</figure>

[mojavelinux]

This seems like a strong proposal. I would be amenable to it. However, to make a final decision I think we should find some references to suggest that this is an endorsed structure. I'm thinking MDN or the like. Somewhere to say that others are doing this. A key goal of this convertor is for the HTML structure to be familiar, so we want as much as possible to build on conventions. If no convention can be found, then we are more free to select what we want.

[ggrossetie]

However, to make a final decision I think we should find some references to suggest that this is an endorsed structure.

A little bird told me that <samp> is not widely used but part of the HTML standard and documented on MDN: https://developer.mozilla.org/en-US/docs/Web/HTML/Element/samp

• https://almanac.httparchive.org/en/2022/markup
• https://docs.google.com/spreadsheets/d/1grkd2_1xSV3jvNK6ucRQ0OL1HmGTsScHuwA8GZuRLHU/edit#gid=2057119066
• https://www.advancedwebranking.com/seo/html-study/