Add tool to generate usage readme

README.md

@@ -27,10 +27,13 @@ It also adds these server commands:
 There's also a setting `schemedit_export_lua` to enable automatic export to .lua files.
 
 ## Usage help
-Usage help can be found when you use the optional Help modpack (mods `doc` and `doc_items`).
+This mod assumes you already have a basic understanding about how schematics in Minetest work.
-The “server” privilege is required for most features.
+If not, refer to the Minetest Lua API documentation to understand more about schematics.
 
-You should also refer to the Minetest Lua API documentation to understand more about schematics.
+To learn how to use all the items in this mod, read `USAGE.md`.
+
+You can also find the same help texts in-game if you if you use the optional Help modpack
+(mods `doc` and `doc_items`).
 
 ## License of everything
 MIT License

init.lua

@@ -5,6 +5,9 @@ local schemedit = {}
 
 local DIR_DELIM = "/"
 
+-- Set to true to enable `make_schemedit_readme` command
+local MAKE_README = false
+
 local export_path_full = table.concat({minetest.get_worldpath(), "schems"}, DIR_DELIM)
 
 -- truncated export path so the server directory structure is not exposed publicly
@@ -1369,3 +1372,7 @@ minetest.register_chatcommand("mts2lua", {
 	end,
 })
 end
+
+if MAKE_README then
+	dofile(minetest.get_modpath("schemedit")..DIR_DELIM.."make_readme.lua")
+end

make_readme.lua

@@ -0,0 +1,66 @@
+-- This file adds a command for generating the schemedit usage help readme
+-- file, in Markdown format. The text is extracted from the metadata of
+-- the items. This is only used for development purposes, after the
+-- help text of any of the items was changed.
+
+-- How to use: Temporarily set MAKE_README to true in init.lua, then
+-- start the game as admin and run “/make_schemedit_readme”. Copy the
+-- generated file back to the mod directory (USAGE.md).
+
+-- Everything here is intentionally NOT translated because it is for text
+-- files only.
+
+
+-- Extract text from item definition
+local get_text = function(item, field)
+	local text = minetest.registered_items[item][field]
+
+	-- Remove translation escapes
+	text = string.gsub(text, "\x1BE", "")
+	text = string.gsub(text, "\x1B%(T@schemedit%)", "")
+
+	-- Fix Markdown syntax error
+	text = string.gsub(text, "schematic_override", "`schematic_override`")
+	return text
+end
+
+
+-- Schemedit items to generate the readme from
+local items = { "creator", "void", "probtool" }
+
+minetest.register_chatcommand("make_schemedit_readme", {
+	description = "Generate the schemedit usage help readme file",
+	privs = {server=true},
+	func = function(name, param)
+
+		local readme = "## Usage help".."\n"
+		readme = readme .. "In this section you'll learn how to use the items of this mod.".."\n"
+		readme = readme .. "Note: If you have the `doc` and `doc_items` mods installed, you can also access the same help texts in-game (possibly translated).".."\n\n"
+
+		local entries = {}
+		for i=1, #items do
+			local item = items[i]
+			local desc = get_text("schemedit:"..item, "description")
+			local longdesc = get_text("schemedit:"..item, "_doc_items_longdesc")
+			local usagehelp = get_text("schemedit:"..item, "_doc_items_usagehelp")
+
+			readme = readme .. "### "..desc.."\n"
+			readme = readme .. longdesc .."\n\n"
+			readme = readme .. "#### Usage\n"
+			readme = readme .. usagehelp .."\n\n"
+		end
+
+		local path = minetest.get_worldpath().."/schemedit_readme.md"
+		local file = io.open(path, "w")
+		if not file then
+			return false, "Failed to open file!"
+		end
+		local ok = file:write(readme)
+		file:close()
+		if ok then
+			return true, "File written to: "..path
+		else 
+			return false, "Failed to write file!"
+		end
+	end
+})