# Improving the doc

31 messages
12
Open this post in threaded view
|

## 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_OperatorsNext I may tackle the more tricky Matrix Multiplication. Suggestion and criticism welcome.
Open this post in threaded view
|

## Re: Improving the doc

 This post has NOT been accepted by the mailing list yet. As I threatened to do, I've completely re-written Matrix Multiplication: https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/The_OpenSCAD_Language#Matrix_MultiplicationI am warning you, I will keep doing it unless someone stops me.
Open this post in threaded view
|

## Re: Improving the doc

 This post has NOT been accepted by the mailing list yet. 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#GeneralYou 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".
Open this post in threaded view
|

## Re: Improving the doc

 This post has NOT been accepted by the mailing list yet. 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-manualhttps://en.wikibooks.org/wiki/OpenSCAD_User_Manual#Overviewhttps://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Print_versionThen 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_objectsAlso this is a gem that I just discovered today: https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/For_C/Java/Python_ProgrammersBoth 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#cylinderThe 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 but still hidden by obscurity.
Open this post in threaded view
|

## Re: Improving the doc

Open this post in threaded view
|

## Re: Improving the doc

 This post has NOT been accepted by the mailing list yet. The issue may well be that I've changed my email address on the forum.  I first registered as c.t.chin@szu.edu.cn and than changed it to doc.core@gmail.com I'd much rather just use the forum without getting emails.  But... anyway... Appreciate your help.
Open this post in threaded view
|

## Re: Improving the doc

 In reply to this post by MichaelAtOz I've un-changed my email back to my work email.  Hope that may be a step to fix my mailing list issue.  Then I've to look into stop receiving emails from the list :-| (this is a test message) On 11/11/2015 5:54 PM, MichaelAtOz wrote: > There seems to be something wrong with your forum/mailing list setup. > -- 錢建庭 教授、教研办副主任 深圳大学 生物医学工程系 CHIN, Chien Ting, Professor, Vice Chairman (Education) Department of Biomedical Engineering Shenzhen University Tel: +86-755-8667-1915 _______________________________________________ OpenSCAD mailing list [hidden email] http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
Open this post in threaded view
|

## Re: Improving the doc

Open this post in threaded view
|

## Re: Improving the doc

Open this post in threaded view
|

## Re: Improving the doc

 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#rotateThe old code was updated to exploit the (not even that recently) added functions norm() and atan2().
Open this post in threaded view
|

## Re: Improving the doc

Open this post in threaded view
|

## Re: Improving the doc

Open this post in threaded view
|

## Re: Improving the doc

 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%29You 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.
Open this post in threaded view
|

## Re: Improving the doc

 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
Open this post in threaded view
|

## Re: Improving the doc

 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
Open this post in threaded view
|

## Re: Improving the doc

 I have seen OpenSCAD called a descriptive language. Perhaps this more quickly gives one the viewpoint you wish to convey. Larry
Open this post in threaded view
|

## Re: Improving the doc

 Administrator Hey, Thanks to all for contributing to the docs. One question: I see that someone accidentally deleted most of this page: https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/TransformationsNot sure who, and somehow Wikibooks doesn’t let me undo it, as it thinks it’s “suspicious”. Could someone with better wikibooks permissions take a look? Cheers,  -Marius _______________________________________________ OpenSCAD mailing list [hidden email] http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
Open this post in threaded view
|

## Re: Improving the doc

 On 11/20/2015 07:35 AM, Marius Kintel wrote: > One question: I see that someone accidentally deleted most of this > page: https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Transformations> Ok, I could not "undo" the change - got the same error. But rejecting it via review worked :-). I did accept the change in the "Rotation rule help" section as this looked fine to me... ciao,   Torsten. _______________________________________________ OpenSCAD mailing list [hidden email] http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org -- Torsten
Open this post in threaded view
|

## Re: Improving the doc

 In reply to this post by kintel Yikes!  It might have been me.  VERY SORRY! It doesn't help that I can't even tell if it's me.  I found out that sometimes I was logged out while editing the doc, leaving only some IP address as the author.   Could the owner of the book limit  editing rights to only those who are logged in as a registered person on Wikibooks?  At least that way it's easier to trace mistakes.   I do get distracted a lot during the day, so sometimes I leave a wiki page in the edit/open state could be some unfortunate combination of events caused the wiping of Transformations.  Luckily wiki is undo-able.   Thanks and SORRY!