semantically meaningful lists¤

lists, sequences, matrices are a life blood of interactive computing. in this document we explore improving the representation of lists in computational literature. as we encode semantics in list representations, we'll discover inequities for both assistive technology users and abled users using the archaic python representations as a reference for rich web representations. ultimately, the html experience can be better for everyone.

## a short list

consider a short list of integers called <var>abc</var>.

    abc = [1, 2, 3]

currently, the output from that python produces for terminal applications is provided in a `pre`.

```html
<pre>{{shell.display_formatter.format([1,2,3])[0]["text/plain"]}}</pre>
```

this representation destroys the rich structure of a list, and 
no one (eg assistive tech users, crawlers) wins when the semantic structure of objects is destroyed.
it would be best to represent the `list` is an `ol` which means ordered list.
assistive tech users benefit from proper semantics. 
most screen readers have easy navigation for lists and announce the size of the element.
in fact, list length might not be apparent to a sighted user while it is made more clear to assistive tech.

the destructive nature of the pre-formatted representations is an artifact of mapping interactive computing into the browser.
extending interactive computing to the browser offers new degrees of freedom that maintain the semantic structure 
of display objects.

a short list¤

consider a short list of integers called abc.

abc = [1, 2, 3]

currently, the output from that python produces for terminal applications is provided in a pre.

<pre>[1, 2, 3]</pre>

this representation destroys the rich structure of a list, and no one (eg assistive tech users, crawlers) wins when the semantic structure of objects is destroyed. it would be best to represent the list is an ol which means ordered list. assistive tech users benefit from proper semantics. most screen readers have easy navigation for lists and announce the size of the element. in fact, list length might not be apparent to a sighted user while it is made more clear to assistive tech.

the destructive nature of the pre-formatted representations is an artifact of mapping interactive computing into the browser. extending interactive computing to the browser offers new degrees of freedom that maintain the semantic structure of display objects.

a semantic ordered list¤

1
2
3

<ol id="abc-simple"><li>1</li><li>2</li><li>3</li></ol>

html for the ordered list representation

in this representation, the ordered list structure is maintained and screen readers will announce the list and its length. light css can be added to capture the visual structure of the python pre-cursor. in this representation, the list is implicitly associated with the variable abc without any visual or audible relationships.

### css to style lists to look like python output


the style changes below bring visual parity to standard python representation.

{% set _ %}
ol {
    list-style-type: none; 
    font-family: monospace;
    li {display: inline;}
}
ol[id^=abc-] {
    li:first-of-type:before {content: "[";}
    li:last-of-type:after {content: "]";}
    li + li:before {content: ",";}
}
{% endset %}

```css
{{_}}
```

<style>{{_}}</style>

unfortunately, the `content` attributes of the screen reader will be reader 
and that will create a lot of noise. it would be best to explicitly add these glyphs and hide them from the screen reader.

css to style lists to look like python output¤

the style changes below bring visual parity to standard python representation.

ol {
    list-style-type: none; 
    font-family: monospace;
    li {display: inline;}
}
ol[id^=abc-] {
    li:first-of-type:before {content: "[";}
    li:last-of-type:after {content: "]";}
    li + li:before {content: ",";}
}

unfortunately, the content attributes of the screen reader will be reader and that will create a lot of noise. it would be best to explicitly add these glyphs and hide them from the screen reader.

## a semantic ordered list 

https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ol#attributes

https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-posinset
https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-setsize

{% set l = 3 %}
{% set _ %}
<section>
<label id="label-abc-short"><var>abc</var></label>
<ol aria-labelledby="label-abc-short" id="abc" reversed="" start="" type="">{% for i in range(1, 4) -%}
    <li aria-posinset="{{loop.index}}" aria-setsize="{{l}}" value="{{loop.index}}">
        {% if loop.first -%}<span aria-hidden="true">[</span>{%- endif -%}{{i}}<span aria-hidden="true">{{",]"[loop.last]}}</span>
</li>{% endfor %}
</ol>
</section>
{% endset %}

{{_}}

```html
{{_}}
```

some motivations for the design are listed below:

* an `ol` is not labellable so the `for` attribute on the `label` doesn't apply. [lists can have titles](https://www.scottohara.me/blog/2020/05/02/labelled-lists.html), and they can be used _situationally_
`aria-labelledby` associates the label with the list.

    matrices, lists, sequences, tensors are comminly represented in notebook documents.
     a lot of ambiguity can arise on a page for screen reader users when the lists are unlabeled.

* the label for the screen reader should be exposed to all users and hidden with a toggle. the standard representation relies on an sighted users to connect the output displays with the source code.
* it is common to shorten long lists, the `aria-setsize` and `aria-posinset` attributes let us capture these semantics.
* punctuation that recaptures that python representation is hidden from screen readers.
* [WHATWG `ol`](https://html.spec.whatwg.org/#the-ol-element) permits `reversed` `type` and `start`.
* [ARIA `role=listitem`]() permits `aria-setsize` `aria-posinset`

some challenges still exist in our representation of this short list.

* sighted users can't easy discover the length of a long list.
* structure is lost because we don't the type of items. is `a` an integer, float, or string?

a semantic ordered list¤

https://developer.mozilla.org/en-US/docs/Web/HTML/Element/ol#attributes

https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-posinset https://developer.mozilla.org/en-US/docs/Web/Accessibility/ARIA/Attributes/aria-setsize

abc

1
2
3

<section>
<label id="label-abc-short"><var>abc</var></label>
<ol aria-labelledby="label-abc-short" id="abc" reversed="" start="" type=""><li aria-posinset="1" aria-setsize="3" value="1">
<span aria-hidden="true">[</span>1<span aria-hidden="true">,</span>
</li><li aria-posinset="2" aria-setsize="3" value="2">
        2<span aria-hidden="true">,</span>
</li><li aria-posinset="3" aria-setsize="3" value="3">
        3<span aria-hidden="true">]</span>
</li>
</ol>
</section>

some motivations for the design are listed below:

an ol is not labellable so the for attribute on the label doesn't apply. lists can have titles, and they can be used situationally aria-labelledby associates the label with the list.

matrices, lists, sequences, tensors are comminly represented in notebook documents. a lot of ambiguity can arise on a page for screen reader users when the lists are unlabeled.
the label for the screen reader should be exposed to all users and hidden with a toggle. the standard representation relies on an sighted users to connect the output displays with the source code.
it is common to shorten long lists, the aria-setsize and aria-posinset attributes let us capture these semantics.
punctuation that recaptures that python representation is hidden from screen readers.
WHATWG ol permits reversed type and start.
ARIA role=listitem permits aria-setsize aria-posinset

some challenges still exist in our representation of this short list.

sighted users can't easy discover the length of a long list.
structure is lost because we don't the type of items. is a an integer, float, or string?

## enriched labelling

{% set _ %}
<label id="label-abc">
<label><var>abc</var></label>
<label aria-label="of type">:</label><output id="type-abc"><code>{{[].__class__.__name__}}</code></output>
<span aria-hidden="true">of</span> <label aria-hidden="true">length</label> <output aria-hidden="true">3</output>
</label>
{% endset %}

<figure>{{_}}
<figcaption>
<figure>

```html
{{_}}
```
<figcaption>
html for the ordered list representation
</figcaption>
</figure>
</figcaption>
</figure>

### type annotations provide further enrichment.

enriched labelling¤

abc :list

<label id="label-abc">
<label><var>abc</var></label>
<label aria-label="of type">:</label><output id="type-abc"><code>list</code></output>
<span aria-hidden="true">of</span> <label aria-hidden="true">length</label> <output aria-hidden="true">3</output>
</label>

html for the ordered list representation

type annotations provide further enrichment.¤

{% set _ %}

<label id="label-abc-long">
<label><var>abc</var></label>
<label aria-label="of type">:</label><code>{{[].__class__.__name__}}</code>
<span aria-hidden="true">of</span> <label aria-hidden="true">length</label> <output aria-hidden="true">3</output>
</label>
<ol aria-labelledby="label-abc-long" id="abc">{% for i in range(1, 4) -%}
    <li>
        {% if loop.first -%}<span aria-hidden="true">[</span>{%- endif -%}
        {{i}}<span aria-hidden="true">{{",]"[loop.last]}}</span>
</li>{% endfor -%}
</ol>
<span></span>
{% endset %}

<figure>{{_}}
<figcaption>
<figure>

```html
{{_}}
```
<figcaption>
html for the ordered list representation
</figcaption>
</figure>
</figcaption>
</figure>

abc :list

1
2
3

<label id="label-abc-long">
<label><var>abc</var></label>
<label aria-label="of type">:</label><code>list</code>
<span aria-hidden="true">of</span> <label aria-hidden="true">length</label> <output aria-hidden="true">3</output>
</label>
<ol aria-labelledby="label-abc-long" id="abc"><li>
<span aria-hidden="true">[</span>1<span aria-hidden="true">,</span>
</li><li>
        2<span aria-hidden="true">,</span>
</li><li>
        3<span aria-hidden="true">]</span>
</li></ol>
<span></span>

html for the ordered list representation