A proposal to make algorithms easier to read using foldable sections.

[pchampin]

As @iherman suggested, I'm using <details>

• the <summary> is a "comment" summarizing the embeded steps
• the rest of the <details> contains the list of steps

See the Context Processing Algorithm, Section 4.1.2, for an example.
If the group thinks that is a good idea, I can apply it to the other algorithms.

---

Preview | Diff

---

Preview | Diff

[pchampin]

Note that one problem of the <details> tag is that its content is not printed unless explicitly unfolded.

This can be seen as a feature (some readers might prefer to print less pages to get an overview of the algorithms). In that case, we could simply add a button/link somewhere to "unfold all", as a convienence for readers who do want to print the algorithms in extenso.

If we decide instead that it is a bug, I see two ways to solve it.

• There are JS snippets out there to automatically unfold all <details> tags just before printing. I don't know how robust they are.
• We can markup the algorithm slightly differently: instead of putting the <ol> list of steps inside the <details>, we put it right after it. Then we add a CSS rule for the screen media only, that hide any <ol> located right after a closed <details>.

The second option above is hacky (the <details> tags only contain a summary, and no details...), but it provides the same user experience as before, while ensuring that algorithms are printed unfolded (and no, there is no cleaner way to do it in pure, see CSS w3c/csswg-drafts#2084). As an example, I used this hack on the step 5.1 of the Context Processing Algorithm, Section 4.1.2. You can check that it behaves exactly like the others, but it does print even when closed on the screen.

[iherman]

As a general approach, I do like it.

I am not overly concerned about the problem of unfolding them all in one step. But doing it in Javascript should not be a huge deal, so if there are already solutions out there, let us bring them in and we can look at it...

[gkellogg]

It is certainly interesting, I’m not sure we’d want to apply it to every embedded <ol> element in a large algorithm, but it could make the algorithm easier to take in.

I’d like @dlongley’s opinion, and we should discuss on Friday.

[dlongley]

An "expand all" button is highly desirable... otherwise I think it's ok.

[BigBlueHat]

Can we have this reviewed for accessibility?

Also, I'd almost prefer it work the other way around--with them open by default and then close-able for anyone who's read them/checked-them-off-while-implementing. With them collapsed by default, I fear they'll be skimmed/skipped--or considered advisory and not essential.

[gkellogg]

Can we have this reviewed for accessibility?

With the appropriate CSS media query, these could default to open. According to this article, summary is taxable, and the opened using the enter/space keys (at least for Windows/Mac)

On Windows/Mac desktops/laptops using browsers that support the elements, the <summary> element automatically becomes a tab stop on the page. Once focus is on the <summary> element, the full <details> content can be toggled by using either the enter key or the space bar.

So the <summary> element is effectively treated as a <button> element.

Also, I'd almost prefer it work the other way around--with them open by default and then close-able for anyone who's read them/checked-them-off-while-implementing. With them collapsed by default, I fear they'll be skimmed/skipped--or considered advisory and not essential.

I think if the summary elements are reasonable, and this may require work on the algorithms to make them so, they should give a good sense of what's in the details, so defaulting to closed should work. That said, as I said above, I think we need to be judicious. For example, loops should probably not be collapsed, but more relatively atomic lists that can be effectively summarized. Done right, it could make the entire document much more approachable.

[iherman]

This issue was discussed in a meeting.

• ACTION: contact Avneesh Singh regarding a11y of fold/unfold button (Ivan Herman)

View the transcript

Rob Sanderson: See API PR #132
Pierre-Antoine Champin: We discussed this a while ago, and I decided to try and make the algorithms a bit easier to read
… Thought it would be convenient to have another view of it for easier to have a global understanding before diving into the details
Gregg Kellogg: See Example for the algorithm
Pierre-Antoine Champin: Tried on one of them to use <detail> that allows folding/unfolding of the algorithm, and I think it does the job providing we use an appropriate title for the detail to give a good summary
… problem of printing. After some exchange in the issue I added some js that unfolds during printing, so the printed version is complete
… dlongley suggested that an unfold all button would be useful
… only question is about ergonomics – where should the button be? Hovering so it’s always there, or somewhere particular?
… perhaps also a keyboard shortcut for it?
Ivan Herman: In general I’m all for this. Looking for an example for where to put the button
… I’m looking for an example about where to put his button.
Ivan Herman: See OWL Primer example with buttons
Ivan Herman: in the OWL primer, you can switch between syntaxes.
Benjamin Young: buttons are specifically here https://www.w3.org/TR/2012/REC-owl2-primer-20121211/#OWL_Syntaxes
Ivan Herman: There is a set of buttons to do that, somewhere in the introduction.
Gregg Kellogg: we have an similar example in the API.
… How much can we get with CSS selectors? Are there any a11y considerations?
… It shouldn’t be considered as normative change, but could this lead us to change the structure of some algorithms?
Ivan Herman: we should ask Avneesh Singh to have a look at pchampin’s example.
Rob Sanderson: We has a similar button in annotation-model, to switch between Turtle and JSON-LD examples,
… this caused much change in layout, because Turtle was much shorter.
Ivan Herman: that’s why I suggest just one, at the top
Gregg Kellogg: plus each individual

has its own button
Action #2: contact Avneesh Singh regarding a11y of fold/unfold button (Ivan Herman)
Rob Sanderson: +1 to complete
Dave Longley: +1 to complete
Ivan Herman: +1 to complete
Benjamin Young: +1 to complete
Pierre-Antoine Champin: we seem to agree that the printed version should be complete, with all details unfoleded
Gregg Kellogg: could this be done via CSS @media query rather than JS?
Pierre-Antoine Champin: unfortunately not
Gregg Kellogg: what about epub?
Ivan Herman: if the JS is self contained, it should work
Rob Sanderson: what if JS does not work?
Pierre-Antoine Champin: it will be printed in its current state: any detail that you opened is printed open
Rob Sanderson: that seems acceptable

[TallTed]

Please correct typo (s/algotithms/algorithms/) in the title of this PR, to make lives of future readers easier.