API.md

   1 # API documentation for version 0.5.0
   2 ## Core concepts
   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 ### Categories and entries
   8 In the documentation system, everything is built on categories and entries.
   9 An entry is a single piece of documentation and is the basis of all actual
  10 documentation. Categories group multiple entries of the same topic together.
  11
  12 Categories also define a template which is used to determine how the final
  13 result in the Entry tab looks like. Entries themselves have a data field
  14 attached to them, this is a table containing arbitrary metadata which is
  15 used to construct the final formspec which is used on the Entry tab.
  16
  17 ## Advanced concepts
  18 ### Viewed and hidden entries
  19 The mod keeps track of which entries have been viewed by any player.
  20 Any entry which has been accessed by a player is instantly marked as “viewed”.
  21
  22 It also allows entries to be hidden. Hidden entries are not visible or
  23 normally accessible to players until they become revealed by function calls.
  24
  25 Marking an entry as viewed or revealed is not reversible with this API.
  26 The viewed and hidden states are stored in the file `doc.mt` inside the
  27 world directory.
  28
  29 ### Entry aliases
  30 Entry aliases are alternative identifiers for entry identifiers. With the
  31 exception of the alias functions themselves, When a function demands an
  32 `entry_id` you can either supply the original `entry_id` or any alias of the
  33 `entry_id`.
  34
  35 ## Possible use cases
  36 I present to you some possible use cases to give you a rough idea what
  37 this mod is capable and how certain use casescould be implemented.
  38
  39 ### Simple use case: Minetest basics
  40 I want to write in freeform short help texts about the basic concepts of
  41 Minetest or my subgame. First I define a category called “Basics”, the data
  42 for each of its entry is just a freeform text. The template function simply
  43 creates a formspec where this freeform text is displayed.
  44
  45 ### Complex use case: Blocks
  46 I could create a category called “Blocks”, and this category is supposed to
  47 contain entries for every single block in the game. For this case, a freeform
  48 approach would be very inefficient and error-prone, as a lot of data can be
  49 reused.
  50
  51 Here the template function comes in handy: The internal entry data
  52 contain a lot of different things about a block, like block name, identifier,
  53 custom description and most importantly, the definition table of the block.
  54
  55 Finally, the template function takes all that data and turns it into
  56 sentences which are just concatenated, telling as many useful facts about
  57 this block as possible.
  58
  59 ## Functions
  60 This is a list of all publicly available functions.
  61
  62 ### Overview
  63 The most important functions are `doc.new_category` and `doc.new_entry`. All other functions
  64 are mostly used for utility and examination purposes.
  65
  66 These functions are available:
  67
  68 * `doc.new_category`: Adds a new category
  69 * `doc.new_entry`: Adds a new entry
  70 * `doc.show_entry`: Shows a particular entry to a player
  71 * `doc.show_category`: Shows the entry list of a category to a player
  72 * `doc.show_doc`: Opens the main Documentation System form for a player
  73 * `doc.get_category_definition`: Returns the definition table of a category
  74 * `doc.get_entry_definition`: Returns the definition table of an entry
  75 * `doc.entry_exists`: Checks whether an entry exists
  76 * `doc.entry_viewed`: Checks whether an entry has been viewed/read by a player
  77 * `doc.entry_revealed`: Checks whether an entry is visible and normally accessible to a player
  78 * `doc.mark_entry_as_viewed`: Manually marks an entry as viewed/read by a player
  79 * `doc.mark_entry_as_revealed`: Make a hidden entry visible and accessible to a player
  80 * `doc.add_entry_alias`: Add an alternative name which can be used to access an entry
  81 * `doc.add_entry_aliases`: Add multiple alternative names which can be used to access an entry
  82 * `doc.get_category_count`: Returns the total number categories
  83 * `doc.get_entry_count`: Returns the total number of entries in a category
  84 * `doc.get_viewed_count`: Returns the number of entries a player has viewed in a category
  85 * `doc.get_revealed_count`: Returns the number of entries a player has access to in a category
  86 * `doc.get_hidden_count`: Returns the number of entries which are hidden from a player in a category
  87
  88 ### `doc.new_category(id, def)`
  89 Adds a new category. You have to define an unique identifier, a name
  90 and a template function to build the entry formspec from the entry
  91 data.
  92
  93 **Important**: You must call this function before any player joins, but not later.
  94
  95 #### Parameters
  96 * `id`: Unique category identifier as a string
  97 * `def`: Definition table, it has the following fields:
  98     * `name`: Category name to be shown in the interface
  99     * `description`: (optional) Short description of the category,
 100        will be shown as tooltip. Recommended style (in English):
 101        First letter capitalized, no puncation at end of sentence,
 102        max. 100 characters
 103     * `build_formspec`: The template function. Takes entry data as its
 104       only parameter (has the data type of the entry data) and must
 105       return a formspec which is inserted in the Entry tab.
 106     * `sorting`: (optional) Sorting algorithm for display order of entries
 107         * `"abc"`: Alphabetical (default)
 108         * `"nosort"`: Entries appear in no particular order
 109         * `"custom"`: Manually define the order of entries in `sorting_data`
 110         * `"function"`: Sort by function defined in `sorting_data`
 111     * `sorting_data`: (optional) Additional data for special sorting methods.
 112         * If `sorting=="custom"`, this field must contain a table (list form) in which
 113           the entry IDs are specified in the order they are supposed to appear in the
 114           entry list. All entries which are missing in this table will appear in no
 115           particular order below the final specified one.
 116         * If `sorting=="function"`, this field is a compare function to be used as
 117           the `comp` parameter of `table.sort`. The parameters given are two entries.
 118         * This field is not required if `sorting` has any other value
 119     * `hide_entries_by_default` (optional, experimental): If `true`, all entries
 120       added to this category will start as hidden, unless explicitly specified otherwise
 121       (default: `false`)
 122
 123 Note: For function-based sorting, the entries provided in the compare function have the
 124 following format:
 125
 126     {
 127         name = n, -- entry name
 128         data = d, -- arbitrary entry data
 129     }
 130
 131 #### Using `build_formspec`
 132 For `build_formspec` you can either define your own function which
 133 procedurally generates the entry formspec or you use one of the
 134 following predefined convenience functions:
 135
 136 * `doc.entry_builders.text`: Expects entry data to be a string.
 137   It will be inserted directly into the entry. Useful for entries with
 138   a freeform text.
 139 * `doc.entry_builders.formspec`: Entry data is expected to contain the
 140   complete entry formspec as a string. Useful if your entries. Useful
 141   if you expect your entries to differ wildly in layouts.
 142
 143 When building your formspec, you have to respect the size limitations.
 144 The documentation system uses a size of `12,9` and you should place
 145 all your formspec elements at positions not lower than `0.25,0.5` to
 146 avoid overlapping.
 147
 148 #### Return value
 149 Always `nil`.
 150
 151 ### `doc.new_entry(category_id, entry_id, def)`
 152 Adds a new entry into an existing category. You have to define the category
 153 to which to insert the entry, the entry's identifier, a name and some
 154 data which defines the entry. Note you do not directly define here how the
 155 end result of an entry looks like, this is done by `build_formspec` from
 156 the category definition.
 157
 158 **Important**: You must call this function before any player joins, but not later.
 159
 160 #### Parameters
 161 * `category_id`: Identifier of the category to add the entry into
 162 * `entry_id`: Unique identifier of the new entry, as a string
 163 * `def`: Definition table, it has the following fields:
 164     * `name`: Entry name to be shown in the interface
 165     * `hidden`: (optional) If `true`, entry will not be displayed in entry list
 166       initially (default: `false`); it can be revealed later
 167     * `data`: Arbitrary data attached to the entry. Any data type is allowed;
 168       The data in this field will be used to create the actual formspec
 169       with `build_formspec` from the category definition
 170
 171 #### Return value
 172 Always `nil`.
 173
 174 ### `function doc.show_doc(playername)`
 175 Opens the main documentation formspec for the player (Main tab).
 176
 177 #### Parameters
 178 * `playername`: Name of the player to show the formspec to
 179
 180 ### `doc.show_category(playername, category_id)`
 181 Opens the documentation formspec for the player at the specified category
 182 (Category tab).
 183
 184 #### Parameters
 185 * `playername`: Name of the player to show the formspec to
 186 * `category_id`: Category identifier of the selected category
 187
 188 #### Return value
 189 Always `nil`.
 190
 191 ### `doc.show_entry(playername, category_id, entry_id, ignore_hidden)`
 192 Opens the documentation formspec for the player showing the specified entry
 193 of a category (Entry tab). If the entry is hidden, an error message
 194 is displayed unless `ignore_hidden==true`.
 195
 196 #### Parameters
 197 * `playername`: Name of the player to show the formspec to
 198 * `category_id`: Category identifier of the selected category
 199 * `entry_id`: Entry identifier of the entry to show
 200 * `ignore_hidden`: (optional) If `true`, shows entry even if it is still hidden
 201   to the player; this will automatically reveal the entry to this player for the
 202   rest of the game
 203
 204 #### Return value
 205 Always `nil`.
 206
 207 ### `doc.get_category_definition(category_id)`
 208 Returns the definition of the specified category.
 209
 210 #### Parameters
 211 * `category_id`: Category identifier of the category to the the definition
 212   for
 213
 214 #### Return value
 215 The category's definition table as spefied in the `def` argument of
 216 `doc.new_category`. The table fields are the same.
 217
 218 ### `doc.get_entry_definition(category_id, entry_id)`
 219 Returns the definition of the specified entry.
 220
 221 #### Parameters
 222 * `category_id`: Category identifier of entry's category
 223 * `entry_id`: Entry identifier of the entry to get the definition for
 224
 225 #### Return value
 226 The entry's definition table as spefied in the `def` argument of
 227 `doc.new_entry`. The table fields are the same.
 228
 229 ### `doc.entry_exists(category_id, entry_id)`
 230 Checks if the specified entry exists and returns `true` or `false`.
 231
 232 #### Parameters
 233 * `category_id`: Category identifier of the category to check
 234 * `entry_id`: Entry identifier of the entry to check for its existance
 235
 236 #### Return value
 237 Returns `true` if and only if:
 238
 239 * The specified category exists
 240 * This category contains the specified entry
 241
 242 Otherwise, returns `false`.
 243
 244 ### `doc.entry_viewed(playername, category_id, entry_id)`
 245 Tells whether the specified entry is marked as “viewed” (or read) by
 246 the player.
 247
 248 #### Parameters
 249 * `playername`: Name of the player to check
 250 * `category_id`: Category identifier of the category to check
 251 * `entry_id`: Entry identifier of the entry to check
 252
 253 #### Return value
 254 `true`, if entry is viewed, `false` otherwise.
 255
 256 ### `doc.entry_revealed(playername, category_id, entry_id)`
 257 Tells whether the specified entry is marked as “revealed” to the player
 258 and thus visible and generally accessible.
 259
 260 #### Parameters
 261 * `playername`: Name of the player to check
 262 * `category_id`: Category identifier of the category to check
 263 * `entry_id`: Entry identifier of the entry to check
 264
 265 #### Return value
 266 `true`, if entry is revealed, `false` otherwise.
 267
 268 ### `doc.mark_entry_as_viewed(playername, category_id, entry_id)`
 269 Marks a particular entry as “viewed” (or read) by a player. This will
 270 also automatically reveal the entry to the player permanently.
 271
 272 #### Parameters
 273 * `playername`: Name of the player for whom to mark an entry as “viewed”
 274 * `category_id`: Category identifier of the category of the entry to mark
 275 * `entry_id`: Entry identifier of the entry to mark
 276
 277 #### Returns
 278 Always `nil`.
 279
 280 ### `doc.mark_entry_as_revealed(playername, category_id, entry_id)`
 281 Marks a particular entry as “revealed” to a player. If the entry is
 282 declared as hidden, it will become visible in the list of entries for
 283 this player and will always be accessible with `doc.show_entry`. This
 284 change is permanently.
 285
 286 For entries which are not normally hidden, this function has no direct
 287 effect.
 288
 289 #### Parameters
 290 * `playername`: Name of the player for whom to reveal the entry
 291 * `category_id`: Category identifier of the category of the entry to reveal
 292 * `entry_id`: Entry identifier of the entry to reveal
 293
 294 #### Returns
 295 Always `nil`.
 296
 297 ### `doc.add_entry_alias(category_id, entry_id, alias)`
 298 Adds a single alias for an entry. When an entry has an alias, supplying the
 299 alias to a function which demands an `entry_id` will work as if the original
 300 `entry_id` has been supplied. Aliases are true within one category only.
 301
 302 #### Parameters
 303 * `category_id`: Category identifier of the category of the entry in question
 304 * `entry_id`: The original (!) entry identifier of the entry to create an alias
 305   for
 306 * `alias`: Alias (string) for `entry_id`
 307
 308 #### Return value
 309 Always `nil`.
 310
 311 ### `doc.add_entry_aliases(category_id, entry_id, aliases)`
 312 Adds an arbitrary amount of aliases for an entry at once. Apart from that, this
 313 function has the same effect as `doc.add_entry_alias`.
 314
 315 #### Parameters
 316 * `category_id`: Category identifier of the category of the entry in question
 317 * `entry_id`: The original (!) entry identifier of the entry to create aliases
 318   for
 319 * `aliases`: Table/list of aliases (strings) for `entry_id`
 320
 321 #### Return value
 322 Always `nil`.
 323
 324 ### `doc.get_category_count()`
 325 Returns the number of registered categories.
 326
 327 ### `doc.get_entry_count(category_id)`
 328 Returns the number of entries in a category.
 329
 330 #### Parameters
 331 * `category_id`: Category identifier of the category in which to count entries
 332
 333 #### Return value
 334 Number of entries in the specified category.
 335
 336 ### `function doc.get_viewed_count(playername, category_id)`
 337 Returns how many entries have been viewed by a player.
 338
 339 #### Parameters
 340 * `playername`: Name of the player to count the viewed entries for
 341 * `category_id`: Category identifier of the category in which to count the
 342   viewed entries
 343
 344 #### Return value
 345 Amount of entries the player has viewed in the specified category. If the
 346 player does not exist, this function returns `nil`.
 347
 348 ### `function doc.get_revealed_count(playername, category_id)`
 349 Returns how many entries the player has access to (non-hidden entries)
 350 in this category.
 351
 352 #### Parameters
 353 * `playername`: Name of the player to count the revealed entries for
 354 * `category_id`: Category identifier of the category in which to count the
 355   revealed entries
 356
 357 #### Return value
 358 Amount of entries the player has access to in the specified category. If the
 359 player does not exist, this function returns `nil`.
 360
 361 ### `function doc.get_hidden_count(playername, category_id)`
 362 Returns how many entries are hidden from the player in this category.
 363
 364 #### Parameters
 365 * `playername`: Name of the player to count the hidden entries for
 366 * `category_id`: Category identifier of the category in which to count the
 367   hidden entries
 368
 369 #### Return value
 370 Amount of entries hidden from the player. If the player does not exist,
 371 this function returns `nil`.
 372
 373
 374 ## Extending this mod (naming conventions)
 375 If you want to extend this mod with your own functionality, it is recommended
 376 that you put all API functions into `doc.sub.<name>`.
 377 As a naming convention, if your mod depends on `doc`, your mod name should also start
 378 with “`doc_`”, like `doc_items`, `doc_minetest_game`, `doc_identifier`.
 379
 380 One mod which uses this convention is `doc_items` which uses the `doc.sub.items`
 381 table.