x_ite 8.8.7 → 8.9.1

package/docs/_posts/components/Shaders/PackagedShader.md

@@ -1,6 +1,6 @@
 ---
 title: PackagedShader
-date: 2022-01-07
+date: 2023-01-07
 nav: components-Shaders
 categories: [components, Shaders]
 tags: [PackagedShader, Shaders]
@@ -13,9 +13,9 @@ tags: [PackagedShader, Shaders]
 
 ## Overview
 
-PackagedShader describes a single file that may contain a number of shaders and combined effects.
+PackagedShader contains a url for a single file that may contain a number of shaders and combined effects.
 
-The PackagedShader node belongs to the **Shaders** component and its default container field is *shaders.* It is available since X3D version 3.0 or later.
+The PackagedShader node belongs to the **Shaders** component and its default container field is *shaders.* It is available from X3D version 3.0 or higher.
 
 ## Hierarchy
 
@@ -32,7 +32,11 @@ The PackagedShader node belongs to the **Shaders** component and its default con
 
 ### SFNode [in, out] **metadata** NULL <small>[X3DMetadataObject]</small>
 
-Metadata are not part of the X3D world and not interpreted by the X3D browser, but they can be accessed via the ECMAScript interface.
+Information about this node can be contained in a MetadataBoolean, MetadataDouble, MetadataFloat, MetadataInteger, MetadataString or MetadataSet node.
+
+#### Hint
+
+- [X3D Architecture 7.2.4 Metadata](https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4-CD1/Part01/components/core.html#Metadata){:target="_blank"}
 
 ### SFString [in, out] **description** ""
 
@@ -40,54 +44,54 @@ Author-provided prose that describes intended purpose of the url asset.
 
 #### Hint
 
-- Many XML tools substitute XML character references for special characters automatically if needed within an attribute value (such as &amp;#38; for & ampersand character, or &amp;#34; for " quotation-mark character).
+- Many XML tools substitute XML character references for special characters automatically if needed within an attribute value (such as &amp;#38; for &amp; ampersand character, or &amp;#34; for " quotation-mark character).
 
 ### SFBool [in] **activate**
 
-*activate* forces the shader to activate the contained objects.
+*activate* forces the shader to *activate* the contained objects.
+
+#### Warning
+
+- It is an error to define this transient inputOnly field in an X3D file, instead only use it a destination for ROUTE events.
 
 ### SFBool [out] **isSelected**
 
 *isSelected* indicates this shader instance is selected for use by browser
 
+#### Warning
+
+- It is an error to define this transient outputOnly field in an X3D file, instead only use it a source for ROUTE events.
+
 ### SFBool [out] **isValid**
 
 *isValid* indicates whether current shader objects can be run as a shader program.
 
-### SFString [ ] **language** "" <small>["Cg"|"GLSL"|"HLSL"|...]</small>
+#### Warning
 
-The language field indicates to the X3D player which shading language is used. The language field may be used to optionally determine the language type if no MIME-type information is available.
+- It is an error to define this transient outputOnly field in an X3D file, instead only use it a source for ROUTE events.
 
-#### Hint
+### SFString [ ] **language** "" <small>["Cg"|"GLSL"|"HLSL"|...]</small>
 
-- Recognized values include "CG" "GLSL" "HLSL" "FX"
+The *language* field indicates to the X3D player which shading *language* is used. The *language* field may be used to optionally determine the *language* type if no MIME-type information is available.
 
-#### See Also
+#### Hint
 
-- [Relates to Internationalization (i18n)](https://www.w3.org/standards/webdesign/i18n){:target="_blank"}
+- Recognized values include "Cg" "GLSL" "HLSL".
 
 ### SFBool [in, out] **load** TRUE
 
-*load*=true means load immediately, load=false means defer loading or else unload a previously loaded asset.
+*load*=true means *load* immediately, *load*=false means defer loading or else unload a previously loaded scene.
 
 #### Hints
 
-- Allows author to design when ImageTextureAtlas loading occurs via user interaction, event chains or scripting.
+- Allows author to design when Inline loading occurs via user interaction, event chains or scripting.
 - Use a separate LoadSensor node to detect when loading is complete.
 
 ### MFString [in, out] **url** [ ] <small>[URI]</small>
 
-Location and filename of image. Multiple locations are more reliable, and including a Web address lets e-mail attachments work.
-
-#### Hints
-
-- MFString arrays can have multiple values, so separate each individual string by quote marks "https://www.web3d.org" "https://www.web3d.org/about" "etc." XML encoding for quotation mark " is &amp;quot; (which is called a character entity). Can replace embedded blank(s) in url queries with %20 for each blank character.
-
-#### Warning
+*url* points to a shader source-code file that may contain a number of shaders and combined effects.
 
-- Strictly match directory and filename capitalization for http links! This is important for portability. Some operating systems are forgiving of capitalization mismatches, but http/https and other operating systems are not.
-
-#### See Also
+#### Hint
 
 - [X3D Scene Authoring Hints, urls](https://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#urls){:target="_blank"}
 
@@ -116,16 +120,18 @@ Location and filename of image. Multiple locations are more reliable, and includ
 
 - Automatically reloading content has security considerations and needs to be considered carefully.
 
-## Description
+## Advisories
 
-### Hint
+### Hints
 
-- PackagedShader contains IS/connect and field definitions.
+- PackagedShader contains field declarations and then corresponding IS/connect statements (if any).
+- Apply default `containerField='shaders'` when parent node is Appearance.
+- [When parent node is LoadSensor, apply `containerField='children'` (X3Dv4) or `containerField='watchList'` (X3Dv3).](https://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#fieldNameChanges){:target="_blank"}
 
 ### Warning
 
-- PackagedShader can contain field declarations, but no CDATA section of plain-text source code.
+- PackagedShader does not contain CDATA section of plain-text source code.
 
-## External Links
+## See Also
 
-- [X3D Specification of PackagedShader](https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/shaders.html#PackagedShader){:target="_blank"}
+- [X3D Specification of PackagedShader node](https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/shaders.html#PackagedShader){:target="_blank"}

package/docs/_posts/components/Shaders/ProgramShader.md

@@ -1,6 +1,6 @@
 ---
 title: ProgramShader
-date: 2022-01-07
+date: 2023-01-07
 nav: components-Shaders
 categories: [components, Shaders]
 tags: [ProgramShader, Shaders]
@@ -13,9 +13,9 @@ tags: [ProgramShader, Shaders]
 
 ## Overview
 
-ProgramShader defines a shader that consists of one or more individually programmable, self-contained pieces. ProgramShader contains IS/connect, programs [ShaderProgram] nodes and field definitions.
+ProgramShader defines a shader that consists of one or more individually programmable, self-contained pieces. ProgramShader contains IS/connect and programs [ShaderProgram] nodes.
 
-The ProgramShader node belongs to the **Shaders** component and its default container field is *shaders.* It is available since X3D version 3.0 or later.
+The ProgramShader node belongs to the **Shaders** component and its default container field is *shaders.* It is available from X3D version 3.0 or higher.
 
 ## Hierarchy
 
@@ -30,42 +30,62 @@ The ProgramShader node belongs to the **Shaders** component and its default cont
 
 ### SFNode [in, out] **metadata** NULL <small>[X3DMetadataObject]</small>
 
-Metadata are not part of the X3D world and not interpreted by the X3D browser, but they can be accessed via the ECMAScript interface.
+Information about this node can be contained in a MetadataBoolean, MetadataDouble, MetadataFloat, MetadataInteger, MetadataString or MetadataSet node.
+
+#### Hint
+
+- [X3D Architecture 7.2.4 Metadata](https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4-CD1/Part01/components/core.html#Metadata){:target="_blank"}
 
 ### SFBool [in] **activate**
 
-*activate* forces the shader to activate the contained objects.
+*activate* forces the shader to *activate* the contained objects.
+
+#### Warning
+
+- It is an error to define this transient inputOnly field in an X3D file, instead only use it a destination for ROUTE events.
 
 ### SFBool [out] **isSelected**
 
 *isSelected* indicates this shader instance is selected for use by browser
 
+#### Warning
+
+- It is an error to define this transient outputOnly field in an X3D file, instead only use it a source for ROUTE events.
+
 ### SFBool [out] **isValid**
 
 *isValid* indicates whether current shader objects can be run as a shader program.
 
+#### Warning
+
+- It is an error to define this transient outputOnly field in an X3D file, instead only use it a source for ROUTE events.
+
 ### SFString [ ] **language** "" <small>["Cg"|"GLSL"|"HLSL"|...]</small>
 
-The language field indicates to the X3D player which shading language is used. The language field may be used to optionally determine the language type if no MIME-type information is available.
+The *language* field indicates to the X3D player which shading *language* is used. The *language* field may be used to optionally determine the *language* type if no MIME-type information is available.
 
 #### Hint
 
-- Recognized values include "CG" "GLSL" "HLSL" "FX"
+- Recognized values include "Cg" "GLSL" "HLSL".
 
-#### See Also
+### MFNode [in, out] **programs** [ ] <small>[ShaderProgram]</small>
 
-- [Relates to Internationalization (i18n)](https://www.w3.org/standards/webdesign/i18n){:target="_blank"}
+ProgramShader contains zero or more ShaderProgram node instances. In general, only two ShaderProgram instances are needed: one each for vertex and fragment processing.
 
-### MFNode [in, out] **programs** [ ] <small>[ShaderProgram]</small>
+#### Hint
+
+- Each shader language defines required behavior for processing this field.
+
+## Advisories
 
-Input/Output field programs.
+### Hint
 
-## Description
+- Apply default `containerField='shaders'` when parent node is Appearance.
 
 ### Warning
 
-- ProgramShader contains no field declarations and no plain-text source code.
+- ProgramShader contains no field declarations and no plain-text CDATA block source code.
 
-## External Links
+## See Also
 
-- [X3D Specification of ProgramShader](https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/shaders.html#ProgramShader){:target="_blank"}
+- [X3D Specification of ProgramShader node](https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/shaders.html#ProgramShader){:target="_blank"}

package/docs/_posts/components/Shaders/ShaderPart.md

@@ -1,6 +1,6 @@
 ---
 title: ShaderPart
-date: 2022-01-07
+date: 2023-01-07
 nav: components-Shaders
 categories: [components, Shaders]
 tags: [ShaderPart, Shaders]
@@ -15,7 +15,7 @@ tags: [ShaderPart, Shaders]
 
 ShaderPart defines the source for a portion of source code used by a ComposedShader node. The source is not required to be a complete shader for all of the vertex/fragment processing.
 
-The ShaderPart node belongs to the **Shaders** component and its default container field is *parts.* It is available since X3D version 3.0 or later.
+The ShaderPart node belongs to the **Shaders** component and its default container field is *parts.* It is available from X3D version 3.0 or higher.
 
 ## Hierarchy
 
@@ -30,7 +30,11 @@ The ShaderPart node belongs to the **Shaders** component and its default contain
 
 ### SFNode [in, out] **metadata** NULL <small>[X3DMetadataObject]</small>
 
-Metadata are not part of the X3D world and not interpreted by the X3D browser, but they can be accessed via the ECMAScript interface.
+Information about this node can be contained in a MetadataBoolean, MetadataDouble, MetadataFloat, MetadataInteger, MetadataString or MetadataSet node.
+
+#### Hint
+
+- [X3D Architecture 7.2.4 Metadata](https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4-CD1/Part01/components/core.html#Metadata){:target="_blank"}
 
 ### SFString [in, out] **description** ""
 
@@ -38,7 +42,7 @@ Author-provided prose that describes intended purpose of the url asset.
 
 #### Hint
 
-- Many XML tools substitute XML character references for special characters automatically if needed within an attribute value (such as &amp;#38; for & ampersand character, or &amp;#34; for " quotation-mark character).
+- Many XML tools substitute XML character references for special characters automatically if needed within an attribute value (such as &amp;#38; for &amp; ampersand character, or &amp;#34; for " quotation-mark character).
 
 ### SFString [ ] **type** "VERTEX" <small>["VERTEX"|"FRAGMENT"]</small>
 
@@ -50,11 +54,11 @@ Author-provided prose that describes intended purpose of the url asset.
 
 ### SFBool [in, out] **load** TRUE
 
-*load*=true means load immediately, load=false means defer loading or else unload a previously loaded asset.
+*load*=true means *load* immediately, *load*=false means defer loading or else unload a previously loaded scene.
 
 #### Hints
 
-- Allows author to design when ImageTextureAtlas loading occurs via user interaction, event chains or scripting.
+- Allows author to design when Inline loading occurs via user interaction, event chains or scripting.
 - Use a separate LoadSensor node to detect when loading is complete.
 
 ### MFString [in, out] **url** [ ] <small>[URI]</small>
@@ -63,15 +67,15 @@ Location and filename of shader. Multiple locations are more reliable, and inclu
 
 #### Hints
 
-- MFString arrays can have multiple values, so separate each individual string by quote marks "https://www.web3d.org" "https://www.web3d.org/about" "etc." XML encoding for quotation mark " is &amp;quot; (which is called a character entity). Can replace embedded blank(s) in url queries with %20 for each blank character.
+- MFString arrays can have multiple values, so separate each individual string by quote marks "https://www.web3d.org" "https://www.web3d.org/about" "etc."
+- Alternative XML encoding for quotation mark " is &amp;quot; (which is an example of a character entity).
+- Can replace embedded blank(s) in *url* queries with %20 for each blank character.
+- [X3D Scene Authoring Hints, urls](https://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#urls){:target="_blank"}
+- Embedded ecmascript: source can also be contained in the sourceCode pseudo-field without escape characters, equivalent to last entry in the *url* list, when using other API codebases and file encodings.
 
 #### Warning
 
-- Strictly match directory and filename capitalization for http links! This is important for portability. Some operating systems are forgiving of capitalization mismatches, but http/https and other operating systems are not.
-
-#### See Also
-
-- [X3D Scene Authoring Hints](https://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#urls){:target="_blank"}
+- Strictly match directory and filename capitalization for http links! This is important for portability. Some operating systems are forgiving of capitalization mismatches, but http/https *url* addresses and paths in Unix-based operating systems are all case sensitive and intolerant of uppercase/lowercase mismatches.
 
 ### SFTime [in, out] **autoRefresh** 0 <small>[0,∞)</small>
 
@@ -98,21 +102,26 @@ Location and filename of shader. Multiple locations are more reliable, and inclu
 
 - Automatically reloading content has security considerations and needs to be considered carefully.
 
-## Description
+## Advisories
 
 ### Hints
 
-- ShaderPart can contain a CDATA section of plain-text source code.
+- ShaderPart can contain a CDATA block of plain-text source code.
+- Embedded ecmascript: source can also be contained in the sourceCode pseudo-field without escape characters, equivalent to last entry in the url list, when using other API codebases and file encodings.
+- Insert an XML Character Data (CDATA) block within the Script node to contain source code embedded within an X3D scene, avoiding the need for escape characters.
+- A contained XML Character Data (CDATA) block for source code protects whitespace, line breaks, and literal characters (such as &amp; for ampersand character, \< for less-than-sign character, and \> for greater-than-sign character) from unintended escape-character modifications by XML parsers.
 - ShaderPart subprograms are written in the same language, which is specified in the parent ComposedShader node.
+- [When parent node is LoadSensor, apply `containerField='children'` (X3Dv4) or `containerField='watchList'` (X3Dv3).](https://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#fieldNameChanges){:target="_blank"}
 
-### Warning
+### Warnings
 
-- ShaderPart contains no field definitions.
+- ShaderPart contains no field declarations.
+- Strict order is required for contained constructs: first field declarations (if any), then IS/connect statements (if any), and finally CDATA source-code block.
 
 ## Example
 
 <x3d-canvas src="https://create3000.github.io/media/examples/Shaders/ShaderPart/ShaderPart.x3d" update="auto"></x3d-canvas>
 
-## External Links
+## See Also
 
-- [X3D Specification of ShaderPart](https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/shaders.html#ShaderPart){:target="_blank"}
+- [X3D Specification of ShaderPart node](https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/shaders.html#ShaderPart){:target="_blank"}

package/docs/_posts/components/Shaders/ShaderProgram.md

@@ -1,6 +1,6 @@
 ---
 title: ShaderProgram
-date: 2022-01-07
+date: 2023-01-07
 nav: components-Shaders
 categories: [components, Shaders]
 tags: [ShaderProgram, Shaders]
@@ -15,7 +15,7 @@ tags: [ShaderProgram, Shaders]
 
 ShaderProgram is contained by ProgramShader and provides the source and interface to a self-contained program that occupies one part of the rendering process: either a vertex or fragment shader.
 
-The ShaderProgram node belongs to the **Shaders** component and its default container field is *programs.* It is available since X3D version 3.0 or later.
+The ShaderProgram node belongs to the **Shaders** component and its default container field is *programs.* It is available from X3D version 3.0 or higher.
 
 ## Hierarchy
 
@@ -30,7 +30,11 @@ The ShaderProgram node belongs to the **Shaders** component and its default cont
 
 ### SFNode [in, out] **metadata** NULL <small>[X3DMetadataObject]</small>
 
-Metadata are not part of the X3D world and not interpreted by the X3D browser, but they can be accessed via the ECMAScript interface.
+Information about this node can be contained in a MetadataBoolean, MetadataDouble, MetadataFloat, MetadataInteger, MetadataString or MetadataSet node.
+
+#### Hint
+
+- [X3D Architecture 7.2.4 Metadata](https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4-CD1/Part01/components/core.html#Metadata){:target="_blank"}
 
 ### SFString [in, out] **description** ""
 
@@ -38,7 +42,7 @@ Author-provided prose that describes intended purpose of the url asset.
 
 #### Hint
 
-- Many XML tools substitute XML character references for special characters automatically if needed within an attribute value (such as &amp;#38; for & ampersand character, or &amp;#34; for " quotation-mark character).
+- Many XML tools substitute XML character references for special characters automatically if needed within an attribute value (such as &amp;#38; for &amp; ampersand character, or &amp;#34; for " quotation-mark character).
 
 ### SFString [ ] **type** "VERTEX" <small>["VERTEX"|"FRAGMENT"]</small>
 
@@ -50,11 +54,11 @@ Author-provided prose that describes intended purpose of the url asset.
 
 ### SFBool [in, out] **load** TRUE
 
-*load*=true means load immediately, load=false means defer loading or else unload a previously loaded asset.
+*load*=true means *load* immediately, *load*=false means defer loading or else unload a previously loaded scene.
 
 #### Hints
 
-- Allows author to design when ImageTextureAtlas loading occurs via user interaction, event chains or scripting.
+- Allows author to design when Inline loading occurs via user interaction, event chains or scripting.
 - Use a separate LoadSensor node to detect when loading is complete.
 
 ### MFString [in, out] **url** [ ] <small>[URI]</small>
@@ -63,15 +67,15 @@ Location and filename of shader. Multiple locations are more reliable, and inclu
 
 #### Hints
 
-- MFString arrays can have multiple values, so separate each individual string by quote marks "https://www.web3d.org" "https://www.web3d.org/about" "etc." XML encoding for quotation mark " is &amp;quot; (which is called a character entity). Can replace embedded blank(s) in url queries with %20 for each blank character.
+- Embedded ecmascript: source can also be contained in the sourceCode pseudo-field without escape characters, equivalent to last entry in the *url* list, when using other API codebases and file encodings.
+- MFString arrays can have multiple values, so separate each individual string by quote marks "https://www.web3d.org" "https://www.web3d.org/about" "etc."
+- Alternative XML encoding for quotation mark " is &amp;quot; (which is an example of a character entity).
+- Can replace embedded blank(s) in *url* queries with %20 for each blank character.
+- [X3D Scene Authoring Hints, urls](https://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#urls){:target="_blank"}
 
 #### Warning
 
-- Strictly match directory and filename capitalization for http links! This is important for portability. Some operating systems are forgiving of capitalization mismatches, but http/https and other operating systems are not.
-
-#### See Also
-
-- [X3D Scene Authoring Hints, urls](https://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#urls){:target="_blank"}
+- Strictly match directory and filename capitalization for http links! This is important for portability. Some operating systems are forgiving of capitalization mismatches, but http/https *url* addresses and paths in Unix-based operating systems are all case sensitive and intolerant of uppercase/lowercase mismatches.
 
 ### SFTime [in, out] **autoRefresh** 0 <small>[0,∞)</small>
 
@@ -98,13 +102,20 @@ Location and filename of shader. Multiple locations are more reliable, and inclu
 
 - Automatically reloading content has security considerations and needs to be considered carefully.
 
-## Description
+## Advisories
 
 ### Hints
 
-- ShaderProgram contains IS/connect and field definitions.
-- ShaderProgram can contain a CDATA section of plain-text source code.
+- ShaderProgram contains field declarations and then corresponding IS/connect statements (if any).
+- Insert an XML Character Data (CDATA) block within the Script node to contain source code embedded within an X3D scene, avoiding the need for escape characters.
+- A contained XML Character Data (CDATA) block for source code protects whitespace, line breaks, and literal characters (such as &amp; for ampersand character, \< for less-than-sign character, and \> for greater-than-sign character) from unintended escape-character modifications by XML parsers.
+- [When parent node is LoadSensor, apply `containerField='children'` (X3Dv4) or `containerField='watchList'` (X3Dv3).](https://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#fieldNameChanges){:target="_blank"}
+- Embedded ecmascript: source can also be contained in the sourceCode pseudo-field without escape characters, equivalent to last entry in the url list, when using other API codebases and file encodings.
+
+### Warning
+
+- Strict order is required for contained constructs: first field declarations (if any), then IS/connect statements (if any), and finally CDATA source-code block.
 
-## External Links
+## See Also
 
-- [X3D Specification of ShaderProgram](https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/shaders.html#ShaderProgram){:target="_blank"}
+- [X3D Specification of ShaderProgram node](https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/shaders.html#ShaderProgram){:target="_blank"}

package/docs/_posts/components/Shape/AcousticProperties.md

@@ -13,21 +13,27 @@ tags: [AcousticProperties, Shape]
 
 ## Overview
 
-AcousticProperties ...
+AcousticProperties specifies the interaction of sound waves with characteristics of geometric objects in the scene. Acoustic coefficient values are expected to fully account for physical and structural characteristics of associated geometry such as width, height, thickness, shape, softness and/or hardness, and density variations.
 
-The AcousticProperties node belongs to the **Shape** component and its default container field is *AcousticProperties.* It is available since X3D version 4.0 or later.
+The AcousticProperties node belongs to the **Shape** component and its default container field is *acousticProperties.* It is available from X3D version 4.0 or higher.
 
 ## Hierarchy
 
 ```
 + X3DNode
+  + X3DAppearanceChildNode
+    + AcousticProperties
 ```
 
 ## Fields
 
 ### SFNode [in, out] **metadata** NULL <small>[X3DMetadataObject]</small>
 
-Metadata are not part of the X3D world and not interpreted by the X3D browser, but they can be accessed via the ECMAScript interface.
+Information about this node can be contained in a MetadataBoolean, MetadataDouble, MetadataFloat, MetadataInteger, MetadataString or MetadataSet node.
+
+#### Hint
+
+- [X3D Architecture 7.2.4 Metadata](https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4-CD1/Part01/components/core.html#Metadata){:target="_blank"}
 
 ### SFString [in, out] **description** ""
 
@@ -35,18 +41,40 @@ Author-provided prose that describes intended purpose of the url asset.
 
 #### Hint
 
-- Many XML tools substitute XML character references for special characters automatically if needed within an attribute value (such as &amp;#38; for & ampersand character, or &amp;#34; for " quotation-mark character).
+- Many XML tools substitute XML character references for special characters automatically if needed within an attribute value (such as &amp;#38; for &amp; ampersand character, or &amp;#34; for " quotation-mark character).
 
 ### SFBool [in, out] **enabled** TRUE
 
+Enables/disables node operation.
+
 ### SFFloat [in, out] **absorption** 0 <small>[0,1]</small>
 
+Specifies the sound *absorption* coefficient of a surface, meaning the ratio of sound intensity not reflected by a surface.
+
 ### SFFloat [in, out] **refraction** 0 <small>[0,1]</small>
 
+Sound *refraction* coefficient of a medium, which determines change in propagation direction of sound wave when obliquely crossing boundary between two mediums where its speed is different.
+
+#### Hint
+
+- [Relationships described by Snell's Law](https://en.wikipedia.org/wiki/Snell%27s_law){:target="_blank"}
+
 ### SFFloat [in, out] **diffuse** 0 <small>[0,1]</small>
 
+*diffuse* coefficient of sound reflection indicates how much of the incident sound energy is reflected back in multiple directions.
+
 ### SFFloat [in, out] **specular** 0 <small>[0,1]</small>
 
-## External Links
+*specular* coefficient of sound reflection striking a plane surface, directly reflected back into space, where angle of reflection equals angle of incidence.
+
+## Advisories
+
+### Hints
+
+- AcousticProperties must have a parent Appearance node, and only affects geometry within the same Shape.
+- Proxy geometry for acoustic response can be far simpler than geometry needed for visual rendering.
+- [X3D Architecture Figure 16.2 Sound Propagation Phenomena](https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19775-1v4-CD1/Part01/components/sound.html#f-SoundPropagationPhenomena){:target="_blank"}
+
+## See Also
 
-- [X3D Specification of AcousticProperties](https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/shape.html#AcousticProperties){:target="_blank"}
+- [X3D Specification of AcousticProperties node](https://www.web3d.org/documents/specifications/19775-1/V4.0/Part01/components/shape.html#AcousticProperties){:target="_blank"}