OpenScad Help Centre

[old man emu]

I have been studying the punctuation in OpenScad and think I've got it under control. I've written up my findings and present them here for your information and critique.

Understanding OpenScad Punctuation
The OpenScad manual goes on for pages and pages giving examples of code which explains the many functions the program can do, however, when someone without a background in programming first looks at some OpenScad coding for an object, or tries to create some, they find that there is no explanation of the punctuation used to get things done. If the punctuation is not correct, nothing works.
Here are the punctuation symbols used by OpenScad, and how their function.

PUNCTUATION SYMBOL	FUNCTION
// /* and */	// is used to insert Coder’s comments into the coding. Anything written on the same line is invisible to the program. If the comment goes into two or more lines, each line must begin with // to continue hiding its content. If the comment goes on for more than three lines, mark the first comment line with /* and end the comment with */
{ and }	Braces hold things in a group. They must be used in pairs with each opening brace { matched with a closing brace }
( and )	Parentheses are used to hold the parameters of an object or operator. The parameter could be the radius of a circle or sphere, or it could be the co-ordinates of a point in space. When used with Boolean operations, the parentheses are left empty.
[ and ]	Square Brackets are used to hold the parameters that describe width and height of squares and also the depth of cubes. When used with Transformations, they hold the x,y and z coordinates associated with the particular operator (Translate, Scale, Mirror etc.) within parentheses.
;	Semi-colons are the symbol that says “Do it!” A semi-colon is placed at the end of the coding that defines the object to be created. If the semi-colon is omitted, nothing is created. The automatic debugging facility in OpenScad will place a marker in the code to indicate where the bug is hiding.

Here is a bit of code that will make the top of a chess bishop. It was copied from here: http://blog.cubehero.com/2013/11/19/...us-in-openscad

Union()
{// teardrop shape
sphere (r=20) ;
translate ([0,0,20*sin(30)])
cylinder (h = 30, r₁ = 20 * cos(30), r₂ = 0) ;
//dollop
translate ([0,0,30 + 20* sin (30)])
sphere (r = 6) ;
}

Here is an explanation of what each line means and what OpenScad does with it:

The Code	The Meaning
union()	I am going to join some things together
{ all the code down to the colon after (r=6)}	This is the group of things I am going to join
// teardrop shape	This is the name I gave to one of the parts of the object I am going to make.
From sphere(r = 20); to r2 = 0	These steps are how I made the teardrop shape
sphere(r = 20)	This made a sphere with a radius of 20 units centred on the Origin (0,0,0)
;	This ended the making of the sphere and let Openscad proceed to the next bit of the shape.
translate([0, 0, 20 * sin(30)])	This told OpenScap to move the centre of the next shape I defined to a point (20 x sin (30) up the Z-axis above the Origin (0,0,0)
cylinder(h = 30, r1 = 20 * cos(30), r2 = 0)	This made a cone 30 units high with its base radius (20 * cos 30) and the top radius a point
;	This ended the making and positioning of the cylinder and let Openscad proceed to the next bit of the shape
// dollop	This is the name of the next part of the thing I am going to make.
From translate to the colon after (r = 6)	These steps are how I made the dollop
translate([0, 0, 30 + 20 * sin(30)])	This told OpenScap to move the centre of the next shape I defined to a point (20 x sin (30) up the Z-axis above the point (0,0,30)
sphere(r = 6)	This made a sphere with a radius of 6 units, centred on the point defined in the Translate command just before it.
;	This ended the making of the dollop and let Openscad proceed to the next bit of the shape.
}	This told OpenScap that I had reached the end of the job of positioning and joining the shapes I made.