API.md

   1 # API documentation for version 0.2.0
   2 ## Core principles
   3 As a modder, you are free to write basically about everything and are also
   4 relatively free in the presentation of information. The Documentation
   5 System has no restrictions on content whatsoever.
   6
   7 In the documentation system, everything is built on categories and entries.
   8 An entry is a single piece of documentation and is the basis of all actual
   9 documentation. Categories group multiple entries of the same topic together.
  10
  11 Categories also define a template which is used to determine how the final
  12 result in the Entry tab looks like. Entries themselves have a data field
  13 attached to them, this is a table containing arbitrary metadata which is
  14 used to construct the final formspec which is used on the Entry tab.
  15
  16 ## Possible use cases
  17 I present to you some possible use cases to give you a rough idea what
  18 this mod is capable and how certain use casescould be implemented.
  19
  20 ### Simple use case: Minetest basics
  21 I want to write in freeform short help texts about the basic concepts of
  22 Minetest or my subgame. First I define a category called “Basics”, the data
  23 for each of its entry is just a freeform text. The template function simply
  24 creates a formspec where this freeform text is displayed.
  25
  26 ### Complex use case: Blocks
  27 I could create a category called “Blocks”, and this category is supposed to
  28 contain entries for every single block in the game. For this case, a freeform
  29 approach would be very inefficient and error-prone, as a lot of data can be
  30 reused.
  31
  32 Here the template function comes in handy: The internal entry data
  33 contain a lot of different things about a block, like block name, identifier,
  34 custom description and most importantly, the definition table of the block.
  35
  36 Finally, the template function takes all that data and turns it into
  37 sentences which are just concatenated, telling as many useful facts about
  38 this block as possible.
  39
  40 ## Functions
  41 This is a list of all publicly available functions.
  42
  43 ### `doc.new_category(id, def)`
  44 Adds a new category. You have to define an unique identifier, a name
  45 and a template function to build the entry formspec from the entry
  46 data.
  47
  48 #### Parameters
  49 * `id`: Unique category identifier as a string
  50 * `def`: Definition table, it has the following fields:
  51     * `name`: Category name to be shown in the interface
  52     * `build_formspec`: The template function. Takes entry data as its
  53       only parameter (has the data type of the entry data) and must
  54       return a formspec which is inserted in the Entry tab.
  55
  56 #### Return value
  57 Always `nil`.
  58
  59 ### `doc.new_entry(category_id, entry_id, def)`
  60 Adds a new entry into an existing category. You have to define the category
  61 to which to insert the entry, the entry's identifier, a name and some
  62 data which defines the entry. Note you do not directly define here how the
  63 end result of an entry looks like, this is done by `build_formspec` from
  64 the category definition.
  65
  66 #### Parameters
  67 * `category_id`: Identifier of the category to add the entry into
  68 * `entry_id`: Unique identifier of the new entry, as a string
  69 * `def`: Definition table, it has the following fields:
  70     * `name`: Entry name to be shown in the interface
  71     * `data`: Arbitrary data attached to the entry. Any data type is allowed;
  72       The data in this field will be used to create the actual formspec
  73       with `build_formspec` from the category definition
  74
  75 #### Return value
  76 Always `nil`.
  77
  78 ### `function doc.show_doc(playername)`
  79 Opens the main documentation formspec for the player (Main tab).
  80
  81 #### Parameters
  82 * `playername`: Name of the player to show the formspec to
  83
  84 ### `doc.show_category(playername, category_id)`
  85 Opens the documentation formspec for the player at the specified category
  86 (Category tab).
  87
  88 #### Parameters
  89 * `playername`: Name of the player to show the formspec to
  90 * `category_id`: Category identifier of the selected category
  91
  92 #### Return value
  93 Always `nil`.
  94
  95 ### `doc.show_entry(playername, category_id, entry_id)`
  96 Opens the documentation formspec for the player showing the specified entry
  97 of a category (Entry tab).
  98
  99 #### Parameters
 100 * `playername`: Name of the player to show the formspec to
 101 * `category_id`: Category identifier of the selected category
 102 * `entry_id`: Entry identifier of the entry to show
 103
 104 #### Return value
 105 Always `nil`.
 106
 107 ### `doc.entry_exists(category_id, entry_id)`
 108 Checks if the specified entry exists and returns `true` or `false`.
 109
 110 #### Parameters
 111 * `category_id`: Category identifier of the category to check
 112 * `entry_id`: Entry identifier of the entry to check for its existance
 113
 114 #### Return value
 115 Returns `true` if and only if:
 116
 117 * The specified category exists
 118 * This category contains the specified entry
 119
 120 Otherwise, returns `false`.
 121
 122 ### `doc.add_entry_alias(category_id, entry_id, alias)`
 123 Adds a single alias for an entry. When an entry has an alias, attempting to open
 124 an entry by an alias name results in opening the entry of the original name.
 125 Aliases are true within one category only.
 126
 127 #### Parameters
 128 * `category_id`: Category identifier of the category of the entry in question
 129 * `entry_id`: Entry identifier of the entry to create an alias for
 130 * `alias`: Alias (string) for `entry_id`
 131
 132 #### Return value
 133 Always `nil`.
 134
 135 ### `doc.add_entry_aliases(category_id, entry_id, aliases)`
 136 Adds an arbitrary amount of aliases for an entry at once. Apart from that, this
 137 function has the same effect as `doc.add_entry_alias`.
 138
 139 #### Parameters
 140 * `category_id`: Category identifier of the category of the entry in question
 141 * `entry_id`: Entry identifier of the entry to create aliases for
 142 * `aliases`: Table/list of aliases (strings) for `entry_id`
 143
 144 #### Return value
 145 Always `nil`.
 146