Introduce entry aliases for items

doc_items.lua

@@ -68,3 +68,50 @@ doc.sub.items.register_factoid("nodes", "misc", function(category_id, def)
 	return string.format("Example factoid: This item has the drawtype “%s”.", def.drawtype)
 end)
 
+
+--[[ USING ENTRY ALIASES
+	Sometimes, mods register multiple items for basically the same thing in different “states”.
+	One example is the furnace from Minetest Game (default:furnace and default:furnace_active).
+	If the node in all “states” is similar enough, you might consider to suppress the entries
+	of some of the entries in order to concentrate information on a single entry. If you do this, you
+	also have to register aliases since the lookup tool will stop working on nodes with suppressed
+	entries.
+	Suppressing entries may also be useful to combine large lists of similar items, but be careful
+	not to overdo it and throw away potentionally valuable information in the process.
+
+	The following code shows two nodes which changes its textures when punched.
+	For the player, doc_example:node2 is basically the same as doc_example:node1, only with a
+	different textures. Only one entry is created for both nodes.
+]]
+-- Node for the first “state”. This no
+minetest.register_node("doc_example:node1", {
+	description = "doc_example test node",
+	_doc_items_longdesc = "When rightclicked, the textures of this block change.",
+	tiles = {"doc_example_1.png"},
+	on_rightclick = function(pos, node, clicker, itemstack, pointed_thing)
+		minetest.set_node(pos, {name="doc_example:node2"})
+	end,
+	groups = {dig_immediate=2},
+})
+
+-- Node for the second “state”. No entry will be created for this.
+minetest.register_node("doc_example:node2", {
+	description = "doc_example test node",
+	-- Suppresses the entry
+	_doc_items_create_entry = false,
+	-- Note that we also do not add _doc_items_longdesc or similar fields,
+	-- since these fiel
+	tiles = {"doc_example_2.png"},
+	on_rightclick = function(pos, node, clicker, itemstack, pointed_thing)
+		minetest.set_node(pos, {name="doc_example:node1"})
+	end,
+	groups = {dig_immediate=2, not_in_creative_inventory=1},
+	drop = "doc_example:node1",
+})
+
+--[[ Register an alias to make sure the lookup tool still works.
+If this is NOT done, the lookup tool will fail when it is
+sed on doc_example:node2. ]]
+doc.add_entry_alias("nodes", "doc_example:node1", "doc_example:node2")
+
+-- Another example of this concept in action be seen in the mod “doc_identifier”.