OpenSCAD can undoubtedly being confusing, particularly to someone who
doesn't have much (or any) background with functional programming. I, too,
don't see the need for a complete documentation rewrite. I do think an
introduction to the OpenSCAD way of thinking would be helpful.

A lot of documentation is written from what I call the "ground-up"
perspective: I'll give you all the details, and you assemble the picture. I
work better with "top-down" documentation: Here's the idea, and here's how
you implement it. Come to think of it, that's probably why I can't get my
mind around BOSL2's documentation of things like attachment.

On Fri, Aug 8, 2025 at 8:10 PM Jon Bondy via Discuss <
discuss@lists.openscad.org> wrote:

Father Horton: Regarding BOSL2: Yes! You have hit upon the key! When I was
still a corporate minion, I would write documentation based upon "Here's
what you do to produce this result." Not, "this parameter does that.".

On Fri, Aug 8, 2025 at 10:02 PM Father Horton via Discuss <
discuss@lists.openscad.org> wrote:

The main BOSL2 manual is a reference manual, but I think the tutorials are
supposed to do what you are asking.  How does, for example, the Attachments
tutorial fail for you?

On Fri, Aug 8, 2025 at 11:17 PM Leonard Martin Struttmann via Discuss <
discuss@lists.openscad.org> wrote:

I agree about BOSL2, but find the extensive examples sufficient for me
to pick a path and make it work.

On 8/8/2025 11:17 PM, Leonard Martin Struttmann via Discuss wrote:

--
This email has been checked for viruses by AVG antivirus software.
www.avg.com

I think BOSL2's documentation is excellent.  It is both a convenient quick
reference and the examples and tutorials provide helpful introductions to
its rich features.  I don't think there is anything particularly wrong with
OpenSCAD's documentation.  I went through it thoroughly when I first
started using OpenSCAD and it got me going fairly quickly.  But it wasn't
until I started using BOSL2 that I was able to see OpenSCAD is
sufficiently powerful to do most of what I want to do in CAD.

My biggest issue with BOSL2 is keeping up with the changes.  It's not a
problem such that I have any worry about my old scripts being broken by
updates to BOSL2.  It's rare I have to fix my old code and when I do it is
mostly because of mistakes or mistaken assumptions on my part.  But rather
I discover new features in a haphazard way sometimes long after they have
been available.  I don't blame BOSL2 for this.  I could more closely
follow the progress on github but mostly I don't as it isn't necessary.
Just sometimes I kick myself for being slow to discover there are better
ways of doing the things I have been doing.

On Sat, Aug 9, 2025 at 5:50 AM Jon Bondy via Discuss <
discuss@lists.openscad.org> wrote:

That's absolutely true, but we have an active discussion going on about
whether we should ensure that the documentation allows for a future
where (absent $fn) it does create a true circle.

That's exciting although it would be most useful to create a true circle if
we also have true arcs and they at least sometimes survive extrusion,
transformations, booleans, hull(), minkowski(), etc. and propagate through
to an exported file.  And the next steps in our tool chain such as slicer
or CAM and the firmwares in our devices can use them.  All of which I
expect is possible but I have no sense of how hard it will be or how long
it might take.

On Fri, Aug 8, 2025 at 2:48 AM Jordan Brown openscad@jordan.maileater.net
wrote:

That will be OpenCascade.

On Sun, Aug 10, 2025, 02:20 Todd Allen via Discuss <
discuss@lists.openscad.org> wrote:

On 8/9/2025 6:20 PM, Todd Allen wrote:

Don't get excited yet.  Nobody has stepped up to do the actual work.  I
just made a proposal to tweak the definition of the various curved
shapes so that if we eventually are able to process true curves, we
wouldn't be breaking our API commitments. (Of course, that would be by
partially backing off on them now, but that would let people have time
to adjust.)

The most aggressive things that I've considered in the short run are:

• Having $fs and $fa default to undef or zero, and have circle() et al
  apply defaults at invocation time, so that the actual defaults used
  are less visible and so less possible to depend on.  And then set
  them to something much smaller so that you get decent circles by
  default.
• Changing the $fa/$fs calculation so that it always rounds up to a
  multiple of 4, so that it always yields circles that touch the
  bounding box on all four sides.
• Doing something to improve spheres.  At least make them touch their
  north and south poles, but preferably switch over to a different
  mesh entirely, e.g. via octahedral subdivision
  https://en.wikipedia.org/wiki/Geodesic_polyhedron.

Yes, that would be a requirement.

That would depend on the output format - STL is polygons-only - but yes,
that would be the goal.

Yes.  At least some devices can do gcode arcs in their firmware, which
is a good step, but I have no idea whether the slicers and CAM connect
those dots.

Yes.  It's clearly theoretically possible... and equally clearly well
beyond me.

Looking at drawing programs, it looks like those operations are more or
less solved for 2D.  One of the things I have wondered is whether we
could do our 2D with true curves, and only switch to polygonal
approximations when extruding.  That would be a bit weird, but if the
defaults are fairly good circles then the difference between the true
circles and the approximations wouldn't be much.

(And of course when you explicitly set $fn you will forever get exactly
what you ask for.)

On 8/9/2025 1:07 AM, vulcan_--- via Discuss wrote:

You are welcome.

It's up to you, of course, but what I'd recommend is:

• Continue to use OpenSCAD.  For all its faults, it really is a nearly
  unique  and powerful tool.  If you understand and accept the risks,
  and can accept a more technical installation process, consider the
  PythonSCAD https://pythonscad.org/ semi-fork.  It lets you
  construct models using OpenSCAD-like constructs, but with Python as
  the base language.
• Hang around, only lurking if you like.  Ask questions when you have
  them - privately if you prefer.  Read the tutorial matter; there is
  no expectation that somebody can learn the language simply from the
  reference material.  The language is very different from most other
  languages, but can look deceptively similar.
• Don't be offended if your changes get backed out. Unfortunately, you
  did introduce some errors, and your changes are so extensive that
  reviewing them requires reading every single page from zero, rather
  than just inspecting changes. Remember that, as you said, it's a
  wiki... once your OpenSCAD is stronger, you can pluck that work out
  and reuse it.
• When you're ready to start contributing again, do it a bit more
  slowly, and do it with an eye toward reviewability.  For instance,
  if you want to split a page in half and you want to update the text,
  do it in two distinct steps.  The first step might be the split,
  without changing anything substantive about the content, while the
  second is the substantive changes (or the other way around).  That
  allows a reviewer to look only at the changes, and not be forced to
  review an entire page that was created anew.  Perhaps further split
  the substantive changes into wordsmithing and other changes that do
  not affect the meaning, and more technical changes.  Consider making
  the changes in a sandbox and ask somebody to review them before
  publishing them.  (Copy the original into the sandbox, save, then
  make changes on top of that, so that a reviewer can see the differences)
• If you have to experiment to figure out how something works, by all
  means experiment... but do not write documentation based on your
  experiments until you talk to people about them.  Your experiments
  may not have revealed the underlying pattern, or you may have
  misinterpreted the results.
• Similarly, if you think you've discovered an underlying pattern that
  is not discussed in the documentation, ask about it before writing
  documentation.  Maybe it's real, maybe it isn't.

Our discussions have been fun.  Take care.

PS:  I'm on a cruise and will soon be totally out of contact for the
next two to three days, so don't expect a response soon.

On Sun, Aug 10, 2025 at 03:39:42PM +0000, Jordan Brown via Discuss wrote:

Yes. I made a 2D foam cutting machine. I bought a "standard"
3D-printer-mainboard in china, installed octoprint on an orange pi
zero, and wrote the GCODE by hand (all 113 lines). I use the machine
for one specific job, so this is way easier than writing a whole
toolchain. There is one curve in the final product. Two products from
one sheet, so there are two arc commands in my GCODE and that works.

I'm using the marlin firmware that the manufacturer put in the
mainboard, so marlin already supports those arcs.

To get openscad to support curves, I'd personally recommend following
Prof. Jim Blinn's advice to just use 3rd degree splines/beziers
everywhere (one or the other: make a choice. Transform the one that
you're not natively supporting). The approximation of a circle and
sphere are then "very good", and by eye you cannot see that they are
not real circles and spheres.

What I don't remember from his class was: Is the curve you get by
intersecting two 3rd degree spline patches also a 3rd degree spline? I
suspect it is not. So that complicates things: intersecting say a
sphere and a cylinder would require you to match a bunch of new 3rd
degree splines with the 6th degree intersection curve (which is hard
to algorithmically find anyway).

Differencing a cylinder along one of the axes with a sphere of the
same radius is going to give predictable results. But rotate the
cylinder off-axis, and you might get "ugly" results, where if say the
sphere is a tiny bit larger than the cylinder, you get ugly edges
(i.e. not a circle).

For openscad the "small steps" road to this support would start with
generalizing the "triangle" between 3 points to supporting bezier/spline
patches between 4 points.

Postpone the difficult parts: When things get messy you can downgrade
the patch to triangles, e.g. to find the intersection.

If we can then export the curves when they haven't been "downgraded",
slicers can already be provided test-data for processing curves.

Roger.

--
** R.E.Wolff@BitWizard.nl ** https://www.BitWizard.nl/ ** +31-15-2049110 **
** Verl. Spiegelmakerstraat 37 2645 LZ  Delfgauw, The Netherlands.
** KVK: 27239233    **
f equals m times a. When your f is steady, and your m is going down
your a** is going up.  -- Chris Hadfield about flying up the space shuttle.
**  'a' for accelleration.