How to improve the onshape featurescript manual

robert_carpenter114

As the shopworn cliche has it, a picture is worth a thousand words.   Now it is scandalous that the manual for a highly visual   system like onshape cad lacks so much as a single illustration.  One is left to try to picture in his mind the concepts being explained in the manual as best he can. This will never do if onshape wants to make good on its bid to take cad into the realm of user created code specific to his specialty.  Its got to be example pictures galore illustrating the featurescript  concepts explained in the manual if the language is ever going to have widespread user adoption. 

emagdalenaC2i

In addition to improve the manual by adding images and more examples:

1) A compilation of FeatureScript  examples is being created from the community on GitHub https://github.com/dcowden/featurescript

2) Something that would be very helpful is to also have the FeatureScript code of the std document in a GitHub repository.

This, for example, would facilitate the search for code examples in the std document, since currently a search must be done in each tab of the std document

This is a method that we have used for some time, in a private repository on GitHub, with very good results

kevin_o_toole_1

emagdalenaC2C said:

2) Something that would be very helpful is to also have the FeatureScript code of the std document in a GitHub repository.

This, for example, would facilitate the search for code examples in the std document, since currently a search must be done in each tab of the std document

In the standard library (or any document with FeatureScript), you can search globally in all tabs by hitting the magnifying glass at the top of the page or pressing ctrl-shift-F (or cmd-shift-F on a mac)

emagdalenaC2i

ok, thanks
In any case we will continue with our current method, because we also have our own code in FeatureScript in the same repository 

kevin_o_toole_1

Seems reasonable, I just figured I would let you know.

@robert_carpenter114
On the documentation, we've got lots of improvement requests that we continue to work on. I think 2D images could certainly helpful in places. If you submit an improvement request here, and others vote on it, that will substantially increase the likelihood that we prioritize this.

Is there some concept in particular that you wish was better illustrated? For many cases, the operation can be complex, and the best solution is not a 2D image but a 3D working example.

robert_carpenter114

Ok I take it all back.  The second part of the excellent Featurescript Tutorial on the Onshape Featurescript Main Page makes everything clear.

https://cad.onshape.com/FsDoc/tutorials/add-sketch-geometry.html

In particular it illuminates the distinction between Queries and Geometric Objects which was crucial to helping me 'get it' finally:

NOTE

FeatureScript has two completely separate ways of representing entities and geometry:

1. Queries, like endPoints are objects which specify criteria for finding a particular entity or set of entities in the Part Studio. These are just specifications, and they contain no information about the geometric or topological properties of any entities. Depending on the context it is evaluated in, a Query may resolve to zero, one, or many entities.

2. Geometric objects, like endPosition, contain data about geometric positions and orientations (including Vectors, Planes, CoordSystems, and more). These are just data, and are not contextually associated with any entities in the Part Studio.

This design gives Onshape Part Studios and features the robust tools needed to maintain fully parametric references.

To get geometric information from a query, use an evaluation function, found in the evaluate module.

john_mcclary

It would be nice if they didn't write the whole thing in wingdings...

I dont find it comprehinsive at all. Feels like a lot of missing information.

i just cant tell when i need to use certain functions in order to read/use a query properly.