[x3d-public] Fwd: xslt3 bombs on spaces. Java Saxon is ok; X3D Scene Authoring Hints - naming conventions
John Carlson
yottzumm at gmail.com
Sat Aug 19 18:26:10 PDT 2023
Replacing " " (space) with "$" (for Java and Java outputs) seems to clear
up the issues with X3DJSONLD and Java code.
This is in case someone decides to use spaces and complains that X3DJSONLD
“doesn’t work .”
“Be liberal in what you accept, etc.”
X3DJSONLD is becoming more robust to weird problems like this, but I still
need to make some changes.
Plus I’m learning new bash stuff to make my code better!
Fun stuff!
John
On Sat, Aug 19, 2023 at 6:40 PM Brutzman, Donald (Don) (CIV) <
brutzman at nps.edu> wrote:
> Glad to hear that this is yielding for you, John.
>
>
>
> Recommendation regarding spaces in file names: don’t do that! Too prone
> to failure, often inexplicably and undiagnosably within tool chains.
>
>
>
> CamelCaseFileNaming.x3d works well, human readable, and searchable too.
>
>
>
> Full set of our best-practice naming conventions follow. All improvements
> always welcome.
>
>
>
>
>
> - X3D Scene Authoring Hints: Naming Conventions
> - These hints provide a collection of style guidelines, authoring tips
> and best practices to improve the quality, consistency and maintainability
> of Extensible 3D (X3D) Graphics models.
> -
> https://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#NamingConventions
>
> *🔖
> <https://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#NamingConventions> Naming
> Conventions*
>
> Clarity is essential for building a meaningful model. Naming conventions
> are appropriate for file names, DEF node identifiers and USE node
> references, prototype names, and more.
>
> - Using clear and consistent names for node names and DEF labels
> greatly improves the clarity of how a scene work. In effect, names can make
> the purpose of a scene self-documenting.
> - CamelCaseNaming: capitalize each word, never use abbreviations,
> strive for clarity, and be brief but complete.
> - *s*tartWithLowerCaseLetter when defining field names (i.e.
> attributes) within Prototypes and Scripts.
> - Ensure consistent capitalization throughout. Of note: the Windows
> operating system is not case sensitive, but http servers are. Thus
> mismatched capitalization can hide target files, and this error only is
> revealed when placed on a server.
> - Avoid embedding spaces in file names since they can be poorly (or
> inconsistently) handled by operating systems and tools.
> - Avoid use of underscores since they look like whitespace when part
> of a URL address. Occasionally it is acceptable to use the underscore
> character ("*_*") to indicate subscripts for definition of a
> mathematical variable.
> - Avoid use of hyphens ("*-*") since these are erroneously turned into
> subtraction operators when converted into class or variable names.
> - Combined: avoid use of whitespace characters, 'apostrophes' and
> "quotation marks" in file names since they can cause lots of problems for
> tools and search, especially when going from one operating system to
> another.
> - Naming conventions can apply to .x3d files and reference files, as
> well as Prototype names, field names, and DEF/USE names. Starting names
> similarly (e.g. NavigationWalk, NavigationFly) can help alphabetize with
> indexing in the pretty-print HTML documentation, thus improving readability
> and searchability.
> - Portability of each name is important especially since X3D models
> may get converted into a variety of programming languages and file formats.
> - There are multiple requirements for characters allowed in DEF/USE
> names, and so using the strictest subset is useful.
> - .x3d, .x3db encodings: must follow XML requirements
> <https://www.w3.org/TR/xml/#NT-Name> for ID/IDREF data type.
> - .x3dv, .wrl encodings: must follow ClassicVRML Grammar
> requirements
> <https://www.web3d.org/documents/specifications/19776-2/V3.3/Part02/grammar.html#Nodes> for
> Id/IdFirstChar, which essentially match except for some special characters.
> - Most restrictive and most interoperable guidance regarding choice of
> characters in names: can start with letter or underscore character, but not
> a number or a colon. Can then include letters, numbers, hyphen, underscore,
> or period characters. This interoperability is important so that files can
> be converted equivalently between encodings without validation problems.
> - Use lower case for filename extensions. Examples: .png .jpg .txt.
> Although Windows systems are insensitive to upper/lower case, any
> differences will cause "file not found" failures on Unix systems (Apple,
> Linux) and http servers.
> - Be consistent. When multiple files pertain to a single entity, start
> with the same name so that they will alphabetize adjacent to each other in
> the catalog and the directory listings. Examples:
> WaypointInterpolatorPrototype.x3d
> <https://savage.nps.edu/Savage/Tools/Animation/WaypointInterpolatorPrototype.x3d>
> WaypointInterpolatorExample.x3d
> <https://savage.nps.edu/Savage/Tools/Animation/WaypointInterpolatorExample.x3d>
> WaypointInterpolatorExample.png
> <https://savage.nps.edu/Savage/Tools/Animation/WaypointInterpolatorExample.png>
> - Similarly good choices for directory and subdirectory names can help
> keep scene names terse.
> - Portability is important. Suggestions for XML Names
> <https://www.w3.org/TR/xml11/#sec-suggested-names> in
> W3C XML 1.1 Recommendation describes best practices for construction of XML
> names and provides detailed character-set guidance. It also notes Names
> which are nonsensical, unpronounceable, hard to read, or easily confusable
> with other names should not be employed.
> - Avoid file names which are identical to an X3D node name, since name
> collisions can thwart interoperability when converting among various
> programming languages.
>
> 🔖
> <https://www.web3d.org/x3d/content/examples/X3dSceneAuthoringHints.html#NameTyping>
> *Typing of name attributes*:
>
> Small variations in SFString types for name attributes can occur in order
> to best achieve strict validation of content.
>
> 1. *type="SFString"* (meaning no restrictions) is applied to name attribute
> for meta statement, matching HTML. However, note that Dublin Core
> Metadata Initiative (DCMI)
> <https://www.dublincore.org/documents/dcmi-terms/#section-1> requires
> name to be a token appendable to a URI, so normal expectation for typical
> names is NMTOKEN.
> 2. *type="SFString"* (meaning that embedded space characters are
> allowed) is applied to name attribute for meta
> <https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/core.html#METAStatement> statement,
> Core component X3DMetadataObject
> <https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/core.html#X3DMetadataObject> Metadata
> nodes, and also applied to CADGeometry component
> X3DProductStructureChildNode
> <https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/componentsCADGeometry.html#X3DProductStructureChildNode> CAD
> nodes. This provides wider latitude when matching terminology structures
> from other metadata nomenclatures. *Warning:* note however that the
> included whitespace characters might be inconsistent. A name value
> containing whitespace might not validate or match other corresponding
> values.
> 3. *type="NMTOKEN"* (meaning that no whitespace characters are
> allowed) is applied to name attribute for component and unit statements,
> simpleType SFString enumeration names, and prototype definitions
> (ProtoDeclare, ExternProtoDeclare, ProtoInstance, field and fieldValue).
> 4. *type="NMTOKEN"* (meaning that no whitespace characters are
> allowed) is applied to name attribute for Humanoid Animation (HAnim)
> <https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/hanim.html> nodes.
> HAnim node names have a prefix if multiple Humanoids appear in a scene,
> e.g. "joe_r_upperarm". Note that an HAnimSite and HAnimDisplacer name
> starts with one of the HAnim featurePointNameValues
> <https://www.web3d.org/specifications/X3dSchemaDocumentation4.0/x3d-4.0_featurePointNameValues.html>.
> HAnimSite must end in '_tip' or '_view' or '_pt' suffix. HAnimDisplacer can
> end in '_feature' or '_action' or '_config' suffix.
> 5. *type="NMTOKEN"* (meaning that no whitespace characters are
> allowed) is applied to name attribute for X3DVertexAttributeNode
> <https://www.web3d.org/documents/specifications/19775-1/V3.3/Part01/components/shaders.html#X3DVertexAttributeNode> nodes
> (FloatVertexAttribute, Matrix3VertexAttribute, Matrix4VertexAttribute) that
> define Shader interface data structures. This provides maximum strictness
> supporting a variety of shader programming languages which typically do not
> support whitespace in names.
>
> *Naming of multiple similar files:*
>
> Naming multiple similar files can be difficult, especially when creating
> autogenerated files. One suggested approach is to concatenate the following
> name components as appropriate. Considering order and alphabetization can
> help. Avoid abbreviations since they complicate search.
>
> For example you might separate components by period characters, since
> underscores disappear as part of a url and since hyphens will break across
> a line.
>
> - ConsistentDescriptiveName
> - .PhysicalLocation (for example *.HawaiiKauai*)
> - .SequenceNumber
> - . 21xx Month01 (or timestamp, for sortability)
> - .ext (filename extension)
>
> *General notes on naming conventions:*
>
> - These conventions are suitable for X3D scenes, XML tagset design,
> and corresponding Java classes.
> - These conventions match the node and field naming conventions in the X3D
> Specification <https://www.web3d.org/x3d/specifications> (and most
> XML).
> - (Ironic) Success Metric: when is a name successful?
> Answer: when no one has to discuss that name any more, it is simply
> understood.
>
>
>
>
>
> HaveFunWithX3D! 8)
>
>
>
> all the best, Don
>
> --
>
> Don Brutzman Naval Postgraduate School, Code USW/Br
> brutzman at nps.edu
>
> Watkins 270, MOVES Institute, Monterey CA 93943-5000 USA
> +1.831.656.2149
>
> X3D graphics, virtual worlds, navy robotics
> https://faculty.nps.edu/brutzman
>
>
>
> *From:* x3d-public <x3d-public-bounces at web3d.org> *On Behalf Of *John
> Carlson
> *Sent:* Saturday, August 19, 2023 9:50 AM
> *To:* X3D Graphics public mailing list <x3d-public at web3d.org>
> *Subject:* [x3d-public] Fwd: xslt3 bombs on spaces. Java Saxon is ok
>
>
>
> Saxon Java rules!
>
>
>
> If anyone can figure out how to use spaces in file names to xslt3, you
> deserve respect!
>
>
>
> I'm still hoping for a XML -> JSON solution for the web!
>
>
>
> John
>
>
>
> ../../../node_modules/.bin/xslt3 -xsl:/c/x3d-code/
> www.web3d.org/x3d/stylesheets/X3dToJson.xslt -s:../data/lily
> 7_3_animate.x3d '-o:../data/lily 7_3_animate.new2.json'
>
> Invalid command line input: 7_3_animate.x3d
>
> Usage: see
> http://www.saxonica.com/saxon-js/documentation/index.html#!nodejs/command-line
> <https://nam10.safelinks.protection.outlook.com/?url=http%3A%2F%2Fwww.saxonica.com%2Fsaxon-js%2Fdocumentation%2Findex.html%23!nodejs%2Fcommand-line&data=05%7C01%7Cbrutzman%40nps.edu%7C7766c635834b447ffde808dba0d4827c%7C6d936231a51740ea9199f7578963378e%7C0%7C0%7C638280606826753368%7CUnknown%7CTWFpbGZsb3d8eyJWIjoiMC4wLjAwMDAiLCJQIjoiV2luMzIiLCJBTiI6Ik1haWwiLCJXVCI6Mn0%3D%7C3000%7C%7C%7C&sdata=DDxMF%2FBghT1O51jRFeJjdpvSrn6kZ6Cp7m81ePjb3Kw%3D&reserved=0>
>
> Options available: -?, -co, -export, -im, -it, -json, -master, -nogo, -ns,
> -o, -relocate, -s, -t, -tp, -xp, -xsl
>
> Use -XYZ:? for details of option XYZ
>
> Params:
>
> param=value Set stylesheet string parameter
>
> +param=filename Set stylesheet document parameter
>
> ?param=expression Set stylesheet parameter using XPath
>
> !param=value Set serialization parameter
>
> (bindings and values containing punctuation may need to be quoted in
> some command shells,
>
> e.g. in PowerShell: "{NS}key=val" ?range="1 to 20" )
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20230819/8f233c3d/attachment-0001.html>
More information about the x3d-public
mailing list