[x3d-public] Request for X3D encoding comment output from X3DPSAIL

John Carlson yottzumm at gmail.com
Wed Jan 7 01:00:32 PST 2026 

While the ticket below remains active, I have replaced the Java code which
contained a SAX Parser with something much simpler, which better achieves
the goal.  I now think that SAX Parsers cannot really achieve X3D's goals
of "least interference" with regards to keeping archives free of massive
changes.

I welcome any work on developing stylesheets based on the Java code, to
replace my code, which is why I think that input and output examples were
requested!  I have many more examples, here: Index of
/X3DJSONLD/src/main/data <http://coderextreme.net/X3DJSONLD/src/main/data/> I
am attaching a text file listing of .x3d files that you can download from
that site.  I am providing them here so they are easier to download.  If
needed, I can provide a curl script.  I will maintain the files on that
site until the final code has been satisfactorily tested, and I may also
create a persistent archive of tests.  Obviously, most of the files are my
creation, which have an Open Source royalty free license, but there are
also files from Joe and the HAnim group there:

AllenDutton.x3d
JinLOA4.x3d
JinLOA4scaled1joe06c.x3d
JinScaledV2L1LOA4OnlyMarkers11g.x3d
JinScaledV2L1LOA4Sites07f.x3d
JinScaledV2L1LOA4Sites08e.x3d
JinScaledV2L1LOA4Sites10h.x3d
JoeDemo5JoeSkin5a.x3d

And Doug Sanden:

x3dconnector.x3d

And NIST:

indexedfaceset_pixeltexture_entire.x3d
indexedfaceset_pixeltexture_part.x3d
indexedfaceset_pixeltexture_plus.x3d
indexedfaceset_pixeltexture_whole.x3d

It will be great to get full support for my sample files with X3DJSAIL.

Modifications to X3dToPython.xslt to create multiple Comment's (or a single
Comment with """...""") for a multiline comment is entirely still under
discussion, realizing that we may have to escape """.  But I do understand
the desire to remove multi-line comments from X3D encoded files, and I
accept that.

It is planned that I won't work during the next couple of days.

John

On Tue, Jan 6, 2026 at 12:28 AM John Carlson <yottzumm at gmail.com> wrote:

> Here's the motivating ticket with Java program and .x3d for
> converting multi-line comments to single-line comments (with many single
> line comments possible per multi-line comment.
>
> x3d / Tickets / #83 Replacing Multiline comments with single line comments
> in Java. Open Source donation <https://sourceforge.net/p/x3d/tickets/83/>
>
> Feel free to convert to a stylesheet for use in X3dToPython.xslt!
>
> John
>
> On Mon, Jan 5, 2026 at 10:42 AM Don Brutzman <don.brutzman at gmail.com>
> wrote:
>
>> Here are some details and a separate XML example that is relevant.
>>
>> XSLT makes it easy to normalize all whitespace characters in a comment,
>> or attribute.  For example, the XSLT function normalize-space(.)
>> replaces a whitespace character, tab, newline, or linebreak character with
>> a single space between other non-whitespace characters.
>>
>> Authors can maintain positive control of their model comments in X3D
>> source files (XML, ClassicVRML, JSON, binary, turtle) by splitting or
>> combining each comment themselves.  JSON does not have any comment
>> capability, by the originator's design, so we have represented them by
>> creating an explicit class.
>>
>> Often a comment with longer edited multiline prose might be better served
>> by producing other documentation, or by splitting and separating into
>> smaller chunks.  Shifting to plain-old XML, for example, the X3D tooltips
>> inserts hints and warnings in attribute text.
>>
>>    - Extensible 3D (X3D) 4.0 Tooltips
>>    - X3D Tooltips provide authoring hints for each node and field found
>>    in X3D Architecture version 4 International Specification (IS).
>>    Developmental work on X3D draft 4.1 is also supported.
>>
>> Corresponding source, XSLT stylesheet and output:
>>
>>    - https://www.web3d.org/x3d/tooltips/x3d-4.0.profile.xml
>>    - https://www.web3d.org/x3d/tooltips/X3dTooltipConversions.xslt
>>    - https://www.web3d.org/x3d/tooltips/X3dTooltips.html
>>
>> As before: persistent multiline comments are not a consistent feature in
>> many file encodings or programming-language bindings.  Nor are they a
>> requirement in X3D Architecture.  The option to maintain persistence of
>> single-line comments is a goal requirement in order to maintain
>> round-tripping interoperability.  Round-trip conversion of comments in X3D
>> Example Archive models is an excellent way to test this, typically starting
>> with the .x3d XML encoding.
>>
>> Popping up a level:  if an author wants to ensure that any downstream
>> application can never legally strip extra information, then they should use
>> X3D MetadataString/MetadataSet structures for always-persistent retention
>> and machine-readable structured data.
>>
>> Popping up another level of abstraction, with apologies to René
>> Magritte:  <!-- this is not a comment -->
>>
>>    - Wikipedia: The Treachery of Images
>>    - https://en.wikipedia.org/wiki/The_Treachery_of_Images
>>
>> all the best, Don
>> --
>> X3D Graphics, Maritime Robotics, Distributed Simulation
>> Relative Motion Consulting  https://RelativeMotion.info
>>
>>
>> On Sun, Jan 4, 2026 at 2:01 PM John Carlson <yottzumm at gmail.com> wrote:
>>
>>> My current plan for replacing multiple line comments with single lines
>>> comments where the comment content are preserved on separate lines is as
>>> follows:
>>>
>>> 1.  Write a Java SAX parser to replace newlines with —>\n<!— inside XML
>>> comments.
>>>
>>> 2.  Compile with GraalVM native-image into rnl.exe, if not taken.
>>>
>>> Write a script to apply to all original .x3d files in my examples.  This
>>> will call vim or ex (vim command-line), with the command, %!rnl.exe, then
>>> save and exit.
>>>
>>> If needed, I will include carriage return.
>>>
>>> Others would try to make this a stylesheet, but I don’t know if
>>> comment() can be split on newlines in XSLT.   So I’ll ask claude.ai
>>> again!
>>>
>>> <xsl:stylesheet version="2.0" xmlns:xsl="
>>> http://www.w3.org/1999/XSL/Transform">
>>>
>>> <xsl:template match="@*|node()">
>>> <xsl:copy>
>>> <xsl:apply-templates select="@*|node()"/>
>>> </xsl:copy>
>>> </xsl:template>
>>>
>>> <xsl:template match="comment()">
>>> <xsl:for-each select="tokenize(., '&#xA;')">
>>> <xsl:if test="normalize-space(.) != ''">
>>> <xsl:comment><xsl:value-of select="normalize-space(.)"/></xsl:comment>
>>> </xsl:if>
>>> </xsl:for-each>
>>> </xsl:template>
>>>
>>> </xsl:stylesheet>
>>>
>>> Gobbledegook to me, but maybe someone can use it.
>>>
>>> John
>>>
>>> On Sun, Jan 4, 2026 at 3:32 PM John Carlson <yottzumm at gmail.com> wrote:
>>>
>>>> For example, it nearly requires program to do this in Python or Perl.
>>>>
>>>> Claude.ai reports:
>>>>
>>>> perl -i -0pe 's/<!--(.*?)-->/join("\n", map {"<!-- $_ -->"} grep
>>>> {s|^\s*||; s|\s*$||; $_} split("\n", $1))/gse' file.xml
>>>>
>>>> Obviously I can put this in a shell script, but I like stuff I can
>>>> understand!
>>>>
>>>> Something in Java would be great!  Maybe I’ll write and contribute if
>>>> it doesn’t already exist?
>>>>
>>>> Seems like a simple SAX parser, frankly!
>>>>
>>>> John
>>>>
>>>> On Sun, Jan 4, 2026 at 3:10 PM John Carlson <yottzumm at gmail.com> wrote:
>>>>
>>>>> Thanks, it wasn’t clear to me that multi-line comments were not
>>>>> supported in X3D XML encoding.  That clears up most of my questions!
>>>>>
>>>>> I will replace multi-line comments with single-line comments in my
>>>>> examples.   Does X3D-Edit support this feature?  This would be great, and
>>>>> encourage me to use it!
>>>>>
>>>>> John
>>>>>
>>>>> On Sun, Jan 4, 2026 at 2:46 PM Don Brutzman <don.brutzman at gmail.com>
>>>>> wrote:
>>>>>
>>>>>> For clarity, here is a recap of key points that can be found in prior
>>>>>> responses and ticket issues:
>>>>>>
>>>>>>    - Persistent single-line comments are an important feature for
>>>>>>    X3D model conversions and interoperability.
>>>>>>    - You are welcome to use all Python features, including
>>>>>>    multi-line comments, whenever programming with Python and x3d.py.
>>>>>>    - Individual multi-line comments are not supported in a number of
>>>>>>    file encodings and programming languages.  Nor are they defined by X3D
>>>>>>    Architecture, nor are they supported by several X3D encodings (such as XML
>>>>>>    and ClassicVRML).  Thus multi-line comments are not a required feature.
>>>>>>    - Persistent comments in x3d.py Python are already supported via
>>>>>>    a Comment class.
>>>>>>    - Persistent single-line comments are now partially supported by
>>>>>>    X3dToPython.xslt converter, if present as children of Scene head and
>>>>>>    grouping nodes.  Further future work on content-model representations in
>>>>>>    the Python class hierarchy may be able to add them elsewhere (e.g. inside
>>>>>>    Shape Appearance Material geometry etc.
>>>>>>    - Tickets are closed after careful review if they are
>>>>>>    unrepeatable or unactionable.  Suggestions and questions about a clearer
>>>>>>    ticket are usually included.
>>>>>>
>>>>>> Hope this helps.
>>>>>>
>>>>>> all the best, Don
>>>>>> --
>>>>>> X3D Graphics, Maritime Robotics, Distributed Simulation
>>>>>> Relative Motion Consulting  https://RelativeMotion.info
>>>>>>
>>>>>>
>>>>>> On Sun, Jan 4, 2026 at 5:57 AM John Carlson <yottzumm at gmail.com>
>>>>>> wrote:
>>>>>>
>>>>>>> Blowing off some steam.  Apologies, I probably should work out
>>>>>>> instead.
>>>>>>>
>>>>>>> I am unsure if it’s easier to output straight line code instead of
>>>>>>> hierarchical code in Python; multi-line non-persistent comments might
>>>>>>> become easier in straight line code.  I don’t know about comments() in
>>>>>>> XSLT.  In straight line code, wrapping a multi or single line comment in
>>>>>>> “””…””” is a cinch.  Even if newlines need to be added for the Python
>>>>>>> interpreter.
>>>>>>> AFAIK, I’ve already mentioned that straight line code is easier to
>>>>>>> debug, in my mind.  I think the Java large file discussion is still
>>>>>>> open; I know hierarchical code is more succinct, and less likely to stack
>>>>>>> overflow.  I think the choices between code structure in Python and Java
>>>>>>> might be different.
>>>>>>>
>>>>>>> Persistent multi-line comments are desirable, even if they aren’t
>>>>>>> present in the archive.  We will probably make different choices between
>>>>>>> hierarchical and straight line code when this feature is available.
>>>>>>>
>>>>>>> Short term hacks like single line comments work until features are
>>>>>>> introduced.  That doesn’t mean tickets should be closed prematurely, or
>>>>>>> examples outside the archives are invalid.
>>>>>>>
>>>>>>> John
>>>>>>>
>>>>>>> On Tue, Dec 30, 2025 at 3:42 AM John Carlson <yottzumm at gmail.com>
>>>>>>> wrote:
>>>>>>>
>>>>>>>> Don, thanks for your comment on this ticket that naively adding
>>>>>>>> Comment to a children field might not work.  That was one of my intentions
>>>>>>>> on expressing myself so vocally.  I apologize for using your time to do
>>>>>>>> this, but I think it revealed a possible design consideration.  I think if
>>>>>>>> I had discovered it, it would have gone over like a wet balloon.
>>>>>>>>
>>>>>>>> Thank you again, I will not put comments arbitrarily in the
>>>>>>>> scenegraph for now with my PythonSerializer.js, until you indicate it’s
>>>>>>>> ready!   I will leave them out of the scenegraph, as they are now.   Since
>>>>>>>> I handle comments generically, I will have to research the nodes you’ve
>>>>>>>> accomplished.
>>>>>>>>
>>>>>>>> Now, can we have other multi-line comments, not in the persistent
>>>>>>>> scenegraph, in Python translated from .x3d, in the short term, like:
>>>>>>>>
>>>>>>>> #
>>>>>>>> # This is comment line 2
>>>>>>>> # This is comment line 3
>>>>>>>> #
>>>>>>>>
>>>>>>>> ?
>>>>>>>>
>>>>>>>> John
>>>>>>>>
>>>>>>>> From the ticket:
>>>>>>>>
>>>>>>>> “
>>>>>>>>
>>>>>>>> This is not an easy fix for converting files because Comment is not
>>>>>>>> part of the content model for all nodes. Solving this will probably require
>>>>>>>> extending class _ X3DNode in x3d.py and sorting out possible subclass
>>>>>>>> collisions. It will also be difficult to retain the original order of child
>>>>>>>> nodes and child comments within a parent node.
>>>>>>>>
>>>>>>>> This might be fixable someday - after some effort I got it working
>>>>>>>> for head, Scene, field, fieldValue.. Deferred as future work.
>>>>>>>>  ”
>>>>>>>>
>>>>>>>> On Mon, Dec 29, 2025 at 12:52 PM Don Brutzman <
>>>>>>>> don.brutzman at gmail.com> wrote:
>>>>>>>>
>>>>>>>>>
>>>>>>>>> I have posted a new ticket to capture this point.  Perhaps
>>>>>>>>> a useful exemplar, as well.
>>>>>>>>>
>>>>>>>>>    - X3D SourceForge ticket #82 creating persistent comments in
>>>>>>>>>    python when converting from XML
>>>>>>>>>    - https://sourceforge.net/p/x3d/tickets/82/
>>>>>>>>>
>>>>>>>>> Hope this helps.  Again thanks for your many efforts.  Have fun
>>>>>>>>> improving X3D!  🤔 👍
>>>>>>>>>
>>>>>>>>>>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20260107/f403b191/attachment-0001.html>
-------------- next part --------------
AllenDutton.x3d
JinLOA4.x3d
JinLOA4scaled1joe06c.x3d
JinScaledV2L1LOA4OnlyMarkers11g.x3d
JinScaledV2L1LOA4Sites07f.x3d
JinScaledV2L1LOA4Sites08e.x3d
JinScaledV2L1LOA4Sites10h.x3d
JoeDemo5JoeSkin5a.x3d
JohnJoint.x3d
JohnJoint2.x3d
OrientationInterpolator.x3d
ball.x3d
bub.x3d
bumpyfreewrljsonverse.x3d
bumpyfreewrlsliders.x3d
bumpyx_ite.x3d
bumpyx_itesliders.x3d
cgeparticleflowers.x3d
flower.x3d
flower3.x3d
flowerproto.x3d
flowerprotofreewrl.x3d
flowers.x3d
flowers2.x3d
flowers4.x3d
flowers7.x3d
force.x3d
forcenode.x3d
fors.x3d
indexedfaceset_pixeltexture_entire.x3d
indexedfaceset_pixeltexture_part.x3d
indexedfaceset_pixeltexture_plus.x3d
indexedfaceset_pixeltexture_whole.x3d
john.x3d
john2.x3d
john3.x3d
particleballs.x3d
personal.x3d
variationalflowers.x3d
variationalflowers2.x3d
x3dconnector.x3d

More information about the x3d-public mailing list