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

IntentName view of literals #459

Closed
wants to merge 2 commits into from
Closed

IntentName view of literals #459

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
4d1b62f
IntentName view of literals and related rewording
dginev Apr 5, 2023
6a69c6c
empty underscore rule
dginev Apr 5, 2023
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
285 changes: 126 additions & 159 deletions src/mixing.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -38,9 +38,9 @@ <h3 id="mixing_intent">The <code class="attribute">intent</code> attribute</h3>
MathML elements allow attributes <code
class="attribute">intent</code> and <code
class="attribute">arg</code> that allow the
<dfn><q>intent</q></dfn> of the term to be specified. This
annotation is not meant to provide a full mathematical definition
of the term. It is primarily meant to help AT generate audio and/or braille renderings, see <a href="#accessibility"></a>.
conceptual <dfn><q>intent</q></dfn> of the element to be specified. This
annotation is not meant to provide a full mathematical definition.
It is primarily meant to help AT generate audio and/or braille renderings, see <a href="#accessibility"></a>.
Nevertheless, it may also be useful to guide translations to Content MathML, or computational systems.</p>

<p>The <code class="attribute">intent</code> attribute encodes a
Expand Down Expand Up @@ -70,54 +70,49 @@ <h4 id="mixing_intent_grammar">The Grammar for <code class="attribue">intent</co

<pre class="def bnf">
intent := self-property-list | expression
self-property-list := property+ S
expression := S ( term property* | application ) S
term := concept-or-literal | number | reference
concept-or-literal := NCName
self-property-list := property+
expression := S ( atom property* | application ) S
atom := concept | literal | number | reference
application := expression '(' arguments ')'
arguments := expression ( ',' expression )*

number := '-'? \d+ ( '.' \d+ )?
reference := '$' NCName
application := expression '(' arguments? S ')'
arguments := expression ( ',' expression )*
property := S ':' NCName
concept := IntentName
literal := '_' IntentName?
property := S ':' IntentName
IntentName := L ('-'? L)*
S := [ \t\n\r]*
</pre>

<p>Here <a href="https://www.w3.org/TR/REC-xml-names/#NT-NCName"><code>NCName</code></a>
is as defined in in [[xml-names]], and <code>digit</code> is a character in the range 0–9.</p>

<p>Here <a href="https://www.unicode.org/versions/Unicode15.0.0/ch04.pdf#G134153"><code>L</code></a>
is a letter as defined in Unicode's "general category L"; <a href="https://www.w3.org/TR/REC-xml-names/#NT-NCName"><code>NCName</code></a>
is as defined in [[xml-names]] and <code>\d</code> is a character in the range 0–9.</p>

<p>The parts consist of:</p>
<dl>
<dt><dfn id="intent_concept-or-literal">concept-or-literal</dfn></dt>
<dd>Names should match the <code>NCName</code> production as used for
no-namespace element name.
A [=concept-or-literal=] are interpreted either as a [=concept=] or [=literal=].
<ul>
<li>
<p>A <dfn id="intent_concept">concept</dfn> corresponds to some mathematical or
application specific function or concept.
<dt><dfn data-dfn-for="intent" id="intent_concept">concept</dfn></dt>
<dd>A [=concept=] corresponds to an encyclopedic name used by STEM practitioners,
or at the least - a new name proposed by the authors of a given math expression.
For many concepts, the words used to speak a concept are very similar to the name
used when referencing a concept.
A [=concept=] matches a name in an [=Intent Concept Dictionary=] recognized by the AT,
A [=concept=] may match a name in an [=Intent Concept Dictionary=] recognized by the AT,
to produce specific audio or braille renderings based on the speech hints
given in the dictionary.</p>
</li>
<li>
<p>A <dfn id="intent_literal">literal</dfn> is a name that does not match a [=concept=]
name known to the application. In this case, a default reading is generated by replacing any
<code>-</code>, <code>_</code>, <code>.</code> in the name by
spaces and then reading the resulting phrase.
Names starting with <q>`_`</q> (U+00F5) are always considered to be [=literal=] names,
and should never be in an [=Intent Concept Dictionary=].</p>
</li>
</ul>
given in the dictionary.
When a [=concept=] is unknown to AT a default reading is generated by replacing any
<code>-</code> in the name by spaces, then reading the resulting phrase.
</dd>
<dt><dfn data-dfn-for="intent" id="intent_literal">literal</dfn></dt>
<dd>A [=literal=] such as <code>_such-as</code> provides raw text to be passed directly to vocalization.
That is done similarly to the default reading of an unknown [=concept=].
Namely, replacing <code>_</code> and <code>-</code> by spaces, then reading the resulting phrase.
</dd>
<dt><dfn data-dfn-for="intent" id="intent_number">number</dfn></dt>
<dd>
A literal <a data-link-for="intent" data-link-type="dfn" href="#intent_number">number</a> such as <code>2.5</code> denotes itself.
</dd>

<dt><dfn id="intent_reference">reference</dfn></dt>
<dt><dfn data-dfn-for="intent" id="intent_reference">reference</dfn></dt>
<dd>
An argument [=reference=] such as <code>$name</code> refers to a descendent element
that has an attribute <code>arg="name"</code>. Unlike <code class="attribute">id</code>
Expand All @@ -134,25 +129,101 @@ <h4 id="mixing_intent_grammar">The Grammar for <code class="attribue">intent</co
<dt><dfn data-dfn-for="intent" id="intent_application">application</dfn></dt>
<dd>
An <a data-link-for="intent" data-link-type="dfn" href="#intent_application">application</a>
denotes a function applied to arguments using
a standard prefix notation. Optionally, between the head of the
function and the list of arguments there may be a [=property=] list as
described below to influence the style of text reading generated, or to
denotes a head expression applied to [=arguments=] using
a standard functional notation. Optionally, an [=atom=] head of an application
can be followed by a list of [=property=] annotations, as
described below, to influence the style of text reading generated, or to
provide other information to any consumer of the intent.

Note: When an empty literal is used as the application head,
such as one or more underscore characters as in <code>_($piece1,$piece2)</code>,
the usual functional narration is not appropriate, as only the arguments are audible.
For this case, a baseline treatment for vocalization would be to
narrate the arguments in order, without additional connectives.
</dd>


<dt><dfn id="intent_property">property</dfn></dt>
<dt><dfn data-dfn-for="intent" id="intent_arguments">arguments</dfn></dt>
<dd>
A [=property=] annotates the intent with an additional
property which may be used by
The list of <a data-link-for="intent" data-link-type="dfn" href="#intent_arguments">arguments</a>
for an [=application=] consists of one or more comma-separated [=expression=] entries.
</dd>

<dt><dfn data-dfn-for="intent" id="intent_property">property</dfn></dt>
<dd>
A [=property=] annotates its carrier with an additional name, such as
`:unit` or `:chemistry` which may be used by
the system to adjust the generated speech or Braille in system
specifc ways. The property may be directly related to the speech
form, such as `:infix` or indirectly affect the style of speech
with properties such as `:unit` or `:chemistry`

specifc ways. Properties may be assigned to [=atom=] and [=self-property-list=] intent values.

<p>The list of properties supported by any system is open but should include
the core properties listed in <a href="mixing_intent_core_properties"></a>.</p>
<code>prefix</code>, <code>infix</code>, <code>postfix</code>, <code>function</code> and <code>silent</code>.
These properties in a function <a data-link-for="intent" data-link-type="dfn"
href="#intent_application">application</a> request that
the reading of the name may be suppressed, or the word ordering may be affected.
Note that the properties <code>prefix</code>, <code>infix</code> and <code>postfix</code>
refer to the spoken word order of the name and arguments,
and <em>not</em> (necessarily) the order used in the displayed mathematical notation.</p>
<ul>
<li>
In the case of a [=concept=] name, the property MAY be used in choosing the alternatives
supported by the AT. For example <code>union</code> is in the
Core dictionary with speech patterns "$1 union $2" and "union of $1 and $2".
An intent <code>union :prefix ($a,$b)</code> would
indicate that the latter style is preferred.
</li>
<li>For an [=application=] with a [=literal=] value as head,
the generated text SHOULD be composed as specified via the property.
</li>
<ul>
<li><code>f :prefix ($x) </code>: <q>f x</q></li>
<li><code>f :infix ($x,y) </code>: <q>x f y</q></li>
<li><code>f :postix ($x) </code>: <q>x f</q></li>
<li><code>f :function ($x, $y)</code>: <q>f of x and y</q></li>
<li><code>f :silent ($x,$y) </code>: <q>x y</q></li>
</ul>
The specific words used above are only examples;
AT is free to choose other appropriate audio renderings.
For example, <code>f:function($x, $y)</code> could also be spoken as
<q>f of x comma y</q>.
</li>
</ul>
<p>
If none of the known properties is provided, and the application head is unknown,
the expression SHOULD be spoken as if it represented function application.
</p>
</dd>
<dt><dfn data-dfn-for="intent" id="intent_atom">atom</dfn></dt>
Atoms are flat values without internal syntax.
There are four kinds of atomic syntax in intent:
[=concept=], [=literal=], [=number=], [=reference=]

With the exception of [=reference=], atoms are terminal values.
All [=atom=] variants can be assigned a [=property=] list.
<dd>
</dd>
<dt><dfn data-dfn-for="intent" id="intent_self_property_list">self-property-list</dfn></dt>
<dd>
An [=self-property-list=] intent provides one or more [=property=] values associated with
this MathML element. Not providing the full intent is expedient for cases that are
already possible to infer without difficulty. A simple example would be an annotated number:
&lt;mn intent=":rational-number">1&lt;/mn>.

<p></p>Specifying [=self-property-list=] intent could be especially useful for large constructs,
such as tables or long horizontal expressions, where it allows the intent of some descendants
to be inferred automatically. That avoids explicitly referencing them from their ancestor element,
as would be the case with an <i>applicaton</i>.</p>

<p>For example, `&lt;mtable intent=":matrix">...` 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>
</dd>
<dt><dfn data-dfn-for="intent" id="intent_expression">expression</dfn></dt>
<dd>
An [=expression=] covers all cases where the intent is explicitly provided,
in contrast to [=self-property-list=]. Namely, an expression is an [=atom=] or [=application=].
</dd>

<dt><dfn id="intent_property_list">self-property-list</dfn></dt>
Expand Down Expand Up @@ -212,7 +283,7 @@ <h4 id="mixing_intent_dictionaries">Intent Concept Dictionaries</h4>
definition but a system
may also fall back on reading the identifier name as given.
Although authors are encouraged to use a name in this list that matches their intent if one exists,
any string that is an <code>NCName</code> is allowed.
any string that is an <code>IntentName</code> is allowed.
</li>
</ul>
<p>Future versions of the concept list may incorporate names from the <q>open</q> list into the
Expand All @@ -222,115 +293,11 @@ <h4 id="mixing_intent_dictionaries">Intent Concept Dictionaries</h4>
class="attribute">intent</code> attribute with entries in the intent
lists, 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).
If the speech hints are not being used
and the literal concept name is being read then each of `-`, `_` and `.` should be
and the literal concept name is being read then each of `-` and `_` should be
read as an inter-word space.</p>
</section>

<section>
<h4 id="mixing_intent_core_properties">Core Properties</h4>
<p>When generating speech a system should use the properties
described in this section. 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"
href="#intent_application">application</a>
or applying to an <code>&lt;mtable&gt;</code>.
The use of these properties in other contexts is not an error,
but as with any properties, is by default ignored but may have a
system-specific effect.</p>
<dl>
<dt id="intent_fixity_hint"><code>prefix</code>,
<code>infix</code>, <code>postfix</code>,
<code>function</code>, <code>silent</code></dt>
<dd>
<p>
These properties in a function <a data-link-for="intent" data-link-type="dfn"
href="#intent_application">application</a> request that
the reading of the name may be suppressed, or the word ordering may be affected.
Note that the properties <code>prefix</code>, <code>infix</code> and <code>postfix</code>
refer to the spoken word order of the name and arguments,
and <em>not</em> (necessarily) the order used in the displayed mathematical notation.</p>
<ul>
<li>
In the case of a [=concept=] name, the property MAY be used in choosing the alternatives
supported by the AT. For example <code>union</code> is in the
Core dictionary with speech patterns "$1 union $2" and "union of $1 and $2".
An intent <code>union :prefix ($a,$b)</code> would
indicate that the latter style is preferred.
</li>
<li>For [=literal=] names, the text generated from the function head SHOULD be read
as specified in the property.
<ul>
<li><code>f :prefix ($x) </code>: <q>f x</q></li>
<li><code>f :infix ($x,y) </code>: <q>x f y</q></li>
<li><code>f :postix ($x) </code>: <q>x f</q></li>
<li><code>f :function ($x, $y)</code>: <q>f of x and y</q></li>
<li><code>f :silent ($x,$y) </code>: <q>x y</q></li>
</ul>
The specific words used above are only examples;
AT is free to choose other appropriate audio renderings.
For example, <code>f:function($x, $y)</code> could also be spoken as
<q>f of x comma y</q>. If none of these properties is used, the
<code>function</code> property should be assumed unless the literal is
silent (for example <code>_</code>) in which case the <code>silent</code> property
should be assumed. See the examples in <a href="#mixing_intent_warning"></a>.</li>
</ul>
</dd>
<dt id="intent_table_hints"><code>matrix</code>,
<code>system-of-equations</code>, <code>lines</code>, <code>continued-equation</code></dt>
<dd>
<p>These properties may be used on an <code>mtable</code> or on a
[=reference=] to an <code>mtable</code>. They affect the way the
parts of an alignment are announced.</p>
<p>The exact wordings used are system specfic</p>
<ul>
<li>`matrix`
should be read in style suitable for matricies, with typically
column numbers being announced.</li>
<li>`system-of-equations` should be read in style suitable for
displayed equations (and inequations), with typically
column numbers not being announced. Each table row would
normally be announced as an "equation" but a
`continued-equation` property on an <code>mtr</code> indicates
that the row continues an equation wrapped from the row
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>
<h4 id="mixing_intent_self">Intent Self References</h4>
<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>
</section>

<section>
<h4 id="mixing_intent_errors">Intent Error Handling</h4>
<p>An intent processor may report errors in intent expressions in
Expand All @@ -355,11 +322,11 @@ <h5 id="mixing_intent_error_recovery">Intent Error Recovery</h5>
<li>If a `reference` such as `$x` does not correspond to an <code
class="attribute">arg</code> attribute with value `x` on a
descendent element, the processor should act as if the reference
were replaced by the literal `_dollar_x`.</li>
were replaced by the literal `_dollar-x`.</li>
</ol>
</section>
</section>


<section>
<h4 id="mixing_intent_warning">A Warning about [=literal=] and [=property=]</h4>
Expand All @@ -380,7 +347,7 @@ <h4 id="mixing_intent_warning">A Warning about [=literal=] and [=property=]</h4>
<li><code>free-algebra-construct:silent (_free, $r, _algebra, _on, $x)</code><br/>
would be read as <q>free r algebra on x</q></li>

<li><code>_(free, _($r,algebra), on, $x)</code><br/>
<li><code>_(_free, $r, _algebra, _on, $x)</code><br/>
would be read as <q>free r algebra; on x</q></li>
</ul>
<p>However, since the literals are not in dictionaries,
Expand Down Expand Up @@ -520,7 +487,7 @@ <h4 id="mixing_intent_examples">Intent Examples</h4>
<blockquote>bell number of 2</blockquote>
</div>


<section>
<h5 id="mixing_intent_examples_mtr">Tables</h5>
<div class="ednote">
Expand All @@ -534,8 +501,8 @@ <h5 id="mixing_intent_examples_mtr">Tables</h5>
<p>Some examples are given below, and the Working Group plans to
propose recommended uses of [=intent=] to address these use
cases. This may require some small extensions to the intent
grammar or to the terms in the Core Concept dictionary of intent
terms. Discussions are taking place in the following two GitHub
grammar or to the entries in the Core Concept dictionary.
Discussions are taking place in the following two GitHub
Issues.</p>

</div>
Expand Down