Wuzzy/minetest_doc
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Minor copy-editing of API.md

Browse Source
This commit is contained in:
Wuzzy 2016-12-22 14:11:20 +01:00
parent 1cb93487f4
commit fe47c6850e
1 changed files with 33 additions and 20 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

51
API.md
View File

@ -12,15 +12,17 @@ documentation. Categories group multiple entries of the same topic together.
Categories also define a template function which is used to determine how the
final result in the tab “Entry list” looks like. Entries themselves have
a data field attached to them, this is a table containing arbitrary metadata
which is used to construct the final formspec which is used on the Entry tab.
which is used to construct the final formspec in the Entry tab. It may also
be used for sorting entries in the entry list.
## Advanced concepts
### Viewed and hidden entries
The mod keeps track of which entries have been viewed on a per-player basis.
Any entry which has been accessed by a player is instantly marked as “viewed”.
Any entry which has been accessed by a player is immediately marked as
“viewed”.
It also allows entries to be hidden. Hidden entries are not visible or
otherwise accessible to players until they become revealed by function calls.
Entries can also be hidden. Hidden entries are not visible or otherwise
accessible to players until they become revealed by function calls.
Marking an entry as viewed or revealed is not reversible with this API.
The viewed and hidden states are stored in the file `doc.mt` inside the
@ -29,13 +31,13 @@ the player states.
### Entry aliases
Entry aliases are alternative identifiers for entry identifiers. With the
exception of the alias functions themselves, for function demanding an
exception of the alias functions themselves, for functions demanding an
`entry_id` you can either supply the original `entry_id` or any alias of the
`entry_id`.
## Possible use cases
Here are some possible use cases to give you a rough idea what
this mod is capable of and how certain use cases should be implemented.
This section shows some possible use cases to give you a rough idea what
this mod is capable of and how these use cases could be implemented.
### Simple use case: Minetest basics
Let's say you want to write in free form short help texts about the basic
@ -68,24 +70,25 @@ This is a list of all publicly available functions.
The most important functions are `doc.new_category` and `doc.new_entry`. All other functions
are mostly used for utility and examination purposes.
If not mentioned otherwise, the return value of all functions is `nil`.
These functions are available:
#### Core
* `doc.new_category`: Adds a new category
* `doc.new_entry`: Adds a new entry
* `doc.set_category_order`: Sets the order of categories in the category list
#### Display
* `doc.show_entry`: Shows a particular entry to a player
* `doc.show_category`: Shows the entry list of a category to a player
* `doc.show_doc`: Opens the main help form for a player
#### Query
* `doc.get_category_definition`: Returns the definition table of a category
* `doc.get_entry_definition`: Returns the definition table of an entry
* `doc.entry_exists`: Checks whether an entry exists
* `doc.entry_viewed`: Checks whether an entry has been viewed/read by a player
* `doc.entry_revealed`: Checks whether an entry is visible and normally accessible to a player
* `doc.mark_entry_as_viewed`: Manually marks an entry as viewed/read by a player
* `doc.mark_entry_as_revealed`: Make a hidden entry visible and accessible to a player
* `doc.mark_all_entries_as_revealed`: Make all hidden entries visible and accessible to a player
* `doc.add_entry_alias`: Add an alternative name which can be used to access an entry
* `doc.add_entry_aliases`: Add multiple alternative names which can be used to access an entry
* `doc.get_category_count`: Returns the total number of categories
* `doc.get_entry_count`: Returns the total number of entries in a category
* `doc.get_viewed_count`: Returns the number of entries a player has viewed in a category
@ -93,7 +96,15 @@ These functions are available:
* `doc.get_hidden_count`: Returns the number of entries which are hidden from a player in a category
* `doc.get_selection`: Returns the currently viewed entry/category of a player
If not mentioned otherwise, the return value of all functions is `nil`.
#### Modify
* `doc.set_category_order`: Sets the order of categories in the category list
* `doc.mark_entry_as_viewed`: Manually marks an entry as viewed/read by a player
* `doc.mark_entry_as_revealed`: Make a hidden entry visible and accessible to a player
* `doc.mark_all_entries_as_revealed`: Make all hidden entries visible and accessible to a player
#### Aliases
* `doc.add_entry_alias`: Add an alternative name which can be used to access an entry
* `doc.add_entry_aliases`: Add multiple alternative names which can be used to access an entry
#### Special widgets
This API provides functions to add unique “widgets” for functionality
@ -102,6 +113,8 @@ functions in `doc.widgets`.
Currently there is a widget for scrollable multi-line text and a
widget providing an image gallery.
### `doc.new_category(id, def)`
Adds a new category. You have to define an unique identifier, a name
and a template function to build the entry formspec from the entry
@ -168,7 +181,7 @@ following predefined convenience functions:
##### Formspec restrictions
When building your formspec, you have to respect the size limitations.
The help form uses a size of 15×10.5 and you must make sure
The help form currently uses a size of 15×10.5 and you must make sure
all entry widgets are inside a boundary box. The remaining space is
reserved for widgets of the help form and should not be used to avoid
overlapping.
@ -460,8 +473,8 @@ nearly the entire entry page.
#### Return value
Two values are returned, in this order:
* String: Contains a complete formspec definition building the widget.
* String: Formspec element ID of the created widget
* string: Contains a complete formspec definition building the widget
* string: Formspec element ID of the created widget
#### Note
If you use this function to build a formspec string, do not use identifiers
@ -516,8 +529,8 @@ at the left and right side of the images.
#### Return values
Two values are returned, in this order:
* String: Contains a complete formspec definition building the gallery
* Number: The height the gallery occupies in the formspec
* string: Contains a complete formspec definition building the gallery
* number: The height the gallery occupies in the formspec
## Extending this mod (naming conventions)
If you want to extend this mod with your own functionality, it is recommended