Improving the doc

classic Classic list List threaded Threaded
31 messages Options
12
Reply | Threaded
Open this post in threaded view
|

Improving the doc

ctchin
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.
Reply | Threaded
Open this post in threaded view
|

Re: Improving the doc

ctchin
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_Multiplication

I am warning you, I will keep doing it unless someone stops me.  
Reply | Threaded
Open this post in threaded view
|

Re: Improving the doc

ctchin
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#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".  
Reply | Threaded
Open this post in threaded view
|

Re: Improving the doc

ctchin
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-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 but still hidden by obscurity.  
Reply | Threaded
Open this post in threaded view
|

Re: Improving the doc

MichaelAtOz
Administrator
Hi Doc,

There seems to be something wrong with your forum/mailing list setup.

As the first post does not say "This post has NOT been accepted by the mailing list yet" but your subsequent post DO, I suspect that something is wrong, or you may have unsubscribed from the OpenSCAD mailing list.

So all the posts where you 'threaten' and get 'mad' have not been seen by the majority of mailing list members. Hence nobody is taking your bait.

I will check on your settings tomorrow, so don't go off half-cocked assuming everyone has seen your posts.

There is at least one other user who was subscribed some time ago, but is not now, so there may have been some issue recently.
Admin - email* me if you need anything,
or if I've done something stupid...
* click on my MichaelAtOz label, there is a link to email me.

Unless specifically shown otherwise above, my contribution is in the Public Domain; to the extent possible under law, I have waived all copyright and related or neighbouring rights to this work.
Obviously inclusion of works of previous authors is not included in the above.


The TPP is no simple “trade agreement.” Fight it! http://www.ourfairdeal.org/ time is running out!
Reply | Threaded
Open this post in threaded view
|

Re: Improving the doc

ctchin
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.

Reply | Threaded
Open this post in threaded view
|

Re: Improving the doc

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

Re: Improving the doc

ctchin
In reply to this post by ctchin
(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.  
Reply | Threaded
Open this post in threaded view
|

Re: Improving the doc

doug.moen
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 <[hidden email]> 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
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org




_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
Reply | Threaded
Open this post in threaded view
|

Re: Improving the doc

ctchin
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().

Reply | Threaded
Open this post in threaded view
|

Re: Improving the doc

L Boyd
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
Reply | Threaded
Open this post in threaded view
|

Re: Improving the doc

L Boyd
Going back over your posts, I would like to read your proposed general section but your link does not get me there.
Larry
Reply | Threaded
Open this post in threaded view
|

Re: Improving the doc

ctchin
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.  
Reply | Threaded
Open this post in threaded view
|

Re: Improving the doc

L Boyd
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
Reply | Threaded
Open this post in threaded view
|

Re: Improving the doc

L Boyd
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
Reply | Threaded
Open this post in threaded view
|

Re: Improving the doc

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

Re: Improving the doc

kintel
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/Transformations

Not 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
tp3
Reply | Threaded
Open this post in threaded view
|

Re: Improving the doc

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

Re: Improving the doc

ctchin
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!
tp3
Reply | Threaded
Open this post in threaded view
|

Re: Improving the doc

tp3
> 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.
>
Don't worry, things happen :-).
There's the review process anyway and even if something slipped through
there, it would be still possible to fix later using the history.

The help with the documentation is very much appreciated.

ciao,
  Torsten.



_______________________________________________
OpenSCAD mailing list
[hidden email]
http://lists.openscad.org/mailman/listinfo/discuss_lists.openscad.org
-- Torsten
12