We have chosen <blockquote class="role-ADMONITION"> rather than <div class="role-ADMONITION"> to represent admonitions (http://www.xmlmind.com/ebookc/_distrib/doc/manual/html/admonitions.html) for a very minor convenience: the default CSS style of blockquotes

blockquote {
    display: block;
    margin-top: 1em;
    margin-bottom: 1em;
    margin-left: 40px;
    margin-right: 40px;

is somewhat adapted to admonitions.

We totally understand your point ("To use blockquote for notes goes against its semantics"), but we don't plan to change our implementation of admonitions in the near future. Sorry.

PS: https://www.w3.org/TR/html52/sections.html#the-aside-element
The aside element represents a section of a page that consists of content that is tangentially related to the content of the parenting sectioning content, and which could be considered separate from that content.

This rules out <aside> for implementing admonitions. An admonition is something 100% related to the rest of the story. The reader may skip reading an <aside>; she/he should not skip reading an admonition.

On 02/25/2018 09:45 PM, Leif Halvard Silli wrote:
You may have taken into account that someone could react to this, so
this could be shot it in the air ... But nevertheless:

The Ebook vocabulary uses <blockquote class="role-FOO">…</blockquote>
for notes (notes, warnings, cautions, restrictions etc). This is
controversial since blockquote is meant for (long) quotations. Citing
HTML: [1]

    ]] The blockquote element represents content that is quoted from
    another source, [[

Obviously, even if the text inside a note is just boilerplate text (and
thus, in a sense taken from somewhere else), it does not represent
”content that is quoted from another source".

The elements that seem correct for the "notes" usecase, are <p
class="role-note"> (or <div class="role-note"><p/></div>), <figure
class="role-note"> or <aside class="role-note"> - all of them good
choices, I think. A quick evaluation of them:

<p class="role-note">: What speaks for <p class="role-note"> is …

  * The HTML5 specification itself uses <p class="note"> for notes. For
    multi-paragraph notes, it uses <div
    class="note"><p>...</p><p>...</p></div>. See for instance the notes
    inside the HTML5 specification of the figure element.2
  * Use of <p> or <div><p/></div> is a strong indication that the note
    is ”part of the content” and not ”complementary” content (see below).

<figure>: What speaks for the the <figure> element is …

 1. that <figcaption> can be used to set the type of note (warning,
    caution, important etc) - currently the type of note is not rendered
    to the reader. (At the very least, currently, when converting to
    HTML, the type is not included.)
 2. that it is not untypical that figures can be reused in many
    different contexts - and the notes use case seems like a case where
    same text can be used in many different locations of a larger text.
 3. that the <figure> also has the same graphical advantages as the use
    of <blockquote>, namely it indents the content so that it is
    visually separate from the surrounding text.

<aside>: What speaks for <aside> is …

 1. that, according to HTML5, the ”aside element represents a section of
    a page that consists of content that is tangentially related to the
    content of the parenting sectioning content, and which could be
    considered separate from that content. Such sections are often
    represented as sidebars in printed typography.”
 2. that <aside> is meant, amongst other things, for ”pull quotes”,
    which have a resemblence of ”notes”.[3]
 3. that the default ARIA role of <aside> is ”complementary”, which
    means that it represents “A large perceivable region that contains
    information about the parent document.“ [4]

The choice between <aside> and the other options seems to boil down to
whether such ”notes” should be considered ”part of the content“. Citing
the specification of <figure>:

    ]] For example, a pull quote that repeats content from an article
    would be more appropriate in an aside than in a figure, because it
    isn’t part of the content, it’s a repetition of the content for the
    purposes of enticing readers or highlighting key topics. [[

The logic to be gleaned seems to be that if the text is an “about text”
- a text about the text - then it is not “part of the content” but
rather an aside. And since - or as long as - "notes” are pieces of text
that tell the user how to read “the content”, the <aside> element seems
right. And, as the HTML spec points out, one may wrap a <figure> inside
the <aside>, if need be - that way one may get the the correct semantics
from <aside>, and the graphical indent from the <figure>.

My preference, based one the semantics that speaks most to me, is to use
<aside class="role-note">.

[1] https://www.w3.org/TR/html/grouping-content.html#the-blockquote-element
[2] https://www.w3.org/TR/html/grouping-content.html#the-figure-element
[3] https://www.w3.org/TR/html/sections.html#the-aside-element
[4] https://www.w3.org/TR/wai-aria-1.1/#contentinfo

XMLmind Ebook Compiler Support List

Reply via email to