Checkboxes not recognized in description list

[Oblomov]

I'm assuming this is intentional, but I think it should be possible (at least by user-choice) to recognize checkboxes in description lists, e.g.:

.TODO list
[ ] some work item:: notes on this work-item
[ ] other work item:: notes on the other work-item
[*] etcoetera:: a first draft of this has been implemented

(I'm keeping this separate from #3211, but it's possible that a more general issue is that checkboxes should be supported in “all” lists?)

[abelsromero]

Checkboxes are a type of list (leaving aside if order or unordered) https://docs.asciidoctor.org/asciidoc/latest/lists/checklist. Your example should work if you add the missing list start, * or -.

.TODO list
* [ ] some work item:: notes on this work-item
* [ ] other work item:: notes on the other work-item
* [*] etcoetera:: a first draft of this has been implemented

.TODO list
- [ ] some work item:: notes on this work-item
- [ ] other work item:: notes on the other work-item
- [*] etcoetera:: a first draft of this has been implemented

[Oblomov]

With that syntax one gets and unordered checklist, as opposed to a “description checklist” (for lack of a better name). The double-colon separating the item from its description is ignored/rendered as-is, with no semantic distinction between the two parts, so I wouldn't consider that as “working”.

For unordered lists, an item starting with a checkbox (checked or not) enables the checklist option on that list. My expectation (or wish, maybe ;-)) is that the same would happen for the description list. I've given a quick look at the code and I think it should be implementable (a quick & dirty test showed that the parsing part is almost trivial, and the HTML5 conversion looks doable albeit requiring a bit more work.

[mojavelinux]

You are correct that the restriction is intentional. It is conventional to have an unordered list act as a checklist (which is a new type of list). We see it in several markup languages, including several variants of Markdown. I have never, however, seen a description list act as a checklist. It's not something I have ever considered, nor has it ever requested until now.

I think adding checklist support to all list types would be incorrect. A checklist is a type of list. It is not a modification of existing lists. Unless there is a very strong argument for why we need this, I would prefer to use existing syntax. If you do feel like you have a strong case, you will need to raise this with the spec as we are not making any modifications to the language until such proposals can be put on a standards track.

If you do want to support something like this, I would encourage you to do it via extension. One idea is to add a role to the description list, then use an extended HTML converter (or otherwise custom converter) to honor that role.

[mojavelinux]

I can maybe see one possible path forward, but I will warn you that it is still a long ways off. We are proposing both an "unordered" and "ordered" style on a description list, which is not a description list at all but rather a way to define an emphasized term for the unordered and ordered list types. See #821. That might then open up the door for a checklist defined that way as well. Something like:

.TODO list
[unordered]
[ ] some work item:: notes on this work-item

So if we combine this request with #821, maybe there's room somewhere in there for it. (Though I really do worry that we're making the syntax too complex). But mind you it will be handled as an unordered list with an emphasized term, not like a description list. (You can find prototype code in Asciidoctor PDF. See https://github.com/asciidoctor/asciidoctor-pdf/blob/e650037b1adf8c79b29c453f7d0ae7df8b491d78/lib/asciidoctor/pdf/converter.rb#L1180)

[abelsromero]

I think adding checklist support to all list types would be incorrect. A checklist is a type of list. It is not a modification of existing lists.

I think most users don't see it as a "type of list", instead they see [ ] as a shorthand for an "checkbox icon" and they expect to be able to use it in other lists or even other elements. I feel the same happens with descriptive lists, users use both features thinking in the resulting formatting more than the semantics. And these creates certain expectations.

I wonder if instead of combining lists we should encourage use of current "pure" list in combination with formatting elements, for example I could get the desired result using :icons:font

.TODO list
icon:square-o[] some work item::
notes on this work-item

icon:check-square-o[] other work item::
notes on the other work-item

[mojavelinux]

I think most users don't see it as a "type of list", instead they see [ ] as a shorthand for an "checkbox icon" and they expect to be able to use it in other lists or even other elements.

I don't necessarily agree with that assertion. We can create a checklist here on GitHub and it is clearly not an unordered list, but rather a list where the marker is a checkbox. So it's visibly a different type of list (only a single marker instead of having two different markers side-by-side).

What we might be able to agree on is that it is a different marker type, just like circle, disc, and square. In that sense, it very much fits. But then it is definitely a modification of a regular list instead of a description list.

I still want to see a semantic argument for where in other established documentation languages there is such a thing as description list that doubles as a checklist. I'm not saying there isn't one, but I need to see where else this has been done so we aren't making up new constructs out of the blue.

[Oblomov]

@mojavelinux I think the proposal for #821 comes very close. It is not clear to me however why the layout result is achieved by back-converting the dlist into a ulist or olist instead of keeping the semantic distinction between subject and description and appropriate use of styling?

I guess he the semantic distinction could be preserved even with the conversion: not with dt/dd, but at least by turning the terms and descriptions into spans or divs with an appropriate class.