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

[John Carlson]

Don, I agree, single-line comments work well with current X3dToPython.xslt.

Multi-line comments do not, last I checked.  It is extremely easy to create
a multi-line comment in .x3d.   Putting more effort into creating yet
another example seems less than productive on my part currently.   Feel
free to report a multi-line example that works.

All I have given you in both a ticket and private emails is multi-line
comments.  Joe should be able to vouchsafe that as I cc’ed him.   I can
also forward emails.

Perhaps instead of closing tickets, you keep them open and create a dialog.
  I suggest assigning them back to me.  I will start looking for that in
the future.

I am not being paid to write tickets, so don’t be surprised if they lack
enthusiasm.

I think I have a way forward now, without X3dToPython.xslt, so I will
pursue that, until I reach a roadblock.  The Comment class was a late
revelation, and I didn’t see it in X3dToPython.xslt output.

If you want me to try to find a multi-line comment in X3D archives, I have
offered to do that.   I don’t currently know if any exist.   Hence the
frustration.   You tell me to use the archives, but if they don’t reflect
my examples from Joe and myself that are failing conversion to Python, I
have to resort to our examples.  A multi-line comment in .x3d is perfectly
valid until the standard says it isn’t.

I agree that your ticket captures one aspect of Comment instances, but I
fear it doesn’t capture the multi-line aspect of .x3d comments, hence the
python output from X3dToPython.xslt will still be invalid from valid .x3d
files with multi-line comments.

I understand there’s difficulty accomplishing some things with XSLT.  You
have done Herculean work.  Perhaps it’s time to do the hard work and
translate the stylesheets to something more capable.  Use a stylesheet to
translate stylesheets to Java.   X3dToPython.java, X3dToJava.java, etc.
 the goal is to get rid of stylesheets, by writing XsltToJava.xslt.  Feel
free to use Saxon.jar!   The ultimate challenge!

John

On Mon, Dec 29, 2025 at 12:52 PM Don Brutzman <don.brutzman at gmail.com>
wrote:

> John, thanks for many good possible ideas.  Translating them into
> effective results is not trivial.
>
> Suggestion: you need to write clearer tickets, simpler test cases, and use
> X3D Example Archives wherever possible.
>
> Here is a detailed explanation of how to create actionable issues with
> long-term value.
>
> Summary.  X3D is pretty amazing in that we can represent the same scene
> graph in many ways.  The goals for both X3DJSAIL Java and X3DPSAIL Python
> are to provide programmers with APIs that can build and manipulate scene
> graphs effectively, without errors.  Both libraries have much capability,
> with X3DJSAIL being actively worked on (for example, last night's
> release).  X3DPSAIL updates will follow in the coming year.
>
> Equivalent X3D examples.  If you want to see example encodings of
> comments, please see
>
>    - X3D Example Archives: X3D4WA, X3D for Web Authors, Chapter 01
>    Technical Overview, Hello World
>    - Simple X3D model example: Hello World!
>    -
>    https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter01TechnicalOverview/HelloWorldIndex.html
>    -
>    https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter01TechnicalOverview/HelloWorld.x3d
>    -
>    https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter01TechnicalOverview/HelloWorld.java
>    -
>    https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter01TechnicalOverview/HelloWorld.py
>
> Equivalent excerpts using X3D Documentation, XML, Java, and Python:
>
>    -
>    https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter01TechnicalOverview/HelloWorld.html#31
>    - *(XML) *     * <!-- Example scene to illustrate X3D nodes and fields
>    (XML elements and attributes) -->*
>    - *(Java) *     *.addComments(" Example scene to illustrate X3D nodes
>    and fields (XML elements and attributes) ")*
>    - *(Python) * *#  Example scene to illustrate X3D nodes and fields
>    (XML elements and attributes)*
>
> Repeatable test evaluation.  For all of our tests, we start with a single
> .x3d (XML) file.  Typical progression:
>   a. is the .x3d file valid,
>   b. is the conversion correct (for Java, Python, etc.)
>   c. does the relevant library correctly support the conversion.
>
> Assets.  We have thousands of examples in version control online.  Using
> those as test cases builds on existing validity testing and, for useful
> test cases, means we are all progressing together.
>
>    - X3D Resources, Examples: Scene Archives for X3D
>    - https://www.web3d.org/x3d/content/examples/X3dResources.html#Examples
>    - Often when you discover some issue, it means we do not have test
>    case yet.  Addition of examples is always welcome.
>
> Additional notes.
>
> a. You have seen firsthand how issue reports and examples are always
> welcome.  X3D is a big language, some tickets take time to resolve.  Thanks
> once again for your many efforts.
>
>    - Sourceforge: x3d tickets
>    - https://sourceforge.net/p/x3d/tickets
>
> b. When an issue ticket is closed, it is typically fixed.
> c. When an issue ticket reaches "wont-fix" status, that means the specific
> ticket is not actionable.  A worthy problem or two might well remain in
> there somewhere, but the ticket doesn't describe it in a repeatable way.
> Several tickets in that category have immense build logs that defy shared
> understanding... Time to reset and redetermine what the problem really is.
> d. Writing a pithy example that demonstrates expected functionality is
> powerful and provides long-term benefits.
> e. Sharing incredibly large and complex models to illustrate a single
> point is rarely useful, it is too hard to handle multiple issues at once.
> f. Simple new examples are welcome, but this is not a service for writing
> and debugging large X3D models.
> g. Programmers can write their code in many many ways. The libraries do
> not mandate how a programmer codes, but internally they are highly
> consistent.  The given approaches to X3D Java and Python provide helpful
> optional libraries for programmers to use when loading, building, adapting,
> or exporting X3D models.
>
> I am looking over your preceding message and not sure what you want to fix
> something, or add a feature, or what.  Am not disagreeing but am not
> understanding whether there is a specific repeatable goal.
>
> We do have Javadoc for X3DJSAIL, so if you want to look at many ways to
> create an X3D comment in Java, please see
>
>    - X3DJSAIL Javadoc, X3D Java Scene Access Interface Library
>    - https://www.web3d.org/specifications/java/javadoc
>    -
>    https://www.web3d.org/specifications/java/javadoc/org/web3d/x3d/jsail/Core/CommentsBlock.html
>
> Perhaps you want to add a similar class in X3DPSAIL x3d.py for persistent
> comments?  The python output above is not persistent... perhaps
> X3dToPython.xslt converter should use the following class in x3d.py instead:
>
>>
>> class Comment(_X3DStatement):
>>     """
>>     X3D statement containing zero or more comment strings.
>>     """
>
>
> 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!  🤔 👍
>
> all the best, Don
> --
> X3D Graphics, Maritime Robotics, Distributed Simulation
> Relative Motion Consulting  https://RelativeMotion.info
>
>
> On Mon, Dec 29, 2025 at 3:25 AM John Carlson <yottzumm at gmail.com> wrote:
>
>> Including Loren.  Loren, Don and I have been discussing how to handle
>> converting multi-line XML comments to Python in XSLT for X3DPSAIL programs.
>>   Particularly using X3dToPython.xslt. I am not an expert at XSLT, and
>> don’t have appropriate tools, so I’ve been leaning on Don unduly.
>>
>> Note that I do like:
>>
>> “””
>> comment here
>> “””
>>
>> Python comments, but I don’t know if we can put them directly in the
>> scenegraph.  Just putting one “#” for a multi-line XML comment when
>> translating to Python isn’t going to work.  Maybe removing line endings
>> would work.   Also a “#” per comment line may also work.
>>
>> I think the combination of a “””…””” multi-line comment and a
>> CommentsBlock class instance constructor wrapper around the comment may do
>> the trick, and also fits in the scene graph for round-tripping.   This has
>> worked in X3DJSAIL, AFAIK.  I don’t know about output from X3DPSAIL yet.  I
>> believe that X3DJSAIL also offers .addComments() methods to add
>> CommentsBlock instances to the scenegraph, in many classes.  I would
>> primarily like this feature in order to do round-trip testing back to XML.
>> Obviously there’s a whole discussion whether we should be converting XML to
>> Java and Python.  That’s how I create Java and Python test cases.  Don
>> prefers hand-coding tests, I think, and probably feels he is serving the
>> programming community.  I feel we have 4000+ XML examples that serve an
>> excellent proving ground.   Plus, I also have my own tests for my JSON
>> loader I create from XML.
>>
>> Ultimately the above will be critical if we wish to output comments using
>> the XML(), VRML() and JSON(), etc. methods in X3DPSAIL to produce
>> documentation inside the scenegraph output.   This will be useful for
>> documenting X3D encoded files output from Maya, Blender, etc.
>>
>> Don hasn’t weighed in on this except to state he needs simple examples,
>> or examples in the archive that he controls.  Previous bug reports have
>> been marked ‘won’t fix.’
>>
>> Joe and I created an .x3d file with multi-line comments that broke the
>> Python generated by X3dToPython.xslt.
>>
>> I can find a multi-line comments in the XML in the X3D archive, if there
>> are any there, the POSIX shell command is relatively simple.   If you need
>> help identifying multi-line comments to reduce to single-line comments,
>> that should be a cinch!   I can probably produce a list of files.
>>
>> Ultimately, the solution may just be to use single-line comments, but
>> that doesn’t allow round-tripping.
>>
>> John
>>
>>>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://web3d.org/pipermail/x3d-public_web3d.org/attachments/20251230/ede9f1f4/attachment-0001.html>