Update docs, add workflow badges (#38)

* Some luatool, tubetool and sharetool docs

* Update main README.md file

* Workflow badges

Co-authored-by: SX <sx@minetest>

README.md

@@ -1,43 +1,52 @@
+![luacheck](https://github.com/S-S-X/metatool/workflows/luacheck/badge.svg)
+![busted](https://github.com/S-S-X/metatool/workflows/busted/badge.svg)
+
 ## What metatool? And why?
 
 Metatool Minetest mod provides API for registering metadata manipulation tools and other tools primarily focused on special node data operations.
 
-## How to use metatool:tubetool
-
-Tubetool is made available for cloning pipeworks node configurations like sorting tube configuration.
-Other registered metatool tools might work in similar way allowing to copy data from one node to another.
+## How to use tools
 
-#### Copy configuration from pipeworks node
+Basic functionality for tools come as two primary functions: copy and paste.
 
-Hold wand in your hand and point node that you want to copy configuration from, hold special or sneak button and left click on node to copy settings.
-Chat will display confirmation message when configuration is copied to wand.
+* Special+left click for copy function.
+* Left click for paste function.
+* Sneak+left click for optional "info" function which might not be available for all nodes.
+  If third function is not implemented then sneak+left click triggers copy function.
 
-#### Apply copied configuration to pipeworks node
+For more complete and tool specific documentation go see README.md files in subdirectories.
 
-Hold wand containing desired configuation in you hand and point node that you want apply settings to.
-Left click with wand to apply new settings, chat will display confirmation message when settings are applied to pointed node.
+* Metatool API [API_REFERENCE.md](API_REFERENCE.md)
+* Luatool [luatool/README.md](luatool/README.md)
+* Tubetool [tubetool/README.md](tubetool/README.md)
+* Sharetool [sharetool/README.md](sharetool/README.md)
 
-## How to add supported nodes
+## How to add supported nodes for tools
 
 Example to add support for technic:injector
 
 ```
 local definition = {
-	group = "technic injector",
-	copy = function(node, pos, player)
-		-- add code for copying data from pointed injector node
-		-- for example get some metadata and store it in wand memory
-		-- also set some nice description of wand
-		local meta = minetest.get_meta(pos)
-		return {
-			description = "This wand has some injector data",
-			myvalue = meta:get_string("owner")
-		}
-	end,
-	paste = function(node, pos, player, data)
-		local meta = minetest.get_meta(pos)
-		meta:set_string("owner", data.myvalue)
-	end,
+	name = "sci",
+	nodes = "technic:injector",
+	tooldef = {
+		group = "technic injector",
+		copy = function(node, pos, player)
+			-- Get some metadata from injector node and store it within
+			-- tool memory and also set new nice description for tool.
+			local meta = minetest.get_meta(pos)
+			return {
+				description = "This wand has some injector data",
+				myvalue = meta:get_string("owner")
+			}
+		end,
+
+		paste = function(node, pos, player, data)
+			-- Restore SCI metatdata from tool memory
+			local meta = minetest.get_meta(pos)
+			meta:set_string("owner", data.myvalue)
+		end,
+	}
 }
 ```
 
@@ -47,12 +56,6 @@ Supply above definition for tool, mytool variable is returned from metatool:regi
 mytool:load_node_definition(definition)
 ```
 
-or by fully qualified tool name
-
-```
-metatool:register_node("metatool:tubetool", definition)
-```
-
 That's all, now you can use tubetool wand to copy/paste metadata owner value from one injector to another.
 
 ## API methods
@@ -151,11 +154,9 @@ Above protection_bypass_write parameters might not work if this is overridden.
 
 `metatool:paste(node, pos, player, data, group)`
 
-## Registered nodes included with tubetool
-
-In nodes subdirectory there is few predefined pipeworks components.
-
 ## Minetest protection checks
 
-Protection checks are done automatically for all wand uses, node registration does not need any protection checks.
-Wand cannot be used to read settings from protected nodes and it cannot be used to write settings to protected nodes.
+Protection checks are done automatically for all tool uses, node registration does not need any protection checks.
+By default tools cannot be used to read data from protected nodes and cannot be used to write data to protected nodes.
+
+Tools can override protection settings and also configuration can be used to override default protection behavior.

luatool/README.md

@@ -0,0 +1,44 @@
+## Luatool basics
+
+Luatool is made available for copying code from one node to another.
+For example it can be used to copy code from one luacontroller to another.
+
+#### Copy configuration from pipeworks node
+
+Hold tool in your hand and point node that you want to copy code from, hold special or sneak button and left click on node to copy code.
+Chat will display confirmation message when code is copied into tool memory.
+
+#### Apply copied configuration to pipeworks node
+
+Hold tool containing desired code in you hand and point node that you want apply code to.
+Left click with tool to apply new settings, chat will display confirmation message when code is applied to pointed node.
+
+## Nodes compatible with luatool
+
+* mesecons_luacontroller:luacontroller
+* mesecons_microcontroller:microcontroller
+* pipeworks:lua_tube
+
+## Minetest protection checks (default settings)
+
+Protection checks are done automatically for all tool uses, node registration does not need any protection checks.
+Tool can be used to read code from protected nodes but it cannot be used to write code to protected nodes.
+
+## Configuration
+
+Luatool configuration keys with default values:
+
+```
+metatool:luatool:nodes:luacontroller:protection_bypass_read = interact
+metatool:luatool:nodes:microcontroller:protection_bypass_read = interact
+metatool:luatool:nodes:luatube:protection_bypass_read = interact
+```
+
+Luatool configuration keys without any default values:
+
+```
+metatool:luatool:privs
+metatool:luatool:nodes:luacontroller:protection_bypass_write
+metatool:luatool:nodes:microcontroller:protection_bypass_write
+metatool:luatool:nodes:luatube:protection_bypass_write
+```

sharetool/README.md

@@ -0,0 +1,67 @@
+## Sharetool basics
+
+Sharetool is moderator tool that can be used to claim  ownership of various nodes and
+then transfer ownership to sppecial shared user account.
+
+For example it can be used to take ownership of book, then change text in book and
+return book to shared account allowing multiple users to write into same book.
+
+Another use is to manage shared travelnet networks without full travelnet admin privileges,
+place and configure travelnet and then transfer ownership to shared account.
+
+#### How to get sharetool
+
+Sharetool is not craftable and using it requires selected privileges.
+Anyone who does have privileges to use sharetool can also get sharetool with chat command:
+
+`/metatool:give metatool:sharetool`
+
+#### Claim ownership
+
+Hold tool in your hand and point node that you want to claim, hold special or sneak button and left click on node to claim ownership.
+Chat will display confirmation message when node ownership is transfered to your account.
+
+#### Return ownership to shared account
+
+Hold tool in your hand and point node that you want to be owned by shared account.
+Left click with tool, chat will display confirmation message when pointed node owner is changed.
+Pointed node is now owned by shared account and node is marked as shared.
+
+## Nodes compatible with sharetool
+
+* homedecor:book
+* travelnet:elevator
+* travelnet:travelnet
+* travelnet:travelnet_private
+* locked_travelnet:travelnet
+
+Planned but not yet added (https://github.com/S-S-X/metatool/issues/16):
+
+* Mission block
+* Mapserver POI
+* Mapserver markers
+
+## Minetest protection checks (default settings)
+
+Tool cannot be used without ban privilege.
+Tool uses special customized protection checks and can bypass protections if node is marked as shared or is owned by shared account.
+
+## Configuration
+
+Sharetool configuration keys with default values:
+
+```
+metatool:sharetool:privs = ban
+metatool:sharetool:shared_account = shared
+```
+
+Sharetool configuration keys without any default values:
+
+```
+metatool:sharetool:nodes:travelnet:protection_bypass_read
+metatool:sharetool:nodes:travelnet:protection_bypass_write
+metatool:sharetool:nodes:book:protection_bypass_read
+metatool:sharetool:nodes:book:protection_bypass_write
+metatool:sharetool:nodes:poi:protection_bypass_read
+metatool:sharetool:nodes:poi:protection_bypass_write
+```

tubetool/README.md

@@ -0,0 +1,22 @@
+## How to use metatool:tubetool
+
+Tubetool is made available for cloning pipeworks node configurations like sorting tube configuration.
+Other registered metatool tools might work in similar way allowing to copy data from one node to another.
+
+#### Copy configuration from pipeworks node
+
+Hold wand in your hand and point node that you want to copy configuration from, hold special or sneak button and left click on node to copy settings.
+Chat will display confirmation message when configuration is copied to wand.
+
+#### Apply copied configuration to pipeworks node
+
+Hold wand containing desired configuation in you hand and point node that you want apply settings to.
+Left click with wand to apply new settings, chat will display confirmation message when settings are applied to pointed node.
+
+## Registered nodes included with tubetool
+
+In nodes subdirectory there is few predefined pipeworks components.
+
+## Minetest protection checks
+
+Protection checks are done automatically for all wand uses.