Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Rearrange Intent section #513

Merged
merged 13 commits into from
Nov 1, 2024
Merged

Rearrange Intent section #513

Changes from 9 commits
Commits
Show all changes
13 commits
Select commit Hold shift + click to select a range
b3ce4ac
Rearrange intent.html to collect speech generation rules into a singl…
brucemiller Oct 26, 2024
c738490
trigger
brucemiller Oct 26, 2024
7ec3268
fixup links
brucemiller Oct 26, 2024
ffbfc9e
fixup link again
brucemiller Oct 26, 2024
9902004
Soften language, reduce clarity; remove obsolete script-specific prop…
brucemiller Oct 29, 2024
2ca1021
Tweak respec?
brucemiller Oct 29, 2024
351e0be
remove dfn from intent_property_list
brucemiller Oct 29, 2024
f3f9fec
VERY tentative sketch of section about infering or completing intent
brucemiller Oct 30, 2024
ab18ecf
Clarified case where intent has no arguments (especially token case);…
brucemiller Oct 31, 2024
02710c3
Corrections suggested by D.Carlisle
brucemiller Oct 31, 2024
74934d2
Changed :matrix back into :array (thanks D.Ginev)
brucemiller Oct 31, 2024
bd66653
Accommodate (mostly) the comments in the recent group meeting
brucemiller Nov 1, 2024
98570e3
Update src/intent.html
brucemiller Nov 1, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
202 changes: 87 additions & 115 deletions src/intent.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -86,16 +86,7 @@ <h3 id="mixing_intent_grammar">The Grammar for <code class="attribue">intent</co
<p>A <dfn id="intent_concept">concept</dfn> corresponds to some mathematical or
application specific function or concept.
For many concepts, the words used to speak a concept are very similar to the name
used when referencing a concept.
A <dfn id="intent_known_concept">known concept</dfn> matches a name
in an [=Intent Concept Dictionary=] recognized by the AT.
This may produce specific audio or braille renderings based on the speech hints
given in the list.
An <dfn id="intent_unknown_concept">unknown concept</dfn> is a concept not
currently known to the AT. These will be treated the same as a [=literal=], spoken as-is
after normalizing each of `-`, `_` and `.` to an inter-word space.
However, future updates of the AT and [=Intent Concept Dictionary=] may
include additional concepts, at which time those concepts may also receive special treatment.</p>
used when referencing a concept.</p>
</li>
<li>
<p>A <dfn id="intent_literal">literal</dfn> is a name starting with <q>`_`</q> (U+00F5).
Expand Down Expand Up @@ -149,10 +140,11 @@ <h3 id="mixing_intent_grammar">The Grammar for <code class="attribue">intent</co
the core properties as described below.</p>
</dd>

<dt><dfn id="intent_property_list">self-property-list</dfn></dt>
<!-- <dt><dfn id="intent_property_list">self-property-list</dfn></dt>-->
<dt>self-property-list</dt>
<dd>At the top level, an [=intent=] may consist of just a
non-empty list of properties. These apply to the current element
as described in <a href="#mixing_intent_self"></a>.</dd>
as described in <a href="#intent_using"></a>.</dd>

<!--<dt><dfn id="intent_expression">expression</dfn></dt>-->
<dt>expression</dt>
Expand All @@ -162,17 +154,15 @@ <h3 id="mixing_intent_grammar">The Grammar for <code class="attribue">intent</co

<section>
<h3 id="mixing_intent_dictionaries">Intent Concept Dictionaries</h3>
<p>An <dfn>Intent Concept Dictionary</dfn> is a mapping from a [=concept=] name
to speech or braille for that concept.
The mapping may take into account any [=property=] that follows the name.
AT that makes use of <code class="attribute">intent</code>
SHOULD be able to produce speech or braille that corresponds to any
of the concepts in the [=Core=] list discussed below.
AT that makes use of <code class="attribute">intent</code>
MAY also include concepts in the [=Open=] list discussed below,
as well as its own built-in dictionaries.
</p>
<p>The Intent Concept Dictionary is somewhat analogous to the <a href="#oper-dict"></a> used by
<p>Every AT system that supports <code class="attribute">intent</code> contains,
at least implicitly, a list of the concepts that it recognizes
(The details of matching and using concept names is given in <a href="#intent_using"></a>).
Such an AT SHOULD recognize the concepts in the [=Core=] list discussed below;
It MAY also include concepts in the [=Open=] list discussed below,
as well as any of its own.</p>
<p>An <dfn>Intent Concept Dictionary</dfn>
maps [=concept=] names to speech, text or braille for that concept;
it is somewhat analogous to the <a href="#oper-dict"></a> used by
MathML renderers in that it provides a set of defaults renderers should be aware of.
The <code>property</code> also has some analogies to the operator dictionary's use of
<code class="attribute">form</code> because a match makes use of fixity properties
Expand All @@ -194,40 +184,6 @@ <h3 id="mixing_intent_dictionaries">Intent Concept Dictionaries</h3>
<q>greater-than</q>. The list is curated by the Math Working
Group based on experience with different AT implementations and
following the guidelines set out in [[?Concept-Lists]].


<p>Some readings benefit from annotating the kind of
mathematical object, rather than giving an explicit concept
name to be spoken. For such cases, one should use an Intent
[=property=] instead of an Intent [=concept=]. The Math
Working Group maintain a similar list of <a
href="https://w3c.github.io/mathml-docs/intent-core-properties/">list
of core property names</a> as described in the following
section.</p>

<p>AT reading MathML attributed with a concept (or property)
in these lists SHOULD consider this concept (or property) to be
a hint how the content could be read. AT systems MAY use this concept
as a hint to improve braille generation. However, because
common notations have many specialized ways of being spoken, AT
is NOT constrained to use the name given. For example, AT may
vocalize a fraction marked up with <code>&lt;mfrac></code>
as <q>three quarters</q> or <q>three over x</q>
or may vocalize an inline fraction marked up as <code>&lt;mo>/&lt;/mo></code>
as <q>three divided by x</q>.
The choice may depend on the contents
and carrier element associated with an
<code>intent="divide($num,$denom)"</code>.</p>

<p>
Depending upon the reader, AT may add words or sounds to make
the speech clearer to the listener. For example, for someone
who can not see the a fraction, AT might say <q>fraction x over
three end fraction</q> so the listener knows exactly what is
part of the fraction. For someone who can see the content,
these extra words might be a distraction. AT should always
produce speech that is appropriate to the community they serve.
</p>
</li>
<li><dfn id="intent-open">Open</dfn>: This is an
<a href="https://w3c.github.io/mathml-docs/intent-open-concepts">open list of concepts</a>
Expand All @@ -243,39 +199,13 @@ <h3 id="mixing_intent_dictionaries">Intent Concept Dictionaries</h3>
<p>Future versions of the concept list may incorporate names from the <q>open</q> list into the
<q>core</q> list if usage indicates that is appropriate.
</p>
<p>When comparing a concept name from the <code class="attribute">intent</code>
attribute with entries in an [=Intent Concept Dictionary=], the comparison should be
<a data-cite="INFRA#ascii-case-insensitive">ASCII case-insensitive</a>
and also normalize
<q>`_`</q> (U+00F5) and <q>`.`</q> (U+002E) to <q>`-`</q> (U+002D).
An intent matches an entry in a concept list when the normalized name, the fixity property
(which may be defaulted in the concept dictionary), and the number of arguments all match.
If a match is found, the speech hint in the list
should be used be used as a guide for the generation of suitable text
for the <a href="#intent_known_concept">known concept</a>.
Recall that any concept not currently known to the AT is an <a href="#intent_unknown_concept">unknown concept</a>
and treated as a <a href="#intent_literal">literal</a>.
Both <a href="#intent_known_concept">known concepts</a> and
<a href="#intent_unknown_concept">unknown concepts</a> should be read in a manner
consistent with any given or default fixity properties.
</p>
</section>

<section>
<h3 id="mixing_intent_properties">Intent Properties</h3>
<p>As with [=Concepts=], The Working group maintains lists
of [=property=] values.
<dfn id="intent-core-properties">Core properties</dfn>: This is a
<a href="https://w3c.github.io/mathml-docs/intent-core-properties">list core of properties</a>
maintained by the Math Working Group
and
<dfn id="intent-open-properties">Open properties</dfn>: This is an
<a href="https://w3c.github.io/mathml-docs/intent-open-properties">open list of properties</a>
with contributions welcome from the community.</p>


<p>When generating speech a system should use any properties
specified in the <code class="attribute">intent</code> attribute.
<p>Intent [=properties=] act as modifiers of the speech or Braille that
otherwise would have been generated by the <code class="attribute">intent</code> attribute.
Most of these properties only have a
defined effect in specific contexts, such as on the head of an
<a data-link-for="intent" data-link-type="dfn"
Expand All @@ -285,10 +215,21 @@ <h3 id="mixing_intent_properties">Intent Properties</h3>
but as with any properties, is by default ignored but may have a
system-specific effect.</p>

<p>As with [=Concepts=], The Working group maintains two lists
of [=property=] values.</p>
<ul>
<li><dfn id="intent-core-properties">Core properties</dfn>: This is a
<a href="https://w3c.github.io/mathml-docs/intent-core-properties">list core of properties</a>
maintained by the Math Working Group</li>
<li><dfn id="intent-open-properties">Open properties</dfn>: This is an
<a href="https://w3c.github.io/mathml-docs/intent-open-properties">open list of properties</a>
with contributions welcome from the community.
Implementors of MathML systems that implement additional properties are encouraged
to make a pull request to add them to the list of [=Open Properties=].</li>
</ul>
<p>Whilst the definitive list of [=Core Properties=] is maintained at
Github, we describe the major classes of property affecting speech generation
below. Implementors of MathML systems that implement additional properties are encouraged
to make a pull request to add them to the list of [=Open Properties=].</p>
below.</p>
<dl>
<dt id="intent_fixity_hint"><code>prefix</code>,
<code>infix</code>, <code>postfix</code>,
Expand Down Expand Up @@ -347,39 +288,70 @@ <h3 id="mixing_intent_properties">Intent Properties</h3>
above.</li>
</ul>
</dd>
<dt id="intent_script_hints"><code>power</code>,
<code>index</code>, <code>evaluate</code></dt>
<dd><p>These properties may be used on children of script
elements, or on [=references=] to such elements. They indicate how
a sub or superscript should be read.</p>
<ul>
<li><code>&lt;msup>&lt;mi>x&lt;/mi>&lt;mn intent=":index">2&lt;/mn>&lt;/msup></code>
<q>x superscipt 2</q> (or perhaps <q>x 2</q> in terse modes), not
<q>x squared</q>.</li>
<li><code>&lt;msubsup>&lt;mi>x&lt;/mi>&lt;mi intent=":index">i&lt;/mi>&lt;mn intent=":power">2&lt;/mn>&lt;/msup></code>
<q>x sub i, squared</q>.</li>
</ul>
</dd>
</dl>
</section>

<section>
<h3 id="mixing_intent_self">Intent Self References</h3>
<p>The grammar allows the intent to omit the leading <i>term</i>
and just consist of a non-empty list of properties, [=self-property-list=]. This should be
interpreted as specfying properties for the current element. This
can be a useful technique, especially for large constructs such as tables as
it allows the children to be inferred without needing to be
explicitly referenced in the `intent` as would be the case with an
<i>applicaton</i>.
For example, `&lt;mtable intent=":array">...` might read the table as
an array of values, and `&lt;mtable intent=":aligned-equations">...`
might read the table in a style more appropriate for a list of
equations. In both cases the navigation of the underlying table
structure can be supplied by the AT system, as it would for an
un-annotated table.</p>
<h3 id="intent_using">Using Intent Concepts and Properties</h3>
<p>When the <code class="attribute">intent</code> attribute corresponding to a specific node
contains a concept component, the AT's [=Intent Concept Dictionary=] should be consulted.
The concept name should be normalized
(<q>`_`</q> (U+00F5) and <q>`.`</q> (U+002E) to <q>`-`</q> (U+002D)),
and compared using <a data-cite="INFRA#ascii-case-insensitive">ASCII case-insensitive</a>
match. If arguments were given explicitly in the <code class="attribute">intent</code>
then their number gives the arity, and the fixity is determined from an explicit property
or may default from the concept dictionary. Otherwise, arity is assumed to be 0.</p>
<p>An concept is considered a <dfn id="intent_known_concept">known concept</dfn> (to the AT)
davidcarlisle marked this conversation as resolved.
Show resolved Hide resolved
when the normalized name, the fixity property, and the arity
all match an entry in the AT's concept dictionary.
The speech hint in the matching entry
can be used be used as a guide for the generation of
specific audio, replacement text or braille renderings, as appropriate.
However, because common notations have many specialized ways of being spoken, the AT
is NOT constrained to use the hint as given. For example, AT may
vocalize a fraction marked up with <code>&lt;mfrac></code>
as <q>three quarters</q> or <q>three over x</q>
or may vocalize an inline fraction marked up as <code>&lt;mo>/&lt;/mo></code>
as <q>three divided by x</q>.
The choice may depend on the contents
and carrier element associated with an
<code>intent="divide($num,$denom)"</code>.
Note that properties other than those specifying fixity
may also indicate different rendering choices.</p>
<p>Otherwise, if the concept name, fixity and arity do not match it is considered to be an
<dfn id="intent_unknown_concept">unknown concept</dfn> (to the AT)
and will be treated the same as a [=literal=];
that is, the name is spoken as-is after normalizing each of `-`, `_` and `.` to an inter-word space.
Even for an unknown concept, if a fixity property and arguments were given,
the speech for the arguments should be composed
in a manner consistent with the given fixity property, if possible.</p>
<p>Note that future updates of the AT and [=Intent Concept Dictionary=] may
include additional concepts, at which time those concepts may also receive special treatment.</p>

<p>In cases where the intent contains neither an explicit nor inferrable concept
the AT should generally read out the MathML in a literal or structural fashion.
However, any given [=properties=] should be respected if possible,
and may be useful to indicate the kind of mathematical object,
rather than giving an explicit [=concept=] name to be spoken.
This can be a useful technique, especially for large constructs such as tables as
it allows the children to be inferred without needing to be
explicitly referenced in the `intent` as would be the case with an <i>applicaton</i>.
For example, `&lt;mtable intent=":array">...` might read the table as
davidcarlisle marked this conversation as resolved.
Show resolved Hide resolved
an array of values, whereas `&lt;mtable intent=":aligned-equations">...`
might read the table in a style more appropriate for a list of
equations. In both cases the navigation of the underlying table
structure can be supplied by the AT system, as it would for an
un-annotated table.</p>

<p>In general, depending upon the reader, AT may add words or sounds to make
the speech clearer to the listener. For example, for someone
who can not see the a fraction, AT might say <q>fraction x over
three end fraction</q> so the listener knows exactly what is
part of the fraction. For someone who can see the content,
these extra words might be a distraction. AT should always
produce speech that is appropriate to the community they serve.</p>
</section>

<section>
<h3 id="mixing_intent_errors">Intent Error Handling</h3>
<p>An intent processor may report errors in intent expressions in
Expand Down
Loading