BelfrySCAD
Reddit feedback on overview
A couple of people provided feedback on the new overview.
It should start small/ simple, and then build/add complexity.
Building blocks (2d and 3d shapes are the core of most parts) Rounding and filleting to refine those building blocks, Textures to decorate them. combine building blocks via Attachments For many common things, there is the Parts Library Sometimes you need more Complex Objects Not that you get the hang of it, here are some Short Hands, programming aids.
Something like that. Where the order of the sections is a story arc.
I think that's a pretty good suggestion.
Another comment:
My POV is a complete outsider just seeing much of this for the first time. For me, I think your list is in a good order. I starting making my own but I realized it was basically the same. I'd push attachments down a bit, since with the limitations of vanilla, I've never made anything complex enough where that would be helpful, though I can obviously see the benefit.
That kind of falls in line with the previous comment.
Those two suggestions aren't exactly in agreement.
My belief is that attachments are helpful as soon as you have two components in the model---complexity is not required for there to be a benefit. As soon as you have two objects you have to face the question of how to establish their relationship, and this is usually easier with attachments.
Starting small and simple in some sense means inverting my idea of how to list things, which was in order of usefuless, or power. Does that in fact make sense? It means listing the weakest, least interesting features first.
Would it make sense to break up the overview into categories? (I'm not quite sure what categories would make sense.)
The agreement between the two comments that I was referring to was about giving the attachments a lower priority in the list, if the list is in a rank order of importance or power.
I've been thinking about attachments and why in spite of their power and usefulness, I've never used them.
- If I have two objects that don't touch, I don't need attachments. I would already know their positions.
- If I have two objects that touch or interact via CSG operations, I can't use attachments because I don't want those two objects to share coplanar surfaces.
- If I have an assembly of parts, for which I would print each object separately, I can't use attachments because the assembly view requires different clearances between parts. It may be possible to manage this with attachments but I cannot tell that it's straightforward and I already know how to position the objects with their clearances.
- If I have two objects in a linkage, then I would surely need attachments, but BOSL2 attachments don't work like I expect for creating mechanical linkages. This would have been useful for my strandbeest model.
- Most of the time, I'm designing a single object, typically it's a VNF, and I don't need attachments for that.
The first suggestion to "start small/simple" is along the lines of a mini-tutorial. That shouldn't be in the overview itself, but should be included after the overview, on the same page. The analogy is a Wikipedia article, which has an overview in the lead section, and goes into more detail in the body of the article, with links out to other pages as needed. The main github landing page sort of does this already with a list of examples, but the wiki landing page could be expanded, possibly.
I note the overview in the Wiki starts out with Shorthands. It should be like the Github landing page, with shorthands further down.
As for categories, well, there are only 9 bullet points. At most it could be split into two or three categories. With two categories, how about using the way the library is currently structured? There are "Standard features" and "Advanced features" that require an extra include statement. The bullets could be shuffled under those two headings. And that would satisfy the "start small/simple" suggestion without requiring extra material on the page.
It seems like most of your cases reduce to the "I just have one object" case.
I would argue that the case of "two objects that don't touch" is really just another version of "only one object". Obviously not much use for attachments in the case of one object.
If you have two objects that interact via CSG operations you can make them overlap just the same as you might without using attachment, except it's a little bit cleaner. That's what the overlap and shiftout parameters are for. So objection two is erroneous.
For objection 3, that also reduces to the "single object" case. Yes, if you have an assembly of parts, where each part is a single object, and you need to be able to conditionally print locate them in different places, then it's possible that attachments might not be the answer---I can't think offhand of a way to do this that doesn't seem clumsy. On the other hand, it might be easier to just have two cases, one case that constructs the full model and one case that calls xdistribute() or whatever to lay the parts out. It's not apparent to me how you do this without entirely laying out two distinct cases anyway, so why not use attachment for the case where everything is, well, attached. Note also that you've tacitly assumed that each part is a single object and didn't need to be created by combining elements.
Perhaps we should discuss the mechanical linkage case. If there is a limitation we can address it might be worth doing. Or if there's a use case that should be demonstrated with examples because it's not obvious how to do it, that might be worth elaborating in the docs or tutorial. Jordan used attachments to make a system for modeling the Lovasac sofa system. This kind of thing may require you to define custom anchors, though, which is arguably a higher level use of the attachment system.
I doubt I have any models that are construct from more than one element without using attachments. The only object in my model that I position with absolute coordinates is the first one.
I just went back to update a design I built without attachments. It was so much worse. Attachments are my favorite thing about BOSL2; it makes writing things so much easier. In the vein of many software projects that try to demonstrate something minimal but cool first, this is the neatest thing I'd want to see first:
include <BOSL2/std.scad>
size=20;
diff() cuboid(size, rounding=2) {
attach(TOP,BOT) cube(size/2);
tag("remove") position(TOP) cylinder(h=size,d=5,orient=RIGHT,anchor=CENTER);
}
bonus points if someone wants to write that in raw openscad as a comparison but the rounding would be super annoying.
I asked on the OpenSCAD mailing list and got eight replies, briefly summarized below, about what people that was important or what they use after looking at the new BOSL2 overview list. It sounds like this list was much needed, as several people mentioned not knowing about things on the list. It is troubling that a couple people found the attachments tutorial incomprehensible. That seems to suggest that it needs work. Two suggestions suggest expanding the "complex models" description to more specifically mention VNFs and...well, to say more...but I'm not sure what. I wonder if attachment should be split into anchoring, relative object positioning, and child geometry operations as three more distinguished things.
I don't have much insight about the optimal order from this.
- I use threading/screws and turtle(). Attachments sound useful but I can't understand the tutorial
- gears, dovetails and threading. Couldn't understand the attachments tutorial. I find it difficult that the examples in the manual use attachments
- Building blocks was my intro, then parts and shorthands. Now I use rounding and path_sweep a lot. Attachments are difficult to use at first because the code syntax is super strange; not comfortable with them except for anchors
- I use anchors CONSTANTLY but never attach one object to another. I use shorthands so much they are what OpenSCAD is in my mind. The parts library is invaluable, especially screws. I use building blocks regularly. Other things are more special purpose, but the complex object support deserves a lot more emphasis
- Add a note about VNFs. I use BOSL2 occasionally because it's overwhelming
- My order: rounding/filleting (use all the time), building blocks, texturing (a few times), shorthands (never heard of, going to try), and that goes for the rest as well
- offset_sweep, path_sweep and skin() are the most important, but everything is valuable
- I use shortcuts a LOT.
Do we have any action items from this issue? Someone had asked for calling out VNFs explicitly, but I'm not sure what else might be worth changing.
I note that the overview on the main landing page is different from the overview on the Wiki landing page. The content is mostly the same, just in different order and therefore different emphasis. Whether that requires action, I don't know, it depends on whether the differing emphasis is intentional or not.
The problem there is that I couldn't update the wiki landing page and Revar thought shortcuts were super important and put them up to the top when he updated it. Right now the version on the main landing page is the corrected and updated one. I will copy it over to the wiki. You can check the latest version if you look in the PR that is currently processing checks.
I have updated both places. Let me know if there are any further changes motivated by any of the discussion above so we can close this out.