From 4d1b62f2df41482a0bdaf5bbeb8491fcdf97a447 Mon Sep 17 00:00:00 2001 From: Deyan Ginev Date: Wed, 5 Apr 2023 17:14:25 -0400 Subject: [PATCH 1/2] IntentName view of literals and related rewording --- src/mixing.html | 285 +++++++++++++++++++++--------------------------- 1 file changed, 126 insertions(+), 159 deletions(-) diff --git a/src/mixing.html b/src/mixing.html index d2a21f2..621bdd9 100644 --- a/src/mixing.html +++ b/src/mixing.html @@ -38,9 +38,9 @@

The intent attribute

MathML elements allow attributes intent and arg that allow the - intent 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 . + conceptual intent 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 . Nevertheless, it may also be useful to guide translations to Content MathML, or computational systems.

The intent attribute encodes a @@ -70,54 +70,49 @@

The Grammar for intent 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]* -

Here NCName - is as defined in in [[xml-names]], and digit is a character in the range 0–9.

- +

Here L + is a letter as defined in Unicode's "general category L"; NCName + is as defined in [[xml-names]] and \d is a character in the range 0–9.

The parts consist of:

-
concept-or-literal
-
Names should match the NCName production as used for - no-namespace element name. - A [=concept-or-literal=] are interpreted either as a [=concept=] or [=literal=]. -
    -
  • -

    A concept corresponds to some mathematical or - application specific function or concept. +

    concept
    +
    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.

    -
    • -
  • -

    A literal 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 - -, _, . in the name by - spaces and then reading the resulting phrase. - Names starting with `_` (U+00F5) are always considered to be [=literal=] names, - and should never be in an [=Intent Concept Dictionary=].

    -
    • -
+ given in the dictionary. + When a [=concept=] is unknown to AT a default reading is generated by replacing any + - in the name by spaces, then reading the resulting phrase. +
+
literal
+
A [=literal=] such as _such-as provides raw text to be passed directly to vocalization. + That is done similarly to the default reading of an unknown [=concept=]. + Namely, replacing _ and - by spaces, then reading the resulting phrase.
number
A literal number such as 2.5 denotes itself.
-
reference
+
reference
An argument [=reference=] such as $name refers to a descendent element that has an attribute arg="name". Unlike id @@ -134,25 +129,101 @@

The Grammar for intentapplication
An application - 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 _($piece1,$piece2), + 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.
- -
property
+
arguments
- A [=property=] annotates the intent with an additional - property which may be used by + The list of arguments + for an [=application=] consists of one or more comma-separated [=expression=] entries. +
+ +
property
+
+ 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. +

The list of properties supported by any system is open but should include - the core properties listed in .

+ prefix, infix, postfix, function and silent. + These properties in a function application request that + the reading of the name may be suppressed, or the word ordering may be affected. + Note that the properties prefix, infix and postfix + refer to the spoken word order of the name and arguments, + and not (necessarily) the order used in the displayed mathematical notation.

+
    +
  • + In the case of a [=concept=] name, the property MAY be used in choosing the alternatives + supported by the AT. For example union is in the + Core dictionary with speech patterns "$1 union $2" and "union of $1 and $2". + An intent union :prefix ($a,$b) would + indicate that the latter style is preferred. +
    • +
  • For an [=application=] with a [=literal=] value as head, + the generated text SHOULD be composed as specified via the property. +
    • +
      +
    • f :prefix ($x) : f x
      • +
    • f :infix ($x,y) : x f y
      • +
    • f :postix ($x) : x f
      • +
    • f :function ($x, $y): f of x and y
      • +
    • f :silent ($x,$y) : x y
      • +
    + The specific words used above are only examples; + AT is free to choose other appropriate audio renderings. + For example, f:function($x, $y) could also be spoken as + f of x comma y. + +
+

+ 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. +

+
+
atom
+ 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. +
+
+
self-property-list
+
+ 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: + <mn intent=":rational-number">1</mn>. + +

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 applicaton.

+ +

For example, `<mtable intent=":matrix">...` might read the table as + an array of values, and `<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.

+
+
expression
+
+ 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=].
self-property-list
@@ -212,7 +283,7 @@

Intent Concept Dictionaries

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 NCName is allowed. + any string that is an IntentName is allowed.

Future versions of the concept list may incorporate names from the open list into the @@ -222,115 +293,11 @@

Intent Concept Dictionaries

class="attribute">intent attribute with entries in the intent lists, the comparison should be ASCII case-insensitive - and also normalize - `_` (U+00F5) and `.` (U+002E) to `-` (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.

-
-

Core Properties

-

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 - application - or applying to an <mtable>. - 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.

-
-
prefix, - infix, postfix, - function, silent
-
-

- These properties in a function application request that - the reading of the name may be suppressed, or the word ordering may be affected. - Note that the properties prefix, infix and postfix - refer to the spoken word order of the name and arguments, - and not (necessarily) the order used in the displayed mathematical notation.

-
    -
  • - In the case of a [=concept=] name, the property MAY be used in choosing the alternatives - supported by the AT. For example union is in the - Core dictionary with speech patterns "$1 union $2" and "union of $1 and $2". - An intent union :prefix ($a,$b) would - indicate that the latter style is preferred. -
    • -
  • For [=literal=] names, the text generated from the function head SHOULD be read - as specified in the property. -
      -
    • f :prefix ($x) : f x
      • -
    • f :infix ($x,y) : x f y
      • -
    • f :postix ($x) : x f
      • -
    • f :function ($x, $y): f of x and y
      • -
    • f :silent ($x,$y) : x y
      • -
    - The specific words used above are only examples; - AT is free to choose other appropriate audio renderings. - For example, f:function($x, $y) could also be spoken as - f of x comma y. If none of these properties is used, the - function property should be assumed unless the literal is - silent (for example _) in which case the silent property - should be assumed. See the examples in .
    • -
-
-
matrix, - system-of-equations, lines, continued-equation
-
-

These properties may be used on an mtable or on a - [=reference=] to an mtable. They affect the way the - parts of an alignment are announced.

-

The exact wordings used are system specfic

-
    -
  • `matrix` - should be read in style suitable for matricies, with typically - column numbers being announced.
    • -
  • `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 mtr indicates - that the row continues an equation wrapped from the row - above.
    • -
-
-
power, - index, evaluate
-

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.

-
    -
  • <msup><mi>x</mi><mn intent=":index">2</mn></msup> - x superscipt 2 (or perhaps x 2 in terse modes), not - x squared.
    • -
  • <msubsup><mi>x</mi><mi intent=":index">i</mi><mn intent=":power">2</mn></msup> - x sub i, squared.
    • -
-
-
-
- -
-

Intent Self References

-

The grammar allows the intent to omit the leading term - 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 - applicaton. - For example, `<mtable intent=":array">...` might read the table as - an array of values, and `<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.

-
-

Intent Error Handling

An intent processor may report errors in intent expressions in @@ -355,11 +322,11 @@

Intent Error Recovery
  • If a `reference` such as `$x` does not correspond to an arg attribute with value `x` on a descendent element, the processor should act as if the reference - were replaced by the literal `_dollar_x`.
    • + were replaced by the literal `_dollar-x`.
    - +

    A Warning about [=literal=] and [=property=]

    @@ -380,7 +347,7 @@

    A Warning about [=literal=] and [=property=]

  • free-algebra-construct:silent (_free, $r, _algebra, _on, $x)
    would be read as free r algebra on x
    • -
  • _(free, _($r,algebra), on, $x)
    +
  • _(_free, $r, _algebra, _on, $x)
    would be read as free r algebra; on x

    • However, since the literals are not in dictionaries, @@ -520,7 +487,7 @@

    Intent Examples

    bell number of 2
    - +
    Tables
    @@ -534,8 +501,8 @@
    Tables

    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.

    From 6a69c6c4b1f499964d774b05d1d45ff100783d52 Mon Sep 17 00:00:00 2001 From: Deyan Ginev Date: Wed, 5 Apr 2023 17:15:20 -0400 Subject: [PATCH 2/2] empty underscore rule --- src/mixing.html | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/mixing.html b/src/mixing.html index 621bdd9..db64a03 100644 --- a/src/mixing.html +++ b/src/mixing.html @@ -79,7 +79,7 @@

    The Grammar for intent