game_doc/README.md

# game_doc
#### In-Game Documentation Tree System


*game_doc* provides a few different functions for other mods and games to use, allowing for much needed in-game documentation for minetest-engine based games and mods. All games/mods that include game_doc by default (adjustable setting) will have a chat command `/doc` to view the main documentation menu.

This mod assumes all documentation will be in the form of either a `hypertext` element, or a `markdown.md` file (or folder of such files) that this mod then uses [markdown2formspec](https://github.com/ExeVirus/markdown2formspec) mod to parse into a hypertext element.


The tree structure is:

Main Menu \> categories \> entry_names \> formspec


The main functions are:

```lua
game_doc.add_direct_entry(category_name, entry_name, hypertext_element, hidden)
-- hidden is always optional, defaults to false
-- Will add <entry_name> to <category_name> containing the hypertext formspec element to be displayed

game_doc.add_file_entry(category_name, entry_name, markdown_file, hidden)
-- hidden is always optional, defaults to false
-- Will parse the provided markdown_file and add the resulting hypertext element to be found at <entry_name> in <category_name>

game_doc.add_folder_entries(category_name, folder_location, hide_category, hide_elements)
-- hide_**** is always optional, defaults to false
-- Will parse the provided folder for any `.md` files that are present, turn them into hypertext elements,
-- use their filename as <entry_name> and add them to the provided category. 
```

## Hidden Entries WIP, CURRENTLY DISABLED

This mod also supports hidden and unhidden entries, all categories and entries are shown by default to all players. To hide or unhide entries use the following, if player_name is nil, this change occurs for all future joining players. If player_name is a boolean of "true", this change will occur
for all known players, and all future joining players. If player_name is a boolean of "false", this change will occur for all currently connected players only. 

```lua

game_doc.hide_category(player_name, category)

game_doc.show_category(player_name, category)

game_doc.hide_entry(player_name, entry)

game_doc.show_entry(player_name, entry)

```

## Direct access

You can access the categories and entries via these functions. **BE CAREFUL**, these are not copies, and changes will affect things, read the mod code if you are worried by this warning.

```lua
game_doc.get_doc_data()
-- Returns a table 
-- {
--  category_name { hidden=false/true, entries { entry1 { hidden=false/true, hypertext }, entry2 {hidden=false/true, hypertext } }
--  category_name { hidden=false/true, entries { entry1 { hidden=false/true, hypertext }, entry2 {hidden=false/true, hypertext } }
--  etc.
-- }
--

game_doc.get_hidden_data
-- Returns a table 
-- { 
--      -- hidden_values actually stores a table of **shown** categories and entries
--      hidden_values { categories {cat1, cat3},
--                  entries[cat1] = { entry2, entry3 },
--                  entries[cat2] = { entry1, entry3 },
--                  entries[cat3] = { entry1, entry2, entry3 }, --possibly entire table doesn't exist
--     selected_category = cat1 --possibly doesn't exist
--     selected_entry = ent1 --possibly doesn't exist
-- }
--

game_doc.get_doc_data()
```

## Settings 

- The entire hidden system can be disabled, which allows the backend code to run faster, and allows the mod to act more like a documentation system only. to make this change, edit your `minetest.conf` and set `game_doc_hidden_enable` to false.
- The chat command `/doc` can be disabled by setting `game_doc_enable_chat_command` in `minetest.conf` to false.

## Other Notes

Notice with the hidden functionality, the use cases for this mod can expand. Categories and entries can be quests/lore/old dialog/etc. No sounds are generated from this mod, and no other popups are created, hopefully letting mod authors have as much flexibility as possible using it. 

Also if you need to access the formspecs this mod generates for your own purposes, these functions are:

```lua
game_doc.main_form(player_name) --playername is optional (for the hidden system)

game_doc.category_form(category, player_name) --playername is optional

game_doc.entry_form(category, entry, player_name) --playername is optional
```