Jordan Brown wrote:

i am not a fan of python and have little practice with it, and trying to use a functional language implemented in a procedural one?? .. naahh .. I am going to explore the use BOSL2 and NopSCADlib and possibly others .. my tinkering with the relativity.scad library is what got me into scad

here we differ. i absolutely expect just that .. if the reference for the language is not enough to completely understand and use it, the documentation has failed its purpose.

And all those potential misunderstandings should be noted on every page where experience has revealed them.

I would have welcomed any and all input from anyone building on my work .. and would not been “miffed” seeing my mistakes reverted.
My experience with teamwork is varied and extensive .. i am well able to work collaboratively, which is to say I
know how to contribute without exerting ownership and without investing my ego in my work product.

What I won’t do is be where i am not welcome nor with people who are rude and possessive.

I did contribute in an overly aggressive manner, now obvious in hindsight .. but some people, your kind self, amatulicm, Kintel and a few others .. provided constructive feedback and allowed me to fix what i had broken .. but the rest of the group have made it clear they don’t play well with newcomers and i am not about to try pushing on a rope.

That wont be happening

Your tips on Way of Work are good ones and i have preserved them in my notes on documentation practice.

And I have enjoyed them too .. i will reach out privately when you are returned from your cruise

many thanks

Jeff

I don't think a language reference should be used for learning a language.
That is for tutorials and books. Marius has written a book about OpenSCAD.

The reference is for looking up exact details about a module or function
when one can't remember the name or arguments.

On Tue, 12 Aug 2025, 13:45 vulcan_--- via Discuss, <
discuss@lists.openscad.org> wrote:

On Tuesday, August 12, 2025 at 09:14:44 AM EDT, nop head via Discuss discuss@lists.openscad.org wrote:

There is an interesting tension on that and one which programming systems seem to have a difficult time balancing.

One site which discusses this is: https://diataxis.fr/ which divides documentation between:

 - Tutorials/Learning
 - How-to Guides/Goals
 - Explanation/Understanding
 - Reference/Information

and working out how each differing need will be addressed is a hurdle which any successful project needs to clear.

For OpenSCAD, this difficulty is even more mired in a fundamental set of divisions:

 - OpenSCAD makes modeling designs using rectangles, cylinders and spheres using mathematically calculated placements and distortions and arrangements simple
 - the usage of OpenSCAD is strongly bounded by the user's knowledge of mathematics, their fluency with the programming constructs which which OpenSCAD affords, and their ability to find modules/libraries/existing projects w/ Customization options which meet their needs
 - the functional programming methodology places some hard limits on modifying state for projects where such a division would be helpful
 
That last is neatly addressed by either programming in a second language and generating OpenSCAD code, or using a second language w/in OpenSCAD as is done by (Open)PythonSCAD: https://pythonscad.org/ with a simply amazing example of this being:

https://old.reddit.com/r/OpenPythonSCAD/comments/1mn2nrd/cool_mech_kinematics_script_in_pythonscad/

which shows the potential of moving beyond OpenSCAD.

I will note that in addition to Marius' wonderful book: https://nostarch.com/programmingopenscad (I've bought multiple copies for the children of co-workers, and just bought the Kindle version at full-price which I rarely purchase at) there is a series of books which looks at mathematics and uses OpenSCAD and 3D printing to enhance the lessons:

 - Geometry: https://www.goodreads.com/book/show/58059196-make
 - Trigonometry: https://www.goodreads.com/book/show/123127774-make
 - Calculus: https://www.goodreads.com/book/show/61739368-make

which I found very helpful and recommend highly. What other books are folks finding useful?

Since documentation is an aspect of my current project which I am still having difficulty with, I would be glad of further thoughts and comments on this.

William

Seems to be some interesting reference books William.

It is always better retention if you learn by doing.

Documentation is a very difficult part, at least for me. I think if there
are some simple and good examples, it is easier to follow, rather than
reading too much text, but again it is a personal choice. Few people would
like to first understand the concept completely and clearly before trying.

Example you shared is interesting. I think this is done through pythonscad.

Python is definitely a much structured language and much more powerful
compared to openSCAD and I would recommend others to also try it.

Appeal of openSCAD is in its simplicity and is much better for starters.

But once things start getting complex ( which definitely will start after a
few days of using openscad) then the natural path would be migrating to
languages like python.

There is so much development done on python and with many libraries
available, it can do a lot more.

Regards
Sanjeev

On Tue, 12 Aug 2025 at 19:28, William F. Adams via Discuss <
discuss@lists.openscad.org> wrote:

nop head wrote:

When i started working with scad the lang ref was not completely useful for those purposes .. it was good in places, incomplete in others, and erroneous in a few. The argument list completion feature of the editor showed me that changes to some modules had not been documented. The list of math functions included str(), ord() and other non-math functions and the descriptions of the operators were sketchy.

The section on user-defined functions did not make clear that there is only one type of module .. the docs on the children() function do not say it can be used to give any module access to its children and the descriptions of the built-in modules separate them into shape creating modules and operators .. which mislead me completely. The descriptions of assert(), echo() and let() did not say they were also modules, but can also be used in expressions as if they were operators  .. and in fact that if-then-else and for-loop were modules too. In fact, the description of  if-then-else and for-loop presented them as if they were statements in a procedural language, to me at least.

just this last week it came clear to me that the syntax for the use of a module has two parts, parent and child:

parent_module( <arg list> ) child_module( <arg list> );

meaning that the call to a module is followed by an optional call to a child module. And then, the child_module, being a module, may then also have a child etc etc
OR, using braces can make a parent apply to a whole bunch of children, like this:

parent_module( <arg list> ) { child_module_1( <arg list> ); child_module_2( <arg list> ); … };

where each child_module_*() statement might have a whole hierarchy of shapes and transforms

None of which is explained in either the tutorials or the lang ref.
Or at least .. i did not see it .. it took several lengthy conversations with Jordan and a few others in these threads to make this all clear.

As for the tutorials .. There are explanations of language features that are ONLY in the tutorials and make use of features without explaining them .. for example .. the specials $fa and $fs .. they appear at the beginning of a lot of the code examples but their importance to making the circular objects look round is never connected.

The importance of recursion to functional programming as a replacement for looping in a procedural language is not covered in the tutorials at all .. but it is a heavily used technique in the relativity.scad library .. which is how i learned about it .. not by doing the tutorials, and not by reading the language reference

But then, i think i should be able to learn all about a language by reading about it in its reference document.

nop head wrote:

When i started working with scad the lang ref was not completely useful for those purposes .. it was good in places, incomplete in others, and erroneous in a few. The argument list completion feature of the editor showed me that changes to some modules had not been documented. The list of math functions included str(), ord() and other non-math functions and the descriptions of the operators were sketchy.

The section on user-defined functions did not make clear that there is only one type of module .. the docs on the children() function do not say it can be used to give any module access to its children and the descriptions of the built-in modules separate them into shape creating modules and operators .. which mislead me completely. The descriptions of assert(), echo() and let() did not say they were also modules, but can also be used in expressions as if they were operators  .. and in fact that if-then-else and for-loop were modules too. In fact, the description of  if-then-else and for-loop presented them as if they were statements in a procedural language, to me at least.

just this last week it came clear to me that the syntax for the use of a module has two parts, parent and child:

parent_module( <arg list> ) child_module( <arg list> );

meaning that the call to a module is followed by an optional call to a child module. And then, the child_module, being a module, may then also have a child etc etc
OR, using braces can make a parent apply to a whole bunch of children, like this:

parent_module( <arg list> ) { child_module_1( <arg list> ); child_module_2( <arg list> ); … };

where each child_module_*() statement might have a whole hierarchy of shapes and transforms

None of which is explained in either the tutorials or the lang ref.
Or at least .. i did not see it .. it took several lengthy conversations with Jordan and a few others in these threads to make this all clear.

As for the tutorials .. There are explanations of language features that are ONLY in the tutorials and make use of features without explaining them .. for example .. the specials $fa and $fs .. they appear at the beginning of a lot of the code examples but their importance to making the circular objects look round is never connected.

The importance of recursion to functional programming as a replacement for looping in a procedural language is not covered in the tutorials at all .. but it is a heavily used technique in the relativity.scad library .. which is how i learned about it .. not by doing the tutorials, and not by reading the language reference

But then, i think i should be able to learn all about a language by reading about it in its reference document.

On 2025-08-12 2:45 p.m., vulcan_--- via Discuss wrote:

Maybe the comment is meant to relate only to the narrow context of
user-defined modules or maybe I've misunderstood where the discussion
has got to, but in the general sense is there really only one type of
module? In my simplistic world view, there are two: primitive modules
that create shapes, and modifier modules that do things to shapes. My
distinction arises because some (native) modules accept children, some
do not. For example OpenSCAD, sensibly, rejects:  cube(1) sphere(1);

Steve

BOSL2 attachment documentation. I have a tough time building a mental model
into which the pieces fit.

Most programmers probably think differently.

I have a tough time building a mental model into which the pieces fit.

I agree, Father Horton. I've gone through the documentation and the
supplied examples several times. I think that I finally understand the
intent of attachments. However, I have yet to find a use-case in my
projects where attachments are easier than the native translate()/rotate()
OpenSCAD primitives.

Also, looking at the number of functions/modules that are documented as
part of attachments in the documentation at...
https://github.com/BelfrySCAD/BOSL2/wiki/attachments.scad
...just... overwhelms me.

On Tue, Aug 12, 2025 at 5:35 PM Father Horton via Discuss <
discuss@lists.openscad.org> wrote: