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

Distinguish literal from unknown concept #466

Merged
merged 2 commits into from
May 4, 2023
Merged

Distinguish literal from unknown concept #466

Changes from 1 commit
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
08f102c
Distinguish literal from unknown concept
brucemiller May 2, 2023
7af376a
Corrections suggested by David Carlisle
brucemiller May 3, 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
50 changes: 32 additions & 18 deletions src/intent.html
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -87,23 +87,32 @@ <h3 id="mixing_intent_grammar">The Grammar for <code class="attribue">intent</co
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 [=concept=] matches 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>
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 dictionary.
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.
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>
</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
<p>A <dfn id="intent_literal">literal</dfn> is a name starting with <q>`_`</q> (U+00F5).
These will never be included in an [=Intent Concept Dictionary=].
The reading of a literal 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>
Note that while AT will often add "glue" words when generating speech
(such as the "of" when <code>intent="f(x)"<code> generates "f of x"),
an empty literal "_" generates no glue words;
effectively it implies the <code>:silent</code>
davidcarlisle marked this conversation as resolved.
Show resolved Hide resolved
<a data-link-for="intent" data-link-type="dfn" href="#mixing_intent_core_properties"> property</a>.</p>
</li>
</ul>
</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.
An explicit <a data-link-for="intent" data-link-type="dfn" href="#intent_number">number</a> such as <code>2.5</code> denotes itself.
Copy link
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

ah good catch, unrelated use of "literal" we should make this change in any case, it is independent of any concept/literal rewording

</dd>

<dt><dfn id="intent_reference">reference</dfn></dt>
Expand Down Expand Up @@ -141,7 +150,7 @@ <h3 id="mixing_intent_grammar">The Grammar for <code class="attribue">intent</co
with properties such as `:unit` or `:chemistry`

<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>
the core properties listed in <a data-link-for="intent" data-link-type="dfn" href="#mixing_intent_core_properties">Core Properties</a>.</p>
</dd>

<dt><dfn id="intent_property_list">self-property-list</dfn></dt>
Expand Down Expand Up @@ -207,14 +216,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 the literal concept name in the <code
class="attribute">intent</code> attribute with entries in the intent
lists, the comparison should be
<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).
If the speech hints are not being used
and the literal concept name is being read then each of `-`, `_` and `.` should be
and the concept name is being read then each of `-`, `_` and `.` should be
read as an inter-word space.</p>
</section>

Expand Down Expand Up @@ -243,13 +251,13 @@ <h3 id="mixing_intent_core_properties">Core Properties</h3>
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
In the case of a [=known 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
<li>For [=literal=] or [=unknown concept=] 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>
Expand Down Expand Up @@ -376,7 +384,13 @@ <h3 id="mixing_intent_warning">A Warning about [=literal=] and [=property=]</h3>
the meaning behind the expressions become more opaque,
and thus excessive use of these features will tend to limit the AT's ability
to adapt to the needs of the user, as well as limit translation and locale-specific speech.
Thus, the last two examples would be discouraged.
Thus, the last two examples would be discouraged.</p>
<p>Conversely, when specific speech not corresponding to a meaningfuil concept
brucemiller marked this conversation as resolved.
Show resolved Hide resolved
is nevertheless required,
it will be better to use a [=literal=] name (prefixed with <q>`_`</q>)
rather than an [=unknown concept=].
This avoids unexpected collisions with future updates to the concept dictionaries.
Thus, the last example is particularly discouraged.
</p>
</section>

Expand Down Expand Up @@ -444,7 +458,7 @@ <h3 id="mixing_intent_examples">Intent Examples</h3>
</div>

<p>Custom accessible descriptions, such as author-preferred variable or operator names, can also be annotated compositionally, via the underscore function.</p>
<p>The above notation could instead intend the custom name "x-new", which we can mark with a single literal `intent="x-new"`, or as a compound narration of two arguments:</p>
<p>The above notation could instead intend the custom name "x-new", which we can mark with a single literal `intent="_x-new"`, or as a compound narration of two arguments:</p>
<div class="example mathml mmlcore">
<pre>
&lt;msup intent="_($base,$script)">
Expand Down Expand Up @@ -495,7 +509,7 @@ <h3 id="mixing_intent_examples">Intent Examples</h3>
z with bar above is not X with bar above</blockquote>
</div>

<p>The intent mechanism is extensible through the use of [=literal=] names.
<p>The intent mechanism is extensible through the use of [=unknown concept=] names.
For example, assuming that the Bell Number is not present in any the dictionaries,
the following example</p>
<div class="example mathml mmlcore">
Expand Down