Introduce style for itemized description list

[mojavelinux]

Introduce a style for description lists that presents the entries as an itemized list with the term text in bold.

You often see lists such as:

* *item a*: about item a

* *item b*: about item b

This is clearly a definition list, but the author wants it to appear as an itemized list. We can capture the author's intent in a way that preserves the semantics.

[itemized]
item a::
about item a

item b::
about item b

The style ordered can be used in place of itemized to create an ordered list.

[mojavelinux]

This should be implemented in a way consistent with the Asciidoctor EPUB3 converter, using the block name itemized for an unordered list and ordered for an ordered list.

See https://github.com/asciidoctor/asciidoctor-epub3/blob/master/lib/asciidoctor-epub3/converter.rb#L519

[mojavelinux]

This is now implemented in Asciidoctor PDF as well. See asciidoctor/asciidoctor-pdf#1280 (comment) I'd like to see it implemented in at least the HTML converter so it can provide a reference for discussing in the AsciiDoc spec.

Here's an example of how it's defined when using Asciidoctor PDF:

[unordered]
* alpha:: partially complete and unstable
* beta:: feature complete and undergoing testing

[goyalyashpal]

continued from #4475

---

but not by introducing new presentation controls. We're getting too far away from semantic markup

propsed were these 5 properties (or say total 12 possible values) quoted below;

• marker: none | ordered | unordered
• start: run-in | stacked
• indent: no | fixed | full-width
• if indent=full-width; only then: align-dt: left | right
• formatting: bold , italic, monospace

pick only first 3 of these properties that is,
just trim down the existing 4 keywords to control only one property and
make them to be orthogonal (i.e. useable with each other; aka cascadable);

even that would allow much more flexibiltiy

the result will be:

• qanda : controls the starting --> lack of it will make run-in
• (horizontal replaced by) full-indented --> lack of it will make fixed indented;
• remove the option for no-indent: use simple lists for no-indent.
• ordered , unordered --> lack of it will make none.

result: most all functionality exposed in just existing 4 words in a fully coherent manner; explainable in single page of documentation.

---

other than that, for the current state of implementation, i will say that:

• describing this feature of description lists alone required 3 different pages in documentation - all starting more-or-less afresh. that alone says a lot about the coherency of itemized list

• also, the horizontal list makes sense to be run-in; but the fact that it is indented at full width - doesn't seem very much intuitive to me at least, ....

[mojavelinux]

describing this feature of description lists alone required 3 different pages in documentation

What pages?

[mojavelinux]

FYI, the original proposal has matured a lot since introduced. It's now described on this page in the documentation: https://docs.asciidoctor.org/asciidoc/latest/lists/description-with-marker/

[mojavelinux]

The proposal you posted is not coherent. I cannot really understand what you are trying to propose. Concrete examples would help.

Keep in mind that we aren't redesigning description lists. We are trying to map into what has existed for nearly two decades. We can't just take the qanda style away. Adding ordered and unordered is a way to reuse the style in a consistent way to make a different kind of a list, less specialized than qanda.

I agree that horizontal should probably be repurposed as an option since it's not technically a style of list. And we have already proposed this in the AsciiDoc specification.

[goyalyashpal]

describing this feature of description lists alone required 3 different pages in documentation

What pages?

• descripttion: https://docs.asciidoctor.org/asciidoc/latest/lists/description/
• horizontal: https://docs.asciidoctor.org/asciidoc/latest/lists/horizontal/
• qanda: https://docs.asciidoctor.org/asciidoc/latest/lists/qanda/
• description with marker: https://docs.asciidoctor.org/asciidoc/latest/lists/description-with-marker/

---

[goyalyashpal]

#821 (comment)

I cannot really understand what you are trying to propose. Concrete examples would help.

• full-indented (absence of qanda makes first line run-in)

• qanda (absence of full-indented makes non-first line to be fixed indented)

• default (no full-indented, no qanda)

[mojavelinux]

Thanks for clarifying.

Regarding the list of pages, these are by-in-large different features so they require dedicated pages to explain them. If you think you can explain it more clearly, or with less pages, feel free to submit a content update to review.

As for the indentation, I don't think it's something that should be controlled with a dedicated style. You are free to add a full named .full-indented and add the necessary to support it. I see no reason to be introducing more syntax in AsciiDoc as this is one of a plethora of presentation layouts a user may want to achieve.

[goyalyashpal]

these are by-in-large different features so they require dedicated pages to explain them

yep, i understand - that's what i was saying: the reason that it requires this many pages is that:

• the implementation of features in current form is not coherent
• not that it was poorly written
• and the proposal's coherency can also be seen from the fact that the proposal's docs can come in same page

no reason to be introducing more syntax in AsciiDoc

the proposal actually doesn't introduce any more syntax? it's the same syntax - same brackets etc, only the properties i.e. the keywords that go inside that bracket changes

---

Keep in mind that we aren't redesigning description lists. We are trying to map into what has existed for nearly two decades.

that's a fair point, and in light of this - the proposal i made can be discarded. my proposal can't fix the current one, it is more suited if a rewrite is planned.

thanks for listening and cooperation :)

[mojavelinux]

only the properties i.e. the keywords that go inside that bracket changes

That's new syntax. It's an additional block style which then must have designation.

We do want to move towards having the most coherent syntax we can. And that is a goal of the AsciiDoc specification. But it won't be solved in Asciidoctor, especially when it means introducing new keywords. The original subject is accounting for a feature already supported and documented, hence why it gets an exception.