Add README and basic modeling instructions, and document the API

Also, tweaked the object names in the standard sign Blender
project file, renamed it, renamed the small/slim pole mount
project file as well, and added a copy of the standard pole
mount project file.

API.md

@@ -0,0 +1,333 @@
+# Signs_lib API
+
+In this text, common terms such as `pos`, `node`, or `placer`/`digger` will not be explained unless they have a different meaning than what's usually used in Minetest mods.  See [minetest/doc/lua_api.txt](https://github.com/minetest/minetest/blob/master/doc/lua_api.txt) for details on these and other common terms, if necessary.  Similarly, common shorthand such as `int`, `float`, etc. should require no explanation.
+
+## Registering a sign
+
+* `signs_lib.register_sign(nodename, def)`
+
+  To put it simply, where you'd have used `minetest.register_node()` before, just replace it with this call.  The syntax is identical, and in general, all settings/items allowed there are allowed here as well.  Anything that `signs_lib` doesn't need to override or alter will be passed straight through to `register_node()`, unchanged (such as `description`, `tiles`, or `inventory_image`).
+
+  The supplied `nodename` will be prepended with `":"`, so that any mod can register signs under any other mod's namespace, if desired.
+
+  Many items have default settings applied when omitted, most of which would produce something equivalent to `"default:sign_wall_wood"` if enough other node defintion settings were to be included.
+
+  * `drawtype = "string"`
+
+    Default: `"mesh"`
+
+  * `mesh = "string"`
+
+    Default: `"signs_lib_standard_wall_sign.obj"`.
+
+  * `paramtype = "string"`
+
+    Default: `"light"`
+
+  * `paramtype2 = "string"`
+
+    As with any other node, this determines how param2 is interpreted.  Since these are signs, only two modes make sense: `"wallmounted"` and `"facedir"`.  Any other string is the same as `"facedir"`.
+
+    Default: `"wallmounted"`
+
+  * `wield_image = "string"`
+
+    Default: whatever the `inventory_image` is set to (if anything).
+
+  * `groups = {table}`
+
+    Sets the sign's groups, as usual.  In addition to whatever arbitrary groups you may have in mind, there are two presets available (both of which have `attached_node` removed, and `sign = 1` added):
+
+    * `signs_lib.standard_wood_groups`, inherited from `"default:sign_wall_wood"`
+    * `signs_lib.standard_steel_groups`, inherited from `"default:sign_wall_steel"`
+
+    Default: `signs_lib.standard_wood_groups`
+
+  * `sounds = something`
+
+    Sets the sign's sound profile, as usual.  In addition to whatever sound profile you may have in mind, there are two presets available:
+
+    * `signs_lib.standard_wood_sign_sounds`, inherited from `"default:sign_wall_wood"`
+    * `signs_lib.standard_steel_sign_sounds`, inherited from `"default:sign_wall_steel"`
+
+    Default: `signs_lib.standard_wood_sign_sounds`
+
+  * `drop = something`
+
+    Default: inherited from the `nodename` argument given to `signs_lib.register_sign()`
+
+  * `after_place_node = function(pos, placer, itemstack, pointed_thing, locked)`
+
+    See below under "Main functions".
+
+    Default: `signs_lib.after_place_node`
+
+  * `on_rightclick = function(pos)`
+
+    See below under "Main functions".
+
+    Default: `signs_lib.construct_sign`
+
+  * `on_construct = function(pos)`
+
+    See below under "Main functions".
+
+    Default: `signs_lib.construct_sign`
+
+  * `on_destruct = function(pos)`
+
+    See below under "Main functions".
+
+    Default: `signs_lib.destruct_sign`
+
+  * `on_receive_fields = function(pos, formname, fields, sender)`
+
+    See below under "Main functions".
+
+    Default: `signs_lib.receive_fields`
+
+  * `on_punch = function(pos)`
+
+    See below under "Main functions".
+
+    Default: `signs_lib.update_sign`
+
+  * `default_color = "string"`
+
+    Sets the default text color for this sign, in hexadecimal (`0-9`, `a-f`), from the standard Linux/IRC/CGA color palette.  Same as the colors shown in the sign's formspec.
+
+    Default: `"0"` (black)
+
+  * `number_of_lines = int`
+
+    Just what it says on the tin.  How many lines you can fit will vary with overall sign node size, font size, scaling, line spacing, etc.
+
+    Default: 6
+
+  * `horiz_scaling = float`
+
+    Scaling factor applied to the entity texture horizontal resolution.  Larger values increase the resolution.  Since a given sign's entity is always displayed at a fixed visual scale, increasing this setting squeezes more pixels into the same horizontal space, making the text appear narrower.
+
+    Default: 1.0
+
+  * `vert_scaling = float`
+
+    Scaling factor applied to the entity texture's vertical resolution.  Larger values increase the resolution, making the text appear shorter, and increasing the number of lines the sign can display.
+
+    Default: 1.0
+
+  * `line_spacing = int`
+
+    Number of blank pixels to add between lines.
+
+    Default: 1
+
+  * `font_size = int`
+
+    Selects which font to use, either 15 or 31 (pixel height).  This setting directly affects the sign's vertical resolution.
+
+    Default: 15
+
+  * `x_offset = int`
+
+    Starting X position in pixels, relative to the text entity UV map left edge.
+
+    Default: 4
+
+  * `y_offset = int`
+
+    Starting Y position in pixels, relative to the text entity UV map top edge.
+
+    Default: 0
+
+  * `chars_per_line = int`
+
+    Approximate number of characters that should fit on a line.  This, the selected font's average character width, and the `horiz_scaling` together set the horizontal resolution of the text entity's texture.
+
+    Default: 35
+
+  * `entity_info = something`
+
+    Describes the entity model and yaw table to use.  May be one of:
+
+    * A table specifying the two directly, such as:
+
+        ```lua
+        entity_info = {
+          mesh = "signs_lib_standard_wall_sign_entity.obj",
+          yaw = signs_lib.wallmounted_yaw
+        }
+        ```
+      * `signs_lib.standard_yaw` is also available as a yaw preset, if desired.
+
+    * `"standard"`: just use the standard wood/steel sign model, in wallmounted mode.  Equivalent to the example above.
+    * If this item is `nil`/not set, the sign will not have a formspec, basically all text-related settings will be ignored and/or omitted entirely, and no entity will be spawned for this sign, thus the sign will not be writable.  This is the default, and is of course what one would want for any sign that's just an image wrapped around a model, as in most of the signs in [my street signs mod](https://forum.minetest.net/viewtopic.php?t=20866).
+
+  * `allow_hanging = bool`
+
+    If `true`, allow the registration function to create a "hanging from the ceiling" version of the initial, base sign node.
+
+    Default: `nil`
+
+  * `allow_onpole = bool`
+
+    Allow creation of an on-pole variant of the base sign.
+
+    Default: `nil`
+
+  * `allow_onpole_horizontal = bool`
+
+    Allow creation of an on-horizontal-pole variant.  This flag is independent of `allow_onpole`; the mod may specify either or both.
+
+    Default: `nil`
+
+  * `allow_widefont = bool`
+
+    Just what it says on the tin.  If enabled, the formspec will have a little "on/off switch" left of the "Write" button, to select the font width.
+
+    Default: `nil`
+
+  * `locked = bool`
+
+    Sets this sign to be locked/owned, like the original default steel wall sign.
+
+    Default: `nil`
+
+### Example sign definition:
+
+```lua
+signs_lib.register_sign("basic_signs:sign_wall_glass", {
+	description = S("Glass Sign"),
+	tiles = {
+		{ name = "basic_signs_sign_wall_glass.png", backface_culling = true},
+		"basic_signs_sign_wall_glass_edges.png",
+	},
+	inventory_image = "basic_signs_sign_wall_glass_inv.png",
+	default_color = "c",
+	locked = true,
+	entity_info = "standard",
+	sounds = default.node_sound_glass_defaults(),
+	groups = {cracky = 3, oddly_breakable_by_hand = 3},
+	allow_hanging = true,
+	allow_widefont = true,
+	allow_onpole = true,
+	allow_onpole_horizontal = true,
+	use_texture_alpha = true,
+})
+```
+
+### Main functions used within a sign definition
+
+* `signs_lib.after_place_node(pos, placer, itemstack, pointed_thing, locked)`
+
+  Determines if the `pointed_thing` is a wall, floor, ceiling, or pole/post, and swaps the placed sign for the correct model.
+
+  * `locked`: if set to true, the sign's meta will be tweaked to indicate its ownership by the `placer`.
+
+* `signs_lib.construct_sign(pos)`
+
+  Sets up the sign's formspec and infotext overlay.
+
+* `signs_lib.destruct_sign(pos)`
+
+  Deletes the sign's entity, if any, when the sign is dug.
+
+* `signs_lib.receive_fields(pos, formname, fields, sender)`
+
+  This handles the text input and wide font on/off switch, logging any actions the user takes.  Bails-out silently if the user is not allowed to edit the sign.  See the standard Minetest lua_api.txt for details.
+
+* `signs_lib.update_sign(pos, fields)`
+
+  If the sign's writable, this deletes any entities in the sign's node space, spawns a new one, and renders whatever text is in the sign's meta.
+
+* `signs_lib.can_modify(pos, player)`
+
+  Returns `true` if the player is allowed to dig, edit, or change the font width of the sign.
+
+* `signs_lib.handle_rotation(pos, node, player, mode)`
+
+  Just what it says on the tin.  Limits the sign's rotation as needed (for example, a sign on a horizontal pole can only flip from one side to the other).
+
+  * `mode`: the screwdriver's mode, as passed from the screwdriver mod.
+
+  Returns `false` if the user tried to right-click with the screwdriver, `true` otherwise.
+
+* `signs_lib.make_selection_boxes(x_size, y_size, foo, x_offset, y_offset, z_offset, is_facedir)`
+
+  * `x_size`/`y_size`: dimensions in inches.  One node is 39.37 inches on a side.  This function uses inches instead of metric because it started out as a selection box maker for MUTCD-compliant signs, which are measured in inches.
+  * `x_offset`/`y_offset`/`z_offset`: shift the selection box (inches, defaults to centered, with the back face flush with the back of the node).
+  * `is_facedir`: if unset, the selection boxes will be created with the assumption that `paramtype2 = "wallmounted"` mode is set.  Any other value creates a selection box for "facedir" mode.
+  * `foo` is ignored (leftover from an argument that's long since been rendered obsolete.
+
+  Returns a table suitable for the `selection_box` node definition entry.
+
+#### Helper functions
+
+You probably won't need to call any of these directly.
+
+* `signs_lib.read_image_size(filename)`
+
+  Returns width and height of the indicated PNG file (return values will be gibberish if it isn't a PNG).
+
+* `signs_lib.split_lines_and_words(text)`
+
+  Just what it says on the tin.
+
+  Returns a table of lines, each line entry being a table of words.
+
+* `signs_lib.delete_objects(pos)`
+
+  Deletes all entities within the node space given by `pos`.
+
+* `signs_lib.spawn_entity(pos, texture)`
+
+  Spawns a new text entity at the given position and assigns the supplied `texture` to it, if any.
+
+* `signs_lib.check_for_pole(pos, pointed_thing)`
+
+  Attempts to determine if the `pointed_thing` qualifies as a vertical pole or post of some kind.
+
+  Returns `true` if a suitable pole/post is found
+
+* `signs_lib.check_for_horizontal_pole(pos, pointed_thing)`
+
+  Same idea, but for horizontal poles/posts.
+
+  Returns `true` if a suitable pole/post is found.
+
+* `signs_lib.check_for_ceiling(pointed_thing)`
+
+  Returns `true` if the `pointed_thing` appears to be the bottom of a node.
+
+* `signs_lib.check_for_floor(pointed_thing)`
+
+  Returns `true` if the `pointed_thing` appears to be the top of a node.
+
+* `signs_lib.set_obj_text(pos, text)`
+
+  Cooks the supplied `text` as needed and passes it to the entity rendering code.  Essentially, this is where rendering text into an image starts.
+
+## Options for pole/post nodes
+
+Occasionally, you'll run into a node that either looks like a pole/post, or has one in the middle of its node space (with room to fit a sign in there), but which isn't detected as a pole/post by the standard sign placement code.  In these situations, some kind of special check is needed.
+
+Supplying one or both of the following in the pole/post node's definition will cause `signs_lib` to skip its usual pole/post detection code, in favor of the supplied function(s).
+
+  * `check_for_pole = function(pos, node, def, pole_pos, pole_node, pole_def)`
+
+    If supplied, this function will be run when the mod is looking for a normal vertical pole/post.  Useful if the target node's orientation and/or shape determine what sides a sign can attach to.  For example, [Pipeworks](https://forum.minetest.net/viewtopic.php?pid=27794) uses this to figure out if a sign can be attached to a tube or pipe, depending on the tube's/pipe's number of junctions, and on its orientation and that of the placed sign.
+
+    * `def`: the placed sign's node defintion
+    * `pole_pos`: the target node's position 
+    * `pole_node`: the target node itself
+    * `pole_def`: its node definition
+
+    Your code must return `true` if the sign should attach to the target node.
+
+    If desired, this entry may simply be set to `check_for_pole = true` if a sign can always attach to this node regardless of facing direction (for example, [Home Decor](https://forum.minetest.net/viewtopic.php?pid=26061) has a round brass pole/post, which always stands vertical, and [Cottages](https://forum.minetest.net/viewtopic.php?id=5120) has a simple table that's basically a fencepost with a platform on top).
+
+  * `check_for_horiz_pole = function(pos, node, def, pole_pos, pole_node, pole_def)`
+
+    If supplied, this does the same thing for horizontal poles.
+
+    Your code must return `true` if the sign should attach to the target node.

MODELS.md

@@ -0,0 +1,94 @@
+# Anatomy of a sign model
+
+In the model files:
+
+* The base sign model should be designed to look like a flat board placed on one side of the node space.  The first material entry in the model file must be assigned to the front and back faces of the sign, the second material must be the sign's edges.  The filename should be something along the lines of `mymod_my_cool_sign.obj`.
+
+* For most signs that are allowed to sit on a vertical pole/post such as a fencepost, the pole-mounted model is just a copy of the base model, shifted back a bit, with a pole mount added to the back.  In these models, the third material in the model file must be assigned to the pole mount.  Name the model file the same as the base sign, but end the name with `_onpole`.  For example, `mymod_my_cool_sign_onpole.obj`.
+
+  For signs that allow mounting onto a horizontal pole (such as a Streets mod horizontal "bigpole"), the third material is still the vertical pole mount as above, but there must also be another the pole mount included, designed to wrap around such a pole/post, to which fourth material must be assigned.  In most cases, this alternate mount will just be a copy of the vertical pole mount, but rotated by 90°, and explicitly centered vertically in the node space.
+
+  While vertical and horizontal pole/post mounting options are independent in the code, if horizontal mounting is enabled, the on-pole model must still have *four* materials, even if the third material is unused, with the horizontal pole mount assigned to the fourth material.  In most situations, you'll probably have both vertical and horizontal pole mounts assigned to the third and fourth materials, as above.
+
+* For hanging sign models, the third material must be assigned to whatever it is that makes the sign look like it's hanging from the ceiling (default signs have a simple, flat rectangle, meant to show an image of a simple pair of chains).  The model file for these must be named the same as the base model, but ending with `_hanging`.  For example, `mymod_my_cool_sign_hanging.obj`.
+
+* For most signs, the sign entity will be a simple rectangle, sized just slightly smaller than the width and height of the sign, and centered relative to the sign face.  Its UV map should cover the entire image area, so that the image is shrunk down to fit within the sign's intended text area.  The rectangle must be positioned slightly in front of the sign (by 10 millimeters or so, due to engine position precision limitations).
+
+In your code:
+
+* For most sign types, `signs_lib` expects the first `tiles{}` entry in the sign definition to be the front-back texture (how the two textures are arranged within the image file is up to you, provided you match your sign model's UV map to the image layout).  The texture for the edges is the second entry.
+
+* For pole/post-mounted sign models, if applicable, the mod will ignore any further tile entries, and will directly set the third and fourth entries so that one of them is blank, while the other is set to the standard pole mount texture.  Which one it sets to the pole mount texture is what controls whether the vertical or horizontal mount is visible.
+
+* For sign models that hang from a ceiling, the third `tiles{}` entry must be set to a suitable image that fits whatever the parts are that suspend the sign from above.
+
+* Some signs may allow for more complex entity shapes, images, and UV mapping.  For example, [street_signs](https://forum.minetest.net/viewtopic.php?t=20866) has a standard city street intersection sign, the entity mesh for which consists of four simple rectangles.  Two of them are identically UV-mapped to the top portion of the texture image, and placed on either side of the upper half of the sign portion of the model.  The other two rectangles are also identically UV-mapped, but point to a lower section of the texture, and are rotated by 90° and shifted down in the model, to place them on either side of the lower half of the sign.  This causes the first line of text to appear on both sides of the upper half of the sign, with the second line of text appearing on both sides of the lower half.
+
+  Signs which don't use the simple models described above may not be compatible with the wall, ceiling, floor, or pole/post placement paradigm, but these things can be overridden/disabled in the node definition, if needed (as with the above intersection sign).
+
+## Blender users
+
+Start a new project, open the "Sidebar" (usually by pressing `N`), and scroll down to the Display section.  Set the Grid floor to 5 lines, Scale to 0.5, and Subdivisions to 8.
+
+This will create an environment where the world origin/center will be the center of a node space at (0,0,0), with major divisions at half-node intervals.  With the camera aligned to an axis, zooming in so that one node space fills the window should put the grid at 16 minor divisions per meter, so the grid will correspond to pixels in a typical 16px-apparent texture, if your UV mapping is correct (though a standard sign model uses 32px-apparent textures).
+
+Zoom in a bit more, and you'll see 256 divisions per meter, which can be thought of as 16 divisions per pixel.  This is where you'll want to be when positioning the sign entity.  In my configuration, the grid maxes out at 256 divisions per meter, even when zoomed in extremely close (this may be standard behavior).
+
+For signs that will use "wallmounted" mode, the model must be lying flat, with its front side facing up along Blender's Z axis, and centered on the X and Y axes.  The back of the sign should be exactly flush with the -0.5m mark on the Z axis, putting the whole sign below the world center.  The bottom edge of the sign faces the negative end of the Y axis.
+
+For signs that will use "facedir" mode, the sign must be upright, with its back flush with the +0.5m mark along the Y axis, centered on X/Z, with the bottom edge of the sign facing down along the Z axis.
+
+When adding materials, you MUST add them in the order you want them to appear in the exported model, as Blender provides no easy way to enforce a particular order if they come out wrong.
+
+If you look in the `models/` directory, you'll find the standard sign project file, `standard wooden sign.blend`, which contains all four variants of the standard sign model ("wallmounted" and "facedir", on-wall and on-pole), designed per the above requirements.  This file also contains both entity variants (on-wall and on-pole).  You'll notice that there are only two entities. This is because entity rotation has no relation to a node's `paramtype2`, so all standard signs use the same pair of upright on-wall and on-pole entities.
+
+To create the text entity model, assuming you're starting with a properly-UV-mapped, "wallmounted" base sign model with a simple one-piece flat design (comparable to, say, a standard wall sign or a [street_signs](https://forum.minetest.net/viewtopic.php?t=20866) warning diamond), do these steps:
+
+1. Snap the cursor to the world center, and set your viewport to Orthographic (usually `5` on the keypad).
+2. Switch to Object Mode.
+3. Select the sign model.
+4. Create a linked duplicate (`Alt-D` in my keymap), as distinct from a simple duplicate (`Shift-D`).  Blender will automatically select the duplicate and immediately go into move/translate mode to let you move it around.
+5. Without bothering to move the duplicate, press `R` `X` to go into rotatation mode around the X axis, which will also snap the duplicate back to its precise starting point in the process.
+6. Rotate the duplicate by 90°, thus putting it upright, with its back side flush with the +0.5m mark on the Y axis.
+7. With the duplicate still selected, switch to Edit Mode.
+8. Select only the duplicate sign's front face.
+9. Rotate your view to the right or left side (usually `3` or `Ctrl-3` on the keypad).
+10. Zoom in close enough to get the grid to show 256 divisions per meter, while keeping the selected face in view.
+11. Make a simple duplicate of the selected face (`Shift-D`).  Blender will automatically select just the new, duplicate face and go into move/translate mode.  Yeah, you're making a copy of a copy. 🙂
+12. Press `Y` to limit movement to just the Y axis, and move the duplicate face in the negative direction, while snapping to the grid.  Put it at least 2 minor divisions from the front of the sign (that is, 2/256 of a meter).
+13. Zoom out far enough to get the grid back to 16 divisions per meter, and align your view forward along the Y axis (usually `1` on the keypad).
+14. With the duplicate face still selected, scale it along X and/or Z until its edges are just within the limits of your sign model's intended text area. You could also directly move the face's edges inward, perhaps while snapping to the grid, if the sign shape lends itself to that.  Make sure the face stays properly-positioned (usually centered) relative to the sign's front!
+15. UV-map the duplicate face: `Mesh` → `UV Unwrap` → `Reset` followed by `Mesh` → `UV Unwrap` → `Project from view (bounds)`.
+16. Separate the duplicate face into a new object (`P` in my keymap, then `Selection` in the menu that pops-up).
+17. Switch to Object Mode
+18. In the model/data tree at the upper-right (well, on my layout), rename the original sign mesh, its duplicate, and the entity mesh to something meaningful.
+19. With only the text entity mesh selected, delete all materials from the list on the right, below the model/data tree (these were inherited from the base sign, and aren't needed with an entity mesh).
+20. Save your project file.
+21. Export the text entity mesh.  It is highly recommended that you export to "Wavefront (.obj)" format, as with most other Minetest node models.
+
+Note that the duplicate sign model you created can also be used directly as a "facedir" sign model, as well as being a position reference for the text entity mesh, so I suggest leaving it in your project file when you save.
+
+Use the following export settings (I strongly advise saving them as an Operator Preset; applies to all models and modes):
+
+	Forward: [_Z_Forward_]
+	Up:      [_Y_Up______]
+	🆇 Selection Only
+	🞎 Animation
+	🆇 Apply Modifiers
+	🞎 Use Modifiers Render Settings
+	🞎 Include Edges
+	🞎 Smooth Groups
+	🞎 Bitflag Smooth Groups
+	🆇 Write Normals
+	🆇 Include UVs
+	🞎 Write Materials
+	🞎 Triangulate Faces
+	🞎 Write Nurbs
+	🞎 Polygroups
+	🆇 Objects as OBJ Objects
+	🞎 Objects as OBJ Groups
+	🆇 Material Groups
+	🞎 Keep Vertex Order
+	(_Scale:________1.00_)
+	Path Mode: [_Auto____]
+

README.md

@@ -0,0 +1,57 @@
+# signs_lib
+
+This is kaeza's and my signs library mod, originally forked from PilzAdam's version and rewritten mostly by kaeza to include a number of new features, then rewritten again a couple more times (finding its way into my  [street_signs](https://forum.minetest.net/viewtopic.php?t=20866) mod for a while, where it developed nicely 🙂).
+
+The purpose of PilzAdam's original mod was to just provide a no-frills way make default signs show their text, via an entity placed right in front.  It was hacky, but it worked!
+
+While still hacky, this library is a modernized, feature-enhanced version of his code, which not only has visible text, but which allows that text to be colored, and displayed at any reasonable size, with any reasonable amount of text (as configured in a given node definition), with two font resolutions available. Plus, almost any sign can be attached to almost any kind of suitable pole or fencepost, or hung from a ceiling, in addition to being flat on a wall, floor, or ceiling.  Unlike previous incarnations of this code, signs' text is visible when the sign is flat on the floor or ceiling, as well as all other supported orientations.
+
+Without any other add-ons, this mod upgrades only the default wooden and steel signs.
+
+## Text formatting
+
+In general, text is rendered exactly as-written, left-to-right, top to bottom, without any translations or modifications.  The standard fonts support 7-bit ASCII as well as Cyrllic.
+
+That said, there are some basic text formatting options:
+
+* Line breaks may be inserted by simply hitting `Enter` twice.
+
+* Eight arrow symbols are available, occupying positions 0x81 through 0x88 in the character set.  These are produced by writing a `^` followed by a number `1-8`:
+
+  `^1` = `⬆`, `^2` = `⬈`, `^3` = `➡`, `^4` = `⬊`, `^5` = `⬇`, `^6` = `⬋`, `^7` = `⬅`, `^8` = `⬉`
+
+  Writing `^` followed by a letter `a-h` will produce double-wide versions of these arrows, in the same order.  These wide arrows occupy 0x89 to 0x91 in the character set.
+
+* A color may be specified in the sign text by using `#` followed by a single hexadcimal digit (`0-9` or `a-f`).  These colors come from the standard Linux/IRC/CGA color set, and are shown in the sign's formspec.  Any color change will remain in effect until changed again, or until the next line break.  Any number of color changes in any arbitrary arrangement is allowed.
+
+## Sign placement and rotation notes
+
+* Pointing at a wall while placing will, of course, place the sign on the wall.
+
+* For most signs, pointing at the ground while placing puts the sign flat on the ground.
+
+  Exception: if you have [basic_signs](https://forum.minetest.net/viewtopic.php?f=11&t=23289) installed, placing a default wooden sign on the ground will instead create a "yard" sign (basically a regular wooden sign mounted upright on a small stick).
+
+* For most signs, pointing at the ceiling while placing will put the sign flat against the ceiling.
+
+  Exception: default wood and steel signs will instead be hung from the ceiling by a pair of chains.  If you have [basic_signs](https://forum.minetest.net/viewtopic.php?f=11&t=23289), all standard signs created by it will do the same.
+
+* Pointing at an X or Z side of something that's detected as a pole/post will mount the sign onto that pole.  Note that the sign actually occupies the node space in front of the pole, since they're still separate nodes.  But, I figure, no one's going to want to use the space in front of the sign anyway, because doing so would of course obscure the sign, so it doesn't matter if the sign logically occupies that node space.
+
+* If a sign is on the wall or flat on the ground, the screwdriver will spin it from one wall to the next, in clockwise order, whether there's a wall to attach to or not, followed by putting it flat on the ground, then flat against the ceiling, then back to wall orientation.
+
+* If a sign is hanging from the ceiling (not flat against it), the screwdriver will just rotate it around its Y axis.
+
+* If a sign is on a vertical pole/post, the screwdriver will rotate it around the pole, but only if there's nothing in the way.
+
+* If a sign is on a horizontal pole/post, the screwdriver will flip it from one side to the other as long as there's nothing in the way.
+
+## Chat commands
+
+At present, only one command is defined:
+
+* `/regen_signs`
+
+This will read through the list of currently-loaded blocks known to contain one or more signs, delete all entities found in each sign's node space, and respawn and re-render each from scratch.
+
+The list of loaded, sign-bearing blocks is created/populated by an LBM (and trimmed by this command if any listed blocks are found to have been unloaded).

api.lua

@@ -841,52 +841,6 @@ function signs_lib.register_fence_with_sign()
 	minetest.log("warning", "[signs_lib] ".."Attempt to call no longer used function signs_lib.register_fence_with_sign()")
 end
 
---[[
-The main sign registration function
-===================================
-
-Example minimal recommended def for writable signs:
-
-signs_lib.register_sign("foo:my_cool_sign", {
-	description = "Wooden cool sign",
-	inventory_image = "signs_lib_sign_cool_inv.png",
-	tiles = {
-		"signs_lib_sign_cool.png",
-		"signs_lib_sign_cool_edges.png"
-	},
-	number_of_lines = 2,
-	horiz_scaling = 0.8,
-	vert_scaling = 1,
-	line_spacing = 9,
-	font_size = 31,
-	x_offset = 7,
-	y_offset = 4,
-	chars_per_line = 40,
-	entity_info = "standard"
-})
-
-* default def assumes a wallmounted sign with on-pole being allowed.
-
-*For signs that can support being on a pole, include in the def:
-	allow_onpole = true,
-	(defaults to disabled)
-
-*For signs that can support being on a horizontal pole, include in the def:
-	allow_onpole_horizontal = true,
-	(defaults to disabled)
-
-* onpole/onpole_horizontal are independent; one may be allowed without the other
-
-* "standard" entity info implies the standard wood/steel sign model, in
-  wallmounted mode.  For facedir signs using the standard model, use:
-
-	entity_info = {
-		mesh = "signs_lib_standard_wall_sign_entity.obj",
-		yaw = signs_lib.standard_yaw
-	},
-
-]]--
-
 function signs_lib.register_sign(name, rdef)
 	local def = table.copy(rdef)