Update Details read-me button content

[terracoda]

The content for the dynamic part of the scene summary and the Details button in Voicing are currently exactly the same, and we hope to keep it that way.

Still updating the table in the design doc.
This issue is also related to checklist issue #74.

[terracoda]

Ok, the tables in the design document is ready, I have copied images here as a record of the design. Please do no include the rows with the grey background. They are just there as edge cases for now.

@jessegreenberg, I tried to make it easier for you to break up the phrases & parameters by only having unique phrases in each cell. The ditto marks mean the string from the cell above applies. And "n/a" means there is no described property for this shape. I hope it is all clear. Note that in the second table, the only difference in the trapezoids' parallel-ness phrase is punctuation - a period for trapezoid and a comma for isosceles trapezoid.

Table: Details & PDOM Summary when Named Shape IS a Parallelogram

Examples:

• Right now, your shape is {{a parallelogram}}. {{Opposite sides}} are parallel and {{have the same length}}, and {{opposite corners}} are {{equal}}.
• Right now, your shape is {{a parallelogram}}, and {{a square}}. {{Opposite sides}} are parallel, {{all sides}} {{have the same length}}}}, and {{all corners}} are {{right angles}}.

Table: Details & PDOM Summary when Named Shape IS NOT a Parallelogram

Examples:

• Right now, your shape is {{not}} {{a parallelogram}}. You have {{a kite}}. {{Pairs of adjacent sides}} {{have the same length}}.
• Right now, your shape is {{not}} {{a parallelogram}}. You have {{a trapezoid}}. {{One}} {{pair of}} {{opposite sides}} is parallel.
• Right now, your shape is {{not}} {{a parallelogram}}. You have {{an isosceles trapezoid}}. {{One}} {{pair of}} {{opposite sides}} is parallel, and {{the other}} {{pair of}} {{opposite sides}} {{have the same length}}.
  

[terracoda]

The above definitions were based on minimal definitions, so I need to iterate to include a full definition of paralell-ness, side length and corners for each and any shape.

[terracoda]

I have iterated. The new approach of focusing solely on corner and side length properties works well for shapes that are parallelograms, but is much more difficult for shapes that are not like kites, trapezoids, general quads.

I still have design questions:

• When to describe opposites or pairs of opposites?
• When to describe adjacent properties?
• When to describe amount of actual degrees?

Kites

Trapezoids

Isosceles Trapezoids

General and Concave Quads

[terracoda]

Ok, at last meeting we discussed having 2 buttons for the shape details, but this not simple at this time because it would involve changes to the Preferences Menu. As a work around which is a good fit for this sim, we will move shape names to the hint button, and keep shape details for the details button. This might mean the arrangement of Strings in the PDOM might be slightly different. I'll open a separate issue for this if needed.

Here's my iteration on the Details button (and PDOM dynamic summary) that includes only corner and side property descriptions.

THE ABOVE STRINGS may still need some tweaking, so not re-assigning yet.

[terracoda]

Ok, I think I have a solid draft of phrases and defined parameters. I would like to discuss this latest version with @BLFiedler before assigning over to @jessegreenberg

Shape Properties: Phrases & Parameters for Details & PDOM Summary

[brettfiedler]

I do see the need for specific information when the resolution of the side length or angle differences is not enough. Especially with the Trapezoid case, where the 1 set of parallel lines is not quite obvious from the description there. Definitely worth a deeper discussion, but it's looking really good!

[terracoda]

@jessegreenberg, in the design doc I have updated the tables posted in previous comments. I am still working on the rules for non-parallelogram shapes. Everything is ready for parallelogram shapes. Everything, that is, except how best to determine the starting vertex and side.

The relevant sections in the design doc start here in Rules for Shape Properties (Dynamic State Descriptions)

Will assign to you when rules for non-parallelograms are documented.

[terracoda]

How to determine the Corner

• We are aiming for the lowest leftmost corner
• Equality matters, so we identify the lowest leftmost corner that has an equal pair as the 1st corner. The paired corner can be an opposite or adjacent pair depending on the shape. The paired corner is the 2nd corner.
• The next pair of corners would again start with the lowest leftmost corner (3rd corner) and its pair would be the 4th corner.
• When we need to describe the corners individually, identify the lowest and leftmost corner.

How to determine the Side

• We are aiming for the important side that is connected to the 1st corner, the parallel or equal side and its pair

[terracoda]

@BLFiedler suggested a different structure for the ordering logic:

Within a sentence or between sentences, when ordering sets of corners or sides:

• Parallel (sides only)* > Equal (sides or corners)* > Remaining corners/sides*

*When ordering within the above sets:

• Bottom (-Y) > Left (-X).
  • Choose the bottom-most (-Y) vertex or side (that has not been described). In the case of a tie, choose the leftmost (-X).

Assumptions:

• Sides are defined by their originating vertex (e.g., Side BC is ordered based on the position of vertex B)

Note that the * emphasizes that the ordering within any "equal" or "parallel" statement is subject to the bottom/left rules.

[terracoda]

@jessegreenberg, the design doc has the latest iteration of the above table screen shots. Here are screen shots of Detail 1 and Details 1 & 2 just for a few parallelogram. There should not be any changes to the phrasing of the 3 main Details of the Shape Properties, but I am still trying to add some details that might be helpful to you for actual phrases, so i don't want to copy that big table in yet. That said, I don't think the phrase details should hold up implementation.

Just let me know if you have any questions.

Detail 1: General description of shape’s corners and sides.

• The general description is always present.
• One sentence works for all shapes

Detail 2: Shape-specific corner descriptions.

• The presence of the corner descriptions depends on the shape.
• If all corners are equal (squares and rectangles), the corner description is not included.

Detail 3: Shape-specific side descriptions.

• The presence of side descriptions depends on the shape.
• If all sides are equal (squares and rhombuses), the side description is not included.

[terracoda]

The ordering logic is in #78 (comment)

[jessegreenberg]

The above commits complete details 2, ready to start details 3.

[jessegreenberg]

OK the "details" button is done and ready for review. There is still some cleanup to do but the Voicing is working.

The only thing I had a little trouble with was ordering the side descriptions according to the priority described in the doc (parallel >equal >vertical >horizontal order). I believe it is correct but there were a few examples in the design doc that did not match the output currently in the sim.

@terracoda this is ready for you to review. This change added ~1100 lines of code though, I am sure there are bugs in there! Let me know what you find.

[jessegreenberg]

In 4/5/22 meeting, we discussed that I didn't get the ordering of the sides quite right. It should always be relative to the first vertex of the side (instead of determining which side is lowest).

Back to me to make this change.

[terracoda]

The description implementation is really good, though I know you are still working on ordering of corner and side names.

One thing I noticed while listening is that there is very little space between Detail 2 and Detail 3. Can you make sure there is a period there (a full stop) and a space. This is quite pronounced in the Parallelogram descriptions.

Is there any way to view the Voiced text on the screen, like in show model values, or something similar.

Text on the screen might be a future feature, so it would be nice to have regardless :-). I'll make an issue, so you can work on it separately.

[terracoda]

@jessegreenberg, I'll create a separate issue to implement the dynamic scene summary since Voicing is the priority.

[jessegreenberg]

Great!

Is there any way to view the Voiced text on the screen, like in show model values, or something similar.

You can run the sim with query param ?printVoicingResponses and it will put the output of Voicing in the dev tools console of your browser.

One thing I noticed while listening is that there is very little space between Detail 2 and Detail 3. Can you make sure there is a period there (a full stop) and a space. This is quite pronounced in the Parallelogram descriptions.

I hear this too, but when I use ?printVoicingResponses it looks like
"Right now, opposite corners are equal, and opposite sides are equal. Equal Corners C and A are a little smaller than equal Corners D and B. Parallel Sides CD and AB are a little longer than parallel Sides BC and DA."

But I hear almost no space between sentences 2 and 3.

[jessegreenberg]

OK, the ordering of sides has been adjusted to match the prioritization in the design doc. @terracoda back to you to review and to review my comment in #78 (comment).

[terracoda]

This ordering prioritization seems to be working well.

@jessegreenberg, it would be great to see the Voicing on the screen, so I can identify any punctuation or phrasing issues that affect the quality of pronunciation in web speech. In some places, I am not hearing a pause when I think there should be a comma or period. This makes things sound smooshed together.

[terracoda]

I'll open a separate issue about making the Voiced text available...maybe @zepumph already has a solution for that in the console?

[terracoda]

In RaP, I can use &printVoicingResponses. I'll try that for Quad.

[terracoda]

I'll open an issue to see if this query parameter is easy to add to Quad.

[terracoda]

I thought we were missing a case, but we are not :-)