<div dir="ltr"><div dir="ltr"><div>John, thanks for many good possible ideas. Translating them into effective results is not trivial.</div><div><br></div>Suggestion: you need to write clearer tickets, simpler test cases, and use X3D Example Archives wherever possible.</div><div dir="ltr"><br></div><div dir="ltr">Here is a detailed explanation of how to create actionable issues with long-term value.<br><div><br></div><div>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.</div><div><br></div><div>Equivalent X3D examples. If you want to see example encodings of comments, please see</div><div><ul><li>X3D Example Archives: X3D4WA, X3D for Web Authors, Chapter 01 Technical Overview, Hello World</li><li>Simple X3D model example: Hello World!</li><li><a href="https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter01TechnicalOverview/HelloWorldIndex.html">https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter01TechnicalOverview/HelloWorldIndex.html</a></li><li><a href="https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter01TechnicalOverview/HelloWorld.x3d">https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter01TechnicalOverview/HelloWorld.x3d</a></li><li><a href="https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter01TechnicalOverview/HelloWorld.java">https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter01TechnicalOverview/HelloWorld.java</a></li><li><a href="https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter01TechnicalOverview/HelloWorld.py">https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter01TechnicalOverview/HelloWorld.py</a></li></ul></div><div>Equivalent excerpts using X3D Documentation, XML, Java, and Python:</div><div><ul><li><a href="https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter01TechnicalOverview/HelloWorld.html#31">https://www.web3d.org/x3d/content/examples/X3dForWebAuthors/Chapter01TechnicalOverview/HelloWorld.html#31</a></li><li><i>(XML) </i> <b> <font face="monospace"><!-- Example scene to illustrate X3D nodes and fields (XML elements and attributes) --></font></b></li><li><i>(Java) </i> <font face="monospace"> <b>.addComments(" Example scene to illustrate X3D nodes and fields (XML elements and attributes) ")</b></font></li><li><i>(Python) </i><font face="monospace"> <b># Example scene to illustrate X3D nodes and fields (XML elements and attributes)</b> </font></li></ul><div>Repeatable test evaluation. For all of our tests, we start with a single .x3d (XML) file. Typical progression:</div></div><div><div> a. is the .x3d file valid,</div><div> b. is the conversion correct (for Java, Python, etc.)</div><div> c. does the relevant library correctly support the conversion.</div></div><div><br></div><div>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.</div><div><ul><li>X3D Resources, Examples: Scene Archives for X3D</li><li><a href="https://www.web3d.org/x3d/content/examples/X3dResources.html#Examples">https://www.web3d.org/x3d/content/examples/X3dResources.html#Examples</a></li><li>Often when you discover some issue, it means we do not have test case yet. Addition of examples is always welcome.</li></ul></div><div>Additional notes.</div><div><br></div><div>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.</div><div><ul><li>Sourceforge: x3d tickets</li><li><a href="https://sourceforge.net/p/x3d/tickets">https://sourceforge.net/p/x3d/tickets</a></li></ul><div>b. When an issue ticket is closed, it is typically fixed.</div><div>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.</div><div>d. Writing a pithy example that demonstrates expected functionality is powerful and provides long-term benefits.</div><div>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.</div><div>f. Simple new examples are welcome, but this is not a service for writing and debugging large X3D models.</div><div>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.</div></div><div><br></div><div>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.</div><div><br></div><div>We do have Javadoc for X3DJSAIL, so if you want to look at many ways to create an X3D comment in Java, please see</div><div><ul><li>X3DJSAIL Javadoc, X3D Java Scene Access Interface Library</li><li><a href="https://www.web3d.org/specifications/java/javadoc">https://www.web3d.org/specifications/java/javadoc</a></li><li><a href="https://www.web3d.org/specifications/java/javadoc/org/web3d/x3d/jsail/Core/CommentsBlock.html">https://www.web3d.org/specifications/java/javadoc/org/web3d/x3d/jsail/Core/CommentsBlock.html</a></li></ul><div>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:</div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><br>class Comment(_X3DStatement):<br> """<br> X3D statement containing zero or more comment strings.<br> """</blockquote><div><br></div><div>I have posted a new ticket to capture this point. Perhaps a useful exemplar, as well.</div><div><ul><li>X3D SourceForge ticket #82 creating persistent comments in python when converting from XML</li><li><a href="https://sourceforge.net/p/x3d/tickets/82/">https://sourceforge.net/p/x3d/tickets/82/</a></li></ul></div><div>Hope this helps. Again thanks for your many efforts. Have fun improving X3D! 🤔 👍</div></div><div><div dir="ltr" class="gmail_signature"><div dir="ltr"><div style="color:rgb(34,34,34)"><font face="monospace"><br></font></div><div style="color:rgb(34,34,34)"><font face="monospace">all the best, Don</font></div><div style="color:rgb(34,34,34)"><font face="monospace">-- </font></div><div style="color:rgb(34,34,34)"><font face="monospace">X3D Graphics, Maritime Robotics, Distributed Simulation</font></div><div style="color:rgb(34,34,34)"><font face="monospace">Relative Motion Consulting <a href="https://RelativeMotion.info" target="_blank">https://RelativeMotion.info</a></font></div></div></div></div><br></div><br><div class="gmail_quote"><div dir="ltr" class="gmail_attr">On Mon, Dec 29, 2025 at 3:25 AM John Carlson <<a href="mailto:yottzumm@gmail.com" target="_blank">yottzumm@gmail.com</a>> wrote:<br></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div dir="auto">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.</div><div dir="auto"><br></div><div dir="auto">Note that I do like:</div><div dir="auto"><br></div><div dir="auto">“””</div><div dir="auto">comment here</div><div dir="auto">“””</div><div dir="auto"><br></div><div dir="auto">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.</div><div dir="auto"><br></div><div dir="auto">I think the combination of a “””…””” multi-line comment <span style="font-family:-apple-system,sans-serif">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.</span></div><div dir="auto"><span style="font-family:-apple-system,sans-serif"><br></span></div><div dir="auto"><span style="font-family:-apple-system,sans-serif"><div style="font-size:inherit"><div dir="auto" style="color:rgb(0,0,0);font-family:-apple-system,sans-serif;font-size:inherit;font-style:normal;font-weight:400;letter-spacing:normal;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px;text-decoration:none">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.</div></div></span></div><div dir="auto"><br></div><div dir="auto">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.’ <div style="font-size:inherit" dir="auto"><span style="color:rgb(0,0,0);font-family:-apple-system,sans-serif;font-size:inherit;font-style:normal;font-weight:400;letter-spacing:normal;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px;text-decoration:none;float:none;display:inline"><br></span></div><div style="font-size:inherit" dir="auto"><span style="color:rgb(0,0,0);font-family:-apple-system,sans-serif;font-size:inherit;font-style:normal;font-weight:400;letter-spacing:normal;text-indent:0px;text-transform:none;white-space:normal;word-spacing:0px;text-decoration:none;float:none;display:inline">Joe and I created an .x3d file with multi-line comments that broke the Python generated by X3dToPython.xslt.</span></div></div><div dir="auto"><br></div><div dir="auto">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.</div><div dir="auto"><br></div><div dir="auto">Ultimately, the solution may just be to use single-line comments, but that doesn’t allow round-tripping.</div><div dir="auto"><br></div><div dir="auto"><span style="font-family:-apple-system,sans-serif">John</span><br></div><div><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div><div><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div><div class="gmail_quote"><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left:1px solid rgb(204,204,204);padding-left:1ex"><div><p></p></div> <div>
<div>
</div>
</div></blockquote></div></div>
</blockquote></div></div>
</div>
</blockquote></div>
</blockquote></div>
</blockquote></div>
</blockquote></div></div>
</blockquote></div>
</div>