[Modpack] Help [1.4.3] [doc]

[Wuzzy]

In-game help about gameplay basics, items and potentionally any other topic of interest. Highly extensible.

The goal of this modpack is to make using Minetest and mods easier for both newcomers and advanced users.
It makes it easier for newcomers by making help more accessible.
It makes life easier for advanced user by making it more convenient to use, by centralizing the help where you most need it: Inside the game.
This modpack will also make modder's life easier by allowing them to add help texts directly into mods (see more about this below).

Mod list

• Basic Help [doc_basics]: Help entries about Minetest, controls, gameplay and other basic topics
• Item Help [doc_items]: Help entries for items (blocks, tools, weapons, crafting items, other items)
• Encyclopedia [doc_encyclopedia]: Item to access the help
• Lookup Tool [doc_identifier]: Tool to identify and show entries for pointed things
• Documentation System [doc]: User interface and core API. Allows mods to add help entries and categories of practically anything

See also: Minetest Game item help (recommended if you play Minetest Game)

Screenshot

entry3.png (66.43 KiB) Viewed 4508 times

Basic concepts

The help is very simply organized:

• The help is organized in entries which can be formatted quite freely
• Categories group multiple entries together
• For gameplay reasons (e.g. to avoid spoilering), certain entries can be hidden to be revealed later

How to use
To open the help, …

• Use the encyclopedia item,
• or click on the question mark button in one of the mods Unified inventory, Inventory++, or Simple Fast Inventory Buttons.
• Or use the command “/helpform”.

The rest should be relatively self-explanatory. Just click through the categories and entries.

In the list of entries, entries which you haven't viewed yet are in cyan. Some entries may be hidden and could be revealed later. Whenever you revealed a new item, a sound is played. Players with the help_reveal privilege can use the command “/help_reveal” to reveal all entries instantly.

Help pages for items are revealed as soon as you: Punch them, mine them, craft them, carry them in your inventory, or use the lookup tool on then.

Encyclopedia

enycl.png (14.28 KiB) Viewed 4508 times

A simple item to open the help. Just wield and leftclick.

Spoiler

There are two crafting recipes, choose your favourite:

Code: Select all

SS_
S_S
SS_

Code: Select all

B
B
B

S=Stick (any member of the “stick” group)
B=Book (from Minetest Game)
_=Nothing

Itemstring: doc_encyclopedia:encyclopedia

Lookup Tool

lookup.png (27.97 KiB) Viewed 4508 times

The lookup tool is a simple tool which shows an appropriate help entry for all or almost all pointable things. It will also automatically reveal the help entries of previously unknown items.

Spoiler

There are two crafting recipes, choose your favourite:

Code: Select all

SS
_S
S_

Code: Select all

G
S

S=Stick (any member of the “stick” group)
G=Glass (from Minetest Game)
_=Nothing

Itemstring: doc_identifier:identifier

Additional information

Spoiler

A few basic configuration options are available in the “Advanced settings” menu of Minetest. You can opt in to show the itemstrings of items in the item help pages, and to show more “friendly” group names (like “Hand-breakable” instead of “oddly_breakable_by_hand”.

Spoiler

If you want dive in right into the action, I have made an example mod “doc_example” with many explanations. You can find it here: https://codeberg.org/Wuzzy/minetest_doc_example

This rest of this section is just an overview of what you can do with all this. Read the README.md files of the mods for the real thing.

The modpack has been designed to be a viable choice for most players and most usual games and you should be able to install it just fine without modifications.
But it is also very flexible: For games which break with a lot of the core assumptions of Minetest, you can safely exclude or replace some or all of the doc-dependant mods (doc_items, doc_basics, doc_identifier) and start with an empty help, adding all categories and entries by yourselves.

Usual workflow

• For each item you add, you should also consider adding manually written help texts with doc_items
• For each entity you add, you also probably should add a) a help entry and b) accociate the entity with this help page with doc_identifier, so that using the Lookup Tool on it will work
• When you're done, proofread all of your entries and check if all important things have an appropriate help page. Use /doc_reveal to see all entries
• For very unique new concepts, you can add your own help categories

Here is a longer overview of the modpack mods:

doc
This contains the core API and the formspec. Most importantly, you can directly add categories and entries with it, but it also contains a bunch of utility functions. With doc alone, you have a completely empty help without any entries and categories. All other mods in this modpack depend on this mod.

doc_items
Generates the item help. Adds the categories “Blocks”, “Tools and weapons” and “Misc. items”. All entries are partially built automatically (based on the item's metadata, such as stack size, pointing range, damage, group memberships, etc.) and partially manually written (optional).
This mod has its own API for adding manually written information on the items in a super-simple manner (you often only need to add additional fields to your item definition). You also need the API to filter out items where adding entries would be unneccessar or redundant. The automatically-written texts can also be extended, but this part of the mod is still WIP.
This mod automatically adds the entries for items without any intervention. However, the resulting entries are very bare-bones, only containing the automatically generated texts (obviously).

doc_identifier
This mod is able to automatically find the correct help page for nodes, dropped items and players.
For custom entities, the mod can also show appropirate entries, but this must be explicitly defined by using this mod's very small API, to connect the entity to the help entry. The tool is unable to show a help page for entities where this has not been made.

doc_encyclopedia
Just adds the encyclopedia item. No API.

doc_basics
Just adds static help texts and images. No API.

Repos
This modpack and all of its mods are free software, licensed under the MIT License.

Here are the Git repositories for the mods (links lead to project pages with a long README):

• doc: https://codeberg.org/Wuzzy/minetest_doc.git
• doc_items: https://codeberg.org/Wuzzy/minetest_doc_items.git
• doc_identifier: https://codeberg.org/Wuzzy/minetest_doc_identifier.git
• doc_encyclopedia: https://codeberg.org/Wuzzy/minetest_doc ... opedia.git
• doc_basics: https://codeberg.org/Wuzzy/minetest_doc_basics.git
• doc_example: https://codeberg.org/Wuzzy/minetest_doc_example.git

The modpack itself has another repository, located at:
https://codeberg.org/Wuzzy/minetest_doc_modpack.git

The modpack repository includes the mods as Git submodules.

Spoiler

• doc: 1.3.2
• doc_items: 1.3.2
• doc_basics: 1.2.2
• doc_encyclopedia: 1.3.2
• doc_identifier: 1.3.2

All version numbers follow SemVer 2.0.0.

Spoiler

The following game uses at least one of the mods found in this modpack:

• MineClone 2

The following mods (incomplete list) use this modpack to provide their own help texts about the stuff they add (mostly item help texts):

• Flying Carpet [flying_carpet]
• Watering Can [wateringcan]
• Magic Beans—Wuzzy's Fork [magicbeans_w]
• Dice [dice2]
• Pep: Player Effects Potions [pep]
• The Origin [origin]
• Point Teleporters [teletool]
• Slime Blocks and Liquids [slimenodes]
• Bedrock Layer [bedrock2]
• Mirror of Returning [returnmirror]
• Surprise Blocks [tsm_surprise]
• Easy Vending Machines [easyvend]
• Minetest Game Plus [mtg_plus]
• Minetest Game item help [doc_minetest_game] (does not add any own gameplay content, only provides help for Minetest Game)
• Modular tunnel boring/building machine [digtron]
• Path marker signs [breadcrumbs]
• QA-Block [qa_block]
• Smart Inventory [smart_inventory]
• [doc_reveal_chest]

For example, [easyvend] makes use of the [doc_items] mod to add long explanations for the vending and depositing machines, extending the default help entries on these blocks.

Spoiler

This mod was born out of the frustration with the way on how many mods are documentated:

• Complex items are often not explained at all or just poorly. Which means newbies have a hard time in even using an item in the first place
• Some modders try to be helpful by including additional help in the “description” field of the item (tooltip). I think this is the wrong approach as this just makes tooltips ugly and unneccessarily large. doc_items helps modders by adding additional fields for the “real” help texts
• Help is often scattered: In forum posts, in wikis, and other places. This makes it a long and tedious (and often frustrating) work to even get started. Don't get me wrong: I do like complex games, bu
• Maintaining wikis is especially time-consuming and tedious for items, especially for all the internal information like digging times, damage or luminance. Experience shows that this is a never-ending and frustrating work, also it becomes outdated very quickly and is error-prone. The mod “doc_items” helps modders by automatically extracting all the “boring” stuff so that you can concentrate on the actual game concepts
• On servers, the situation is very bad: Many servers are pretty complex and include many different mods. It is hard, time-consuming and very frustrating even for advanced users to find the help of each of the mods
• Existing help is often incomplete or of low quality or poorly maintained.
• In practice, you often cannot just quickly lookup even the simplest things like the damage of a sword

I have the strong opinion that all good games should also have a strong focus on in-game help. Minetest, and especially Minetest Game currently heavily rely on external resources such as wikis, which are often error-prone. From the user perspective, being forced to use wikis (and other external stuff) breaks the “flow” (or call it “immersion” if you want) if you have to go to wikis each time you want to look up the damage of a sword.

One thing which this mod is NOT concerned about are crafting recipes. Other mods are readily available for this task. I recommend Unified Inventory [unified_inventory] or, to a lesser extent, Crafting Guide [craftguide].

Download and stuff

• Downloads: from ContentDB here:
  • Documentation System (core)
  • Basic help
  • Item help
  • Encyclopedia
  • Lookup Tool
• For Minetest 5.0.0 or later
• Dependencies: None.
• Optional dependencies:
  • Unified Inventory [unified_inventory] (for a button)
  • Simple Fast Inventory Buttons [sfinv_buttons] (for a button)
  • Inventory++ [inventory_plus] (for a button)
  • Central Message [central_message] (for notification messages when you reveal entries)
  • [default] from Minetest Game (for optional crafting recipes)
• License of everything: MIT License
• Author of all mods: Wuzzy
• Repository command for developers: git clone https://codeberg.org/Wuzzy/minetest_doc_modpack.git --recurse-submodules

[Wuzzy]

Hi everyone! For those who already know the Documentation System, here I give you some information about the new modpack and what is new, as compared to the previous version of the individual mods.

For those who are new to this Documentation System, you can safely ignore the this post. The post above has everything you need to know.

This modpack is a re-organization of the previously released mods [doc], [doc_items] and [doc_identifier].
Also, this is the first public release of the mod doc_basics, a mod which includes basic help texts for Minetest. See the first post for a screenshot.

Also, this is the release of version 0.7.0 of each of those mods. I will eventully phase out the existing threads of the individual mods and request to move them to the Old Mods subforum. Please do not continue posting your questions in those threads.

The mods are still very modular, like before. I chose to release a modpack because I think this makes installation for the most likely use case much easier. There is no real reason why a player would not want the item help when also installing the core mod.

And here is the changelog from the previous versions:

Documentation System (initial modpack release notes):

• [doc], [doc_items] and [doc_identifier] re-released as a modpack
• New mod [doc_basics] for gameplay basics
• Licensed under MIT License

Note that the Minetest Game item help [doc_minetest_game] is still released as a standalone mod because it is specific to Minetest Game.

Documentation System core [doc]:

• You can now add an arbitrary number of categories
• Further refined the API documentation
• Define the boundaries of entry widgets
• It is now documented and supported to receive callbacks from widgets you add into entries. For example, you could add a button in an entry, and it could actually do something (you should read the API docs, however)
• Fix mod not working with intllib and mod security enabled at once
• Entry selection is now (hopefully) reliably saved and restored when you click through the tabs, buttons and lists, instead of randomly jumping around
• Fix bug in text template: The final line was lost
• Show warning for entries without title
• Fix version number not shown in error message

Sorry, the major feature for adding hyperlinks or references or something like that is still not there. It would be super-convenient if you could just click on a word or whatever in an entry and immediately see another entry. But I figured while this would be a great feature, it it not an essential one and I might end up releasing version 1.0.0 without links.
The main reason why this is still missing is because I have no real idea how to implement it in the actual user interface which is easily recognizable and usable. I think I may have to wait for Minetest to add a hyperlink-like feature on its own (because it doesn't have one yet). But if you have an idea on how to make it easier to go from entry to entry right now, please share it! Your suggestion will be appreciated. :-)

Item Documentation [doc_items]:

• The API was greatly simplified: For adding a long item description, you only need to add an additional field to your item definition, which is IMO much more logical to do
• Add setting to optionally show itemstring in entries
• Rename some API functions (they were unused to my knowledge)
• Simplify the mod API documentation a bit
• Add screenshot
• Add intllib support
• Add German translation
• Fix incorrect factoid regarding falling nodes
• Fix some other small bugs

Most of the functions in doc.sub.items will eventually be phased out, do not use them.

Here's an example of the new recommended way to add help to simple items:

Code: Select all

minetest.register_node("example:dice", {
		description = "Example Dice",
		_doc_items_longdesc = "A huge wooden dice with the numbers 1-6, just for fun.",
		_doc_items_usagehelp = "Rightclick on a placed dice to “throw” it, which rotates it randomly.",
-- And so on ...
})

Also, because of the changed API, you can expect a re-release of many of my mods pretty soonish.

Modders: Please remember all mods in this Documentation System are still WIP. While you can of course try to add support, I do not yet guaranteed backwards-compability, so be prepared.

Lookup Tool [doc_identifier]:

• Fix mod not working with mod security and intllib enabled at the same time
• Compability with new doc_items version
• Use “Sie” instead of “du” in German translation

Basic Help [doc_basics]:
And finally, here are some notes about the new mod, doc_basics:
This mod includes some help texts about Minetest itself. It contains the very basic features of Minetest, the controls, gameplay and other stuff which (mostly) holds true for pretty much all subgames and mods. This mod is still pretty incomplete and has some empty or incomplete entries. I plan to finish all pages for this mod for version 1.0.0 ofthis modpack.

[u34]

when i enable intlib i got following error! when i delete intlib all works fine now!

Code: Select all

2016-11-18 21:05:30: ERROR[Main]: ModError: Failed to load and run script from D:\Users\chype\Documents\minetest x64\win64\bin\..\games\minetest_game\mods\awards\init.lua:
2016-11-18 21:05:30: ERROR[Main]: C++ exception
2016-11-18 21:05:30: ERROR[Main]: Siehe debug.txt für Details.
2016-11-18 21:06:09: [#0x38c0]: INFO: event_handler(): Ctrl+C, Close Event, Logoff Event or Shutdown Event, shutting down.

[Wuzzy]

I am not convinced this bug is caused by Documentation System. Try to update your awards mod first.

[Wuzzy]

Version 0.8.0 released! Updates (core mod [doc] only):

- Add function to sort categories
- Set a default order of categories
- Changed the mod icon
- Add low-resolution icon
- Fix bad screenshot size
- Copy-editing of the API documentation

[Wuzzy]

A new version of the modpack is there, with a new mod and updates to two mods!

New mod added: Encyclopedia [doc_encyclopedia].
This adds a simple encyclopedia item to access the documentation system by wielding and leftclick. Craft it with 6 sticks in a “D” shape (see 1st post).


Basic help [doc_basics]
The basic help has been greatly extended! Many entries now include images to illustrate the entries. Examples:




I also have rewritten most entries and added many new ones. I have put a lot of work in that mod lately. This means the basic help is now much more complete!

This is the current list of basic entries:

• Minetest
• Controls
• Sneaking
• Pointing
• Items
• Inventory
• Hotbar
• Tools
• Blocks
• Liquids
• Mining
• Building
• Craft
• Cooking
• Groups
• Players
• Minimap
• Camera
• Settings
• Glossary
• Online resources
• Introduction to online play (Very incomple entry)
• Privileges
• Commands

The basic help is still a bit of a work-in-progress and I still not 100% happy with the current texts and images. I try to make the entries so that it is convenient to look them up in-game while not being TOO much of a large wall of text. I hope with the illustrations the entries should be now much more visually pleasing. Still there is a lot of text. But my goal with this modpack is to provide a full in-game documentation and to replace the wiki for the most part.

I really wish Minetest would offer a way to highlight words or to otherwise format the text, it would improve readability a lot.

Feedback on the help entries in the categories “Basics” or “Online” is very much appreciated! (especially if you a NOT a pro Minetest player)

However, because of the added images, the mod has become significantly larger (>1 MiB). :-(
For singleplayer this is probably not a big deal but for servers this probably is. I will probably adding a server setting to disable images for reducing server load (if needed).

Updates to the core mod [doc] (version 0.9.0):

• Add new gallery widget to add a scrollable image set to entries (arbitrary amounts of images are supported, number of images and image size can be set)
• Add a new entry template which contains a text field and a simple gallery (used by doc_basics)
• New parameter to build_formspec: playername

[Spaghetti Developer]

Very interesting! I 'very useful, because it is called the internal wiki to play, not to go out and search the web. I have to try this mod absolutely! I'd love an internal machining guide, and a list of game controls and the control of chatter in singleplayer and multiplayer, this thing is really useful. Thanks Wuzzy, you are a good modders :D

[u34]

maybe the download link is broken?

[Wuzzy]

Yeah, my hoster seems to have some problems lately. I have added a temporary mirror, please try it. I am so sorry that it is one of those crappy one-click hosters, I will replace it with something better if I find something.

https://www.load.to/MBvHVYRuXT/doc.zip

I guess it is time to start looking for new hosters sooner or later. Sigh. :-(

[Wuzzy]

Time for a new release of this modpack. A couple of mod updates are pouring in again!
I now consider the mods doc_encyclopedia and doc_identifier to be very stable and finished. There are 3 more mods to go until I officially release the whole modpack as version 1.0.0.

Basic Help [doc_basics] (0.1.0)
- Add category: Advanced usage
- Remove category: Online
- New help entries in category “Basics”: Quick start, Weapons
- New help entries in category “Advanced usage”: Coordinates, Console, Light, Movement modes
- Remove entry “Introduction to online play”
- Rewrite pretty much all of the help entries again, mostly to fix factual mistakes and typos and to simplify the texts as much as possible
- Apply a more or less logical entry order (hopefully)
- Add more images to a few help pages
- Add README file

Item Help [doc_items] (0.8.0)
- Fix crash when trying to parse unknown item
- Item entries now show their itemstring to all players with the “give” or “debug” privilege
- API: Extend custom factoid support to tools and craftitems (still only for groups so far)
- Change setting: The itemstring setting now allows to force the itemstring to be always displayed (regardless of privileges)
- Fix custom texts of air or hand not working anymore
- Spell-check README files

Encyclopedia [doc_encyclopedia] (1.0.0)
- Official 1.0.0 release!
- Add README file

Lookup Tool [doc_identifier] (1.0.0)
- Official 1.0.0 release!
- Rewrite README files and fix some mistakes in the contained texts

Core Framework [doc] (0.10.0):
- Allow gallery to display item images
- Update default category order
- Add support for sfinv_buttons (unreleased mod)
- Fix a leaking global variable


Note: A review of the help texts of the Basic Help (doc_basics) will be very much appreciated. Please tell me how well you think they could be understood.

[Wuzzy]

For interested modders, I give some hints for you today to understand this modpack a bit better.
If you want to see the APIs in this modpack in action with other mods, just look at the mods which are already actively using this modpack to add their own help texts.

This is an (incomplete) list of mods which currently make use of the APIs to add more customized help:

• Dice [dice2]
• Flying Carpet [flying_carpet]
• Orienteering [orienteeering]
• Watering Can [wateringcan]
• Magic Beans—Wuzzy's Fork [magicbeans_w]
• Pep: Player Effects Potions [pep]
• The Origin [origin]
• Point Teleporters [teletool]
• Slime Blocks and Liquids [slimenodes]
• Bedrock Layer [bedrock2]
• Mirror of Returning [returnmirror]
• Surprise Blocks [tsm_surprise]
• Easy Vending Machines [easyvend]
• Minetest Game Plus [mtg_plus]
• Minetest Game item help [doc_minetest_game] (does not add any own gameplay content, only provides help for Minetest Game)

Most of these mods add longer descriptions and an usage help for blocks and other items. I suggest you to start looking at the first mod [dice2] because it is very small. As another example, the flying carpet mod updates the entry on the flying carpet with a long explanation on how to use it. :-)
Please be aware this modpack is still officially a WIP, so there are no promises of not breaking stuff.

My goal in the long run is that it will be a standard practice among modders to add help texts for their mods. I suppose it will become especially valuable for complex mods or modpacks like Mesecons or Technic.

I am also announcing that I am going to delete a bunch of functions which weren't used anyway in the [doc_items] mod for the next release. Specifically, most functions in doc.sub.items will be gone. The mod now uses item definition fields for the interesting stuff like the long description or usage help. In the unlikely event that you already depended on this mod, please ask me in this thread for help for a smooth transition.

Finally, I will rename the modpack to “Help” in the next release. I think this name is much more obvious and simpler for the end user. The name “Documentation System” was too technical for my taste.
But the core mod [doc] will be called “Documentation System” again. Of course, the shortnames will not be changed.
Long story short:
- The entire modpack (and, by extension, the collection of all help entries) will be called “Help”.
- The core framework [doc] will be called “Documentation System”.

[u34]

when I click on advanced usage, I get following error!

Code: Select all

2016-12-12 17:43:53: ERROR[Main]: ServerError: Lua: Runtime error from mod 'doc' in callback on_playerReceiveFields(): ...inetest x64\win64\bin\..\builtin\common\misc_helpers.lua:589: table index is nil
2016-12-12 17:43:53: ERROR[Main]: stack traceback:
2016-12-12 17:43:53: ERROR[Main]:       ...inetest x64\win64\bin\..\builtin\common\misc_helpers.lua:589: in function 'copy'
2016-12-12 17:43:53: ERROR[Main]:       ...4\win64\bin\..\games\minetest_game\mods\doc\doc\init.lua:849: in function 'get_sorted_entry_names'
2016-12-12 17:43:53: ERROR[Main]:       ...4\win64\bin\..\games\minetest_game\mods\doc\doc\init.lua:788: in function 'generate_entry_list'
2016-12-12 17:43:53: ERROR[Main]:       ...4\win64\bin\..\games\minetest_game\mods\doc\doc\init.lua:905: in function 'formspec_category'
2016-12-12 17:43:53: ERROR[Main]:       ...4\win64\bin\..\games\minetest_game\mods\doc\doc\init.lua:1010: in function <...4\win64\bin\..\games\minetest_game\mods\doc\doc\init.lua:974>
2016-12-12 17:43:53: ERROR[Main]:       ...ents\minetest x64\win64\bin\..\builtin\game\register.lua:412: in function <...ents\minetest x64\win64\bin\..\builtin\game\register.lua:392>
2016-12-12 17:43:53: ACTION[Main]: [doc] Server shuts down. Rescuing player data into doc.mt.
2016-12-12 17:43:53: ACTION[Main]: [doc] Wrote player data into C:\Users\chype\Documents\minetest x64\win64\bin\..\worlds\map dezi v7/doc.mt.

[Wuzzy]

Whoops! I just uploaded a quick fix (version 0.10.1), I hope it works.

[u34]

works fine ...

[Wuzzy]

It's time to go into the beta test phase of this modpack! Version 0.11.0 is now ready. I consider this version to be almost “feature complete”. Please test this modpack and report any bugs you find. Also report anything you find hard to understand. I too will perform some tests. If you're a modder, please take a look at the APIs and write your thoughts.

The modpack is now officially called “Help”. The core mod [doc] is now officially called as “Documentation System” again. The shortnames of all mods stay the same. I will keep the old modpack name in this thread name for a while.

Changelogs:

Modpack:
- Renamed to “Help”

Documentation System [doc] (0.11.0):
- Renamed to “Documentation System”
- Fix incorrect counting of categories
- Tweak some user messages
- Change chat command names: Use “/helpform” to access the help and “help_reveal” to reveal all entreis
- Make background of text widgets fully black to make the text easier to read
- Increase overall size of the form to use as much screen space as possible
- Increase width of category buttons
- Bugfix: Player data was destroyed in many situations, resetting the list of read/revealed entries in the process
- Minor API documentation rewrite

Basic Help [doc_basics] (0.2.0):
- Rewrite the Mining entry to be more complete
- Fix crash when used without the doc_minetest_game mod
- Add intllib support (warning: the strings may still heavily change)

Item Help [doc_items] (0.9.0):
- Entries for mining tools now show number of uses
- Entries for mining tools now show digging times
- API: Add support for many more custom factoid types (basically just controls where in the text they're placed)
- API: _doc_items_durability to specify exact number of tool uses or describe it in text form
- Change entry sorting for tools and weapons: Sort the entry list roughly based on the tool's performance
- Fix bugs relating to air, hand and ignore items
- Custom help texts for hand, air or even ignore can be added by overwriting them
- API: Remove unused legacy functions



Encyclopedia [doc_encyclopedia] (1.1.0):
- Reflect the new modpack name

Lookup Tool [doc_identifier] (1.1.0):
- Reflect the new modpack name



I am not entirely happy with the way I tried to expose the mining information, and I especially am not happy with the use of my terminolgy. I feel the entry on Mining is way too hard to understand, and the mining times on the tool pages may not be self-explanatory. I think this is the last nontrivial feature I have to finish before release. If you have any suggestions on how to explain the rather complex mining system in simple terms, I would be very glad. If you can come up with easy words to explain the various concepts, that would be a big help as well.

[echosa]

I just installed this mod into my subgame, and everything seems to work except for the "Tools and weapons" button. When I click that, Minetest crashes. Here's what I see at the end of the log:

Code: Select all

2016-12-28 17:44:55: ERROR[Main]: ServerError: Lua: Runtime error from mod 'doc' in callback on_playerReceiveFields(): .../minetest/games/echosa_game/mods/help/doc_items/init.lua:967: bad argument #1 to 'pairs' (table expected, got nil)
2016-12-28 17:44:55: ERROR[Main]: stack traceback:
2016-12-28 17:44:55: ERROR[Main]: 	[C]: in function 'pairs'
2016-12-28 17:44:55: ERROR[Main]: 	.../minetest/games/echosa_game/mods/help/doc_items/init.lua:967: in function <.../minetest/games/echosa_game/mods/help/doc_items/init.lua:921>
2016-12-28 17:44:55: ERROR[Main]: 	[C]: in function 'sort'
2016-12-28 17:44:55: ERROR[Main]: 	...upport/minetest/games/echosa_game/mods/help/doc/init.lua:888: in function 'get_sorted_entry_names'
2016-12-28 17:44:55: ERROR[Main]: 	...upport/minetest/games/echosa_game/mods/help/doc/init.lua:793: in function 'generate_entry_list'
2016-12-28 17:44:55: ERROR[Main]: 	...upport/minetest/games/echosa_game/mods/help/doc/init.lua:910: in function 'formspec_category'
2016-12-28 17:44:55: ERROR[Main]: 	...upport/minetest/games/echosa_game/mods/help/doc/init.lua:1015: in function <...upport/minetest/games/echosa_game/mods/help/doc/init.lua:979>
2016-12-28 17:44:55: ERROR[Main]: 	...inetest.app/Contents/Resources/builtin/game/register.lua:412: in function <...inetest.app/Contents/Resources/builtin/game/register.lua:392>

Also, as far as wording goes, may I recommend a few changes?

Category list => Categories
Entry list => Entries
Tools and weapons => Tools and Weapons
Miscellaneous items => Miscellaneous Items
Advanced usage => Advanced Usage

You also don't really need the "This is the help." text.

Finally, it'd be really great if we could double-click on entries in the entry list to open them up in the entry view.

Awesome mod, BTW! I've been looking for something like this! :-)

[Wuzzy]

Echosa, I've recently released version 1.0.0. I suggest you update this modpack and mods which depend on mods in this modpack and try again. I will post a release announcement in a couple of hours.

Also, double-clicking on entries in the entry list already works.

[echosa]

I just have been out of date, I guess. However, with 1.0.0, my game won't even start. Looks like maybe an incompatibility with the returnmirror mod?

Code: Select all

2016-12-28 18:30:52: ERROR[Main]: ModError: Failed to load and run script from /Users/echosa/Library/Application Support/minetest/games/echosa_game/mods/returnmirror/init.lua:
2016-12-28 18:30:52: ERROR[Main]: ...Support/minetest/games/echosa_game/mods/doc/doc/init.lua:377: table index is nil
2016-12-28 18:30:52: ERROR[Main]: stack traceback:
2016-12-28 18:30:52: ERROR[Main]: 	...Support/minetest/games/echosa_game/mods/doc/doc/init.lua:377: in function 'add_entry_alias'
2016-12-28 18:30:52: ERROR[Main]: 	...rt/minetest/games/echosa_game/mods/returnmirror/init.lua:147: in main chunk

[Wuzzy]

Version 1.0.0 has been released! Party time! :-)
This is a major milestone.



Important: The API of the core mod has changed, so you must update some mods which depend on the Help mods. This is definitely the case if you have one of these mods: returnmirror, wateringcan, doc_minetest_game, easyvend. I released updates to all of these mods and you can download them now, I just did not officially announce the updates yet.

Changelogs
The Help modpack (1.0.0)
I declare all mod APIs now to be ready to be used in production. If you're a modder who wants to document your mod, items and other things, you can use this modpack to do so. See the developer information in the first post for more information. I also just released an example mod (doc_example, this mod is ONLY for modders) to help you get started very fast. See the first post, developer information for the link. API documentation is provided in the mods. I've also listed this modpack in http://dev.minetest.net/Mod_interoperability.

I also renamed the modpack folder name back to “doc” again for easier sorting. But you can rename the modpack folder name as you like, it doesn't matter. I recommend you delete all older versions of the help modpack and its mods, as I don't promise compability with pre-1.0.0 mods.

Documentation System [doc] (1.0.0)

• Add support for Inventory++ [inventory_plus]
• Use some text colorization in some places
• Use opaque background for the main form for better readability
• API change: doc.new_category → doc.add_category
• API change: doc.new_entry → doc.add_category
• API change: doc.add_entry_alias now supports aliases across different categories. The function syntax has been changed
• API change: doc.add_entry_aliases was removed
• Update readme file and API documentation
• Fix typos
• Refactor code

Basic Help [doc_basics] (1.0.0)

• Mention the new zoom feature
• Compability for core API changes

Item Help [doc_items] (1.0.0)

• Fix typos all over the place
• Compability for core API changes
• Bugfix: Incorrect use count for tools with infinite uses
• Bugfix: Mining tools sometimes showed an mining time of infinity seconds
• Update API documentation: Overwriting hand and air entries
• Remove outdated code and files

Encyclopedia [doc_encyclopedia] (1.2.0)

• Add crafting recipe for Minetest Game (3 books vertically)
• Reveal encyclopedia entry by default

Lookup Tool [doc_encyclopedia] (1.2.0)

• Reveal lookup tool entry by default
• Compability for core API changes

Future plans
Version 1.0.0 will not be the end of the road (I hope). But version 1.0.0 provides a pretty decent help system IMO, so this is a big milestone. I still have a couple of features on my TODO list for this mod. From version 1.0.0 on, I try hard not to break compability anymore. Maybe I'll write more on my future plans later. But the bigger feature plans will stay on hold for at least 2 weeks from now on.
The next important step I have is to convince modders to adopt this modpack so that all Minetest mods have good in-game explanations. :-)

[echosa]

Hooray! Congrats on the big 1.0 release!

[Nathan.S]

Maybe I'm just an idiot, probably am, but every time I try to clone this modpack all I get is a bunch of empty folders for the individual mods, and some text files in the root dir.

I'm using this code to clone

Code: Select all

git clone --recursive git://repo.or.cz/minetest_doc_modpack.git

and I keep getting this error:
fatal: unable to access 'https://repo.or.cz/minetest_doc.git/': server certificate verification failed. CAfile: /etc/ssl/certs/ca-certificates.crt CRLfile: none
fatal: clone of 'https://repo.or.cz/minetest_doc.git' into submodule path 'doc' failed

Any ideas what the problem could be?

[Wuzzy]

Whoops. This was my fault. The .gitmodules had HTTPS links but they should be HTTP because HTTPS requires you to have a cert you don't have. Which is why you had access denied all the time.
I have fixed this in the repository now. Try to clone this again (same command) from scratch.

[Nathan.S]

That worked, :) Thank you.

[crazyR]

Wuzzy, Is there a github repo for this? It would make my life easier in terms of maintaining my server?

[Wuzzy]

No. I use repo.or.cz.
The main repository is on http://repo.or.cz/minetest_doc_modpack.git. It uses Git submodules.

Read the first post for more information.