[x3d-public] Fwd: xslt3 bombs on spaces. Java Saxon is ok; X3D Scene Authoring Hints - naming conventions

Sat Aug 19 16:40:44 PDT 2023

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.
*	startWithLowerCaseLetter 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.

a.	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.
b.	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.
c.	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).
d.	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.
e.	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 <http://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/84783f8a/attachment-0001.html>
-------------- next part --------------
A non-text attachment was scrubbed...
Name: smime.p7s
Type: application/pkcs7-signature
Size: 5464 bytes
Desc: not available
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20230819/84783f8a/attachment-0001.p7s>