[Mod] Documentation System [0.6.0] [doc]

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

[Mod] Documentation System [0.6.0] [doc]

by Wuzzy » Sun Jul 24, 2016 22:58

This thead is outdated. The Documentation System is now released as a modpack: viewtopic.php?f=9&t=15912&p=240152

A framework for an in-game documentation system to document various things.

This mod provides a simple and highly extensible formspec in which the user can access help pages about various things and the modder can add those pages. The mod itself does not provide any help texts, just the framework.

Download (and stuff)
Download: http://repo.or.cz/minetest_doc.git/snap ... 627f5e.zip

Git project page: http://repo.or.cz/minetest_doc.git
License of everything: MIT License
Mandatory dependencies: None!
Optional dependencies: Unified Inventory [unified_inventory], [intllib], Central Message [central_message]
Version: 0.6.0

Mods using this mod
- Item Documentation [doc_items]
- Lookup Tool [doc_identifier]

Player's perspective
This mod is not useful on its own for you, as it does not contain any actual help texts, you will only need this mod as a dependency. You find the help texts in their own mods.

You can access the documentation system by saying “/doc” in chat or with a button in Unified Inventory.

The whole documentation system is very simple, it boils down to categories and entries. Categories cover a wider topic, such as “Basic concepts” or “Blocks”. Categories are there to group related entries together. The entries contain the actual help about a specific topic, for example, an entry “Sand” in the “Blocks” category.

Modder's perspective
First a warning: This is a very early version of this mod. It's API is poorly documented and subject to change. You are, however, welcome to study and comment. If you have your own ideas for a development direction, please share it with me as soon as possible to avoid later possible interoperability issues.
Your comments and feedback are very appreciated.

Here's how the system works: You have a set of categories, and each category has a set of entries. All categories and entries can be added manually.
Entries contain the “meat” of your documentation, here you write the help texts. Internally, entries can an have an arbitrary amount of data attached to them. With a category, you also define a template function for all of its entries. When displaying an entry, this mod takes the data of the entry, passes it to the template function of its category which in turn creates the final formspec piece out of it. The final result is then displayed on the actual entry page.

The modder is free to write about basically everything, and the template function helps you in aligning your formspec elements as you wish. This principle hopefully makes this framework simple to use yet powerful enough for complex use cases.

Simple use case: Minetest basics: I want to write in freeform short help texts about the basic concepts of Minetest or my subgame. First I define a category called “Basics”, the data for each of its entry is just a freeform text. The template function simply creates a formspec where this freeform text is displayed.

Complex use case: Blocks: I could create a category called “Blocks”, and this category is supposed to contain entries for every single block in the game. For this case, a freeform approach would be very inefficient and error prone, as a lot of data can be reused. Here the template function comes in handy: The internal entry data contain a lot of different things about a block, like block name, identifier, custom description and most importantly, the definition table of the block. Finally, the template function takes all that data and turns it into sentences which are just concatenated, telling as many useful facts about this block as possible. The item icon is also added at the top right corner.

In this use case, the end result might look like this:
Image
In this example, the description is a text which was actually written specifically for this block. The other sentences, however, are generic and are used for many other blocks. They are not part of the description, but instead inserted by the template function based on simple conditionals (e.g. if block is in flammable group, the text about being flammable is displayed).

This example is taken from Minetest Game item help, a mod which documents Minetest Game's blocks, items, tools, etc.

To-do list
  • [!!!] Real-world testing
  • [!!!] Get your feedback ;-)
  • [!!] Add support for something like hyperlinks to change from one entry to another with a single click
  • [!] After adding hyperlinks, add buttons for going back and forwards in the “history”, like in a web browser

Background (or: Designer's perspective)
The motivation behind this mod comes out from the frustration with how complicated games in Minetest can be. Writing new subgames is great, but a complicated new subgame which introduces many new concepts (think of Technic or Realtest) it is hard to get into, even for seasoned Minetesters. Additionally, writing documentation in wikis is a tedious task, plus they get outdated quickly with every change, and as a player, permanently switching between the browser and Minetest is annoying. I am a big proponent of the concept of complete in-game documentation. This will (hopefully) finally allow mod and subgame authors to add in-game documentation for almost anything they desire, they just need to write it; it might also reduce redundancy as the need for external sources like wikis. Goals are to improve overall quality of subgames and lowering the barrier of entrance even for very complex subgames and also Minetest itself. The main goal is to provide as much information in-game as possible and making external documation (like wikis) obsolete.

Major design goals are simplicity, flexibility, extensibility and usability.

  • Simplicity: The help system itself should be self-explanationary from its concepts alone. The help system should not require another help system. ;-)
  • Flexibility: The way the information is displayed should be mostly open to the modder.
  • Extensibility: Modders should add as much content as they wish, there should be no artificial limits.
  • Usability: Browsing through the various help pages should go quickly, accessing the help should be easy, using it should be convenient.
Last edited by Wuzzy on Thu Nov 17, 2016 22:01, edited 19 times in total.
I'm creating MineClone 2, a Minecraft clone for Minetest.
I made the Help modpack, adding in-game help to Minetest.
 

Byakuren
Member
 
Posts: 441
Joined: Tue Apr 14, 2015 01:59
GitHub: raymoo
IRC: Hijiri

Re: [Mod] Documentation System [0.1.0] [doc]

by Byakuren » Mon Jul 25, 2016 06:17

I have a couple suggestions:
  • Make it possible to hide entries from players and reveal them later: This can allow the doc to double as a tutorial, by presenting the player with the first steps, and revealing more as the player obtains the resources needed to do the next thing.
  • Linking to Unified Inventory, Inventory Plus, etc: Allow linking players to craft recipes within the doc, so that players can check the recipe while reading.
  • "Back" button for hyperlinks: In reading some part of the doc, a player might go several links deep because they found a concept they wanted to check the documentation on. A back button would let them get back to where they were after they are finished reading the linked section. It should be possible for a link to be specified not to add to the "back stack".
Every time a mod API is left undocumented, a koala dies.
 

User avatar
cd2
Member
 
Posts: 552
Joined: Mon Jun 01, 2015 06:30
GitHub: cdqwertz
IRC: freenode - cd2 InchraNet - cd
In-game: cd cd2

Re: [Mod] Documentation System [0.1.0] [doc]

by cd2 » Mon Jul 25, 2016 07:15

+1
 

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

Re: [Mod] Documentation System [0.1.0] [doc]

by Wuzzy » Mon Jul 25, 2016 09:08

Thank you for your feedback.

Byakuren wrote:Make it possible to hide entries from players and reveal them later: This can allow the doc to double as a tutorial, by presenting the player with the first steps, and revealing more as the player obtains the resources needed to do the next thing.

Yes, very good suggestion. I also had this idea, I just did not write it down. My main use case for hiding was that it could be useful to avoid “spoilers”, by not exposing all items right from the beginning, and, for example, blocks have first to be seen for their entries to become “unlocked”. This would also give some give a sense of progress in the game. :-)
Still, in the actual documentation texts I would still make sure a basic set ot entries is always available, and I am not sure that your hiding feature would be useful to make some tutorial-like thing. Maybe here some way to make sure that pages are read in order would make more sense. I also think when I implement the hyperlink feature, this will already help a lot for your use case, as they can be used for cross-references. I could also make sure that special entries could rise to the top (something like an introduction to the category or whatever).

Byakuren wrote:Linking to Unified Inventory, Inventory Plus, etc: Allow linking players to craft recipes within the doc, so that players can check the recipe while reading.

I am not sure what you mean by that. If you mean I should allow to add a button which automatically opens the inventory formspec and place some items in the crafting grid, I don't think this will work so easily, because my mod has to know how large the crafting grid is and if there even is a crafting grid (this depends on subgame).

But I had the idea to add a button to Inventory Plus (to access the documentation formspec) because that's pretty obvious. However, I have no idea how to do it, it seems this mod expects my mod to override the inventory formspec, but my mod actually uses its own formspec.

Byakuren wrote:"Back" button for hyperlinks: In reading some part of the doc, a player might go several links deep because they found a concept they wanted to check the documentation on. A back button would let them get back to where they were after they are finished reading the linked section. It should be possible for a link to be specified not to add to the "back stack".

Sure, why not? I still have to work out how “hyperlinks” would work in the first place. They are not actually supported by Minetest. Obviously, a back button will also require a “forward” button to undo going back.
The closest thing I can get are probably buttons but they can't be painlessly inserted into long text, I have to explicitly reserve new space for this. I don't think disabling the back button or intentionally *not* adding a page to the “back stack” is a good idea, or when did you last see a link in the web which does this? HTML never supported such a feature natively and I think for a good reason. I think such a feature just breaks usability, the back button should always go back, period.
I'm creating MineClone 2, a Minecraft clone for Minetest.
I made the Help modpack, adding in-game help to Minetest.
 

Byakuren
Member
 
Posts: 441
Joined: Tue Apr 14, 2015 01:59
GitHub: raymoo
IRC: Hijiri

Re: [Mod] Documentation System [0.1.0] [doc]

by Byakuren » Mon Jul 25, 2016 09:17

By linking to craft recipes, I just meant opening the craft guide of the inventory mod to the item's recipes. I'm not sure if those mods support that, though.

The "back" feature honestly I just got from how guidebooks seem to be done in Minecraft. Typically an entry on something will have multiple pages, but clicking on a link (like an item -> go to a craft recipe) would create history so that you could press a back button to go to where you were before you pressed the link. Sort of like continuations? Pressing the arrows to turn to the next/previous page would not add anything to the back stack. There also wasn't a forward stack.
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] Documentation System [0.1.0] [doc]

by Wuzzy » Mon Jul 25, 2016 09:24

I see. Yeah, I need to check whether this “linking to crafting recipe” works in the first place. ;-)

The idea of having multiple pages for a single entry is good and obviously this should be independent from having links. The buttons to “flip pages” would not be considered hyperlinks at all, it's like scrolling on a single webpage.

The main problem is that for long entries, it might not be trivial to figure out the ideal size to make sure all widgets fit. I wish Minetest would somehow support a scroll area. :-/
So the devil lies in the (implementation) details. ;-)

I also updated my to-do list.
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] Documentation System [0.1.0] [doc]

by azekill_DIABLO » Mon Jul 25, 2016 09:41

wow. very evry great and nice work!
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
DS-minetest
Member
 
Posts: 707
Joined: Thu Jun 19, 2014 19:49
GitHub: DS-Minetest
In-game: DS

Re: [Mod] Documentation System [0.1.0] [doc]

by DS-minetest » Mon Jul 25, 2016 12:46

nice mod, it remembers me to the help in hybriddogs' nether mod
it would be nice to have an item to get access to certain informations by scanning an item, node or entity, so that you dont get spoilered about everything
Do not call me -minetest.
Call me DS or DS-minetest.
I am German, so you don't have to pm me English if you are also German.
The background is a lie.
 

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

Re: [Mod] Documentation System [0.1.0] [doc]

by Wuzzy » Mon Jul 25, 2016 13:08

DS-minetest wrote:it would be nice to have an item to get access to certain informations by scanning an item, node or entity, so that you dont get spoilered about everything

Here you go: viewtopic.php?f=9&t=15225

About avoiding spoilers: This will be possible when the framework allows for hiding certain entries, and this is definitely on my to-do list.
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.2.0

by Wuzzy » Mon Aug 01, 2016 22:20

Version 0.2.0 released!

Updates:
- Documentation System has now a button in Unified Inventory (optional dependency)
- Non-read entries are displayed in cyan color (but status is not remembered after restarts, this is planned for later)
- Add API documentation
- Implement basic category sorting
- New functions for entry aliases
- New functions for counting entries, categories and more
- Add some icons for mods to use
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

Release 0.3.0

by Wuzzy » Fri Aug 05, 2016 03:46

Version 0.3.0 released!
Updates:
- Category buttons now can have tooltips
- Total number of entries and number of read entries are shown
- Show error message when trying to open the help formspec when the help files are missing
- Changed the main text labels to be slightly more helpful
- Bugfix: Mod crashed when attempting to view empty category
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.4.0

by Wuzzy » Sun Aug 14, 2016 06:50

Version 0.4.0 released!

Changes:
- Add buttons in entry page to view previous and next entries. Very convenient.
- Allow mods to sort the entry list differently rather than just alphabetically. Supported sorting algorithms are: alphabetically, manual predefined order, custom sorting function, no sorting.
- Slightly better error message when categories are missing
- Add some loose naming conventions into API documentation
- Other minor changes

Note: The previous/next buttons are still a bit buggy. If the entry page was opened by a mod (e.g. Lookup Tool [doc_identifier]), the buttons don't work. Apart from that, they seem to work so far.
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] Documentation System [0.4.0] [doc]

by azekill_DIABLO » Sun Aug 14, 2016 08:25

+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

Version 0.5.0

by Wuzzy » Wed Aug 31, 2016 21:32

Version 0.5.0 released!

The most important change this time is the support for hidden entries. Hidden entries are not displayed to players in the list of entries and if a mod tries to open a hidden entry, the player sees an error message (but this can be overwritten). For each player the mod remembers who has access to which entry.
If the player is viewing a category with hidden entries inside, the entry list will show how many of the entries are still hidden. So the player is kinda kept in the dark, but not entirely. ;-)
For mods it is possible to “reveal” any entry to a player, after which the entry will become permanently visible.

This feature could become useful for complex subgames which implement some concepts you don't want to reveal too early in the game. It can be useful to prevent spoilers, until the time is right. :-)

The other changes are mostly of technical nature.

Changes:
- Add support for hidden entries (and related API calls)
- List of viewed and revealed entries is persisted across multiple games (saved into file)
- New API functions: get_category_definition, get_entry_definition, and more
- Make API documentation slightly easier to navigate
- Bugfix: previous/next buttons now finally work even when entry was opened by a mod
- Bugfix: Many functions ignored entry aliases, which made aliases unreliable



The development of this mod is slowly going into release stage. On my to-do list the only major thing remaining is support for a “hyperlink”-like feature for allowing cross-references. I honestly have no really good idea for this.
My number one idea for this would be clickable text links like in HTML. But current formspec don't have any widget like that. So I have to get creative.
My second idea was to implement a simple list of “related” entries and the user can move to another entry with a double click. It's not really pretty because this takes away valuable space on the entry formspec. :-/
If any of you has a better idea how to implement a cross-reference feature without wasting too much formspec space, that would be great. I also try to design a more or less usable system but currently i have not come up with something nice yet. :-/

I also ask every modder around here for feedback on the API and the documentation. Please point any weirdnesses, confusions, ugly design, etc. so I can change that before release. This is important because after release I will try hard to not break compability anymore.
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:06

Version 0.6.0 released!

Changelog:
- Entries using freeform text can now be scrolled (previously the text was just cut off, very serious issue)
- Play notification sound when a hidden entry has been revealed
- If central_message mod is active: Show notification message when a hidden entry has been revealed
- Chat command and privilege “doc_reveal” to instantly reveal all entries
- intllib support
- German translation
- Don't display entry list if all entries of a category are hidden
- API: doc.get_hidden_count
- Spellcheck entire mod
- Update API docs
- License is now MIT License
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

Future development plans

by Wuzzy » Thu Nov 03, 2016 16:40

I am announcing big plans for the Documentation System ecosystem (this mean, this mod and related mods). I am planning to not post any major releases until November 12, but after that day, anything is possible (expect an “release orgy”).

I am planning to put the mods Documentation System [doc], Item Documentation [doc_items] and Lookup Tool [doc_identifier] into a single modpack to make it simpler to use and understand for the average user. The mods are chosen on the basis that the average user probably will always need for the best user experience with the Documentation System.

The mods themselves will still be independent units. No dependencies are changed here.

Moreover, I am planning to officially release a new mod Basic Help [doc_basics] which contains basic help texts and references (e.g. controls) for getting started with Minetest. Many texts will be adapted from the Tutorial subgame. The mod is still pretty raw and is this mod is currently not my top priority. For those interested, a very early of doc_basics can be viewed here: http://repo.or.cz/minetest_doc_basics.git

For doc_items, I am going to plan a major deprecation and major simplification of the API. 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. (Read more here: viewtopic.php?f=9&t=15300&p=238704#p238704)

Finally, I wish to hear some suggestions/ideas for help-related mods which I should add to the upcoming core modpack. Ask yourselves: What other topics (besides “Getting started” guides (doc_basics) and item help texts (doc_items)) do you wish to see in the core modpack? Please only important things which are (more or less) true for any subgame. Mod-specific stuff (e.g. help for mobs) is likely not going into the core modpack, but if the idea is still good in general, I might create the mod outside of the modpack.
However, note that your suggestions will probably stay “on hold” for a while. I plan to release 1.0.0 of all core mods first before starting any new core mods, to concentrate my efforts.
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] Documentation System [0.6.0] [doc]

by BrunoMine » Thu Nov 03, 2016 17:28

You use a whole sentence to explain a single group. This looks great, the players do not want to see development terms, just that they are true. (Explain what each group is, in a friendly way)
 

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

Re: [Mod] Documentation System [0.6.0] [doc]

by Wuzzy » Thu Nov 03, 2016 21:07

Thanks, BrunoMine. One of Documentation System's main goals is making Minetest useful to players in a convenient way. And this includes trying to keep the gory technical details either hidden or explained.

Remember the screenshot shown is just an example. The Documentation System is technically capable of showing help pages for almost anything, not “just” blocks and items.
Although I think help texts for blocks and items (the “doc_items” mod) is probably one of the most important mods.

I think I have to rewrite the first post of this thread (and the related mod threads) sooner or later. The text is way too long. ;-)
I probably do it when I release the modpack.
I'm creating MineClone 2, a Minecraft clone for Minetest.
I made the Help modpack, adding in-game help to Minetest.
 


Return to Old Mods

Who is online

Users browsing this forum: No registered users and 4 guests

cron