[Mod] Item Documentation [0.6.0] [doc_items]

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

[Mod] Item Documentation [0.6.0] [doc_items]

by Wuzzy » Fri Aug 05, 2016 04:05

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.
I'm creating MineClone 2, a Minecraft clone for Minetest.
I made the Help modpack, adding in-game help to Minetest.
 

User avatar
MineYoshi
Member
 
Posts: 4267
Joined: Wed Jul 08, 2015 13:20
GitHub: MineYosh
IRC: MineYoshi
In-game: Kirby_Retro

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

by MineYoshi » Sat Aug 06, 2016 20:29

Nice.
+100
People talk about freedom of speech, so i'll say that God exists.
Open your eyes!! See The big unicorn conspiracy.!! :D The government has been lying to us about unicorns!!
"I've learned there are three things you don't discuss with people: religion, politics and the Great Pumpkin" - Linus Van Pelt
I'm the Officially 1st ABJist in the world ( ͡° ͜ʖ ͡°)
 

User avatar
BrunoMine
Member
 
Posts: 902
Joined: Thu Apr 25, 2013 17:29
GitHub: BrunoMine

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

by BrunoMine » Fri Aug 12, 2016 19:39

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: 2161
Joined: Mon Sep 24, 2012 15:01
GitHub: Wuzzy2
IRC: Wuzzy
In-game: Wuzzy

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

by Wuzzy » Fri Aug 12, 2016 21:41

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.
I'm creating MineClone 2, a Minecraft clone for Minetest.
I made the Help modpack, adding in-game help to Minetest.
 

User avatar
BrunoMine
Member
 
Posts: 902
Joined: Thu Apr 25, 2013 17:29
GitHub: BrunoMine

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

by BrunoMine » Fri Aug 12, 2016 23:13

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: 441
Joined: Tue Apr 14, 2015 01:59
GitHub: raymoo
IRC: Hijiri

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

by Byakuren » Sat Aug 13, 2016 02:23

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: 902
Joined: Thu Apr 25, 2013 17:29
GitHub: BrunoMine

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

by BrunoMine » Sat Aug 13, 2016 03:00

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: 441
Joined: Tue Apr 14, 2015 01:59
GitHub: raymoo
IRC: Hijiri

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

by Byakuren » Sat Aug 13, 2016 04:21

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: 2161
Joined: Mon Sep 24, 2012 15:01
GitHub: Wuzzy2
IRC: Wuzzy
In-game: Wuzzy

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

by Wuzzy » Sat Aug 13, 2016 07:52

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).
I'm creating MineClone 2, a Minecraft clone for Minetest.
I made the Help modpack, adding in-game help to Minetest.
 

User avatar
BrunoMine
Member
 
Posts: 902
Joined: Thu Apr 25, 2013 17:29
GitHub: BrunoMine

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

by BrunoMine » Sat Aug 13, 2016 14:11

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: 441
Joined: Tue Apr 14, 2015 01:59
GitHub: raymoo
IRC: Hijiri

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

by Byakuren » Sat Aug 13, 2016 20:10

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: 902
Joined: Thu Apr 25, 2013 17:29
GitHub: BrunoMine

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

by BrunoMine » Sat Aug 13, 2016 20:33

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: 2161
Joined: Mon Sep 24, 2012 15:01
GitHub: Wuzzy2
IRC: Wuzzy
In-game: Wuzzy

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

by Wuzzy » Sat Aug 13, 2016 20:50

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.
I'm creating MineClone 2, a Minecraft clone for Minetest.
I made the Help modpack, adding in-game help to Minetest.
 

User avatar
BrunoMine
Member
 
Posts: 902
Joined: Thu Apr 25, 2013 17:29
GitHub: BrunoMine

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

by BrunoMine » Sat Aug 13, 2016 22:01

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: 2161
Joined: Mon Sep 24, 2012 15:01
GitHub: Wuzzy2
IRC: Wuzzy
In-game: Wuzzy

Version 0.4.0

by Wuzzy » Sun Aug 14, 2016 06:36

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
I'm creating MineClone 2, a Minecraft clone for Minetest.
I made the Help modpack, adding in-game help to Minetest.
 

User avatar
BrunoMine
Member
 
Posts: 902
Joined: Thu Apr 25, 2013 17:29
GitHub: BrunoMine

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

by BrunoMine » Sun Aug 14, 2016 13:06

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: 2161
Joined: Mon Sep 24, 2012 15:01
GitHub: Wuzzy2
IRC: Wuzzy
In-game: Wuzzy

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

by Wuzzy » Sun Aug 14, 2016 13:31

Thanks, but I wouldn't recommend translating right now, can you please wait until I added intllib support?
I'm creating MineClone 2, a Minecraft clone for Minetest.
I made the Help modpack, adding in-game help to Minetest.
 

User avatar
BrunoMine
Member
 
Posts: 902
Joined: Thu Apr 25, 2013 17:29
GitHub: BrunoMine

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

by BrunoMine » Sun Aug 14, 2016 18:25

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: 2161
Joined: Mon Sep 24, 2012 15:01
GitHub: Wuzzy2
IRC: Wuzzy
In-game: Wuzzy

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

by Wuzzy » Sun Aug 14, 2016 21:26

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.
I'm creating MineClone 2, a Minecraft clone for Minetest.
I made the Help modpack, adding in-game help to Minetest.
 

User avatar
BrunoMine
Member
 
Posts: 902
Joined: Thu Apr 25, 2013 17:29
GitHub: BrunoMine

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

by BrunoMine » Sun Aug 14, 2016 22:11

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

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

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

by Wuzzy » Sun Aug 14, 2016 23:49

Yes. And thanks for your time. :-)
I'm creating MineClone 2, a Minecraft clone for Minetest.
I made the Help modpack, adding in-game help to Minetest.
 

twoelk
Member
 
Posts: 1092
Joined: Fri Apr 19, 2013 16:19

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

by twoelk » Thu Aug 18, 2016 01:40

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

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

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

by Wuzzy » Thu Aug 18, 2016 04:06

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.
I'm creating MineClone 2, a Minecraft clone for Minetest.
I made the Help modpack, adding in-game help to Minetest.
 

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

Version 0.5.0

by Wuzzy » Wed Aug 31, 2016 21:57

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
I'm creating MineClone 2, a Minecraft clone for Minetest.
I made the Help modpack, adding in-game help to Minetest.
 

twoelk
Member
 
Posts: 1092
Joined: Fri Apr 19, 2013 16:19

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

by twoelk » Thu Sep 01, 2016 15:36

probably not important ;-P
+ from debug.txt
 

User avatar
azekill_DIABLO
Member
 
Posts: 3458
Joined: Wed Oct 29, 2014 20:05
GitHub: azekillDIABLO
In-game: azekill_DIABLO

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

by azekill_DIABLO » Sun Sep 04, 2016 13:39

my mt does that for nearly all mods.
Your phone or window isn't wide enough to display the code box. If it's a phone, try rotating it to landscape mode.
Code: Select all
Hi, my username is azekill_DIABLO and i'm an exelent bug-maker(yeah...i know...i have a bad reputation)

azekill_DIABLO said: Mineyoshi+ABJ+Baggins= TOPIC HIJACKED.
My Mods and Stuff | Voxellar | VoxBox on GITHUB | M.I.L.A Monster engine
WEIRD MODDING CONTEST !!!
 

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

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

by Wuzzy » Sun Sep 04, 2016 15:46

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.
I'm creating MineClone 2, a Minecraft clone for Minetest.
I made the Help modpack, adding in-game help to Minetest.
 

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

Version 0.6.0

by Wuzzy » Sat Oct 22, 2016 15:15

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
I'm creating MineClone 2, a Minecraft clone for Minetest.
I made the Help modpack, adding in-game help to Minetest.
 

User avatar
azekill_DIABLO
Member
 
Posts: 3458
Joined: Wed Oct 29, 2014 20:05
GitHub: azekillDIABLO
In-game: azekill_DIABLO

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

by azekill_DIABLO » Sat Oct 22, 2016 19:15

+1
Your phone or window isn't wide enough to display the code box. If it's a phone, try rotating it to landscape mode.
Code: Select all
Hi, my username is azekill_DIABLO and i'm an exelent bug-maker(yeah...i know...i have a bad reputation)

azekill_DIABLO said: Mineyoshi+ABJ+Baggins= TOPIC HIJACKED.
My Mods and Stuff | Voxellar | VoxBox on GITHUB | M.I.L.A Monster engine
WEIRD MODDING CONTEST !!!
 

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

Future development plans

by Wuzzy » Thu Nov 03, 2016 17:07

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:

Your phone or window isn't wide enough to display the code box. If it's a phone, try rotating it to landscape mode.
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”
I'm creating MineClone 2, a Minecraft clone for Minetest.
I made the Help modpack, adding in-game help to Minetest.
 

Next

Return to Old Mods

Who is online

Users browsing this forum: No registered users and 7 guests

cron