Improving the doc
There... I'm starting to put my words where my mouth is... ehh something like
that.
I've extensively edited a small (manageable) section of the doc:
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/The_OpenSCAD_Language#Relational_Operators
Next I may tackle the more tricky Matrix Multiplication.
Suggestion and criticism welcome.
--
View this message in context: http://forum.openscad.org/Improving-the-doc-tp14333.html
Sent from the OpenSCAD mailing list archive at Nabble.com.
(I'm re-posting my posts yesterday due to a tech issue, apologies if I'm
annoying...)
As I threatened to do, I've completely re-written Matrix Multiplication:
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/The_OpenSCAD_Language#Matrix_Multiplication
I am warning you, I will keep doing it unless someone stops me.
Continuing my rampage...
I've created an alternate version of the Section 1.1 General:
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/General_(by_c.t.chin)
While it still can use some work and refinement, I propose to replace the
entirety of General with it:
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/The_OpenSCAD_Language#General
You may notice I've written in my (perhaps very) radical idea of trimming
down all the statements,
etc etc down to just FOUR types: objects, variable assignments, preprocessor
commands, and
function and module definitions.
I've decide that primitives and transformations are just modules.
Primitives require no children, and a transformation, on its own, generates
no objects. But they are both modules. cube() can be given children (which
are ignored) and rotate() can be given no child (which produces nothing).
So in the doc for programming language, "objects" is perfectly sufficient
to cover modules, primitives and transformations.
I've also cut out a lot of materials, e.g. select() (it's not part of the
language!), Getting Input (belongs much later in the doc), and other bits
(e.g. legacy issues) that adds unnecessary burden to someone who's learning
the language (target reader of this section). The materials that I cut out
has been saved on separate files on my own PC so I'll find appropriate spots
to put back into the wiki.
Since it's a radical re-write, I am only proposing this version for
consideration by the community.
If the response is hot, I will continue work on it and eventually overwrite
the existing Wiki page(s).
If the response is warm, I will continue work on it but not edit the
existing Wiki until the response improves (or I quit).
If the response is cold, I will abandon it and get back to spending my time
on "more important things".
I'm getting madder by the minute.
L Boyd wrote
The existing manual consists of many files, each of which describe a small
portion of the total picture. There is a list ( 3 actually ) of these
files, which allow a user to access these various portions.
Where are these three lists you talked about? If you mean these three:
http://www.openscad.org/documentation.html#user-manual
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual#Overview
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Print_version
Then yikes each is unsatisfactory. For example, the following article is
pretty important in a comprehensive documentation:
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/undersized_circular_objects
Also this is a gem that I just discovered today:
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/For_C/Java/Python_Programmers
Both seem to be missing in any kind of complete doc, but can be found only
by linking:
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Primitive_Solids#cylinder
The For C/Java/Python Programmers page wasn't even linked to by any page
until today.
Is there even a comprehensive list of all the articles/pages on the Wiki? I
suspect some more
gems have been written up by the good folks but still hidden due to
obscurity.
--
View this message in context: http://forum.openscad.org/Improving-the-doc-tp14333p14388.html
Sent from the OpenSCAD mailing list archive at Nabble.com.
I like what you did with Matrix Multiplication.
I'll read your rewritten General section later, when I have a big enough
block of time to compare both versions.
On 11 November 2015 at 23:21, ctchin c.t.chin@szu.edu.cn wrote:
(I'm re-posting my posts yesterday due to a tech issue, apologies if I'm
annoying...)
As I threatened to do, I've completely re-written Matrix Multiplication:
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/The_OpenSCAD_Language#Matrix_Multiplication
I am warning you, I will keep doing it unless someone stops me.
Continuing my rampage...
I've created an alternate version of the Section 1.1 General:
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/General_(by_c.t.chin)
While it still can use some work and refinement, I propose to replace the
entirety of General with it:
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/The_OpenSCAD_Language#General
You may notice I've written in my (perhaps very) radical idea of trimming
down all the statements,
etc etc down to just FOUR types: objects, variable assignments,
preprocessor
commands, and
function and module definitions.
I've decide that primitives and transformations are just modules.
Primitives require no children, and a transformation, on its own, generates
no objects. But they are both modules. cube() can be given children
(which
are ignored) and rotate() can be given no child (which produces nothing).
So in the doc for programming language, "objects" is perfectly sufficient
to cover modules, primitives and transformations.
I've also cut out a lot of materials, e.g. select() (it's not part of the
language!), Getting Input (belongs much later in the doc), and other bits
(e.g. legacy issues) that adds unnecessary burden to someone who's learning
the language (target reader of this section). The materials that I cut out
has been saved on separate files on my own PC so I'll find appropriate
spots
to put back into the wiki.
Since it's a radical re-write, I am only proposing this version for
consideration by the community.
If the response is hot, I will continue work on it and eventually overwrite
the existing Wiki page(s).
If the response is warm, I will continue work on it but not edit the
existing Wiki until the response improves (or I quit).
If the response is cold, I will abandon it and get back to spending my time
on "more important things".
I'm getting madder by the minute.
L Boyd wrote
The existing manual consists of many files, each of which describe a
small
portion of the total picture. There is a list ( 3 actually ) of these
files, which allow a user to access these various portions.
Where are these three lists you talked about? If you mean these three:
http://www.openscad.org/documentation.html#user-manual
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual#Overview
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Print_version
Then yikes each is unsatisfactory. For example, the following article is
pretty important in a comprehensive documentation:
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/undersized_circular_objects
Also this is a gem that I just discovered today:
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/For_C/Java/Python_Programmers
Both seem to be missing in any kind of complete doc, but can be found only
by linking:
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Primitive_Solids#cylinder
The For C/Java/Python Programmers page wasn't even linked to by any page
until today.
Is there even a comprehensive list of all the articles/pages on the Wiki?
I
suspect some more
gems have been written up by the good folks but still hidden due to
obscurity.
--
View this message in context:
http://forum.openscad.org/Improving-the-doc-tp14333p14388.html
Sent from the OpenSCAD mailing list archive at Nabble.com.
OpenSCAD mailing list
Discuss@lists.openscad.org
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
Thanks for the positive feedback(s). I am pushing on with the assumption
that someone knowledgeable is keeping at least half an eye open.
Getting bolder, I have actually change an example code:
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/The_OpenSCAD_Language#rotate
The old code was updated to exploit the (not even that recently) added
functions norm() and atan2().
--
View this message in context: http://forum.openscad.org/Improving-the-doc-tp14333p14613.html
Sent from the OpenSCAD mailing list archive at Nabble.com.
Keep it up!
The 3 places with manual order I was talking about are:
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual#Overview
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/The_OpenSCAD_Language
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Print_version
I completely reworked all of them to agree and made a virtual separation
into two books.
Larry
View this message in context: http://forum.openscad.org/Improving-the-doc-tp14333p14629.html
Sent from the OpenSCAD mailing list archive at Nabble.com.
Going back over your posts, I would like to read your proposed general
section but your link does not get me there.
Larry
View this message in context: http://forum.openscad.org/Improving-the-doc-tp14333p14632.html
Sent from the OpenSCAD mailing list archive at Nabble.com.
The link I put in my post is still good. But the forum parsed it incorrectly
so when you simple click on the link the URL is missing the last closing
bracket. Here this one should work:
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/General_%28by_c.t.chin%29
You are all also invited to scrutinize my draft substitute for the main part
of the doc:
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/The_OpenSCAD_Language/Fast_Guide%28c.t.chin%29
(hmm this time wonder how will the forum treat the URL, just verify you
browser is using a sensible URL with a closing bracket)
The "Fast Guide" is very incomplete, as I work on it on and off, it's
turning into a complete reference. So it will have to be renamed for sure.
A fast guide will still be forthcoming, but perhaps it makes more sense to
rework the complete reference before starting a proper fast guide.
So the (currently) misnamed complete reference is supposed to (1) cover the
language comprehensively, (2) TIGHT in terms of jargon, e.g. in the old
doc, operator sometimes means "+" and "==", and other times means "rotate()"
and "union()", no more, every jargon should have only one clear meaning and
consistent usage, (3) eliminate un-necessary or un-helpful categorization
and anything "special" or "other", if it's in the language it's in the doc,
there's no 2d subsystem, there's no Other language features. text() is
a 2D primitive, import() is a 3D primitive; union() and rotate_extrude() and
rotate() and project() are all transformations, not in 3 or 4 different
chapters.
Basically the old doc tries to teach a topic at a time, but there's not
enough holistic planning and then some smaller topics are left behind and
they get shoved into a "Other features" or a single primitive text() gets
its own chapter. Let's first create a comprehensive reference, organized
not by topics, but by linguistic logic. Then someone could create a
topic-by-topic fast guide/deep tutorial by just collecting links from the
ref. Add some hand-holding explanation as needed.
--
View this message in context: http://forum.openscad.org/Improving-the-doc-tp14333p14640.html
Sent from the OpenSCAD mailing list archive at Nabble.com.
Just to pass along what I learned about the physical organization. WikiBooks
expects each chapter to be all of one or more files.
When one visits the printable version pages they load everything so that it
looks like one page to the printer.
[[https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/The_OpenSCAD_Language]]
[[https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Print_version]]
When viewed online from the main page, or the cheat sheet, only the file
containing the part you selected is loaded.
This affects how parts should be ordered within each file. If one file
contains parts for more than one chapter, the print version could end up
with more than one copy of this file, one in each chapter.
When viewed online this is less important since you are taken to the place
you selected regardless of where it is physically. However, if there is a
closely related part, you must go back to the selection page, unless they
are both in the same file.
Keep up the good work
Larry
View this message in context: http://forum.openscad.org/Improving-the-doc-tp14333p14645.html
Sent from the OpenSCAD mailing list archive at Nabble.com.
Just looked at your introduction. Without looking closely at all the details,
my impression is that it gives a much improved view of what the language is
and is not.
Larry
View this message in context: http://forum.openscad.org/Improving-the-doc-tp14333p14646.html
Sent from the OpenSCAD mailing list archive at Nabble.com.
I have seen OpenSCAD called a descriptive language. Perhaps this more quickly
gives one the viewpoint you wish to convey.
Larry
View this message in context: http://forum.openscad.org/Improving-the-doc-tp14333p14647.html
Sent from the OpenSCAD mailing list archive at Nabble.com.