[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 21:11:23 PDT 2023
Thanks for the warning. I'll probably revert some of my code. I was using
_ before I think. Maybe I'll go back to that.
John
On Sat, Aug 19, 2023 at 9:49 PM Brutzman, Donald (Don) (CIV) <
brutzman at nps.edu> wrote:
> Whatever you like is fine by me. Nevertheless, you have been warned that
> such construct will not validate across various operating systems, file
> encodings and programming languages. If a file name can’t be included as
> metadata in the file itself, then it is questionable whether the file will
> properly survive at all. As you wish.
>
> It is also interesting to consider whether special characters in file
> names can lead to security attacks, such as buffer over runss. There are
> RFC requirements and a line of work out there that looks at URL security,
> so there are security restrictions which your file name is probably
> violating. So deliver lack of reuse may be allowed, but perhaps not so
> desirable.
>
> v/r Don
> ------------------------------
> *From:* John Carlson <yottzumm at gmail.com>
> *Sent:* Saturday, August 19, 2023 6:26:10 PM
> *To:* Brutzman, Donald (Don) (CIV) <brutzman at nps.edu>
> *Cc:* X3D Graphics public mailing list <x3d-public at web3d.org>
> *Subject:* Re: [x3d-public] Fwd: xslt3 bombs on spaces. Java Saxon is ok;
> X3D Scene Authoring Hints - naming conventions
>
>
> NPS WARNING: *external sender* verify before acting.
>
> 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
>
> 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/925bfda9/attachment-0001.html>
More information about the x3d-public
mailing list