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

John Carlson yottzumm at gmail.com
Mon Jan 5 10:42:35 PST 2026 

What’s relevant to me is I have often commented out large multi-line chunks
of XML in my .x3d files with a multi-line comment, so going back and making
them multiple single line comments without making long lines is especially
relevant!

I’m going to pursue the Java SAXParser in the short term as an experiment.
If it doesn’t work out, I’ll revert the .x3d code and think again!

If you put a newline in an “XML” attribute in a multi-line comment, dang
it, I can’t handle that yet,  can a better XSLT tokenizer identify newlines
between quotes in a multi-line comment?  What a hairy mess!

I don’t really like newlines in XML attributes, maybe they should be banned
in the XML encoding?

I guess I can put a better parser for comments in the SAXParser.

Back to you, Don.

Thanks for wise words,

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/20260105/9fc1fb14/attachment-0001.html>

More information about the x3d-public mailing list