User manual order

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

User manual order

L Boyd
Although less important with the cheat sheet, this is my 1st pass at, hopefully, a more logical order.

The biggest change is separating the language reference from the rest

Link on this trial page are not active.

Trial_Reorder

Please post your comments
Larry
Reply | Threaded
Open this post in threaded view
|

Re: User manual order

doug.moen
Overall, I think it is a big improvement to put the entire language reference manual into a single node.

A small issue: the "Export as STL" command is in the GUI and CLI, it is not part of the language, so shouldn't be in the language reference manual. See section 8.5 of your reordered language reference manual.

On 2 November 2015 at 16:00, L Boyd <[hidden email]> wrote:
Although less important with the cheat sheet, this is my 1st pass at,
hopefully, a more logical order.

The biggest change is separating the language reference from the rest

Link on this trial page are not active.

Trial_Reorder
<https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Trial_Reorder>

Please post your comments



--
View this message in context: http://forum.openscad.org/User-manual-order-tp14271.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: User manual order

L Boyd
Was not sure about export and import.
Thanks for the feedback
Larry
Reply | Threaded
Open this post in threaded view
|

Re: User manual order

Neon22
Looks really good.
(How about rename Include to "Include and Use Statements")
Reply | Threaded
Open this post in threaded view
|

Re: User manual order

Peter Ragosch
Am Tue, 3 Nov 2015 04:13:38 -0700 (MST)
schrieb Neon22 <[hidden email]>:

> Looks really good.
> (How about rename Include to "Include and Use Statements")
>
>
>
>
> --
> View this message in context:
> http://forum.openscad.org/User-manual-order-tp14271p14274.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
>

"Include and Use Statements" sounds good.


In the headings there are no commands used, except "import_dxf" - why
not useing "DXF Import"


My two cent ;)
--
Mit freundlichen Grüßen
Kind Regards

Peter Ragosch


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

Re: User manual order

ctchin
In reply to this post by L Boyd
Dear All,

My first post!  Hopefully many more will come.

I salute you for taking on this important and monumental task.  The
current doc is just functional enough but far from professional
quality.  I too have started making my own "book"  with a faintest hope
of writing and publishing an actual book. When I use OpenSCAD, I like to
have a "dead-tree version" by my keyboard.  And I can imagine a lot of
users would similarly desired a nicely-printed book.

But alas, I discipline myself NOT to spend time on my "book" because I
should put my time on more "important" things.

So perhaps my best hope to air my views (some might be considered
radical) and perhaps trick you into writing the book that I want to
have, but may not want to write :P

Firstly, I am mystified why there's such a thing as 2D __subsystem__.  I
use both 2D and 3D primitives and transformations frequently and I find
no sense in talking about a subsystem.  It makes no sense as the same as
talking about a vector subsystem or string subsystem. It is very
confusing because "offset" which operates on 2D isn't found in the 2D
subsystem chapter but in the Transformation chapter/section.  Similarly
it's arbitrary to put projection in 3D and extrusions in 2D.

I propose merging all primitives in one chapter, first listing all the
solids: cube, sphere etc, then list the 2D shapes, square, circle and
polygon.  A short section preceding the primitives should clearly
explain 2D and 3D objects and preview a few commands (to be covered
later) that transform between 2D and 3D objects.

Then after primitives, all transformations should be covered.  Each
should be clearly labelled to work on 3D objects, 2D objects or both.  
It is easy to create a module that operates on a mix of 2D and 3D
children.  It makes no sense to divide projection, extrusions and
"common" transformation (e.g. rotate) into three different sections.

Now, for a radical idea: treat "for", "intersection_for",  "if" as
transformations.

I have more radical ideas/views, but enough for today: just expunge
"subsystem" and treat "for" as a transformation.

Hope I am stirring the pot in a positive way.


On 11/3/2015 5:00 AM, L Boyd wrote:

> Although less important with the cheat sheet, this is my 1st pass at,
> hopefully, a more logical order.
>
> The biggest change is separating the language reference from the rest
>
> Link on this trial page are not active.
>
> Trial_Reorder
> <https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Trial_Reorder>
>
> Please post your comments
>
>
>
> --
> View this message in context: http://forum.openscad.org/User-manual-order-tp14271.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

--
錢建庭 教授、教研办副主任
深圳大学 生物医学工程系

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: User manual order

jdawgaz
In addition to the reorder and Chien TIng's nice post.

I have been teaching openscad to some members of my Amateur Radio Club.
Most have not come from ANY programming type background, and are having trouble.
I have retired from doing programming for 40+ years.

A lot of this is over their heads, but they want to learn.

In the first steps section, I would like to see a detailed tutorial on building some simple part. The steps taken, and why, and what each little step looks like when previewed.

Then you could maybe link out to some youtube, and other links that you know of that are "tutorials" or how to's.

I am not sure that everyone coming to openscad has a programming background. Having done scripting for years it is easy for me to KNOW that for every ( you must have a corresponding ), and for every {, a }. But I know there are some people that wonder why at just those simple things.

I would be willing to help in this regard, if asked. Being retired, I DO have the time.

Jerry


--
Extra Ham Operator: K7AZJ
Registered Linux User: 275424
Raspberry Pi and Arduino developer

The most exciting phrase to hear in science - the one that heralds new discoveries - is not "Eureka!" but "That's funny...".
- Isaac. Asimov

If you give someone a program, you will frustrate them for a day; if you teach them how to program, you will frustrate them for a lifetime. 
- Anonymous

If writing good code requires very little comments, then writing really excellent code requires no comments at all!
- Ken Thompson


On Tue, Nov 3, 2015 at 7:51 PM, CHIN, Chien Ting 钱建庭 <[hidden email]> wrote:
Dear All,

My first post!  Hopefully many more will come.

I salute you for taking on this important and monumental task.  The current doc is just functional enough but far from professional quality.  I too have started making my own "book"  with a faintest hope of writing and publishing an actual book. When I use OpenSCAD, I like to have a "dead-tree version" by my keyboard.  And I can imagine a lot of users would similarly desired a nicely-printed book.

But alas, I discipline myself NOT to spend time on my "book" because I should put my time on more "important" things.

So perhaps my best hope to air my views (some might be considered radical) and perhaps trick you into writing the book that I want to have, but may not want to write :P

Firstly, I am mystified why there's such a thing as 2D __subsystem__.  I use both 2D and 3D primitives and transformations frequently and I find no sense in talking about a subsystem.  It makes no sense as the same as talking about a vector subsystem or string subsystem. It is very confusing because "offset" which operates on 2D isn't found in the 2D subsystem chapter but in the Transformation chapter/section.  Similarly it's arbitrary to put projection in 3D and extrusions in 2D.

I propose merging all primitives in one chapter, first listing all the solids: cube, sphere etc, then list the 2D shapes, square, circle and polygon.  A short section preceding the primitives should clearly explain 2D and 3D objects and preview a few commands (to be covered later) that transform between 2D and 3D objects.

Then after primitives, all transformations should be covered.  Each should be clearly labelled to work on 3D objects, 2D objects or both.  It is easy to create a module that operates on a mix of 2D and 3D children.  It makes no sense to divide projection, extrusions and "common" transformation (e.g. rotate) into three different sections.

Now, for a radical idea: treat "for", "intersection_for",  "if" as transformations.

I have more radical ideas/views, but enough for today: just expunge "subsystem" and treat "for" as a transformation.

Hope I am stirring the pot in a positive way.



On 11/3/2015 5:00 AM, L Boyd wrote:
Although less important with the cheat sheet, this is my 1st pass at,
hopefully, a more logical order.

The biggest change is separating the language reference from the rest

Link on this trial page are not active.

Trial_Reorder
<https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Trial_Reorder>

Please post your comments



--
View this message in context: http://forum.openscad.org/User-manual-order-tp14271.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

--
錢建庭 教授、教研办副主任
深圳大学 生物医学工程系

CHIN, Chien Ting, Professor, Vice Chairman (Education)
Department of Biomedical Engineering
Shenzhen University
Tel: <a href="tel:%2B86-755-8667-1915" value="+8675586671915" target="_blank">+86-755-8667-1915




_______________________________________________
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: User manual order

L Boyd
First of all, I am not rewriting the OpenSCAD manual.  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.
The task, which I have assigned myself, is to reorder these lists in a more logical fashion, hopefully making things easier to find. Reordering these lists does not entail changing the contents of the the various files pointed to in the list.

There have been some excellent suggestions about content. I would encourage each of you, just as others have encouraged me, to dig in and make your changes.
 
Larry
Reply | Threaded
Open this post in threaded view
|

Re: User manual order

ctchin
In reply to this post by jdawgaz
In my unwritten book, I open the introduction with the following paragraphs:

The official introduction page of OpenSCAD declares it is a software for creating solid 3D CAD models.  A better description is found in the tagline: The Programmer’s Solid 3D CAD Modeller.  Unlike most CAD software, which have the designer working with data specifying a model, in OpenSCAD, the designer write a program to create a model.  This design philosophy encourage designers to engineer a parametric model instead of sculpting a work of creation. 

Software like Google Sketch-up is the natural choice for designers who are not trained in mathematics and programming and who need to create organic or artistic designs. 

Software like AutoCAD and Pro/Engineer are used by many enterprises and professionals for mechanical or structure designs.  They are loaded with very advanced and powerful features which would be very challenging (and likely too costly) for the amateur or occasional users. 

OpenSCAD is the best choice for designers who needs mathematical precision in the creation but cannot or would not dive into the deep ocean of a full-brown professional CAD package.  The instruction set is quite small (and it’s fair to complain that it lacks powerful features), but its simplicity is a great advantage for generalists, hobbyists and professionals who possess a number of technical and artistic skills and integrate them in his or her projects. 


In another word, if you and your class come to OpenSCAD without at least some exposure to computer programming then you ought to think a bit harder if there's a easier way to build your projects.  Have you looked into Google SketchUp, AutoDesk 123D, TinkerCAD? 

Of course it's not forbidden to learn OpenSCAD as your first programming language, but there are a variety of choices for building a design (for 3D printing, I presume?).  Blender (I presume to characterize it) is attractive to artists, 123D might be good for mechanical  engineers who knew drafting, and OpenSCAD is attractive to programmers. 


On 11/6/2015 4:25 AM, Jerry Davis wrote:
In addition to the reorder and Chien TIng's nice post.

I have been teaching openscad to some members of my Amateur Radio Club.
Most have not come from ANY programming type background, and are having trouble.
I have retired from doing programming for 40+ years.

A lot of this is over their heads, but they want to learn.

In the first steps section, I would like to see a detailed tutorial on building some simple part. The steps taken, and why, and what each little step looks like when previewed.

Then you could maybe link out to some youtube, and other links that you know of that are "tutorials" or how to's.

I am not sure that everyone coming to openscad has a programming background. Having done scripting for years it is easy for me to KNOW that for every ( you must have a corresponding ), and for every {, a }. But I know there are some people that wonder why at just those simple things.

I would be willing to help in this regard, if asked. Being retired, I DO have the time.

Jerry


--
Extra Ham Operator: K7AZJ
Registered Linux User: 275424
Raspberry Pi and Arduino developer

The most exciting phrase to hear in science - the one that heralds new discoveries - is not "Eureka!" but "That's funny...".
- Isaac. Asimov

If you give someone a program, you will frustrate them for a day; if you teach them how to program, you will frustrate them for a lifetime. 
- Anonymous

If writing good code requires very little comments, then writing really excellent code requires no comments at all!
- Ken Thompson


On Tue, Nov 3, 2015 at 7:51 PM, CHIN, Chien Ting 钱建庭 <[hidden email]> wrote:
Dear All,

My first post!  Hopefully many more will come.

I salute you for taking on this important and monumental task.  The current doc is just functional enough but far from professional quality.  I too have started making my own "book"  with a faintest hope of writing and publishing an actual book. When I use OpenSCAD, I like to have a "dead-tree version" by my keyboard.  And I can imagine a lot of users would similarly desired a nicely-printed book.

But alas, I discipline myself NOT to spend time on my "book" because I should put my time on more "important" things.

So perhaps my best hope to air my views (some might be considered radical) and perhaps trick you into writing the book that I want to have, but may not want to write :P

Firstly, I am mystified why there's such a thing as 2D __subsystem__.  I use both 2D and 3D primitives and transformations frequently and I find no sense in talking about a subsystem.  It makes no sense as the same as talking about a vector subsystem or string subsystem. It is very confusing because "offset" which operates on 2D isn't found in the 2D subsystem chapter but in the Transformation chapter/section.  Similarly it's arbitrary to put projection in 3D and extrusions in 2D.

I propose merging all primitives in one chapter, first listing all the solids: cube, sphere etc, then list the 2D shapes, square, circle and polygon.  A short section preceding the primitives should clearly explain 2D and 3D objects and preview a few commands (to be covered later) that transform between 2D and 3D objects.

Then after primitives, all transformations should be covered.  Each should be clearly labelled to work on 3D objects, 2D objects or both.  It is easy to create a module that operates on a mix of 2D and 3D children.  It makes no sense to divide projection, extrusions and "common" transformation (e.g. rotate) into three different sections.

Now, for a radical idea: treat "for", "intersection_for",  "if" as transformations.

I have more radical ideas/views, but enough for today: just expunge "subsystem" and treat "for" as a transformation.

Hope I am stirring the pot in a positive way.



On 11/3/2015 5:00 AM, L Boyd wrote:
Although less important with the cheat sheet, this is my 1st pass at,
hopefully, a more logical order.

The biggest change is separating the language reference from the rest

Link on this trial page are not active.

Trial_Reorder
<https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/Trial_Reorder>

Please post your comments



--
View this message in context: http://forum.openscad.org/User-manual-order-tp14271.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

--
錢建庭 教授、教研办副主任
深圳大学 生物医学工程系

CHIN, Chien Ting, Professor, Vice Chairman (Education)
Department of Biomedical Engineering
Shenzhen University
Tel: <a moz-do-not-send="true" href="tel:%2B86-755-8667-1915" value="+8675586671915" target="_blank">+86-755-8667-1915




_______________________________________________
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

-- 
錢建庭 教授、教研办副主任
深圳大学 生物医学工程系

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: User manual order

ctchin
I hear you, L.  I had the same idea even before 2015-03 was released but ... with due respect to the developers/writers who contributed so much already, a pure re-ordering without adding and correcting the text would not be satisfactory.  For example:

Matrix multiplication: https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/The_OpenSCAD_Language#Matrix_Multiplication
The text is completely inadequate.  It is not reasonable to expect most readers to understand "matrix multiplication", as many have never learned linear algebra and most who have do not retain that knowledge.  At least a  reference (e.g. Wikipedia) and an example is needed. The behavior of ill-posed matrix multiplication () should be explained (result in undef).

The text for minkowski() is also inadequate,  it is not an easy concept to explain but at least an attempt should be made, and at least two examples (2D and 3D) should be given.

There are more!

I've been wondering about the "source code" for the documentation, especially with the "online" and "print" editions being somewhat different.  Where can I find the list(s) and the files themselves?  Then I can actually put in my (draft) edit for the community to consider instead of just whining about it on the mailing list.
Reply | Threaded
Open this post in threaded view
|

Re: User manual order

doug.moen
I am hoping that L will put both the print and online editions into the same order.

On Monday, 9 November 2015, ctchin <[hidden email]> wrote:
I hear you, L.  I had the same idea even before 2015-03 was released but ...
with due respect to the developers/writers who contributed so much already,
a pure re-ordering without adding and correcting the text would not be
satisfactory.  For example:

Matrix multiplication:
https://en.wikibooks.org/wiki/OpenSCAD_User_Manual/The_OpenSCAD_Language#Matrix_Multiplication
The text is completely inadequate.  It is not reasonable to expect most
readers to understand "matrix multiplication", as many have never learned
linear algebra and most who have do not retain that knowledge.  At least a
reference (e.g. Wikipedia) and an example is needed. The behavior of
ill-posed matrix multiplication () should be explained (result in undef).

The text for minkowski() is also inadequate,  it is not an easy concept to
explain but at least an attempt should be made, and at least two examples
(2D and 3D) should be given.

There are more!

I've been wondering about the "source code" for the documentation,
especially with the "online" and "print" editions being somewhat different.
Where can I find the list(s) and the files themselves?  Then I can actually
put in my (draft) edit for the community to consider instead of just whining
about it on the mailing list.




--
View this message in context: http://forum.openscad.org/User-manual-order-tp14271p14331.html
Sent from the OpenSCAD mailing list archive at Nabble.com.

_______________________________________________
OpenSCAD mailing list
<a href="javascript:;" onclick="_e(event, &#39;cvml&#39;, &#39;Discuss@lists.openscad.org&#39;)">Discuss@...
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: User manual order

L Boyd
The main page contents list has been revised close to what I proposed. The language reference is now logically separate from the rest of the user manual. There are links on the main page to where you will find printable version of the 2 manuals.

The printable versions are now in the same order as the main page. These are not a second  copy of the contents.  Instead, when you visit the printable page, the latest versions of the various components are assembled into a single page.

Besides being printable as a unit, the manual can be viewed online. The table of contents has active links just like the main page.

Yes, the contents can be improved. I encourage each of you to do something about it. WikiBooks allows you to edit portions without rewriting the whole book. Jerry, you should definitely work on the getting started chapter.

Hopefully the revised organization is helpful.

Larry
Larry
Reply | Threaded
Open this post in threaded view
|

Re: User manual order

doug.moen
Thank you.

On Friday, 13 November 2015, L Boyd <[hidden email]> wrote:
The main page contents list has been revised close to what I proposed. The
language reference is now logically separate from the rest of the user
manual. There are links on the main page to where you will find printable
version of the 2 manuals.

The printable versions are now in the same order as the main page. These are
not a second  copy of the contents.  Instead, when you visit the printable
page, the latest versions of the various components are assembled into a
single page.

Besides being printable as a unit, the manual can be viewed online. The
table of contents has active links just like the main page.

Yes, the contents can be improved. I encourage each of you to do something
about it. WikiBooks allows you to edit portions without rewriting the whole
book. Jerry, you should definitely work on the getting started chapter.

Hopefully the revised organization is helpful.

Larry




--
View this message in context: http://forum.openscad.org/User-manual-order-tp14271p14448.html
Sent from the OpenSCAD mailing list archive at Nabble.com.

_______________________________________________
OpenSCAD mailing list
<a href="javascript:;" onclick="_e(event, &#39;cvml&#39;, &#39;Discuss@lists.openscad.org&#39;)">Discuss@...
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