README and TIPS_AND_TRICKS updates

README.md

@@ -14,15 +14,19 @@ Relevant links:
 
 The easiest (though not the best) way to run this program is to boot it up in [Thingiverse's Customizer](https://www.thingiverse.com/apps/customizer/run?thing_id=2783650). Explanations of each option are provided, as well as some default variables. Twiddle the variables to see how the keycap changes!
 
+The customizer is not always kept up to date, so I recommend the options below.
+
 #### OpenSCAD Customizer
 
 If you find that the Thingiverse Customizer is timing out, but you're not technically inclined enough to start programming in OpenSCAD, you can look into [getting OpenSCAD's customizer working](https://github.com/rsheldiii/KeyV2/wiki/Getting-the-OpenSCAD-Customizer-working).
 
 #### OpenSCAD Proper
 
-First, you'll need OpenSCAD: http://www.openscad.org/downloads.html. I highly recommend installing the development snapshot, as they are much further along than the current stable release (as of writing, 2015.03-3).
+If you are technically inclined at all, this is definitely the recommended way to run the code. It's not very hard!
 
-After you have openSCAD installed, you need to download the code and run it. running `git clone https://github.com/rsheldiii/openSCAD-projects.git` if you have git, or downloading [this zip](https://github.com/rsheldiii/openSCAD-projects/archive/master.zip) and extracting the code should do it. Then all you need to do is open `keys.scad` with openSCAD and you are set! It is possible to edit this project with an external editor by checking off Design => Automatic Reload and Preview in OpenSCAD.
+First, you'll need OpenSCAD: http://www.openscad.org/downloads.html. I highly recommend installing the development snapshot, as they generally support more features and are relatively stable. Development snapshots are listed in their own section on the downloads page.
+
+After you have openSCAD installed, you need to download the code and run it. running `git clone https://github.com/rsheldiii/openSCAD-projects.git` if you have git, or downloading [this zip](https://github.com/rsheldiii/openSCAD-projects/archive/master.zip) and extracting the directory should do it. Then all you need to do is open `keys.scad` with openSCAD and you are set! It is possible to edit this project with an external editor by checking off Design => 'Automatic Reload and Preview' in OpenSCAD.
 
 All examples below assume you are running the library on your computer with OpenSCAD.
 
@@ -30,7 +34,7 @@ All examples below assume you are running the library on your computer with Open
 
 This library supports Cherry and Alps switches, and has pre-defined key profiles for SA, DSA, DCS, G20, Hi-Pro and (some form of) OEM keycaps. `keys.scad` is the entry point for everything but the most technical use. Pre-programmed key profiles can be found in the `key_profiles` directory.
 
-Every key starts with defaults that are overridden by each function call. The simplest cherry key you can make would be:
+Every key starts with default settings (provided in `settings.scad`) that are overridden by each function call. The simplest key you can make would be:
 
 ```
 key();
@@ -38,9 +42,12 @@ key();
 ![a bog-standard cherry key](assets/example1.JPG)
 
 
-which is a bog-standard DCS row 5 (number / function row) keycap. To change how the key is generated, you add predefined modifier functions like so:
+which is a bog-standard DCS row 5 (number / function row) keycap. To change how the key is generated, you can modify the settings directly or add predefined modifier functions like so:
 
 ```
+// directly modified setting
+$stem_inset = 1;
+// settings changed through modifier function
 sa_row(2) 2u() key();
 ```
 
@@ -48,11 +55,27 @@ You can chain as many modifier functions as you like!
 
 ![a 2 unit SA row 2 cherry key](assets/example2.JPG)
 
-## Tweaking individual keycaps
+## Modifier functions
 
-There is a bevy of supporting functions to customize your keycaps. You can add a brim to more easily print the stem with `brimmed_stem_support`, make 2x2 keycaps with `2u() 2uh()`, add legends, rotate stems, and more. These functions can be found in `key_profiles/` for different keycap profiles, `key_types.scad` for predefined settings for common keys (spacebar, left shift, etc), `key_sizes.scad` for common unit sizes, and `key_transformations.scad` for everything else. For a full list of helper functions with explanations, [Check out the wiki!](https://github.com/rsheldiii/KeyV2/wiki/KeyV2-Helper-Documentation)
+There is a bevy of supporting functions to customize your keycaps. You can add a brim to more easily print the stem with `brimmed_stem_support`, make 2x2 keycaps with `2u() 2uh()`, add legends, rotate stems, and more. All these functions manipulate the settings available to you in [`settings.scad`](https://github.com/rsheldiii/KeyV2/blob/master/src/settings.scad), though [some of them](https://github.com/rsheldiii/KeyV2/blob/master/src/key_transformations.scad#L128) are quite complex.
 
-These modifier functions don't cover everything; in that case, you may have to write some SCAD yourself.
+These modifier functions can be found in [`key_profiles/`](https://github.com/rsheldiii/KeyV2/blob/master/src/key_profiles) for different keycap profiles, [`key_types.scad`](https://github.com/rsheldiii/KeyV2/blob/master/src/key_types.scad) for predefined settings for common keys (spacebar, left shift, etc), [`key_sizes.scad`](https://github.com/rsheldiii/KeyV2/blob/master/src/key_sizes.scad) for common unit sizes, and [`key_transformations.scad`](https://github.com/rsheldiii/KeyV2/blob/master/src/key_transformations.scad) for everything else. I encourage you to do some sleuthing but for a list of (most) helper functions with explanations, [Check out the wiki!](https://github.com/rsheldiii/KeyV2/wiki/KeyV2-Helper-Documentation)
+
+These modifier functions may not cover every use case; in that case, you may have to write some SCAD yourself.
+
+## Layouts
+
+new to the library and still in a beta state, layouts allows you to generate an entire layout for a keyboard!
+
+It is recommended to use tined stem support and set `$extra_long_stem_support = true` if you plan on printing these keycaps.
+
+```
+60_percent_default("dcs") key();
+```
+
+![a standard 60 percent layout](assets/layout.png)
+
+layouts accept children, so you can use them as a chained function like other modifiers. Be wary of accidentally overriding something the layout does for you though.
 
 #### Example customizations
 
@@ -61,7 +84,7 @@ Let's say you wanted to generate some 2u stabilized keycaps for an Ergodox, you
 ```
 legends = ["Enter", "Escape", "Tab", "Shift"];
 for(y=[0:3]) {
-  translate_u(0,y) 2u() dsa_row() stabilized() cherry() key(inset=true) { keytext(legends[y], [0,0], 6); }
+  translate_u(0,y) 2u() dsa_row() stabilized() cherry() legend(legends[y], [0,0, 6]) key();
 }
 ```
 
@@ -81,6 +104,10 @@ cherry() key() {
 
 Artisan support also supports _subtracting_ children by doing `key(inset=true) { ... }`, which is super helpful if you want to make keycaps with legends that are not text. The children will be placed just above the middle of the dish as per usual; you will need to translate them downwards (`ex translate([0,0,-1])`) to get them to 'dig in' to the top of the key.
 
+## Tips and tricks
+
+Looking for information or something specific? you could try checking out the [tips and tricks](TIPS_AND_TRICKS.md) section.
+
 ## What if I want to get _really_ technical?
 
 Now we're talkin!

TIPS_AND_TRICKS.md

@@ -1,7 +1,25 @@
-# WIP
+# WIP Tips and Tricks section
 
 just want to make sure I put this here, I'm going to make this a much better document later
 
+## Fully sculpted caps
+
+Fully sculpted keycaps are caps that also tilt inwards / outwards, cupping your fingers a bit.
+
+Most profiles should support this now; you pass in a "column" value after the row value, and the cap will calculate how much extra height and tilt for that column.
+
+the way this works is the program projects a large, imaginary cylinder that it inscribes the top of the keycaps into. Thus, the height and tilt can be tweaked by changing the `$double_sculpt_radius`, which changes the radius of that imaginary cylinder.
+
+At the end of the day though, all the columnular sculpting is doing is adding extra height and y tilt to the top of the key. if you have some other aim than fitting to a cylinder you can control this directly with appropriate changes to `$top_tilt_y` and `$total_depth`, or perhaps changing the `side_tilt()` and `extra_side_tilt_height()` functions in [`functions.scad`](https://github.com/rsheldiii/KeyV2/blob/master/src/functions.scad) which are what the row profiles use.
+
+## skin mode
+
+SA, HiPro and DSA keycaps take _forever_ to render. This is a multifaceted issue that I don't want to get into here, but suffice to say _one_ of the reasons it takes so long is how the keycap is constructed from multiple, smaller slices. OpenSCAD takes more time to render the more objects you have, regardless of how they interact. Enter `$skin_extrude_shape = true`.
+
+`skin()` is a list comprehension function available [here](https://github.com/openscad/list-comprehension-demos/blob/master/skin.scad). The gist of it is that instead of having x number of keycap slices unioned together, we give `skin()` a set of profiles and it makes a single object out of it for us. This reduces the number of objects per keycap, which makes it easier to render them.
+
+One current limitation of `skin()` is that I suck at math and can't translate [rounded_square](https://github.com/rsheldiii/KeyV2/blob/master/src/shapes/rounded_square.scad) into a function, which means that we miss out on the very nice bowing exhibited on these profiles. once we can translate that to math however, we'll be in business.
+
 ## Printing upside down
 
 still in beta, but using `upside_down()` in a method chain will rotate keycaps to be upside down. This makes the stem print better and requires no support, but generally the top of the keycap comes out worse - unless it is flat.
@@ -27,6 +45,10 @@ and comment out either `key(true)` or the whole `dished` segment. This code gene
 
 Run just the legends through your slicer first and make sure to turn off anything like skirts or brims, it should print your legends in a single layer on your print bed. Leave them there, swap filaments, and then print the rest of the keycaps around them in a different color. The result is pretty impressive. They aren't quite doubleshot, since the main benefit of doubleshots is the plastic goes all the way through the keycap, but they look incredibly impressive for what they are.
 
+### No stem support
+
+If you're printing updside down you'll want to disable stem supports. you can change the `$stem_support_type`, or just use the `no_stem_support()` modifier function
+
 ## front print legends and location / font size
 
 still in beta, set `$front_print_legends = true` to have legends print on the front instead of the top of the keycaps.   
@@ -45,3 +67,7 @@ g20_row() legend("Q", [0,0], 3) {
    %envelope();
  }
 ```
+
+## stem inset
+
+If you want the more refined top surface that printing upright brings, but you are having a bad time with elephant's foot, you can enable some `$stem_inset` and see if that helps. you'll have to figure out what support works best for you.