[Mod] Item Documentation [0.6.0] [doc_items]

User avatar
Wuzzy
Member
Posts: 4786
Joined: Mon Sep 24, 2012 15:01
GitHub: Wuzzy2
IRC: Wuzzy
In-game: Wuzzy
Contact:

[Mod] Item Documentation [0.6.0] [doc_items]

by Wuzzy » Post

This thead is outdated. This mod is now released as part of a modpack: viewtopic.php?f=9&t=15912&p=240152

Automatically generated documentation of blocks, tools, weapons, and other items, with support for extension and writing your own item help texts

The goal is to tell the player as much about basically almost all items as possible, making it very convenient to look up simple things. This mod is out of the frustration that on servers you often see tons of weird items where you have no clue what they are good for and you have no place to look.

The ultimate goal behind this mod is that eventually all relevant items have a complete in-game documentation so no item leaves you confused.

For modders, this mod allows you to add custom help texts and even generated help texts by using the documented API. The more modders document their obscure, complex and weird items ( :D ), the easier Minetest will be to grasp for everyone. Thus, this mod depends on the collaboration of modders. Although the item help provided by this mod alone is already useful, but incomplete without usage of other mods.

Details
This mod is useful to learn the hard facts about practically all items, like how much damage weapon XYZ deals or whether you can dig that block.
This mod does NOT give you long explanations about how to use certain nontrivial things, like how to use the furnace from Minetest Game. This info is supposed to be provided by other mods like Minetest Game item help [doc_minetest_game].

This mod provides 3 categories for the Documentation System:

* Blocks (e.g. dirt, stone, wooden stair)
* Tools and weapons (e.g. wooden pickaxe, steel sword, screwdriver)
* Misc. items (e.g. dye, stick, flour)

Entries are automatically added. The information in the entries is mostly automatically generated. It countains information about a wide range of topics:

For blocks, it tells you about physics, digging properties, drops (including probabilities), liquid information, pointability, whether it glows in the dark, how light interacts with it, and much more.
For tools and weapons, it mostly tells you about mining capabilities and damage.
For all items, their range and stack size is shown, amoong some other minor facts.

Screenshot of an entry:
Image

As you see, it's useful to know, but pretty raw, it solely consists of auto-generated info as this mod doesn't know anything about Minetest Game. The entry will be enhanced when doc_minetest_game is installed. See:

Image

That's why support from other mod is important for the success of this mod and the Documentation System in general.

Extensibility
This mod also allows for mods to adding custom written description and usage help texts in freeform and even custom automatically generated texts for mod-specific information like flammability in Minetest Game.
The freeform texts are always split in a general description and a usage help text.

For modders, this mod enables you to add your own bits and pieces of documentation for your own items by adding custom descriptions, usage help texts and custom generated texts. An API documentation is already available.

Note if you only use doc_items, the item help may be sometimes a bit raw. It's still useful but incomplete, as crucial info on mining properties, or just simple explanations will be missing. This mod depends on the collaboration of other modders to add their own pieces of information. Note this mod is still in development.

Mods using this mod Feedback
I want to hear feedback on how useful you think the automatically generated texts are. For testing, disable doc_minetest_game to focus on the doc_items help only. Please tell me which texts you find confusing.
If you are a modder, and have questions about the API, please ask. I am also VERY interested in hearing in how easy or hard you think it is to use since I want to to make it as painless as possible to add help texts.

Download (and stuff)
Download: http://repo.or.cz/minetest_doc_items.gi ... 6df117.zip

Git project page and readme file: http://repo.or.cz/minetest_doc_items.git
License of everything: WTFPL
Mandatory dependency: Documentation System [doc] (version 0.6.0 or later)

See also
Lookup Tool (open block's help page by punching)
Last edited by Wuzzy on Thu Nov 17, 2016 22:02, edited 9 times in total.

User avatar
MineYoshi
Member
Posts: 5373
Joined: Wed Jul 08, 2015 13:20
Contact:

Re: [Mod] Item Documentation [0.3.0] [doc_items]

by MineYoshi » Post

Nice.
+100
Have a nice day! :D

User avatar
BrunoMine
Member
Posts: 1082
Joined: Thu Apr 25, 2013 17:29
GitHub: BrunoMine
Location: SP-Brasil
Contact:

Re: [Mod] Item Documentation [0.3.0] [doc_items]

by BrunoMine » Post

This can show definitions in different languages? This can be useful in international servers.

In some situations, it may be more interesting to create a website to explain these things from the server.

User avatar
Wuzzy
Member
Posts: 4786
Joined: Mon Sep 24, 2012 15:01
GitHub: Wuzzy2
IRC: Wuzzy
In-game: Wuzzy
Contact:

Re: [Mod] Item Documentation [0.3.0] [doc_items]

by Wuzzy » Post

Translation support is not implemented, but it is planned, just not for now. The strings are still way too much in flux as I would recommend to translate them. But this is definitely a requirement for version 1.0.0.

I have no idea on what kind of obscure situations a website might be better. Just name me one item which this mod couldn't explain properly (by principle). I think this mod together with doc_minetest_game already proofs that rather complex items can already be in-game documented with this system, like TNT. If you want to dispute this, you should give me some concrete examples where my approach would fail rather than throwing vague assertions at me. :P
This mod and the documentation system as a whole were born out of the frustration of the outdatedness and error-proniness of wikis. No matter how much worktime I put into it, there's always a number (like damage) which needs fixing. Especially all the metadata of items and blocks is very error-prone to write down manually, and this is exactly what this mod does automatically. IMO the community wiki is very inferior to the automatically-generated text approach when it comes to item help, and I say this as someone who edited TONS of stuff in the wiki. There is a such a vast amount of metadata you can extract from the item definition and it is simply much more efficient use of worktime and leads to more accurate texts when I simply display this extracted information, rather than going manually through source code to write a lengthy manual text once which gets outdated soon anyway.
I hope you can understand now why this mod exists. :-)

I will of course gladly take suggestions regarding the help texts created by doc_items.

User avatar
BrunoMine
Member
Posts: 1082
Joined: Thu Apr 25, 2013 17:29
GitHub: BrunoMine
Location: SP-Brasil
Contact:

Re: [Mod] Item Documentation [0.3.0] [doc_items]

by BrunoMine » Post

Wuzzy wrote:Just name me one item which this mod couldn't explain properly (by principle).
I have a GPS on my server (minemacro) and use a wiki of my website for explain this.
If you compare, the wiki is much more attractive and requires no intervention in the game (which already has many other mods to work)

Byakuren
Member
Posts: 818
Joined: Tue Apr 14, 2015 01:59
GitHub: raymoo
IRC: Hijiri
In-game: Raymoo + Clownpiece

Re: [Mod] Item Documentation [0.3.0] [doc_items]

by Byakuren » Post

BrunoMine wrote:This can show definitions in different languages? This can be useful in international servers.

In some situations, it may be more interesting to create a website to explain these things from the server.
Do you mean the mod should generate a website?
Every time a mod API is left undocumented, a koala dies.

User avatar
BrunoMine
Member
Posts: 1082
Joined: Thu Apr 25, 2013 17:29
GitHub: BrunoMine
Location: SP-Brasil
Contact:

Re: [Mod] Item Documentation [0.3.0] [doc_items]

by BrunoMine » Post

It seems that there is some communication problem here.

There are two different types of information items: how (what is the way to get an item) and why (what is the usefulness of this).
Some items have a very complex usefulness that needs to be described (This can not be generated dynamically). I believe this is the main feature of this mod (describe the usefulness of an item). Otherwise, it will look more like a craft_guide.

I know it yet but this mod can be interesting for players who want to know technical details about the items (damage, range, punch interval, etc). But I am interested much the usefulness of the item description (and this can not be generated dynamically as it depends on various factors external to the coding)

Byakuren
Member
Posts: 818
Joined: Tue Apr 14, 2015 01:59
GitHub: raymoo
IRC: Hijiri
In-game: Raymoo + Clownpiece

Re: [Mod] Item Documentation [0.3.0] [doc_items]

by Byakuren » Post

BrunoMine wrote:It seems that there is some communication problem here.

There are two different types of information items: how (what is the way to get an item) and why (what is the usefulness of this).
Some items have a very complex usefulness that needs to be described (This can not be generated dynamically). I believe this is the main feature of this mod (describe the usefulness of an item). Otherwise, it will look more like a craft_guide.

I know it yet but this mod can be interesting for players who want to know technical details about the items (damage, range, punch interval, etc). But I am interested much the usefulness of the item description (and this can not be generated dynamically as it depends on various factors external to the coding)
This mod allows modders to register custom documentation for their items/nodes, and have it integrated with the auto-generated information.
Every time a mod API is left undocumented, a koala dies.

User avatar
Wuzzy
Member
Posts: 4786
Joined: Mon Sep 24, 2012 15:01
GitHub: Wuzzy2
IRC: Wuzzy
In-game: Wuzzy
Contact:

Re: [Mod] Item Documentation [0.3.0] [doc_items]

by Wuzzy » Post

Indeed. Here is the entry for the GPS device from my orienteering mod (help text will be included in next Orienteering release):
Image

Both “Description” and “Usage help” are NOT automated. Without these fields, the item info on this would admittedly be pretty raw, that's why I included support for custom texts. But everything else on this page was automated. The naked doc_item mod would only include the automated texts (it does not know about the intention of the GPS device). doc_items together with the next version of Orienteering will result in the entry above (the freeform texts are part of Orienteering, not doc_items). :-)
I already have updated a few of my mods to include freeform text item desciptions for doc_items: dice2, origin, returnmirror, bedrock2, pep, teletool. And there's of course doc_minetest_game which includes a large set of custom texts only for Minetest Game.

I was perfectly aware that solely automatically information are not enough. This mod allows modders to register a general description and an usage help for any item, and those texts are indeed freeform text. Stuff like this can not automated, of course.

So, the “why” question is already answered. :-) But the mods in question have to play along (this is important).

What is interesting in your post is the “how” question (how to obtain it).
In my example of the GPS device, the answer is simple: It's crafted from a recipe. The Item Documentation mod will never include a fully-featured crafting guide or stuff like this, there are already other mods which do a much better than this.

I think for most items the question of “how” can be automated. If its by crafting, then its not the job by doc_items to list all crafting recipes, that is simply overkill.
I could maybe add a single sentence that this item may be obtained by crafting and that's it.
Another common way to obtain items is by drops. Like, you may obtain wheat seed from grass or the wheat plants. This information can also be fully automated, actually but it isn't supported yet. What is supported is displaying what a block drops by itself, but not the other way round (from which blocks it is dropped).
On the other hand, the crafting guide from Unified Inventory also lists drops, even the tricky probability-based ones (well, most of the time).

For the remaining items which are neither obtained by crafting nor drops users could either just use the general description field or maybe, if there is a bigger need, I add another optional freeform text field; but I'd rather add such a field when there are enough items which require a custom “obtain” description, not just for 1 or 2 items.
Os GPSs ajudam o jogador a chegar em lugares facilmente. Basta salvar o lugar em que você está naquele instante e então posteriormente você poderá configurar seu GPS para localizar os lugares que você já tenha salvo nele.

Códigos secretos de GPS
É possível usar o GPS para chegar em lugares secretos. Para isso digite o código secreto no GPS e clique em Localizar e então será ativado.
I don't understand anything of this, but this text looks short enough to perfectly fit into the description /usage help fields.


Oh, a final request: If you have any ideas for types of custom texts to add which go beyond “general description” and “usage help”, please share them. If they seem common or useful enough to me, I might include them (but I try not to overdo it with custom texts).

User avatar
BrunoMine
Member
Posts: 1082
Joined: Thu Apr 25, 2013 17:29
GitHub: BrunoMine
Location: SP-Brasil
Contact:

Re: [Mod] Item Documentation [0.3.0] [doc_items]

by BrunoMine » Post

I believe custom texts are more important because they allow players to understand how to play.
On the first topic you said that there are servers with many items which we do not know what it is for. That's exactly what I agree, but this can not be solved with technical data. The explanation of an item can only be well done trough an explanation with custom text.

I know the potential of your mod. But I believe this mod can be the solution we all needed in a matter of internationalization (in servers).

Byakuren
Member
Posts: 818
Joined: Tue Apr 14, 2015 01:59
GitHub: raymoo
IRC: Hijiri
In-game: Raymoo + Clownpiece

Re: [Mod] Item Documentation [0.3.0] [doc_items]

by Byakuren » Post

BrunoMine wrote:I believe custom texts are more important because they allow players to understand how to play.
On the first topic you said that there are servers with many items which we do not know what it is for. That's exactly what I agree, but this can not be solved with technical data. The explanation of an item can only be well done trough an explanation with custom text.

I know the potential of your mod. But I believe this mod can be the solution we all needed in a matter of internationalization (in servers).
Did you read the responses? There is support for custom text. Or is there a reason you think that the current support for custom text is not sufficient?
Every time a mod API is left undocumented, a koala dies.

User avatar
BrunoMine
Member
Posts: 1082
Joined: Thu Apr 25, 2013 17:29
GitHub: BrunoMine
Location: SP-Brasil
Contact:

Re: [Mod] Item Documentation [0.3.0] [doc_items]

by BrunoMine » Post

I thought I had already said.
Use custom text will occupy a lot of server memory. For this reason a separate wiki may be better.

User avatar
Wuzzy
Member
Posts: 4786
Joined: Mon Sep 24, 2012 15:01
GitHub: Wuzzy2
IRC: Wuzzy
In-game: Wuzzy
Contact:

Re: [Mod] Item Documentation [0.3.0] [doc_items]

by Wuzzy » Post

Oh boy. Are you serious?
We are not talking about lots of server memory here. These are just text files.

The mod “doc_minetest_game” depends on doc_items and contains many custom texts for a lot of items from Minetest Game.
The size of all text files together is ca. 47 KiB at this time. This is a joke. Media files like sounds and images have a much bigger impact, so server operators certiainly don't have to worry about the size of text files if they run into space issues.
For comparison, Minetest Game itself occupies (unpacked) about 3652 KiB or about 3.6 MiB.
There are no file size issues with the documentation mods.

User avatar
BrunoMine
Member
Posts: 1082
Joined: Thu Apr 25, 2013 17:29
GitHub: BrunoMine
Location: SP-Brasil
Contact:

Re: [Mod] Item Documentation [0.4.0] [doc_items]

by BrunoMine » Post

I did the calculations. You're right. I never thought the difference was so great (I have a paranoia with weak computers)

I'll help you build it (if you allow)

User avatar
Wuzzy
Member
Posts: 4786
Joined: Mon Sep 24, 2012 15:01
GitHub: Wuzzy2
IRC: Wuzzy
In-game: Wuzzy
Contact:

Version 0.4.0

by Wuzzy » Post

Version 0.4.0 released!
Changes:

- New factoid for blocks which are silent on walking over, mining or placing
- Interpret nodes which have “diggable=false” in their node definition as “not diggable”
- Hide other internal mining information if node is diggable instantly by any tool
- Automatically detect all mining groups; these are now simply all groups which can be dug by at least 1 tool in any mod. Mining groups no longer need to be manually defined by mods
- Enlarge space used by text
- Fix very incorrect display of range
- Range now shows whether a tool has “inherited” the range from hand (rather than having its own range)
- Improve liquid factoids by making it a bit more readable
- Fix often incorrect factoids about pointabilty of liquids (they are not non-pointable, but pointable by special tools only)
- Use bullet points
- API: Add some template descriptions and texts for common item purposes like food
- API: New function: doc.sub.items.add_suppressed_item_entries
- API: Function removed: doc.sub.items.add_mining_groups
- A couple of smaller changes and bugfixes I forgot to mention



Oh, and BrunoMine: I don't know what you mean with “helping me building it”. With exactly do you want to help? Of course I will gladly accept contributions if they're good. You could maybe help me with:
- General testing
- Proofreading
- Checking if the presented text is actually true (very important to me)
- Testing the API
- Telling whether the API documentation is understandable
- Telling me if any crucial information is missing
- Writing new factoids (little pieces of information which are automatically generated)
- Giving ideas for new factoids
- Whatever else seems important to you

User avatar
BrunoMine
Member
Posts: 1082
Joined: Thu Apr 25, 2013 17:29
GitHub: BrunoMine
Location: SP-Brasil
Contact:

Re: [Mod] Item Documentation [0.4.0] [doc_items]

by BrunoMine » Post

First I'll translate into Portuguese.

Edit:
Please make compatible with translations. (intllib)
Last edited by BrunoMine on Sun Aug 14, 2016 13:33, edited 1 time in total.

User avatar
Wuzzy
Member
Posts: 4786
Joined: Mon Sep 24, 2012 15:01
GitHub: Wuzzy2
IRC: Wuzzy
In-game: Wuzzy
Contact:

Re: [Mod] Item Documentation [0.4.0] [doc_items]

by Wuzzy » Post

Thanks, but I wouldn't recommend translating right now, can you please wait until I added intllib support?

User avatar
BrunoMine
Member
Posts: 1082
Joined: Thu Apr 25, 2013 17:29
GitHub: BrunoMine
Location: SP-Brasil
Contact:

Re: [Mod] Item Documentation [0.4.0] [doc_items]

by BrunoMine » Post

Sorry. I usually contributes in projects on GitHub through forks (pull requests)
How do I contribute to your project?
  • Forks (how?)
  • send files by email or forum
  • Commits directly in the project repo (If you give me permission)
  • Other (how?)

User avatar
Wuzzy
Member
Posts: 4786
Joined: Mon Sep 24, 2012 15:01
GitHub: Wuzzy2
IRC: Wuzzy
In-game: Wuzzy
Contact:

Re: [Mod] Item Documentation [0.4.0] [doc_items]

by Wuzzy » Post

Well, you could fork the project and then host your repository anywhere, including on repo.or.cz (but it really doesn't matter where). Forking is really nothing more than cloning the project and doing your changes. And in our case, also hosting your own repository publicly, so I can take your changes. Makes sense, right? ;-)

There is even a “fork” link on repo.or.cz.
When you're done, just give me a list of commits you want me to take and I look into what I could merge. No guarantees that I take them, however. For large tasks, it would be nice if you say beforehand what you try to do, to avoid later disappointments or duplicate work.

You could also just send in patches via e-mail.

I want to add intllib support by myselves, just not right now. First I want to make sure the strings are more or less stable.

User avatar
BrunoMine
Member
Posts: 1082
Joined: Thu Apr 25, 2013 17:29
GitHub: BrunoMine
Location: SP-Brasil
Contact:

Re: [Mod] Item Documentation [0.4.0] [doc_items]

by BrunoMine » Post

Okay. I will perform pull requests and then send the notice by email. (almikes@aol.com ?).
Correct?

User avatar
Wuzzy
Member
Posts: 4786
Joined: Mon Sep 24, 2012 15:01
GitHub: Wuzzy2
IRC: Wuzzy
In-game: Wuzzy
Contact:

Re: [Mod] Item Documentation [0.4.0] [doc_items]

by Wuzzy » Post

Yes. And thanks for your time. :-)

twoelk
Member
Posts: 1482
Joined: Fri Apr 19, 2013 16:19
GitHub: twoelk
IRC: twoelk
In-game: twoelk
Location: northern Germany

Re: [Mod] Item Documentation [0.4.0] [doc_items]

by twoelk » Post

could it be that wheat (stage8) and water are not recognised?

User avatar
Wuzzy
Member
Posts: 4786
Joined: Mon Sep 24, 2012 15:01
GitHub: Wuzzy2
IRC: Wuzzy
In-game: Wuzzy
Contact:

Re: [Mod] Item Documentation [0.4.0] [doc_items]

by Wuzzy » Post

Water: No, it should be automatically fetched as “Water Source”. Maybe you overlooked it?
Wheat: Yes it is not automatically recognized with doc_items alone. Install doc_minetest_game as well to make it visible, plus an actually useful help text on this plant. :-)
Doc_items assumes that the wheat plant should be hidden because it is not in creative inventory. For most things this heuristic works, but not always, that's where doc_minetest_game comes into play to clarify things.

User avatar
Wuzzy
Member
Posts: 4786
Joined: Mon Sep 24, 2012 15:01
GitHub: Wuzzy2
IRC: Wuzzy
In-game: Wuzzy
Contact:

Version 0.5.0

by Wuzzy » Post

Version 0.5.0 released!

Changelog:
- Compability with [doc] 0.5.0
- Automatically recognize all mining groups, mods no longer have to manually specify them
- Major rework of the block drop analysis: Many bugs and calculation errors fixed (especially for very complex drops), catch more corner cases, shorten the resulting text, reduce redundancy in text
- More detailed explanation of blocks which are replaced when building into (like Minetest Game grass)
- Explain the impact of falling blocks on other blocks in more detailed (e.g. what happens when a falling block falls into a torch)
- Detect unbreakable blocks like Minetest Game's unused Cloud block more reliably
- Complete rework of the concept of suppressed items (see documentation)
- Sort many node factoids based in importance (e.g. damage comes before light levels)
- Ignore newlines in original item descriptions (they broke the interface)
- Add very basic support for hidden entries (from [doc])
- API: Add support for custom item images
- A couple of other factual mistakes fixed everywhere
- Various grammar and spelling mistakes fixed

twoelk
Member
Posts: 1482
Joined: Fri Apr 19, 2013 16:19
GitHub: twoelk
IRC: twoelk
In-game: twoelk
Location: northern Germany

Re: [Mod] Item Documentation [0.5.0] [doc_items]

by twoelk » Post

probably not important ;-P
Spoiler
WARNING[Server]: Undeclared global variable "dig_immediate" accessed at ...-win32\bin\..\worlds\Romans\worldmods\doc_items\init.lua:448

Post Reply

Who is online

Users browsing this forum: No registered users and 1 guest