[x3d-public] X3D Comments, in XML or Classic VRML encodings

[Brutzman, Donald (Don) (CIV)]

X3D spec sayeth

  *
X3D 4.0 Architecture, 7 Core component, 7.2.5.1 Organization
  *
(last paragraph) "Comments may appear at various places throughout an X3D model, with syntax varying according to file encoding. Comments have no effect on scene functionality. Comments are not X3D nodes and not X3D statements. Comments may be interspersed between other X3D nodes and statements as long as they do not interfere with the functionality of the model."
  *
https://www.web3d.org/specifications/X3Dv4/ISO-IEC19775-1v4-IS/Part01/components/core.html#Organization

  *
Table 7.2 — Core component support levels
  *
https://www.web3d.org/specifications/X3Dv4/ISO-IEC19775-1v4-IS/Part01/components/core.html#t-CoresupportLevels

  *
Level
Prerequisites
Nodes/Features
Support
1
None
Comments
Full Support


Here are corresponding sections from draft XML and ClassicVRML encoding specifications.  Review and comment are welcome.

  *
19776-1 XML Encoding version 4.0, 4. Concepts, 4.3.4 Comments
  *
Comments do not affect the rendering or interaction of an X3D model. Nevertheless, comments are essential information to communicate author intent, design considerations, model capabilities, and expectations for continued development. Comment functionality is described in ISO/IEC 19775-1 X3D Architecture, Core component, 7.2.5.1 Organization.

  *
A single form for comment syntax is possible in the X3D XML encoding, exactly matching that defined by XML.

  *
EXAMPLE
  *
        <WorldInfo/> <!-- this is a comment between elements (nodes or statements) -->
  *

  *
        <!-- this is another XML comment
  *
            <WorldInfo/>
  *
            <Group/>
  *
        -->

  *
XML comments are not allowed within XML elements (i.e. X3D nodes or X3D statements). Whitespace within XML comments may be normalized.
  *

  *
It is important to consider that X3D model comments might not necessarily be preserved by intermediate processes when compressed, or when X3D files are relayed over the Web. Further, the exact placement of comments within an X3D model's structure may necessarily vary among X3D file encodings and programming language bindings. When appropriate, critical model information can also be retained in a lossless and consistently structured fashion by capturing it within META statements or the various Metadata nodes.
  *
https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19776-1v4.0-WD1/Part01/concepts.html#Comments
  *
Tracked in Mantis 1487: syntax for XML comments
  *
https://mantis.web3d.org/view.php?id=1487


and

  *
19776-2, X3D Classic VRML Encoding v4.0 draft, 4 Concepts, 4.3.4 Comments
  *
Comments do not affect the rendering or interaction of an X3D model. Nevertheless, comments are essential information to communicate author intent, design considerations, model capabilities, and expectations for continued development. Comment functionality is described in ISO/IEC 19775-1 X3D Architecture, Core component, 7.2.5.1 Organization.
  *
Two forms of comment syntax are possible in the Classic VRML encoding, single-line comments and block comments, each described in Grammar A.1.2 Overview.

  *
EXAMPLE
  *
        WorldInfo { } # this is a single-line comment between nodes and statements
  *

  *
        WorldInfo {
  *
            title "comment test" # this is another single-line comment following a field
  *
        }
  *

  *
        #/* This is a block comment
  *
            WorldInfo { }
  *
            Group { }
  *
        */#

  *
It is important to consider that X3D model comments might not necessarily be preserved by intermediate processes when compressed, or when X3D files are relayed over the Web. Further, the exact placement of comments within an X3D model's structure may necessarily vary among X3D file encodings and programming language bindings. Critical model information can also be retained in a lossless and consistently structured fashion by capturing it within META statements or the various Metadata nodes.
  *
https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19776-2v4.0-WD1/Part02/concepts.html#Comments

  *
Annex A Grammar, A.1.2 Overview
  *
For the Classic VRML encoding, the # character begins a comment. The first line of the file, the header, also starts with a # character. Two forms of comment are allowed, a single line comment and a block comment. A single line comment starts with a # and continues until the next line or file terminator, whichever comes first. A block comment starts with #/* and continues until */#. Line terminators are ignored. An unterminated block comment is an error.
  *
Within either a single line comment or a block comment, all characters are ignored except as described above. A single line or block comment cannot start within a double-quoted SFString or within MFString fields. Within an SFString or MFString field, the # character or #/* character sequence is considered part of the SFString or MFString field.
  *
https://www.web3d.org/specifications/X3Dv4Draft/ISO-IEC19776-2v4.0-WD1/Part02/grammar.html#Overview

  *
Tracked in Mantis 1486, syntax for Classic VRML comments
  *
https://mantis.web3d.org/view.php?id=1487


Hopefully this adds clarity in a sometimes-tricky topic.  Parsing is always an exceedingly strict business, so careful checking is welcome.

Personal motto: comments and skateboarding are not a crime.

# Have fun with X3D!  🙂


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


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20250106/5734e9ed/attachment-0001.html>