add convert list methods to the semantic HTML 5 converter

[ggrossetie]

original work: @redbow-kimee

[ggrossetie]

In summary:

<ul class="list">
<li><span class="listitem">alice</span>
<ul>
<li>subpoint 1</li>
<li>subpoint 2</li>
</ul>
</li>
</ul>

Should we also add the <span> element when there's a nested list? (for consistency)

<ul class="list">
<li><span class="listtext">alice</span>
<ul>
<li><span class="listtext">subpoint 1</span></li>
<li><span class="listtext">subpoint 2</span></li>
</ul>
</li>
</ul>

Regarding, description list should we use a desctext class name?

<dl class="list qanda">
<dt>Question 1?</dt>
<dd><span class="desctext">Answer 1.</span></dd>
</dl>

[redbow-kimee]

@ggrossetie Regarding <span> within a nesting list. I'm not sure why we need <span>s at all? Unless, is it to target just the text of the li itself without going into the subpoint's text. In that case, if there were a sub-subpoint we should have a span on the subpoint text to target that text without the text of the sub-subpoint?. Maybe we should have spans all the way down? although somebody could write their CSS to understand nesting levels.

/* For example if somebody wanted most fonts to be sans, but first level LIs to be serif, and subseqent nesting levels to go back to sans. Idk why anybody would want to change font family in particular, but I'm uncreative with my examples */

{
  font-family: sans;
}

li {
  font-family: serif;
}

li li {
  font-family: sans;
}

My personal preference would be to go with a system like this in CSS rather than adding extra spans and what not to facilitate a different system for writing CSS. But I understand that my opinions on CSS may differ from others, and that the spans don't prevent me from writing CSS in the shown manor. (They do cost extra characters on download, to the extent that actually matters with compression these days).

[redbow-kimee]

Regarding class='desctext', I don't see what that offers over already being inside a dd tag?

[redbow-kimee]

How should we handle titles in lists. Currently we get

.List title
* List item 1
* List item 2

<ul>
<strong class="title">List title</strong>
<li>List item 1</li>
<li>List item 2</li>
</ul>

But that leaves us with <strong> on its own inside the <ul>. Most browsers display the <strong> as a block tag (although I believe strong is an inline tag). Although CSS can fix this (ul>strong.title:first-child { display: block; }) to sort of force our intended behavior in the case of a browser that doesn't do what we expect it to. Is this the way to go?

[mojavelinux]

Regarding <span> within a nesting list. I'm not sure why we need <span>s at all?

From my experience styling HTML generated from AsciiDoc, I can say for certain that the <span> is crucial. Without it, there is no way to target the text of a list item in CSS without effecting other content. And without it, there would be no way to use the before and after pseudo-selectors, which are an important tool when styling list items. So this tag must remain.

Note that this tag is replacing a <p> in the output of the current HTML converter. There have been numerous complains about this because it adds extra space around each list item when no stylesheet is used, or no dedicated stylesheet is used (like on GitHub). The <span> is an ideal compromise.

Keep in mind that it's not poor semantics to add additional tags, especially div and span. That thread traces all the way back to the CSS Zen Garden days. If there an insufficient amount of tags, it makes the designer have to resort to using a lot of hacks, which is what we're trying to get away from.

What I'm not yet comfortable with is the name of the CSS class on it. I think that "listtext" is too specific when "text" would do. In CSS, you want to avoid redundant words in the hierarchy. If the class were just text, it could be targeted precisely using the li > span.text:first-child selector. I think we should try that until it's not sufficient.

[mojavelinux]

Regarding class='desctext', I don't see what that offers over already being inside a <dd> tag?

It's the same argument. This is the principal text. There can be other tags inside <dd> that follow it, and without a span around the text there is no way to target just the text and not the content that follows.

[mojavelinux]

I want to point out that in the spec, we're formalizing the name of the text of a list item, which precedes any attached blocks. That name is "principal text". That's why I still insist that the class be "principal" (as in span.principal) rather than "listtext" (or even "text" as I wrote above). Though since the formal term is "principal text" and the hierarchy suggests that it is principal based on its location, I would be willing to settle on "text".

[mojavelinux]

How should we handle titles in lists.

After reading some other threads in which the block title came up, I'm becoming convinced that it needs to be wrapped in a <div>. The <strong> is there since we must accept the fact that HTML generated from AsciiDoc is going to be rendered in places that will never provide a proper stylesheet, such as on GitHub. The addition of <strong> both provides an important default and extra emphasis that it's a title. (I'd be willing to go with <em> as an alternative for this reason).

But the fact that we're using an inline tag, yet treating it as a block, I don't think is sufficient. I think it needs to be inside of a block tag like <div>. (I've also seen <h3> used for this purpose, but I've never been quite convinced about the validity of that choice). The other alternative is to wrap any block element with a title in <figure> with a <figcaption>. However, I can just hear people in my mind complaining about that being too elaborate.

Again, keep in mind that we don't need to be austere with tags. What we're shooting for is something that looks readable and semantic with no stylesheet (or a deficient one like on GitHub) while at the same time being reasonable to style. There are a lot of concerns that the current HTML is awkward to target using CSS. If the structure we choose does not feel awkward, we will have achieved what we set out to achieve. There's no such thing as perfect HTML (even though many of probably yearn for such a thing, as I certainly do).

[redbow-kimee]

I can give a go at working up something like this after work.

<ul>
<div role="heading"><strong class="title">List title</strong></div>
<li><span class="principal">List item 1</span></li>
<li><span class="principal">List item 2</span></li>
</ul>

I think role="heading" might be the correct way to promote a non <Hn> to a heading of imprecise number. Although it has a friend tag aria-level="n" for the heading number which defaults to 2, so it might just default to being an <h2> tag.

[redbow-kimee]

the <header> tag might actually be appropriate for titles too. https://developer.mozilla.org/en-US/docs/Web/HTML/Element/header.

[mojavelinux]

I'd be open to exploring both ideas.

[redbow-kimee]

I'm going to go for <header> for the time being, to avoid potential conflation with section titles.

[redbow-kimee]

Okay, see work here ggrossetie#7