See that edit link in the top right corner of the page? You can now, for better or worse, edit the documentation if you're a registered user.
You would think the documentation system would be good this time, but amazingly, it has evolved into an abomination again. This is because the whole system was nearly finished when people started demanding that it be made editable. The 'wiki' functionality is therefore haphazardly smashed on top of a system which was never intended for release, and it shows. Notably in the error reporting (or lack thereof).
Because the documentation consists of 'static' HTML pages, it must be regenerated manually after you edit a page.
We needed a format less verbose than XML, and something suitable for web-editing. YAML is pretty close, but the whole indent-is-scope thing is a pain when it's not really needed. Existing wiki formats, like the one used by Wikipedia, are too general and article-centric.
The format we ended up with has no name (yet). It works like this:
:key [data]Where
:key
is the keyword (colon plus three letters), and data
is any string that may be parsed in different ways depending on the keyword. Also, data
can span multiple lines. In fact, data
applies until the next :key
or until the end of the file.
Inline formatting, like bold, italic, underline and monospace
.
There are two types of links. Global links, like Google, and LÖVE, and internal links, like love.graphics, love.graphics.setColor, FileMode, File and Introduction.
When referring to LÖVE, always write LÖVE without the umlaut. The umlaut will be added automatically.
Unordered lists.
Ordered lists.
Code without syntax highlighting and line numbers.
Some code goes here
Code without syntax highlighting, but with line numbers.
Lua code in full glory.
foo
with bar
, the result is always foobar
.
:dsc
) if looks better, but never on the first line (see first "don't").
:lua
), but keep them reasonably short.
:txt
about something if there is much to say.
:dsc
). The first line is used as a short description in menus and so forth, and the BBCode will not be parsed there.
:txt
). Don't use it in descriptions for modules, types or functions. If there is much to say about something, create a :txt
for the subject instead.
:mod love :mod love.graphics
:typ love.graphics.Image :dsc A drawable Image object.
:fnc love.graphics.newImage :dsc Creates a new Image.
:txt
).
:mod love :dsc The root module.
Occasionally, you want to go in-depth on a certain topic. This keyword allows you to create 'custom' pages associated with a module, function, or type.
The first argument is the 'name' of the page, consisting of location ('love') and the filename ('page_license'). After that, an optional number indicates the priority of the page. Pages on the same parent will be ordered by their priority in descending order. Finally, a required title for the page (can contain spaces). This title is the identifier for the page. Therefore, no two pages can have the same title, even if they have different parents.
:txt love.page_license 5 License :txt love.page_index 1000 Welcome
Creates an argument for a function.
:fnc love.filesystem.exists :arg string filename The filename to check for existence. :ret bool exists True if file exists, false otherwise.You can also specify a default value for an argument.
:fnc love.filesystem.setColor :arg number r Red component (0-255). :arg number g Green component (0-255). :arg number b Blue component (0-255). :arg number a=255 Alpha component (0-255).
Creates a return value for a function. Functions may have multiple return values. Return values may not have defaults.
:fnc love.filesystem.getColor :ret number r Red component (0-255). :ret number g Green component (0-255). :ret number b Blue component (0-255). :ret number a Alpha component (0-255).
Creates a new constant group on a module or type. No two groups can have the same name, even if they are in different modules.
:grp love.filesystem.File.FileMode :con r Read mode. :con w Write mode. :con a Append mode.
Adds a constant to the current :grp
.
:grp love.filesystem.File.FileMode :con r Read mode. :con w Write mode. :con a Append mode.
:fnc love.graphics.print :lua Hello World function love.draw() love.graphics.print("Hello World", 400, 300) end
:typ love.physics.CircleShape :sup love.physics.Shape
Adds entries to the 'See Also' section of a function, module, or type.
:fnc love.graphics.newImage :see love.image.ImageData
You can use ::::
for comments in the source.
:::: This is a comment