[Mod] Item Documentation [0.6.0] [doc_items]

[azekill_DIABLO]

my mt does that for nearly all mods.

[Wuzzy]

OK, this warning has been fixed recently, and it actually was a clue about a hidden bug in this mod. So thank you for reporting.

This is a warning about sloppy Lua code. Accessing globals out of the blue is often a clue about a hidden bug and is often caused by typos. It is not always directly a bug but this practice is very problematic, so the warning is totally justified; it can and should always be fixed; this warning should not be ignored by developers. Sadly, it is way too common in Minetest mods as this is a kind of sloppiness which can very easly sneak in if you don't check for it explicitly.
As users, don't think too much about it, just report this warning as this helps making the code more stable. This is true for all mods, not just this one.

[Wuzzy]

Version 0.6.0 released!
This release is mostly for ensuring compability with Documentation System 0.6.0. And bugfixes.

Changelog:
- Compability with Documentation System 0.6.0
- Entry text is now scrollable
- Hide item entries by default
- Item entries are revealed by digging, punching, placing, crafting, eating or holding them for a short moment in your inventory
- Clean up messy handling of line breaks. No more annoying/ugly double/triple/more line breaks
- Bugfix: Incorrect display of fall damage when fall_damage_add_percent < -100
- Code refactoring

[azekill_DIABLO]

+1

[Wuzzy]

I am going to plan a major deprecation and major simplification of the API of this mod.
I try to throw away most of the functions and instead move most of the help text specification directly into the item definition table when using minetest.register_node (and so on).

The main planned change is that I change how mods can add their help texts. Adding the help texts will be now just as simple as:

Code: Select all

minetest.register_node("example:dice", {
  description="Dice", -- <<<< Remember, this is just the default tooltip used by Minetest.
  x_doc_items_longdesc="A simple playing dice made out of wood with the numbers 1-6 on its sides.", -- <<<<< NEW!!!
  x_doc_items_usagehelp="Rightclick the dice to roll it.", -- <<<<< NEW!!!
  tiles = {"example_dice.png"},
  groups={dice=1, flammable=1},
  -- and so on …
}
)

IMO this is a much simpler practice make the source code much more readable and gives a higher motivation to add help texts to your items. :-) The current pracice of using functions has shown to be pretty unwieldy, especially for more complex mods with many nodes.

If you have already added doc_items support in your mod, sorry, but you probably have to update your mod when doc_items 1.0.0 comes out. But as far I know, nobody except me depended on doc_items so far, which is good.
But this also means that you can expect many re-releases of my mods around November 12.

I will probably not remove the existing functions before 1.0.0, but on 1.0.0 release, most functions will be removed to have a small clean and simple API. The reason why I want this is because I want to make it as simple as possible for modders to improve documentation of their own item. Maybe, just maybe I will even be establishing some sort of de-facto standard with this.
That is, that entering the long item explanation will be as normal as setting the default “description” field or the “tiles” field, etc.
My “dream” with this mod is that eventually every single non-trivial node is described in-game and unwieldy and outdated wikis or other external documents become a thing of the past.


In other development news, I have added a few settings in the dev version of this mod. One setting to expose the itemstring in the help pages. And one setting to toggle the group name mode.
I am currently not sure how to handle group names. (Reminder: Groups in Minetest are used for many things: To mark “joker” places in crafting recipes, to show that multiple items are somehow similar, to determine digging times, and a few other things.)
Currently, Minetest only has ugly group names like “cracky”, “oddly_breakable_by_hand”, “dig_immediate”, and so on. There is no official way to assign these groups more “friendly” (=for user) names and this mod attempts to fill this gap. So you (as of 0.6.0) see group names like “Leaves and Needles” instead of “leaves”. However, I figured out that this approach is also a bit problematic since I pretty much invented those alternative names and they are not used anywhere else. For example, the mod “Unified Inventory” shows the internal group names in the craft guide if a group item is used. If you hover a stone with a “G” symbol on the recipe for a furnace, you will currently see “Any item of the stone group” (“stone” being the internal name here).

Ultimately, I have decided (for now) to revert to the “internal” and ugly group names because they are at least canonical and equal everywhere.
What do you think? Should I go with the internal names like “oddly_breakable_by_hand” (until a better solution is found) or should I use the more “friendly” (but faked) names like “Hand-breakable” by default? Note that the current dev version has a setting for this.

Note that the dev version of doc_items and pretty much all other doc-related mods is a bit chaotic for now. As an user, please stick with the stable versions for now.


See also: Future dev. plans of the entire Documentation System “ecosystem”

[u34]

nice mod
+1