is color an actual operator module ?
drat .. the links i pasted into my reply to john are not visible. I repeat them here
glossary https://en.wikibooks.org/wiki/User:VulcanWikiEdit/sandbox/SCADGlossary
updated page i am happy with ( and answers some of the issues John raised)
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Using_the_2D_Subsystem
and a complete rewrite of the page on Operators ( + - * ?: etc) that is still in my sandbox
https://en.wikibooks.org/wiki/User:VulcanWikiEdit/sandbox/Operators_Discussion
rotate(45) cube(10);
as calling cube() to create a cube, and passing the result to rotate() to rotate it.
if we could agree that the term “call a module” to mean: ( using cube(10) as the example)
jump to the chunk of code labeled cube() passing its defined argument list with default values except size=45
execute that code and then return
Sure.
in your example cube() is not in the parameter list of the call to rotate(), so i do not like to say it is “passed” to rotate()
Weeeeellllll…. It kind of is in the parameter list. There are two parameter lists. One is a conventional parameter list. The other is the child list, which in this case has a single entry and so does not need braces, but could have multiple entries surrounded by braces.
I’m happy with saying that cube() probably ends up being called. The questions are what calls it, and when.
The simple mental model says that it’s called by the top level, and the result passed to rotate(). But that’s not correct, or not exactly correct. What’s passed down to rotate() is the list of child statements, rotate() evaluates those statements, and that evaluation leads to cube() being called.
My new understanding of the module’s syntax is that it includes a following child module,
It’s best that when you’re being formal you distinguish between a module instantiation (or perhaps “call” or “invocation”) and a module definition. I believe that you’re referring to a module instantiation here.
thus the definition of a statement’s syntax when a module is being called is (hacking BNF brutally) :
module <name>( <arg>* ) [ | child_module()* | {<statement>* } ];
The keyword “module” indicates a module definition. It is roughly akin to “def” in Python or “function” in JavaScript.
The syntax of the body of a module is very similar to the syntax of a statement. (I think it might be identical, but don’t want to go check the parser right now.).
I think you’re trying to describe a module instantiation, so let’s drop “module”:
<name>( <arg>* ) [ | child_module()* | {<statement>* } ];
I assume that you are using brackets to indicate grouping for the | alternatives, rather than to indicate optionality.
A semicolon is not used after a brace-enclosed list, and the * on child_module() includes the case of zero so you don’t need the empty case.
Also, “<arg>” doesn’t describe argument list syntax correctly, so let’s just push the details down into a separate and not-defined-here level. Net, next draft:
<name>( <args> ) [ child_module() ; | {<statement>* } ]
But that’s not quite right, because the last child module installation can have a brace-enclosed list. I think you could syntactically describe it as
<name>( <args>) child_module()* [ ; | {<statement>* } ]
But that’s not really the best representation, because it does not represent the nesting.
Best is probably a recursive definition, something like:
module_instantiation:
<name>(<args>);
| <name>(<args>) <module_instantiation>
| <name>(<args>) { <statement>* }
But for the formally correct definition, refer to the parser, src/core/parser.y.
The subject is still "is color an actual operator???"
I'm losing focus on this thread :)
Jordan Brown via Discuss schreef op 2025-08-06 13:02:
rotate(45) cube(10);
as calling cube() to create a cube, and passing the result to rotate()
to rotate it.
if we could agree that the term "call a module" to mean: ( using
cube(10) as the example)
jump to the chunk of code labeled cube() passing its defined argument
list with default values except size=45
execute that code and then return
Sure.
in your example cube() is not in the parameter list of the call to
rotate(), so i do not like to say it is "passed" to rotate()
Weeeeellllll.... It kind of is in the parameter list. There are
two parameter lists. One is a conventional parameter list. The other
is the child list, which in this case has a single entry and so does not
need braces, but could have multiple entries surrounded by braces.
I'm happy with saying that cube() probably ends up being called. The
questions are what calls it, and when.
The simple mental model says that it's called by the top level, and the
result passed to rotate(). But that's not correct, or not exactly
correct. What's passed down to rotate() is the list of child statements,
rotate() evaluates those statements, and that evaluation leads to cube()
being called.
My new understanding of the module's syntax is that it includes a
following child module,
It's best that when you're being formal you distinguish between a
module instantiation (or perhaps "call" or "invocation") and a module
definition. I believe that you're referring to a module instantiation
here.
thus the definition of a statement's syntax when a module is being
called is (hacking BNF brutally) :
module <name>( <arg>* ) [ | child_module()* | {<statement>* } ];
The keyword "module" indicates a module definition. It is roughly
akin to "def" in Python or "function" in JavaScript.
The syntax of the body of a module is very similar to the syntax of a
statement. (I think it might be identical, but don't want to go check
the parser right now.).
I think you're trying to describe a module instantiation, so let's drop
"module":
<name>( <arg>* ) [ | child_module()* | {<statement>* } ];
I assume that you are using brackets to indicate grouping for the |
alternatives, rather than to indicate optionality.
A semicolon is not used after a brace-enclosed list, and the * on
child_module() includes the case of zero so you don't need the empty
case.
Also, "<arg>*" doesn't describe argument list syntax correctly, so let's
just push the details down into a separate and not-defined-here level.
Net, next draft:
<name>( <args> ) [ child_module()* ; | {<statement>* } ]
But that's not quite right, because the last child module installation
can have a brace-enclosed list. I think you could syntactically
describe it as
<name>( <args>) child_module()* [ ; | {<statement>* } ]
But that's not really the best representation, because it does not
represent the nesting.
Best is probably a recursive definition, something like:
module_instantiation:
<name>(<args>);
| <name>(<args>) <module_instantiation>
| <name>(<args>) { <statement>* }
But for the formally correct definition, refer to the parser,
src/core/parser.y.
OpenSCAD mailing list
To unsubscribe send an email to discuss-leave@lists.openscad.org
colour is simply a module. In fact I think all named items that are allowed
in a statement are modules. There is no such thing as operator modules.
They are just modules.
On Wed, 6 Aug 2025, 12:09 Matthieu Hendriks via Discuss, <
discuss@lists.openscad.org> wrote:
The subject is still "is color an actual operator???"
I'm losing focus on this thread :)
Jordan Brown via Discuss schreef op 2025-08-06 13:02:
rotate(45) cube(10);
as calling cube() to create a cube, and passing the result to rotate() to
rotate it.
if we could agree that the term "call a module" to mean: ( using cube(10)
as the example)
jump to the chunk of code labeled cube() passing its defined argument list
with default values except size=45
execute that code and then return
Sure.
in your example cube() is not in the parameter list of the call to
rotate(), so i do not like to say it is "passed" to rotate()
Weeeeellllll.... It kind of is in the parameter list. There are two
parameter lists. One is a conventional parameter list. The other is the
child list, which in this case has a single entry and so does not need
braces, but could have multiple entries surrounded by braces.
I'm happy with saying that cube() probably ends up being called. The
questions are what calls it, and when.
The simple mental model says that it's called by the top level, and the
result passed to rotate(). But that's not correct, or not exactly correct.
What's passed down to rotate() is the list of child statements, rotate()
evaluates those statements, and that evaluation leads to cube() being
called.
My new understanding of the module's syntax is that it includes a
following child module,
It's best that when you're being formal you distinguish between a module
instantiation (or perhaps "call" or "invocation") and a module definition.
I believe that you're referring to a module instantiation here.
thus the definition of a statement's syntax when a module is being called
is (hacking BNF brutally) :
module <name>( <arg>* ) [ | child_module()* | {<statement>* } ];
The keyword "module" indicates a module definition. It is roughly akin
to "def" in Python or "function" in JavaScript.
The syntax of the body of a module is very similar to the syntax of a
statement. (I think it might be identical, but don't want to go check the
parser right now.).
I think you're trying to describe a module instantiation, so let's drop
"module":
<name>( <arg>* ) [ | child_module()* | {<statement>* } ];
I assume that you are using brackets to indicate grouping for the |
alternatives, rather than to indicate optionality.
A semicolon is not used after a brace-enclosed list, and the * on
child_module() includes the case of zero so you don't need the empty case.
Also, "<arg>*" doesn't describe argument list syntax correctly, so let's
just push the details down into a separate and not-defined-here level.
Net, next draft:
<name>( <args> ) [ child_module()* ; | {<statement>* } ]
But that's not quite right, because the last child module installation can
have a brace-enclosed list. I think you could syntactically describe it as
<name>( <args>) child_module()* [ ; | {<statement>* } ]
But that's not really the best representation, because it does not
represent the nesting.
Best is probably a recursive definition, something like:
module_instantiation:
<name>(<args>);
| <name>(<args>) <module_instantiation>
| <name>(<args>) { <statement>* }
But for the formally correct definition, refer to the parser,
src/core/parser.y.
OpenSCAD mailing list
To unsubscribe send an email to discuss-leave@lists.openscad.org
OpenSCAD mailing list
To unsubscribe send an email to discuss-leave@lists.openscad.org
umm .. then how better to understand it? the docs and tutorials did
not do enough so i started to experiment to see how things worked. I
have dozens of test and example code snippets to back up what i write
about how scad works ..
Yes, you should experiment, but that only tells you about the behavior
of the current implementation, not the API contract. You have to think
about what is the truly important thing, and ignore everything that are
not crucial. If you include things that are not crucial, this is
overspecification. The real specification probably only exists in the
devs' mind, if that exists, so deciding what to include requires a bit
of personal judgement and requires thinking like the devs. Here are some
examples (note that these are just my opinion, I am not the core dev and
I don't have the final say over the spec):
- In the 2D subsystem page, "Although they are infinitely thin, they
are rendered with a 1-unit thickness.". This is an example where the
documentation overspecifies (and this is preview, not the F6
render). Why? Because this doesn't really affect anything. This
thickness choice is arbitrary. The reason it has thickness is
probably due to how preview rendering works. Note that I am not
opposed to mentioning this in the reference manual, but I am
opposing to mentioning it two more times when talking about square
and circle. (I think it is there for a long time, I'm just looking
for random examples from the wiki) - Your confusion over how render works is an example of what I meant
by overfit. The API contract is simple: The output of the render
module is a mesh. Trying to understand why the implementation
chooses quad over triangles in some cases but not the other is
futile because it is complex and can be changed later. Writing it
down in documentation will confuse people and make future updates
harder (people will complain it is a breaking change).
To quote Jordan's comment: "OpenSCAD makes no particular promises
about the details of its rendering. It does not promise that
everything will be reduced to triangles, and it does not promise
that it won’t, and whether or not a particular case is reduced to
triangles can depend on subtle factors. It would be entirely with
the specification (such as it is) for it to randomly do one or the
other. (We don’t like that answer for testability reasons, but it
would be legal.)". - The starting point of the circle module is an important detail in
the API documentation, because it can be used to draw regular polygons.
I am in the process of fixing these terminology issues .. in a
previous post i published the glossary i am now working with
https://en.wikibooks.org/wiki/User:VulcanWikiEdit/sandbox/SCADGlossary
It is good that you are fixing this. My recommendation is to avoid terms
with similar meaning unless you have a really, really convincing reason
to use both of them frequently and you can clearly show the difference
between them. "Shape" and "geometry" doesn't pass this test for me, at
least I have no idea why you want to have them both. For "drawn", do you
want to use it only when describing GUI or use it in the language
reference manual? I don't think you need this word. And I really want to
get rid of the term "action". Why is "statement" not good enough?
if you take a look at the new pages i am happiest with you will see
that i am trying to answer the questions you raised. I too found the old
docs imprecise and in a few places contradictory
I have quite a few comments about style. IMO a reference manual is not
for beginners, and it should be written in a way that helps people
scanning and finding what they need, i.e. consistent style and concise.
First, people reading the reference manual probably don't care much
about the default behavior, so things like "By default this module draws
a unit circle centered on the origin [0,0] as a pentagon with its
starting point on the X-axis at X=1. Its lines have no thickness but the
shape is drawn as a 1 unit high, filled plane." should not be put at the
top of the documentation for the circle module. The first description
should be about the general behavior, written in a concise manner. The
old one "Creates a circle at the origin." is good enough for me, or
maybe you can say "Creates a regular polygon that approximates a circle
at the origin".
Second, the way you document the parameters is hard to understand. Again
for the circle module example, I wouldn't understand its signature if I
had no experience with openscad. The old documentation is not great
either in this case. I would rather want something like
circle(radius)
circle(r=radius)
circle(d=diameter)
radius: circle radius
diameter: circle diameter
And you talk about $fa, $fs, $fn at the end about quality of the
approximation and where the first point is placed, not as parameters.
You only give examples at the end, not interleave examples like the old
circle module documentation.
Third, we should have a more uniform way of writing
deprecated/experimental things. Instead of natural language like "Object
data structures have been introduced to the language recently. [Note:
Requires version 2025.07.11].", a simple highlight with "Since
2025.07.11:" or "Development snapshot only:" will be good. We should
probably put this in the section heading or at the top of the section if
that section is about something new (or deprecated..).
Fourth, we should have things like a grammar for expression and
statements, instead of natural language description such as "A vector or
list is a sequence of zero or more OpenSCAD values. Vectors are
collections of numeric or boolean values, variables, vectors, strings or
any combination thereof. They can also be expressions that evaluate to
one of these. Vectors handle the role of arrays found in many imperative
languages. The information here also applies to lists and tables that
use vectors for their data. A vector has square brackets, [] enclosing
zero or more items (elements or members), separated by commas. A vector
can contain vectors, which can contain vectors, etc.". This should be
left in the example. Note that the current documentation is also
imprecise: Vector (as a value) elements cannot be unevaluated
expressions, they must be values. You can have expressions in the
constructor of a vector, i.e., the square bracket form. And for things
like matrix, we should at least say whether it is column- or row-major,
i.e., whether the inner vector is a row or a column. This is never
described explicitly in the documentation.
These are what I meant by "too verbose and not detailed enough". I hope
I made my points clear. I will try to write something when I have time
as an example of the style that I want in the reference manual, but I am
running out of time now.
Best,
John
pca006132 wrote:
yeah .. i am still a bit shaky on rendering .. but i am getting there
- Your confusion over how render works is an example of what I meant
by overfit. The API contract is simple: The output of the render
module is a mesh. Trying to understand why the implementation
chooses quad over triangles in some cases but not the other is
futile because it is complex and can be changed later. Writing it
down in documentation will confuse people and make future updates
harder (people will complain it is a breaking change).
i get all that .. i have been using docs updates as a way to clarify my thoughts on rendering ..
it is working slowly .. there will be a few more revisions to the rendering page till it is right.
- The starting point of the circle module is an important detail in
the API documentation, because it can be used to draw regular polygons.
. "Shape" and "geometry" doesn't pass this test for me, at
least I have no idea why you want to have them both.
this is my new glossary : https://en.wikibooks.org/wiki/User:VulcanWikiEdit/sandbox/SCADGlossary
For "drawn", do you
want to use it only when describing GUI
I need a word for everywhere that a module .. does whatever it is that results in a mesh being created.
Jordan tells me the word in use in the community is “render” .. that is a problem for me as my
background in 3D modelling and animation that word was only used for when images were being
generated from a mesh or model.
i settled on “draw” to mean “make or add to a mesh being created by an scad script running”
I don't think you need this word. And I really want to
get rid of the term "action".
action is waaayy too general a word for “doing something”
Why is "statement" not good enough?
“statement“ has a particular lexical and syntactic meaning in the context of coding
in a programming language .. i use in the way i describe in
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/General#Program_Structure
First, people reading the reference manual probably don't care much
about the default behavior, so things like "By default this module draws
a unit circle centered on the origin [0,0]
i have to disagree with you on this. IMHO a clear, complete, and accurate statement
of a built-in function or modules default behavior is a good starting point for a
newcomer to OpenSCAD.
I start with that because when i was just starting out with it was a nice confirmation
of what i was seeing in my experiments .. and from there i write about the parameters
in a concise list .. and then for the params that have some complexity i add additional
sections to cover that .. complexity
The first description
should be about the general behavior, written in a concise manner. The
old one "Creates a circle at the origin." is good enough for me, or
maybe you can say "Creates a regular polygon that approximates a circle
at the origin".
But that .. is too cringe for me. Circle creates a circle .. not a polygon .. it is drawn
as a polygon, but that is an approximation of its shape. The polygon’s size
is determined by it being inscribed inside the circle of the given diameter.
Second, the way you document the parameters is hard to understand.
i agree .. i have experimented with a few templates for param lists .. no final
answer yet … but my current favorite is in the docs for linear_extrude()
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/3D_Modelling#linear_extrude()_Operator_Module
You only give examples at the end, not interleave examples like the old
circle module documentation.
actually i strongly prefer to interleave examples .. the places you are seeing them
bunched up at the end of a section or page are mostly legacy pages that are still
in progress in being reafactored
Third, we should have a more uniform way of writing
deprecated/experimental things.
to this end i have created templates specific to our needs .. see them on
my sandbox page
https://en.wikibooks.org/wiki/User:VulcanWikiEdit/sandbox#templates
Fourth, we should have things like a grammar for expression and
statements,
well this would be a can of worms to open.
I prefer natural language expressions and descriptions over symbolic
syntax specs like BNF .. as long as the wording is clear and concise i feel
words are better.
But i am willing to hear a discussion on this point .. it is an important one.
I do make the warning that in my working career the ONLY time that a
team could agree on a standard for documentation was when i was in the
position of being able to unilaterally dictating it.
These are what I meant by "too verbose and not detailed enough". I hope
I made my points clear.
I would say so John, and thanks again for the feedback
Best,
John
Guten Abend
Jeff
speaking only of the built-in modules .. the modules that draw shapes .. circle, sphere etc. only create shapes in the model and cannot do anything with child modules that follow them in a statement .. if there are any
I have been calling these Object Modules, copying that terminology from one or two places in the docs, but now we have actual objects so my attempt to build a consensus crashes and burns :)
and .. built-ins for modifying or moving those objects .. translate, color etc .. these are modules that ONLY operate on their children, can’t draw shapes and are not useful if they end a statement.
There was as place in the docs that referred to these as operating on the other type of module .. thus object modules and operator modules became a “thing” for me and i wrote them up that way .. it seemed a useful distinction .. for the built-in modules.
Not so much for user-defined modules .. folks have been telling me about the cool and complicated things being done in BOSL2 and NopSCADlib .. modules that both draw shapes and do operations on their children.
if we can come up with a better terminology i am all ears
thanks for your input Noppy
I just read this:
I need a word for everywhere that a module .. does whatever it is that
results in a mesh being created.
Jordan tells me the word in use in the community is “render” .. that is
a problem for me as my
background in 3D modelling and animation that word was only used for
when images were being
generated /from/ a mesh or model.
i settled on “draw” to mean “make or add to a mesh being created by an
scad script running”
I can't speak for anyone else, but I thought that the documentation was
OK (not great, but OK), and now we're entertaining changing how
everything is described, because we are not using the same terms as
elsewhere on the web. This is not a compelling argument, at least to me.
I wish that, before ANY of these changes were even CONTEMPLATED, the
community (not someone inexperienced with OpenSCAD) came up with a list
of issues that needed to be resolved, and then we resolved them. I do
not believe that a wholesale change to the documentation was required or
desired. Pieces? Sure. Dealing with the new term "object"? Sure.
I, for one, find what Vulcan is doing to be terrifying. And I do not
have the patience to read all of the new documentation, over and over
again, trying to figure out what else has been broken.
I don't doubt that Vulcan's intentions are good, but I wonder if there
really is a problem that needs solving. I also wonder whether the
community would be better off with an experienced OpenSCAD programmer
making the changes.
I understand that the documentation should be accessible to an OpenSCAD
newbie, but I am not sure that these changes will produce the best product.
If I'm way off base, I apologize.
Jon
On 8/6/2025 5:37 PM, vulcan_--- via Discuss wrote:
pca006132 wrote:
yeah .. i am still a bit shaky on rendering .. but i am getting there
*
Your confusion over how render works is an example of what I
meant by overfit. The API contract is simple: The output of
the render module is a mesh. Trying to understand why the
implementation chooses quad over triangles in some cases but
not the other is futile because it is complex and can be
changed later. Writing it down in documentation will confuse
people and make future updates harder (people will complain it
is a breaking change).
i get all that .. i have been using docs updates as a way to clarify
my thoughts on rendering ..
it is working slowly .. there will be a few more revisions to the
rendering page till it is right.
*
The starting point of the circle module is an important detail
in the API documentation, because it can be used to draw
regular polygons.
. "Shape" and "geometry" doesn't pass this test for me, at least I
have no idea why you want to have them both.
this is my new glossary :
https://en.wikibooks.org/wiki/User:VulcanWikiEdit/sandbox/SCADGlossary
For "drawn", do you want to use it only when describing GUI
I need a word for everywhere that a module .. does whatever it is that
results in a mesh being created.
Jordan tells me the word in use in the community is “render” .. that
is a problem for me as my
background in 3D modelling and animation that word was only used for
when images were being
generated /from/ a mesh or model.
i settled on “draw” to mean “make or add to a mesh being created by an
scad script running”
I don't think you need this word. And I really want to get rid of
the term "action".
action is waaayy too general a word for “doing something”
Why is "statement" not good enough?
“statement“ has a particular lexical and syntactic meaning in the
context of coding
in a programming language .. i use in the way i describe in
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/General#Program_Structure
First, people reading the reference manual probably don't care
much about the default behavior, so things like "By default this
module draws a unit circle centered on the origin [0,0]
i have to disagree with you on this. IMHO a clear, complete, and
accurate statement
of a built-in function or modules default behavior is a good starting
point for a
newcomer to OpenSCAD.
I start with that because when i was just starting out with it was a
nice confirmation
of what i was seeing in my experiments .. and from there i write about
the parameters
in a concise list .. and then for the params that have some complexity
i add additional
sections to cover that .. complexity
The first description should be about the general behavior,
written in a concise manner. The old one "Creates a circle at the
origin." is good enough for me, or maybe you can say "Creates a
regular polygon that approximates a circle at the origin".
But that .. is too cringe for me. Circle creates a circle .. not a
polygon .. it is drawn
as a polygon, but that is an approximation of its /shape/. The
polygon’s size
is determined by it being inscribed inside the circle of the given
diameter.
Second, the way you document the parameters is hard to understand.
i agree .. i have experimented with a few templates for param lists ..
no final
answer yet … but my current favorite is in the docs for linear_extrude()
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/3D_Modelling#linear_extrude()_Operator_Module
You only give examples at the end, not interleave examples like
the old circle module documentation.
actually i strongly prefer to interleave examples .. the places you
are seeing them
bunched up at the end of a section or page are mostly legacy pages
that are still
in progress in being reafactored
Third, we should have a more uniform way of writing
deprecated/experimental things.
to this end i have created templates specific to our needs .. see them on
my sandbox page
https://en.wikibooks.org/wiki/User:VulcanWikiEdit/sandbox#templates
Fourth, we should have things like a grammar for expression and
statements,
well this would be a can of worms to open.
I prefer natural language expressions and descriptions over symbolic
syntax specs like BNF .. as long as the wording is clear and concise i
feel
words are better.
But i am willing to hear a discussion on this point .. it is an
important one.
I do make the warning that in my working career the ONLY time that a
team could agree on a standard for documentation was when i was in the
position of being able to unilaterally dictating it.
These are what I meant by "too verbose and not detailed enough". I
hope I made my points clear.
I would say so John, and thanks again for the feedback
Best, John
Guten Abend
Jeff
OpenSCAD mailing list
To unsubscribe send an email todiscuss-leave@lists.openscad.org
--
This email has been checked for viruses by AVG antivirus software.
www.avg.com
vulcan_ wrote:
But that .. is too cringe for me. Circle creates a circle .. not a polygon
.. it is drawn
as a polygon, but that is an approximation of its shape. The polygon’s size
is determined by it being inscribed inside the circle of the given diameter.
It NEVER makes a circle. It isn't just drawn as a polygon. It makes a
polygon with the number of sides determined by the value of special
variables such as $fn or $fs and $fa.
On Wed, Aug 6, 2025 at 4:37 PM vulcan_--- via Discuss <
discuss@lists.openscad.org> wrote:
pca006132 wrote:
yeah .. i am still a bit shaky on rendering .. but i am getting there
-
Your confusion over how render works is an example of what I meant by
overfit. The API contract is simple: The output of the render module is a
mesh. Trying to understand why the implementation chooses quad over
triangles in some cases but not the other is futile because it is complex
and can be changed later. Writing it down in documentation will confuse
people and make future updates harder (people will complain it is a
breaking change).
i get all that .. i have been using docs updates as a way to clarify my
thoughts on rendering ..
it is working slowly .. there will be a few more revisions to the
rendering page till it is right.
-
The starting point of the circle module is an important detail in the
API documentation, because it can be used to draw regular polygons.
. "Shape" and "geometry" doesn't pass this test for me, at least I have no
idea why you want to have them both.
this is my new glossary :
https://en.wikibooks.org/wiki/User:VulcanWikiEdit/sandbox/SCADGlossary
For "drawn", do you want to use it only when describing GUI
I need a word for everywhere that a module .. does whatever it is that
results in a mesh being created.
Jordan tells me the word in use in the community is “render” .. that is a
problem for me as my
background in 3D modelling and animation that word was only used for when
images were being
generated from a mesh or model.
i settled on “draw” to mean “make or add to a mesh being created by an
scad script running”
I don't think you need this word. And I really want to get rid of the term
"action".
action is waaayy too general a word for “doing something”
Why is "statement" not good enough?
“statement“ has a particular lexical and syntactic meaning in the context
of coding
in a programming language .. i use in the way i describe in
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/General#Program_Structure
First, people reading the reference manual probably don't care much about
the default behavior, so things like "By default this module draws a unit
circle centered on the origin [0,0]
i have to disagree with you on this. IMHO a clear, complete, and accurate
statement
of a built-in function or modules default behavior is a good starting
point for a
newcomer to OpenSCAD.
I start with that because when i was just starting out with it was a nice
confirmation
of what i was seeing in my experiments .. and from there i write about the
parameters
in a concise list .. and then for the params that have some complexity i
add additional
sections to cover that .. complexity
The first description should be about the general behavior, written in a
concise manner. The old one "Creates a circle at the origin." is good
enough for me, or maybe you can say "Creates a regular polygon that
approximates a circle at the origin".
But that .. is too cringe for me. Circle creates a circle .. not a polygon
.. it is drawn
as a polygon, but that is an approximation of its shape. The polygon’s
size
is determined by it being inscribed inside the circle of the given
diameter.
Second, the way you document the parameters is hard to understand.
i agree .. i have experimented with a few templates for param lists .. no
final
answer yet … but my current favorite is in the docs for linear_extrude()
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/3D_Modelling#linear_extrude()_Operator_Module
You only give examples at the end, not interleave examples like the old
circle module documentation.
actually i strongly prefer to interleave examples .. the places you are
seeing them
bunched up at the end of a section or page are mostly legacy pages that
are still
in progress in being reafactored
Third, we should have a more uniform way of writing
deprecated/experimental things.
to this end i have created templates specific to our needs .. see them on
my sandbox page
https://en.wikibooks.org/wiki/User:VulcanWikiEdit/sandbox#templates
Fourth, we should have things like a grammar for expression and
statements,
well this would be a can of worms to open.
I prefer natural language expressions and descriptions over symbolic
syntax specs like BNF .. as long as the wording is clear and concise i feel
words are better.
But i am willing to hear a discussion on this point .. it is an important
one.
I do make the warning that in my working career the ONLY time that a
team could agree on a standard for documentation was when i was in the
position of being able to unilaterally dictating it.
These are what I meant by "too verbose and not detailed enough". I hope I
made my points clear.
I would say so John, and thanks again for the feedback
Best, John
Guten Abend
Jeff
OpenSCAD mailing list
To unsubscribe send an email to discuss-leave@lists.openscad.org
. "Shape" and "geometry" doesn't pass this test for me, at least I have no
idea why you want to have them both.
this is my new glossary :
https://en.wikibooks.org/wiki/User:VulcanWikiEdit/sandbox/SCADGlossary
This doesn't answer my question. When would you mention the word "geometry"?
For "drawn", do you want to use it only when describing GUI
I need a word for everywhere that a module .. does whatever it is that
results in a mesh being created.
circle() "creates" a regular polygon that approximates a circle. Isn't that
good enough? Why draw? Btw, we never add to a mesh, we only create new
meshes.
Why is "statement" not good enough?
“statement“ has a particular lexical and syntactic meaning in the context
of coding
in a programming language .. i use in the way i describe in
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/General#Program_Structure
Well, I still don't get why "statement" is not good enough and the word
"action" is needed. I know programming languages well, I am doing a PhD
with it, and we define what a statement means all the time.
The first code block about <perform named action>; just confuse me further.
This is not a grammar description, nor an example, and it doesn't tell me
anything. The description about "invokes one or more modules to instantiate
a shape
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/General#Constructing_Solid_Geometry
that appears in the preview panel
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/The_OpenSCAD_User_Interface"
is just wrong because we can do it without the GUI. Similarly in the second
code block <Named variable> = <expression>; is also confusing: does that
imply we have unnamed variables?
The sentence "Normally a statement does just one thing, and for assignment
expressions that is enough." is also confusing: Statements doing only one
thing is just a special form, why bother? And assignment is a statement,
not an expression.
I don't want to continue on-and-on, there are too many issues that I can
point out here. I would suggest you to just start with a BNF form and
describe each construct, don't interleave them and try to write a good
prose.
First, people reading the reference manual probably don't care much about
the default behavior, so things like "By default this module draws a unit
circle centered on the origin [0,0]
i have to disagree with you on this. IMHO a clear, complete, and accurate
statement
of a built-in function or modules default behavior is a good starting
point for a
newcomer to OpenSCAD.
I start with that because when i was just starting out with it was a nice
confirmation
of what i was seeing in my experiments .. and from there i write about the
parameters
in a concise list .. and then for the params that have some complexity i
add additional
sections to cover that .. complexity
https://diataxis.fr/reference/ is, in my opinion, a good resource about
writing technical documentation. It says that "Reference material describes
the machinery. It should be austere. One hardly reads reference
material; one consults it.".
And I should probably clarify, by experts I mean people mature enough to
read the docs. A reference manual written in a clear, concise, predictable
style can only help people understand things.
The first description should be about the general behavior, written in a
concise manner. The old one "Creates a circle at the origin." is good
enough for me, or maybe you can say "Creates a regular polygon that
approximates a circle at the origin".
But that .. is too cringe for me. Circle creates a circle .. not a polygon
.. it is drawn
as a polygon, but that is an approximation of its shape. The polygon’s
size
is determined by it being inscribed inside the circle of the given
diameter.
Who cares if the reference manual is stating the obvious? You come to the
reference manual to find things you care, not to read a prose, and
typically not to look for the simple default behaviour. Also, the
description being obvious is a good thing, not a bad thing.
You only give examples at the end, not interleave examples like the old
circle module documentation.
actually i strongly prefer to interleave examples .. the places you are
seeing them
bunched up at the end of a section or page are mostly legacy pages that
are still
in progress in being reafactored
As mentioned above, one consults the reference manual. If you interleave
examples with description of the API, it makes it long, and people will
need more time to find the thing they need.
Third, we should have a more uniform way of writing
deprecated/experimental things.
to this end i have created templates specific to our needs .. see them on
my sandbox page
https://en.wikibooks.org/wiki/User:VulcanWikiEdit/sandbox#templates
Fourth, we should have things like a grammar for expression and
statements,
well this would be a can of worms to open.
I prefer natural language expressions and descriptions over symbolic
syntax specs like BNF .. as long as the wording is clear and concise i feel
words are better.
But i am willing to hear a discussion on this point .. it is an important
one.
I do make the warning that in my working career the ONLY time that a
team could agree on a standard for documentation was when i was in the
position of being able to unilaterally dictating it.
I am not saying we should not have natural language description. Again, it
is from a point of a quick search over the reference manual. If you have
the expertise in reading things like BNF, BNF is just the most concise way
to convey the information. You can supplement it with natural language
later. And as mentioned above, the current way is absolutely not clear, at
least to me.
Best,
John