Mercurial > molko

changeset 239:d47e70da760e

Find changesets by keywords (author, files, the commit message), revision number or hash, or revset expression.
doc: switch to mkdocs+doxybook2, closes #2516 @2h
author David Demelier <markand@malikania.fr>
date Fri, 27 Nov 2020 17:00:30 +0100
parents b30c3af37a01
children d7e5e02f70a1
files CMakeLists.txt doc/CMakeLists.txt doc/about.rst doc/api.rst doc/api/core/action.rst doc/api/core/alloc.rst doc/api/core/animation.rst doc/api/core/clock.rst doc/api/core/color.rst doc/api/core/core.rst doc/api/core/drawable.rst doc/api/core/error.rst doc/api/core/event.rst doc/api/core/font.rst doc/api/core/game.rst doc/api/core/image.rst doc/api/core/inhibit.rst doc/api/core/key.rst doc/api/core/maths.rst doc/api/core/mouse.rst doc/api/core/music.rst doc/api/core/painter.rst doc/api/core/panic.rst doc/api/core/save.rst doc/api/core/script.rst doc/api/core/sound.rst doc/api/core/sprite.rst doc/api/core/state.rst doc/api/core/sys.rst doc/api/core/texture.rst doc/api/core/trace.rst doc/api/core/util.rst doc/api/core/wait.rst doc/api/core/window.rst doc/api/libcore.rst doc/build.rst doc/conf.py doc/docs/about.md doc/docs/dev/error.md doc/docs/dev/faq.md doc/docs/dev/howto/01-init.md doc/docs/dev/ownership.md doc/docs/index.md doc/docs/install.md doc/docs/specs/map.md doc/docs/specs/tileset.md doc/docs/tools/bcc.md doc/docs/tools/map.md doc/docs/tools/tileset.md doc/doxybook.json doc/doxygen/groups.c doc/index.rst doc/mkdocs.yml doc/spec-map.rst doc/spec-tileset.rst doc/specifications.rst doc/tool-bcc.rst doc/tool-map.rst doc/tool-tileset.rst doc/tools.rst doxygen/CMakeLists.txt doxygen/groups.c doxygen/mainpage.c doxygen/page-faq.c doxygen/page-howto-error.c doxygen/page-howto-initialization.c doxygen/page-howto-ownership.c doxygen/page-portability.c
diffstat 68 files changed, 933 insertions(+), 1293 deletions(-) [+]
line wrap: on
line diff
--- a/CMakeLists.txt	Fri Nov 27 13:32:52 2020 +0100
+++ b/CMakeLists.txt	Fri Nov 27 17:00:30 2020 +0100
@@ -24,8 +24,7 @@
 set(CMAKE_C_EXTENSIONS Off)
 set(CMAKE_MODULE_PATH "${CMAKE_SOURCE_DIR}/cmake")
 
-option(MOLKO_WITH_DOXYGEN "Enable Doxygen build" On)
-option(MOLKO_WITH_DOC "Enable documentation (requires sphinx)" On)
+option(MOLKO_WITH_DOC "Enable documentation (requires doxygen, doxybook2 and mkdocs)" On)
 option(MOLKO_WITH_TESTS "Enable unit tests" On)
 option(MOLKO_WITH_EXAMPLES "Enable build of examples" On)
 
@@ -48,10 +47,6 @@
 add_subdirectory(extern/libgreatest)
 add_subdirectory(extern/libsqlite)
 
-if (MOLKO_WITH_DOXYGEN)
-	add_subdirectory(doxygen)
-endif ()
-
 add_subdirectory(tools/bcc)
 add_subdirectory(tools/map)
 add_subdirectory(tools/tileset)
@@ -63,10 +58,6 @@
 add_subdirectory(molko)
 
 if (MOLKO_WITH_DOC)
-	if (NOT MOLKO_WITH_DOXYGEN)
-		message(FATAL_ERROR "Can't build documentation with doxygen disabled")
-	endif ()
-
 	add_subdirectory(doc)
 endif ()
 
--- a/doc/CMakeLists.txt	Fri Nov 27 13:32:52 2020 +0100
+++ b/doc/CMakeLists.txt	Fri Nov 27 17:00:30 2020 +0100
@@ -18,36 +18,118 @@
 
 project(doc)
 
-find_program(SPHINX_EXE sphinx-build DOC "Path to sphinx-build")
+find_package(Doxygen QUIET)
+find_program(MKDOCS_EXE mkdocs DOC "Path to mkdocs")
+find_program(DOXYBOOK2_EXE doxybook2 DOC "Path to doxybook2")
 
-if (SPHINX_EXE)
+if (DOXYGEN_FOUND AND MKDOCS_EXE AND DOXYBOOK2_EXE)
+	set(
+		DOXYGEN_SOURCES
+		libcore
+		libui
+		librpg
+		${doc_SOURCE_DIR}/doxygen/groups.c
+	)
+
 	set(
-		SOURCES
-		${doc_SOURCE_DIR}/about.rst
-		${doc_SOURCE_DIR}/build.rst
-		${doc_SOURCE_DIR}/conf.py
-		${doc_SOURCE_DIR}/index.rst
-		${doc_SOURCE_DIR}/spec-map.rst
-		${doc_SOURCE_DIR}/spec-tileset.rst
-		${doc_SOURCE_DIR}/specifications.rst
-		${doc_SOURCE_DIR}/tool-bcc.rst
-		${doc_SOURCE_DIR}/tool-map.rst
-		${doc_SOURCE_DIR}/tool-tileset.rst
-		${doc_SOURCE_DIR}/tools.rst
+		DOXYGEN_STRIP_FROM_PATH
+		${CMAKE_SOURCE_DIR}/libcore
+		${CMAKE_SOURCE_DIR}/libui
+		${CMAKE_SOURCE_DIR}/librpg
+	)
+	set(
+		DOC_SOURCES
+		${doc_SOURCE_DIR}/docs/specs/map.md
+		${doc_SOURCE_DIR}/docs/specs/tileset.md
+		${doc_SOURCE_DIR}/docs/tools/bcc.md
+		${doc_SOURCE_DIR}/docs/tools/map.md
+		${doc_SOURCE_DIR}/docs/tools/tileset.md
+		${doc_SOURCE_DIR}/docs/about.md
+		${doc_SOURCE_DIR}/docs/index.md
+		${doc_SOURCE_DIR}/docs/install.md
+		${doc_SOURCE_DIR}/mkdocs.yml
 	)
 
-	configure_file(
-		${doc_SOURCE_DIR}/conf.py
-		${doc_BINARY_DIR}/conf.py
+	# 1. Generate XML structure with Doxygen.
+	set(DOXYGEN_SHOW_GROUPED_MEMB_INC NO)
+	set(DOXYGEN_SHOW_INCLUDE_FILES NO)
+	set(DOXYGEN_SHOW_USED_FILES NO)
+	set(DOXYGEN_ALLOW_UNICODE_NAMES YES)
+	set(DOXYGEN_AUTOLINK_SUPPORT NO)
+	set(DOXYGEN_ENABLE_PREPROCESSING YES)
+	set(DOXYGEN_EXAMPLE_PATH examples)
+	set(DOXYGEN_EXCLUDE_PATTERNS *_p.h)
+	set(DOXYGEN_FILE_PATTERNS *.h)
+	set(DOXYGEN_GENERATE_LATEX NO)
+	set(DOXYGEN_GENERATE_MAN NO)
+	set(DOXYGEN_GENERATE_XML YES)
+	set(DOXYGEN_GENERATE_HTML NO)
+	set(DOXYGEN_INPUT_ENCODING UTF-8)
+	set(DOXYGEN_MAX_INITIALIZER_LINES 0)
+	set(DOXYGEN_OPTIMIZE_OUTPUT_FOR_C YES)
+	set(DOXYGEN_OUTPUT_DIRECTORY doxygen)
+	set(DOXYGEN_PREDEFINED DOXYGEN)
+	set(DOXYGEN_XML_OUTPUT ${doc_BINARY_DIR}/doxygen-xml)
+	#set(DOXYGEN_PROJECT_BRIEF "2D RPG game in C")
+	#set(DOXYGEN_PROJECT_NAME "Molko's Adventure")
+	set(DOXYGEN_QUIET YES)
+	set(DOXYGEN_RECURSIVE YES)
+	set(DOXYGEN_TAB_SIZE 8)
+	set(DOXYGEN_WARNINGS YES)
+
+	# 1. Generate XML from doxygen.
+	doxygen_add_docs(
+		doc-doxygen-xml
+		${DOXYGEN_SOURCES}
+		WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}"
+	)
+
+	# 2. Convert XML through markdown with doxybook2.
+	add_custom_target(
+		doc-doxybook
+		VERBATIM
+		DEPENDS doc-doxygen-xml
+		COMMAND
+			${CMAKE_COMMAND} -E make_directory ${doc_BINARY_DIR}/docs
+		COMMAND ${DOXYBOOK2_EXE} -q
+			-i ${doc_BINARY_DIR}/doxygen-xml
+			-o ${doc_BINARY_DIR}/docs
+			-c ${doc_SOURCE_DIR}/doxybook.json
+	)
+
+	# 3. Copy the directory containing hand-made documentation and call mkdocs.
+	add_custom_target(
+		doc
+		VERBATIM
+		DEPENDS doc-doxybook
+		WORKING_DIRECTORY ${doc_BINARY_DIR}
+		COMMAND
+			${CMAKE_COMMAND} -E copy_directory
+				${doc_SOURCE_DIR}/docs
+				${doc_BINARY_DIR}/docs
+		COMMAND
+			${CMAKE_COMMAND} -E copy
+				${doc_SOURCE_DIR}/mkdocs.yml
+				${doc_BINARY_DIR}
+		COMMAND
+			${MKDOCS_EXE} build
+				-d ${doc_BINARY_DIR}/html
 	)
 
 	add_custom_target(
-		doc
-		ALL VERBATIM
-		SOURCES ${SOURCES}
-		COMMAND ${SPHINX_EXE} -c ${doc_BINARY_DIR} -q . ${doc_BINARY_DIR}
-		WORKING_DIRECTORY ${doc_SOURCE_DIR}
-		COMMENT "Generating documentation"
-		DEPENDS doxygen
+		doc-serve
+		VERBATIM
+		DEPENDS doc-doxybook
+		WORKING_DIRECTORY ${doc_BINARY_DIR}
+		COMMAND
+			${CMAKE_COMMAND} -E copy_directory
+				${doc_SOURCE_DIR}/docs
+				${doc_BINARY_DIR}/docs
+		COMMAND
+			${CMAKE_COMMAND} -E copy
+				${doc_SOURCE_DIR}/mkdocs.yml
+				${doc_BINARY_DIR}
+		COMMAND
+			${MKDOCS_EXE} serve
 	)
 endif ()
--- a/doc/about.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,19 +0,0 @@
-=====
-About
-=====
-
-Molko's Adventure is a 2D solo RPG game and an API to build more RPG games. It
-is designed with the following characteristics:
-
-- Turn based battle. Similar to old RPG games battle operate on a dedicated game
-  state where the player and enemies select actions to perform when the member
-  is ready to play.
-- Tile based maps using scrolling and pixel granularity movements.
-- Theme system to allow customization of some user interface components.
-- Set of predefined dialog windows to control the game.
-
-While the API is flexible and powerful enough to create different games, it is
-still kept as simple possible without cluttering the API with dozen of
-abstraction and generics all over the place. This means that there are
-predefined kinds of character status (poison, slow, etc) along with kind of
-spells (earth, neutral).
--- a/doc/api.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,22 +0,0 @@
-=============
-API Reference
-=============
-
-Official C API reference.
-
-The API is split into individual libraries:
-
-``libcore``
-  Low level access to the library that provides input, sound, animations and
-  windowing system.
-
-``libui``
-  User interface elements.
-
-``librpg``
-  Every other components that are related to the RPG gameplay.
-
-.. toctree::
-   :maxdepth: 1
-
-   api/libcore
--- a/doc/api/core/action.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,5 +0,0 @@
-========================
-#include <core/action.h>
-========================
-
-.. doxygenfile:: core/action.h
--- a/doc/api/core/alloc.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,5 +0,0 @@
-=======================
-#include <core/alloc.h>
-=======================
-
-.. doxygenfile:: core/alloc.h
--- a/doc/api/core/animation.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,5 +0,0 @@
-===========================
-#include <core/animation.h>
-===========================
-
-.. doxygenfile:: core/animation.h
--- a/doc/api/core/clock.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,5 +0,0 @@
-=======================
-#include <core/clock.h>
-=======================
-
-.. doxygenfile:: core/clock.h
--- a/doc/api/core/color.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,5 +0,0 @@
-=======================
-#include <core/color.h>
-=======================
-
-.. doxygenfile:: core/color.h
--- a/doc/api/core/core.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,5 +0,0 @@
-======================
-#include <core/core.h>
-======================
-
-.. doxygenfile:: core/core.h
--- a/doc/api/core/drawable.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,5 +0,0 @@
-==========================
-#include <core/drawable.h>
-==========================
-
-.. doxygenfile:: core/drawable.h
--- a/doc/api/core/error.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,5 +0,0 @@
-=======================
-#include <core/error.h>
-=======================
-
-.. doxygenfile:: core/error.h
--- a/doc/api/core/event.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,5 +0,0 @@
-=======================
-#include <core/event.h>
-=======================
-
-.. doxygenfile:: core/event.h
--- a/doc/api/core/font.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,5 +0,0 @@
-======================
-#include <core/font.h>
-======================
-
-.. doxygenfile:: core/font.h
--- a/doc/api/core/game.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,5 +0,0 @@
-======================
-#include <core/game.h>
-======================
-
-.. doxygenfile:: core/game.h
--- a/doc/api/core/image.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,5 +0,0 @@
-=======================
-#include <core/image.h>
-=======================
-
-.. doxygenfile:: core/image.h
--- a/doc/api/core/inhibit.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,5 +0,0 @@
-=========================
-#include <core/inhibit.h>
-=========================
-
-.. doxygenfile:: core/inhibit.h
--- a/doc/api/core/key.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,5 +0,0 @@
-=====================
-#include <core/key.h>
-=====================
-
-.. doxygenfile:: core/key.h
--- a/doc/api/core/maths.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,5 +0,0 @@
-=======================
-#include <core/maths.h>
-=======================
-
-.. doxygenfile:: core/maths.h
--- a/doc/api/core/mouse.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,5 +0,0 @@
-=======================
-#include <core/mouse.h>
-=======================
-
-.. doxygenfile:: core/mouse.h
--- a/doc/api/core/music.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,5 +0,0 @@
-=======================
-#include <core/music.h>
-=======================
-
-.. doxygenfile:: core/music.h
--- a/doc/api/core/painter.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,5 +0,0 @@
-=========================
-#include <core/painter.h>
-=========================
-
-.. doxygenfile:: core/painter.h
--- a/doc/api/core/panic.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,5 +0,0 @@
-=======================
-#include <core/panic.h>
-=======================
-
-.. doxygenfile:: core/panic.h
--- a/doc/api/core/save.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,5 +0,0 @@
-======================
-#include <core/save.h>
-======================
-
-.. doxygenfile:: core/save.h
--- a/doc/api/core/script.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,5 +0,0 @@
-========================
-#include <core/script.h>
-========================
-
-.. doxygenfile:: core/script.h
--- a/doc/api/core/sound.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,5 +0,0 @@
-=======================
-#include <core/sound.h>
-=======================
-
-.. doxygenfile:: core/sound.h
--- a/doc/api/core/sprite.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,5 +0,0 @@
-========================
-#include <core/sprite.h>
-========================
-
-.. doxygenfile:: core/sprite.h
--- a/doc/api/core/state.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,5 +0,0 @@
-=======================
-#include <core/state.h>
-=======================
-
-.. doxygenfile:: core/state.h
--- a/doc/api/core/sys.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,5 +0,0 @@
-=====================
-#include <core/sys.h>
-=====================
-
-.. doxygenfile:: core/sys.h
--- a/doc/api/core/texture.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,5 +0,0 @@
-=========================
-#include <core/texture.h>
-=========================
-
-.. doxygenfile:: core/texture.h
--- a/doc/api/core/trace.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,5 +0,0 @@
-=======================
-#include <core/trace.h>
-=======================
-
-.. doxygenfile:: core/trace.h
--- a/doc/api/core/util.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,5 +0,0 @@
-======================
-#include <core/util.h>
-======================
-
-.. doxygenfile:: core/util.h
--- a/doc/api/core/wait.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,5 +0,0 @@
-======================
-#include <core/wait.h>
-======================
-
-.. doxygenfile:: core/wait.h
--- a/doc/api/core/window.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,5 +0,0 @@
-========================
-#include <core/window.h>
-========================
-
-.. doxygenfile:: core/window.h
--- a/doc/api/libcore.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,38 +0,0 @@
-================
-Library: libcore
-================
-
-.. toctree::
-   :maxdepth: 1
-
-   core/action
-   core/alloc
-   core/animation
-   core/clock
-   core/color
-   core/core
-   core/drawable
-   core/error
-   core/event
-   core/font
-   core/game
-   core/image
-   core/inhibit
-   core/key
-   core/maths
-   core/mouse
-   core/music
-   core/painter
-   core/panic
-   core/save
-   core/script
-   core/sound
-   core/sprite
-   core/state
-   core/sys
-   core/texture
-   core/trace
-   core/util
-   core/util
-   core/wait
-   core/window
--- a/doc/build.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,98 +0,0 @@
-====================
-Building from source
-====================
-
-This page will explain how to build Molko's Adventure and libraries.
-
-Requirements
-------------
-
-The following requirements are necessary to build the project.
-
-- C11 compiler: obviously,
-- cmake_: the build system,
-- `SDL2`_: the main game library,
-- `SDL2_image`_: to load images,
-- `SDL2_mixer`_: to play sounds and music,
-- `SDL2_ttf`_: to open fonts,
-- `Jansson`_: only for ``mlk-tileset`` and ``mlk-map`` tools.
-
-Platforms supported
--------------------
-
-The project has been tested on the following platforms.
-
-- Windows 10: only with `MSYS2`_, Visual Studio **is not** supported yet.
-- macOS 11.0 (Big Sur): using Xcode 12 and libraries from `brew`_,
-- Linux: on Alpine Linux (musl) and Arch Linux.
-
-C and POSIX features
---------------------
-
-Both of the API and the game are written using C99 and C11 but not all of the
-features from both C versions are required. Here's a list of functionalities
-that are required:
-
-From C99
-^^^^^^^^
-
-Features:
-
-- `Compound literals`_,
-- `inline`_ keyword.
-
-Headers:
-
-- `stdbool.h`_
-
-Functions:
-
-- `snprintf`_
-
-From C11
-^^^^^^^^
-
-- `stdnoreturn.h`_
-
-From POSIX
-^^^^^^^^^^
-
-Expectations:
-
-- We use a few parts of POSIX_ specification but try to keep its use limited as
-  not all platforms are POSIX compliant.
-- We assume that ``fopen``, ``malloc`` and friends set errno in case of failures.
-
-Functions:
-
-- `dirname`_,
-- `getopt`_.
-
-Headers:
-
-- `libgen.h`_
-
-Macros:
-
-- PATH_MAX: in limits.h.
-
-.. note:: When a POSIX requirement isn't present it is replaced by a shim
-   specified for the platform.
-
-.. _Compound literals: https://en.cppreference.com/w/c/language/compound_literal
-.. _Jansson: https://digip.org/jansson
-.. _MSYS2: https://www.msys2.org
-.. _POSIX: https://pubs.opengroup.org/onlinepubs/9699919799
-.. _SDL2: http://libsdl.org
-.. _SDL2_image: https://www.libsdl.org/projects/SDL_image
-.. _SDL2_mixer: https://www.libsdl.org/projects/SDL_mixer
-.. _SDL2_ttf: https://www.libsdl.org/projects/SDL_ttf
-.. _brew: https://brew.sh
-.. _cmake: http://cmake.org
-.. _dirname: https://pubs.opengroup.org/onlinepubs/9699919799/functions/dirname.html
-.. _getopt: https://pubs.opengroup.org/onlinepubs/9699919799/functions/getopt.html
-.. _inline: https://en.cppreference.com/w/c/language/inline
-.. _libgen.h: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/libgen.h.html
-.. _snprintf: https://en.cppreference.com/w/c/io/fprintf
-.. _stdbool.h: https://en.cppreference.com/w/c/language/arithmetic_types#Boolean_type
-.. _stdnoreturn.h: https://en.cppreference.com/w/c/types
--- a/doc/conf.py	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,38 +0,0 @@
-#
-# conf.py -- sphinx documentation configuration
-#
-# Copyright (c) 2020 David Demelier <markand@malikania.fr>
-#
-# Permission to use, copy, modify, and/or distribute this software for any
-# purpose with or without fee is hereby granted, provided that the above
-# copyright notice and this permission notice appear in all copies.
-#
-# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
-# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
-# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
-# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
-# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
-# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
-# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-#
-
-# Project information.
-project = "Molko's Adventure"
-copyright = "2020, David Demelier"
-author = "David Demelier"
-release = '0.1.0'
-
-# General settings.
-templates_path = ["_templates"]
-exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
-
-# HTML output.
-html_theme = "haiku"
-html_static_path = ["_static"]
-
-# Doxygen bridge through breathe.
-extensions = [ "breathe" ]
-breathe_projects = {
-    "molko": "@doxygen_BINARY_DIR@/doxygen/xml"
-}
-breathe_default_project = "molko"
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/docs/about.md	Fri Nov 27 17:00:30 2020 +0100
@@ -0,0 +1,17 @@
+# About
+
+Molko's Adventure is a 2D solo RPG game and an API to build more RPG games. It
+is designed with the following characteristics:
+
+- Turn based battle. Similar to old RPG games battle operate on a dedicated game
+  state where the player and enemies select actions to perform when the member
+  is ready to play.
+- Tile based maps using scrolling and pixel granularity movements.
+- Theme system to allow customization of some user interface components.
+- Set of predefined dialog windows to control the game.
+
+While the API is flexible and powerful enough to create different games, it is
+still kept as simple possible without cluttering the API with dozen of
+abstraction and generics all over the place. This means that there are
+predefined kinds of character status (poison, slow, etc) along with kind of
+spells (earth, neutral).
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/docs/dev/error.md	Fri Nov 27 17:00:30 2020 +0100
@@ -0,0 +1,72 @@
+# Error handling
+
+How error handling is used within the API and the user code.
+
+## Synopsis
+
+Error handling is always a complicated task in the software development. In
+Molko's Adventure there is three kinds of errors:
+
+1. Programming error.
+2. Recoverable error at runtime.
+3. Unexpected error at runtime.
+
+## Kind of errors
+
+### Assertions
+
+One of the easiest errors to detect are about programming errors. In the
+Molko's Adventure API they are usually detected at runtime when you use a
+function with preconditions unmet. In that case standard C `assert` is used.
+
+For example, it happens when you:
+
+- Pass a NULL pointer where the function expects non-NULL,
+- Pass invalid arguments such as out of bounds indicies.
+
+Always read carefully preconditions that are annotated through the
+documentation.
+
+### Recoverable errors
+
+Next, come recoverable errors. Those arise when you may expect a failure from
+the API and can do something else.
+
+For example, it happens when you:
+
+- Open a font file that is invalid,
+- Open a music file that is no longer on the disk.
+
+In these situations, the API indicates usually by a return code that the
+function was unable to complete correctly (and you can use error to retrieve
+the specified error). In some case, you *MUST* not ignore the return value
+because if the function takes an input as argument it will be kept untouched.
+For example, the texture_new function may fail to create a texture and in that
+case it is left untouched.
+
+### Unexpected errors
+
+Finally, come what we call unexpected errors. Those happen while they are not
+supposed to.
+
+For example, it happens when there is a severe issue either in the kernel,
+graphics or any other library that aren't raised by the API itself.
+
+This includes (but not limited to):
+
+- A rendering error (caused by an internal issue).
+
+In these situations, the API calls the function panic which definitely calls
+the panic_handler. The default implementation prints an error and exit with a
+code of 1. User may pass a custom function but should quit the game because the
+API does not take care of deallocating data before calling panic.
+
+## Error handling in Molko's Adventure API
+
+The following table shows what is used and when.
+
+|         | `assert`           | Booleans            | panic                                     | Notes                             |
+|---------|--------------------|---------------------|-------------------------------------------|-----------------------------------|
+| libcore | Programming errors | As much as possible | Only in memory utilities from util.h      | Never called from libcore itself. |
+| libui   | Programming errors | When applicable     | Mostly in rendering errors                | None.                             |
+| librpg  | Programming errors | When applicable     | Mostly in rendering errors                | None.                             |
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/docs/dev/faq.md	Fri Nov 27 17:00:30 2020 +0100
@@ -0,0 +1,71 @@
+# FAQ
+
+Frequently asked questions about the development.
+
+## Why not creating a game engine?
+
+Game engines are usually too generic, too complex and do too much things. Lots
+of them also use scripting language which require another learning curve to be
+used.
+
+Molko's Adventure is a solo tactical 2D RPG and its core is especially designed
+for that gameplay. Thus the code stay simple to understand and to follow.
+Coupling a general purpose game engine with a game design is sometimes more
+complicated than writing small code.
+
+However, game engines are still interesting for people who already know how to
+use them and feel confident with them.
+
+## Why no prefix like "ma_" or "MA_"?
+
+See also question above.
+
+The purpose of Molko's Adventure is not to provide a drop-in reusable library
+to create RPG games. It is highly coupled with the gameplay of the original
+game. Thus we wanted to keep the codebase extremely simple and minimalist
+without adding bunch of generics.
+
+The core API isn't meant to be installed system wide (possible, but not
+recommended), instead users are encouraged to copy the core code and to adapt
+to their gameplay.
+
+A simple example: if someone wants to create a game and would like to allow
+only three playable entities at a time, it should simply edit appropriates
+structures and everything is adapted. Then, structures and array can stay
+static without dynamic allocations.
+
+Also, having a large amount of different data types, this would generate very
+large function and type names.
+
+## Why C instead of *FOO*?
+
+C is an awesome language. It still has its place in the industry especially in
+low-level, kernel and game design.
+
+Games are usually designed without OO in mind using simple procedural codes and
+lots of data. In C, writing code makes easier to understand what's happening
+under the hood without having to check if functions will generate dynamic
+allocations or not.
+
+However, we also love modernity and as such, C11 is the minimal requirement to
+build and run Molko's Adventure.
+
+## Can I make a MMORPG with that?
+
+Not easily.
+
+This core API is really tied to a unique solo RPG adventure and therefore it
+does not separate logic from rendering.
+
+Also, note that creating a server-client game is really different in terms of
+architecture than a local solo game. Most of the logic part is done server side
+and requires much more code to analyze to avoid cheats, lag, synchronisation and
+many other stuff than a local game does not require.
+
+There are no plans to create a network oriented core API anytime soon.
+
+## What are these stranges symbols `(+-*&?)` in member fields?
+
+It's a custom notation to indicate ownership and user access.
+
+See [ownership](ownership.md) file for more information.
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/docs/dev/howto/01-init.md	Fri Nov 27 17:00:30 2020 +0100
@@ -0,0 +1,37 @@
+# Howto: initialization
+
+Howto initialize the API before developing.
+
+## Synopsis
+
+Before using the core, you need to initialize the subsystems and internal
+backend API.
+
+!!! caution
+    Even non-rendering modules requires initialization and some of them even
+    require a window to be open.
+
+## Usage
+
+The following table summarize the functions to be used at the beginning and
+the end of your game.
+
+| System  | Init function    | Close function     | Remarks                |
+|---------|------------------|--------------------|------------------------|
+| General | sys_init         | sys_finish         | Required for most API  |
+| Window  | window_init      | window_finish      | Required by some parts |
+
+All init functions set an error code if any and you're encouraged to test the
+result and check the error if any.
+
+## Example
+
+Init the core and create a window of Full HD resolution. The function \ref
+panic will all the panic handler.
+
+```c
+if (!sys_init())
+	panic();
+if (!window_init("My Awesome Game", 1920, 1080))
+	panic();
+```
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/docs/dev/ownership.md	Fri Nov 27 17:00:30 2020 +0100
@@ -0,0 +1,127 @@
+# Howto: ownership and memory management
+
+How memory and ownership is used within Molko's Adventure API.
+
+## Synopsis
+
+In C, memory management can be a cumbersome issue and a major common complain
+when it comes to leak.
+
+As such, the API itself does not use dynamic allocations in most of the case.
+Instead it is kept to the user responsability to handle storage of data. In that
+manner the code stays simpler, stronger and more flexible. The API itself does
+not have to deal with memory management and deallocation, it only expect data
+from user and work with that.
+
+You can imagine a situation with a DVD player and some movies on DVDs. You have
+one DVD player where you put some DVDs inside but the DVD player never make its
+own copy, it simply reads your disc and you get it back afterwards.
+
+Following this philosophy, the Molko's Adventure API for this scenario would
+look like this:
+
+```c
+struct dvd_player player;
+struct dvd dvd;
+
+dvd_open(&dvd, "/dev/sr0");
+
+dvd_player_turn_on();
+dvd_player_insert(&player, &dvd);
+dvd_player_play(&player);
+dvd_player_turn_off();
+```
+
+## Memory handling
+
+### Arrays
+
+Some modules in the API may require an array. Depending on the situation they
+can be passed as parameter or are usually of a fixed reasonable size in
+structures.
+
+They are always annotated with a macro to let the user flexibility over it if
+necessary.
+
+Example, a player has a set of spells.
+
+```c
+#define PLAYER_SPELL_MAX (16)
+
+struct player {
+    struct spell *spells[PLAYER_SPELL_MAX];
+};
+```
+
+!!! note
+    You may think that we could use a pointer to pointer of spell to let user
+    pass a variable number of spells. That would help flexibility but makes user
+    code more complex and painful, instead the macro can be redefined at build
+    time.
+
+### Strings
+
+When dealing with strings, they are almost always referenced and not copied
+unless explicitly required. As such, no allocation/deallocation required either.
+
+```c
+struct player {
+    const char *name; // Not allocated, no deallocation
+```
+
+## Ownership
+
+Alongside the memory handling comes the ownership. Related to the DVD scenario
+explained above, not having to *own* a resource within a structure means no
+allocation/deallocation required.
+
+Also, since C does not have a scoped mechanism, all fields in structured are
+publicly available and to avoid allocating them on the heap they are always
+declared to the user even if they need internal data.
+
+As a documentation notice, fields are always annotated using (XYZ) prefix with
+some symbols to indicate whether user is allowed to touch or not.
+
+The letter *X* defines the following restriction
+
+`+`
+:   The property is readable/editable by the user,
+
+`-`
+:   The property is readable by the user,
+
+`*`
+:   The property is not meant to be used directly by the user.
+
+The letter *Y* can be set to `&` in that case means it is only referenced and is
+not an owned property (usually a non-owning pointer). Which means user is
+responsible for deallocation if required.
+
+The finall letter *Z* can be set to `?` which means it is optional (like a
+nullable pointer).
+
+Examples:
+
+```c
+struct foo {
+    int x;                /*!< (+) Position in x. */
+    int y;                /*!< (+) Position in y. */
+    struct theme *th;     /*!< (+&?) Theme to use. */
+    unsigned int elapsed; /*!< (-) Elapsed time since last frame. */
+    struct texture text;  /*!< (*) Texture used for rendering. */
+};
+```
+
+Within this structure, the fields `x` and `y` are completely accessible to the
+user for both reading/writing. The field `th` is an optional non-owning pointer
+to a theme which is also readable/writable. The field `elapsed` is readable but
+should not be modified. Finally, the field `text` is private and should not be
+touched by the user.
+
+## Memory handling in Molko's Adventure API
+
+|         | Dynamic allocation? | Notes                                                   |
+|---------|---------------------|---------------------------------------------------------|
+| libcore | None                | The util.h provides convenient allocators for the user. |
+| libui   | None                |                                                         |
+| librpg  | In map.h module     | Maps are big chunk of data.                             |
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/docs/index.md	Fri Nov 27 17:00:30 2020 +0100
@@ -0,0 +1,11 @@
+# Molko's Adventure documentation
+
+Welcome to the Molko's Adventure documentation.
+
+This documentation provides informations for both users of the game of the same
+name and creators that desire to create their own game.
+
+## Introduction
+
+The Molko project is a framework for developing 2D RPG games in C. It is
+designed in mind to be simple, fast, convenient, flexible and fun to use.
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/docs/install.md	Fri Nov 27 17:00:30 2020 +0100
@@ -0,0 +1,120 @@
+# Installation
+
+This page will explain how to build Molko's Adventure and libraries.
+
+## Requirements
+
+The following requirements are necessary to build the project.
+
+- C11 compiler: obviously,
+- [CMake][]: the build system,
+- [SDL2][]: the main game library,
+- [SDL2_image][]: to load images,
+- [SDL2_mixer][]: to play sounds and music,
+- [SDL2_ttf][]: to open fonts,
+- [Jansson][]: only for `mlk-tileset` and `mlk-map` tools.
+
+## Platforms supported
+
+The project has been tested on the following platforms.
+
+- Windows 10: only with [MSYS2][], Visual Studio **is not** supported yet.
+- macOS 11.0 (Big Sur): using Xcode 12 and libraries from [brew][],
+- Linux: on Alpine Linux (musl) and Arch Linux (glibc).
+
+## C and POSIX features
+
+Both of the API and the game are written using C99 and C11 but not all of the
+features from both C versions are required. Here's a list of functionalities
+that are required:
+
+### From C99
+
+Features:
+
+- [Compound literals][]
+- [inline] keyword
+
+Headers:
+
+- [stdbool.h][]
+
+Functions:
+
+- [snprintf][]
+- [vsnprintf][]
+
+### From C11
+
+- [stdnoreturn.h][]
+
+### From POSIX
+
+Expectations:
+
+- We use a few parts of [POSIX][] specification but try to keep its use limited
+  as not all platforms are POSIX compliant.
+- We assume that `fopen`, `malloc` and friends set errno in case of failures.
+
+Functions:
+
+- [dirname][]
+- [getopt][]
+
+Headers:
+
+- [libgen.h][]
+
+Macros:
+
+- `PATH_MAX`: in limits.h.
+
+!!! note
+    When a POSIX requirement isn't present it is replaced by a shim
+       specified for the platform.
+
+## Building with CMake
+
+Enter the source directory and type the following commands. In this example we
+will use the "Unix Makefiles".
+
+    mkdir build
+    cd build
+    cmake .. -DCMAKE_BUILD_TYPE=Debug
+    make
+
+!!! note
+    If you use a CMake generator that supports configuration types (e.g. Xcode,
+    Visual Studio) do not set `CMAKE_BUILD_TYPE`.
+
+### Available options
+
+The following CMake options are availble:
+
+`MOLKO_WITH_DOC`
+:   Enable documentation (default: On).
+
+`MOLKO_WITH_EXAMPLES`
+:   Build examples (default: On).
+
+`MOLKO_WITH_TESTS`
+:   Build tests (default: On).
+
+[CMake]: http://cmake.org
+[Compound literals]: https://en.cppreference.com/w/c/language/compound_literal
+[Jansson]: https://digip.org/jansson
+[MSYS2]: https://www.msys2.org
+[POSIX]: https://pubs.opengroup.org/onlinepubs/9699919799
+[SDL2]: http://libsdl.org
+[SDL2_image]: https://www.libsdl.org/projects/SDL_image
+[SDL2_mixer]: https://www.libsdl.org/projects/SDL_mixer
+[SDL2_ttf]: https://www.libsdl.org/projects/SDL_ttf
+[brew]: https://brew.sh
+[dirname]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/dirname.html
+[getopt]: https://pubs.opengroup.org/onlinepubs/9699919799/functions/getopt.html
+[inline]: https://en.cppreference.com/w/c/language/inline
+[libgen.h]: https://pubs.opengroup.org/onlinepubs/9699919799/basedefs/libgen.h.html
+[snprintf]: https://en.cppreference.com/w/c/io/fprintf
+[vsnprintf]: https://en.cppreference.com/w/c/io/fprintf
+[stdbool.h]: https://en.cppreference.com/w/c/language/arithmetic_types#Boolean_type
+[stdnoreturn.h]: https://en.cppreference.com/w/c/types
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/docs/specs/map.md	Fri Nov 27 17:00:30 2020 +0100
@@ -0,0 +1,107 @@
+# Spec: map
+
+Maps are probably the most important files within the game, it provides the map
+definition, structure, actions and player interactions.
+
+It consists of:
+
+- A tileset to use (only one),
+- A size in terms of number of rows and columns,
+- 3 layers (background, foreground and above),
+- 1 layer of actions.
+
+Just like [tileset](tileset.md), maps are defined in a custom map file format in
+plain text.
+
+Maps have an extension of ``.map``.
+
+## File format
+
+The file format is a simple plain text where each each line consist of a
+directive.
+
+!!! caution
+    Order is important. You must make sure that every directives are listed in
+    the same order.
+
+The file format must be defined as following where each ``<>`` must be replaced
+by the appropriate C type name.
+
+    title|<const char *>
+    columns|<unsigned int>
+    rows|<unsigned int>
+    tileset|<const char *>
+    origin|<int>|<int>
+    layer|background
+    <int>
+    <int>
+    ...
+    layer|foreground
+    <int>
+    <int>
+    ...
+    layer|above
+    <int>
+    <int> 
+    ...
+    layer|actions
+    <int>|<int>|<unsigned int>|<unsigned int>|<const char *>
+
+Description of directives:
+
+title
+:   Map title, must not exceed 64 bytes.
+
+columns
+:   Number of columns.
+
+rows
+:   Number of rows.
+
+tileset
+:   The tileset to use given as a string name. The path must be relative.
+
+origin
+:   (Optional) Position in where the player starts bt specifying ``x``, ``y``
+    respectively.
+
+layer
+:   (Optional) For layers of type ``background``, ``foreground`` and ``above``,
+    defines the tiles to use in order from top-left to bottom-right starting
+    from 1, a value of 0 means no tile to render. If a map has a dimensions of
+    4 columns and 6 the number of tiles must not exceed 24.
+
+    For the layer action, defines an object to be implemented in the API. The
+    first 4 integers define the ``x``, ``y``, ``width`` and ``height`` dimensions
+    of the action rectangle respectively. The final string is an argument to pass
+    to the action.
+
+## Examples
+
+The following file is a map with 4 columns and 2 rows (it is probably small for
+a real game but at least it is readable for this example). The player starts at
+10, 10, the background is using the same tile while the foreground is using
+different tiles.
+
+    title|Small map
+    columns|4
+    rows|2
+    origin|10|10
+    layer|background
+    1
+    1
+    1
+    1
+    1
+    1
+    1
+    1
+    layer|foreground
+    0
+    0
+    2
+    2
+    0
+    0
+    3
+    3
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/docs/specs/tileset.md	Fri Nov 27 17:00:30 2020 +0100
@@ -0,0 +1,92 @@
+# Spec: tileset
+
+Tilesets are files that are used to draw a map by copying individual cells from
+an image into the screen by repeating those. A unique tileset can be reused by
+several maps to avoid recreating every collision and animations each time a new
+map is created.
+
+They can be used directly as C code but can be written and read from files as
+well.
+
+Tilesets consists of:
+
+- An image to use as a sprite,
+- Dimensions of individual cells in that image,
+- Set of animations for specific tiles,
+- Set of collision masks for specific tiles.
+
+Tilesets have an extension of `.tileset`.
+
+## File format
+
+The file format is a simple plain text where each each line consist of a
+directive.
+
+!!! caution
+    Order is important. You must make sure that every directives are listed in
+    the same order.
+
+The file format must be defined as following where each ``<>`` must be replaced
+by the appropriate C type name.
+
+    tilewidth|<unsigned int>
+    tileheight|<unsigned int>
+    image|<const char *>
+    tiledefs
+    <unsigned short>|<int>|<int>|<unsigned int>|<unsigned int>
+    ...
+    animations
+    <unsigned short>|<const char *>|<unsigned int>
+
+Description of directives:
+
+tilewidth
+:   Cell width in the image.
+
+tileheight
+:   Cell height in the image.
+
+image
+:   Path to image to use (must be relative).
+
+tiledefs
+:   Start a list of tile definitions to describe a collision mask for a given
+    tile. Each line after this directive describe a unique rectangle for one
+    tile by specifying `tile id`, `x`, `y`, `width`, `height` in order.
+
+    This section is optional and can be omitted entirely.
+
+animations
+:   Start a list of tile animations that should be used instead of drawing from
+    the image sprite itself. Each line after this directive describe an animation
+    for a given tile by specifying ``tile id``, ``animation file``, ``delay`` in
+    order.
+
+## Examples
+
+The following file is a tileset using the image *world.png* that has 64x64
+dimensions for each cell.
+
+    tilewidth|64
+    tileheight|64
+    image|world.png
+
+The following file adds some collision rectangles on tiles *3* and *5*. The
+rectangle collision for the tile id *3* has dimensions of W=30, H=30, X=5, Y=5
+and the rectangle for the tile id *5* has dimensions of W=10, H=15, X=10, Y=10.
+
+    tilewidth|64
+    tileheight|64
+    image|world.png
+    tiledefs
+    3|30|30|5|5
+    5|10|15|10|10
+
+The following file adds an animation for the tile id *3* using the file
+*animation-water.png* with a delay of *500* ms per tile.
+
+    tilewidth|64
+    tileheight|64
+    image|world.png
+    animations
+    3|animation-water.png|500
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/docs/tools/bcc.md	Fri Nov 27 17:00:30 2020 +0100
@@ -0,0 +1,39 @@
+# Tool: mlk-bcc
+
+This utility generates C byte array from any input file. Its main purpose is to
+allow embedding data directly into the executable without having to load files
+from disk.
+
+It reads the given file and generate the output to the standard output.
+
+Synopsis:
+
+	mlk-bcc [-0csu] [-I num] [-i num] filename variable
+
+Options and arguments:
+
+-0
+:   Terminate the array with a NUL terminator.
+
+-c
+:   Generate a ``const`` C array.
+
+-s
+:   Generate a ``static`` C array.
+
+-u
+:   Use ``unsigned char`` instead of ``signed char`` when generating the byte
+    array.
+
+-I num
+:   Use ``num`` tabs to indent (defaults to 1).
+
+-i num
+:   Use ``num`` spaces to indent.
+
+filename
+:   Filename to read as input, a value of ``-`` will read the standard input.
+
+variable
+:   The C variable to generate, any character that is not valid in C will be
+    replaced by a ``_`` but the variable must still not start with a digit.
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/docs/tools/map.md	Fri Nov 27 17:00:30 2020 +0100
@@ -0,0 +1,11 @@
+# Tool: mlk-map
+
+Convert a map generated from [Tiled][tiled] into a Molko's Adventure compatible one.
+
+The utility will read standard input and write the converted map to the standard
+output.
+
+!!! caution
+    Only JSON files are supported.
+
+[Tiled]: http://mapeditor.org
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/docs/tools/tileset.md	Fri Nov 27 17:00:30 2020 +0100
@@ -0,0 +1,11 @@
+# Tool: mlk-tileset
+
+Convert a tileset generated from [Tiled] into a Molko's Adventure compatible one.
+
+The utility will read standard input and write the converted tileset to the
+standard output.
+
+!!! caution
+    Only JSON files are supported.
+
+[Tiled]: http://mapeditor.org
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/doxybook.json	Fri Nov 27 17:00:30 2020 +0100
@@ -0,0 +1,19 @@
+{
+  "baseUrl": "/",
+  "indexInFolders": true,
+  "linkSuffix": "/",
+  "indexClassesName": "index",
+  "indexFilesName": "index",
+  "indexGroupsName": "index",
+  "indexNamespacesName": "index",
+  "indexRelatedPagesName": "index",
+  "indexExamplesName": "index",
+  "mainPageInRoot": true,
+  "mainPageName": "index",
+  "folderClassesName": "classes",
+  "folderExamplesName": "examples",
+  "folderFilesName": "files",
+  "folderGroupsName": "modules",
+  "folderNamespacesName": "namespaces",
+  "folderRelatedPagesName": "pages"
+}
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/doxygen/groups.c	Fri Nov 27 17:00:30 2020 +0100
@@ -0,0 +1,47 @@
+/*
+ * groups.c -- describe "Modules" in Doxygen
+ *
+ * Copyright (c) 2020 David Demelier <markand@malikania.fr>
+ *
+ * Permission to use, copy, modify, and/or distribute this software for any
+ * purpose with or without fee is hereby granted, provided that the above
+ * copyright notice and this permission notice appear in all copies.
+ *
+ * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+ * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+ * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+ * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+ * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+ * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+ * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+ */
+
+/**
+ * \defgroup actions Actions
+ * \brief Predefined actions.
+ */
+
+/**
+ * \defgroup states States
+ * \brief Predefined states.
+ */
+
+/**
+ * \defgroup basics Basics
+ * \brief Basics utilities.
+ */
+
+/**
+ * \defgroup drawing Drawing
+ * \brief Modules for rendering on the screen.
+ */
+
+/**
+ * \defgroup input Input and events
+ * \brief Input and event handling.
+ */
+
+/**
+ * \defgroup ui UI
+ * \brief User interface elements.
+ */
--- a/doc/index.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,33 +0,0 @@
-===============================
-Molko's Adventure documentation
-===============================
-
-Welcome to the Molko's Adventure documentation.
-
-This documentation provides informations for both users of the game of the same
-name and creators that desire to create their own game.
-
-Introduction
-------------
-
-The Molko project is a framework for developing 2D RPG games in C. It is
-designed in mind to be simple, fast, convenient, flexible and fun to use.
-
-Contents
---------
-
-.. toctree::
-   :maxdepth: 1
-
-   about
-   build
-   specifications
-   tools
-   api
-
-Indices and tables
-==================
-
-* :ref:`genindex`
-* :ref:`modindex`
-* :ref:`search`
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/doc/mkdocs.yml	Fri Nov 27 17:00:30 2020 +0100
@@ -0,0 +1,45 @@
+#
+# mkdocs.yml.txt -- documentation for Molko's Adventure
+#
+# Copyright (c) 2020 David Demelier <markand@malikania.fr>
+#
+# Permission to use, copy, modify, and/or distribute this software for any
+# purpose with or without fee is hereby granted, provided that the above
+# copyright notice and this permission notice appear in all copies.
+#
+# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
+# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
+# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
+# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
+# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
+# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
+# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
+#
+
+site_name: Molko's Adventure
+theme: material
+markdown_extensions:
+  - admonition
+  - tables
+  - def_list
+nav:
+  - Home: index.md
+  - About: about.md
+  - Installation: install.md
+  - Specifications:
+    - map: specs/map.md
+    - tileset: specs/tileset.md
+  - Tools:
+    - mlk-bcc: tools/bcc.md
+    - mlk-map: tools/map.md
+    - mlk-tileset: tools/tileset.md
+  - Developer corner:
+    - Notes:
+      - Error handling: dev/error.md
+      - Ownership: dev/ownership.md
+      - FAQ: dev/faq.md
+    - Howto:
+      - dev/howto/01-init.md
+    - API Reference:
+      - Modules: modules/index.md
+      - Files: files/index.md
--- a/doc/spec-map.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,117 +0,0 @@
-.. toctree::
-.. _spec-map:
-
-=========
-Spec: map
-=========
-
-Maps are probably the most important files within the game, it provides the map
-definition, structure, actions and player interactions.
-
-It consists of:
-
-- A tileset to use (only one),
-- A size in terms of number of rows and columns,
-- 3 layers (background, foreground and above),
-- 1 layer of actions.
-
-Just like :ref:`spec-tileset`, maps are defined in a custom map file format in
-plain text.
-
-Maps have an extension of ``.map``.
-
-File format
------------
-
-The file format is a simple plain text where each each line consist of a
-directive.
-
-.. caution:: Order is important. You must make sure that every directives are
-   listed in the same order.
-
-The file format must be defined as following where each ``<>`` must be replaced
-by the appropriate C type name.
-
-.. code-block:: text
-
-  title|<const char *>
-  columns|<unsigned int>
-  rows|<unsigned int>
-  tileset|<const char *>
-  origin|<int>|<int>
-  layer|background
-  <int>
-  <int>
-  ...
-  layer|foreground
-  <int>
-  <int>
-  ...
-  layer|above
-  <int>
-  <int> 
-  ...
-  layer|actions
-  <int>|<int>|<unsigned int>|<unsigned int>|<const char *>
-
-Description of directives:
-
-``title``
-  Map title, must not exceed 64 bytes.
-
-``columns``
-  Number of columns.
-
-``rows``
-  Number of rows.
-
-``tileset``
-  The tileset to use given as a string name. The path must be relative.
-
-``origin``
-  (Optional) Position in where the player starts bt specifying ``x``, ``y``
-  respectively.
-
-``layer``
-  (Optional) For layers of type ``background``, ``foreground`` and ``above``,
-  defines the tiles to use in order from top-left to bottom-right starting from
-  1, a value of 0 means no tile to render. If a map has a dimensions of 4
-  columns and 6 the number of tiles must not exceed 24.
-
-  For the layer action, defines an object to be implemented in the API. The
-  first 4 integers define the ``x``, ``y``, ``width`` and ``height`` dimensions
-  of the action rectangle respectively. The final string is an argument to pass
-  to the action.
-
-Examples
---------
-
-The following file is a map with 4 columns and 2 rows (it is probably small for
-a real game but at least it is readable for this example). The player starts at
-10, 10, the background is using the same tile while the foreground is using
-different tiles.
-
-.. code-block:: text
-
-  title|Small map
-  columns|4
-  rows|2
-  origin|10|10
-  layer|background
-  1
-  1
-  1
-  1
-  1
-  1
-  1
-  1
-  layer|foreground
-  0
-  0
-  2
-  2
-  0
-  0
-  3
-  3
--- a/doc/spec-tileset.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,102 +0,0 @@
-.. toctree::
-.. _spec-tileset:
-
-=============
-Spec: tileset
-=============
-
-Tilesets are files that are used to draw a map by copying individual cells from
-an image into the screen by repeating those. A unique tileset can be reused by
-several maps to avoid recreating every collision and animations each time a new
-map is created.
-
-They can be used directly as C code but can be written and read from files as
-well.
-
-Tilesets consists of:
-
-- An image to use as a sprite,
-- Dimensions of individual cells in that image,
-- Set of animations for specific tiles,
-- Set of collision masks for specific tiles.
-
-Tilesets have an extension of ``.tileset``.
-
-File format
------------
-
-The file format is a simple plain text where each each line consist of a
-directive.
-
-.. caution:: Order is important. You must make sure that every directives are
-   listed in the same order.
-
-The file format must be defined as following where each ``<>`` must be replaced
-by the appropriate C type name.
-
-.. code-block:: text
-
-  tilewidth|<unsigned int>
-  tileheight|<unsigned int>
-  image|<const char *>
-  tiledefs
-  <unsigned short>|<int>|<int>|<unsigned int>|<unsigned int>
-  ...
-  animations
-  <unsigned short>|<const char *>|<unsigned int>
-
-Description of directives:
-
-``tilewidth``
-  Cell width in the image.
-``tileheight``
-  Cell height in the image.
-``image``
-  Path to image to use (must be relative).
-``tiledefs``
-  Start a list of tile definitions to describe a collision mask for a given
-  tile. Each line after this directive describe a unique rectangle for one tile
-  by specifying ``tile id``, ``x``, ``y``, ``width``, ``height`` in order.
-
-  This section is optional and can be omitted entirely.
-``animations``
-  Start a list of tile animations that should be used instead of drawing from
-  the image sprite itself. Each line after this directive describe an animation
-  for a given tile by specifying ``tile id``, ``animation file``, ``delay`` in
-  order.
-
-Examples
---------
-
-The following file is a tileset using the image *world.png* that has 64x64
-dimensions for each cell.
-
-.. code-block:: text
-
-  tilewidth|64
-  tileheight|64
-  image|world.png
-
-The following file adds some collision rectangles on tiles *3* and *5*. The
-rectangle collision for the tile id *3* has dimensions of W=30, H=30, X=5, Y=5
-and the rectangle for the tile id *5* has dimensions of W=10, H=15, X=10, Y=10.
-
-.. code-block:: text
-
-  tilewidth|64
-  tileheight|64
-  image|world.png
-  tiledefs
-  3|30|30|5|5
-  5|10|15|10|10
-
-The following file adds an animation for the tile id *3* using the file
-*animation-water.png* with a delay of *500* ms per tile.
-
-.. code-block:: text
-
-  tilewidth|64
-  tileheight|64
-  image|world.png
-  animations
-  3|animation-water.png|500
--- a/doc/specifications.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,23 +0,0 @@
-.. toctree::
-   :hidden:
-
-Specifications
-==============
-
-This page describe file data, conventions and project structure required to
-write a game using Molko's Adventure API. Most of the code relies on the
-`conventions over configuration`_ principle where the user data is required to
-be in a certain manner rather than allowing lots of parameters. In that way both
-of the API and the user code stay solid and simple.
-
-For example, the game expect sprites to be designed in such a way that the code
-can simply select a row/column depending on the orientation. See individual
-specifications for more details.
-
-.. toctree::
-   :maxdepth: 1
-
-   spec-tileset
-   spec-map
-
-.. _conventions over configuration: https://en.wikipedia.org/wiki/Convention_over_configuration
--- a/doc/tool-bcc.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,51 +0,0 @@
-=============
-Tool: mlk-bcc
-=============
-
-This utility generates C byte array from any input file. Its main purpose is to
-allow embedding data directly into the executable without having to load files
-from disk.
-
-It reads the given file and generate the output to the standard output.
-
-Synopsis::
-
-  mlk-bcc [-0csu] [-I num] [-i num] filename variable
-
-Options and arguments:
-
-.. program:: mlk-bcc
-
-.. option:: -0
-
-   Terminate the array with a NUL terminator.
-
-.. option:: -c
-
-   Generate a ``const`` C array.
-
-.. option:: -s
-
-   Generate a ``static`` C array.
-
-.. option:: -u
-
-   Use ``unsigned char`` instead of ``signed char`` when generating the byte
-   array.
-
-.. option:: -I num
-
-   Use ``num`` tabs to indent (defaults to 1).
-
-.. option:: -i num
-
-   Use ``num`` spaces to indent.
-
-.. option:: filename
-
-   Filename to read as input, a value of ``-`` will read the standard input.
-
-.. option:: variable
-
-   The C variable to generate, any character that is not valid in C will be
-   replaced by a ``_`` but the variable must still not start with a digit.
--- a/doc/tool-map.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,12 +0,0 @@
-=============
-Tool: mlk-map
-=============
-
-Convert a map generated from Tiled_ into a Molko's Adventure compatible one.
-
-The utility will read standard input and write the converted map to the standard
-output.
-
-.. caution:: Only JSON files are supported.
-
-.. _Tiled: http://mapeditor.org
--- a/doc/tool-tileset.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,12 +0,0 @@
-=================
-Tool: mlk-tileset
-=================
-
-Convert a tileset generated from Tiled_ into a Molko's Adventure compatible one.
-
-The utility will read standard input and write the converted tileset to the
-standard output.
-
-.. caution:: Only JSON files are supported.
-
-.. _Tiled: http://mapeditor.org
--- a/doc/tools.rst	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,13 +0,0 @@
-=====
-Tools
-=====
-
-The following tools are provided by the Molko's Adventure build and can be used
-for creators.
-
-.. toctree::
-   :maxdepth: 1
-
-   tool-bcc
-   tool-tileset
-   tool-map
--- a/doxygen/CMakeLists.txt	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,77 +0,0 @@
-#
-# CMakeLists.txt -- CMake build system for doxygen
-#
-# Copyright (c) 2020 David Demelier <markand@malikania.fr>
-#
-# Permission to use, copy, modify, and/or distribute this software for any
-# purpose with or without fee is hereby granted, provided that the above
-# copyright notice and this permission notice appear in all copies.
-#
-# THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
-# WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
-# MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
-# ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
-# WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
-# ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
-# OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
-#
-
-project(doxygen)
-
-find_package(Doxygen QUIET)
-
-if (DOXYGEN_FOUND)
-	set(
-		INPUT
-		doxygen/groups.c
-		doxygen/mainpage.c
-		doxygen/page-faq.c
-		doxygen/page-howto-error.c
-		doxygen/page-howto-initialization.c
-		doxygen/page-howto-ownership.c
-		doxygen/page-portability.c
-		libcore
-		libui
-		librpg
-	)
-
-	set(
-		DOXYGEN_STRIP_FROM_PATH
-		${CMAKE_SOURCE_DIR}/libcore
-		${CMAKE_SOURCE_DIR}/libui
-		${CMAKE_SOURCE_DIR}/librpg
-	)
-
-	set(DOXYGEN_SHOW_GROUPED_MEMB_INC NO)
-	set(DOXYGEN_SHOW_INCLUDE_FILES NO)
-	set(DOXYGEN_ALLOW_UNICODE_NAMES YES)
-	set(DOXYGEN_AUTOLINK_SUPPORT NO)
-	set(DOXYGEN_ENABLE_PREPROCESSING YES)
-	set(DOXYGEN_EXAMPLE_PATH examples)
-	set(DOXYGEN_EXCLUDE_PATTERNS *_p.h)
-	set(DOXYGEN_FILE_PATTERNS *.h)
-	set(DOXYGEN_GENERATE_LATEX NO)
-	set(DOXYGEN_GENERATE_MAN NO)
-	set(DOXYGEN_GENERATE_XML YES)
-	set(DOXYGEN_GENERATE_HTML NO)
-	set(DOXYGEN_INPUT_ENCODING UTF-8)
-	set(DOXYGEN_MAX_INITIALIZER_LINES 0)
-	set(DOXYGEN_OPTIMIZE_OUTPUT_FOR_C YES)
-	set(DOXYGEN_OUTPUT_DIRECTORY doxygen)
-	set(DOXYGEN_PREDEFINED DOXYGEN)
-	set(DOXYGEN_PROJECT_BRIEF "2D RPG game in C")
-	set(DOXYGEN_PROJECT_NAME "Molko's Adventure")
-	set(DOXYGEN_QUIET YES)
-	set(DOXYGEN_RECURSIVE YES)
-	set(DOXYGEN_TAB_SIZE 8)
-	set(DOXYGEN_WARNINGS YES)
-
-	doxygen_add_docs(
-		doxygen
-		${INPUT}
-		ALL
-		WORKING_DIRECTORY "${CMAKE_SOURCE_DIR}"
-	)
-
-	set_target_properties(doxygen PROPERTIES FOLDER misc)
-endif ()
--- a/doxygen/groups.c	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,47 +0,0 @@
-/*
- * groups.c -- describe "Modules" in Doxygen
- *
- * Copyright (c) 2020 David Demelier <markand@malikania.fr>
- *
- * Permission to use, copy, modify, and/or distribute this software for any
- * purpose with or without fee is hereby granted, provided that the above
- * copyright notice and this permission notice appear in all copies.
- *
- * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
- * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
- * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
- * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
- * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
- * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
- * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
- */
-
-/**
- * \defgroup actions Actions
- * \brief Predefined actions.
- */
-
-/**
- * \defgroup states States
- * \brief Predefined states.
- */
-
-/**
- * \defgroup basics Basics
- * \brief Basics utilities.
- */
-
-/**
- * \defgroup drawing Drawing
- * \brief Modules for rendering on the screen.
- */
-
-/**
- * \defgroup input Input and events
- * \brief Input and event handling.
- */
-
-/**
- * \defgroup ui UI
- * \brief User interface elements.
- */
--- a/doxygen/mainpage.c	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,71 +0,0 @@
-/*
- * mainpage.c -- describe "Main Page" in Doxygen
- *
- * Copyright (c) 2020 David Demelier <markand@malikania.fr>
- *
- * Permission to use, copy, modify, and/or distribute this software for any
- * purpose with or without fee is hereby granted, provided that the above
- * copyright notice and this permission notice appear in all copies.
- *
- * THE SOFTWARE IS PROVIDED "AS IS" AND THE AUTHOR DISCLAIMS ALL WARRANTIES
- * WITH REGARD TO THIS SOFTWARE INCLUDING ALL IMPLIED WARRANTIES OF
- * MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL THE AUTHOR BE LIABLE FOR
- * ANY SPECIAL, DIRECT, INDIRECT, OR CONSEQUENTIAL DAMAGES OR ANY DAMAGES
- * WHATSOEVER RESULTING FROM LOSS OF USE, DATA OR PROFITS, WHETHER IN AN
- * ACTION OF CONTRACT, NEGLIGENCE OR OTHER TORTIOUS ACTION, ARISING OUT OF
- * OR IN CONNECTION WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
- */
-
-/**
- * \mainpage
- *
- * Welcome to the Molko's reference API.
- *
- * # About
- *
- * Molko's Adventure is a 2D solo RPG written in pure C, using SDL2 and SDL2
- * addons.
- *
- * As its heart, the game is split into multiple parts, libraries, game data and
- * game code.
- *
- * - It is not a game engine! Many aspects in the core are still tightly coupled
- *   with the original game design. We wanted the core to be kept simple without
- *   thousands of dynamic allocations and genericity all over the place.
- * - It is not meant to be used as system library. Functions were kept simple
- *   and not prefixed by any "namespace"-like word. Instead, it is meant to be
- *   bundled with your game as boilerplate code with the possibility for you to
- *   change all internals if you want.
- *
- * # Usage
- *
- * If you plan to create your own game, simply copy the whole directory
- * directory to your project and select which libraries you need.
- *
- * \note If you find a bug regarding your platform, feel free to send bug
- *       reports and patches.
- *
- * Then, check this API or read .h files for documentation. The files ending
- * with _p.h are usually reserved for the implementation and should not be used
- * unless you know what you're doing.
- *
- * # Libraries
- *
- * The following libraries are available and built separately:
- *
- * | Library | Description                                  | Dependencies                           |
- * |---------|----------------------------------------------|----------------------------------------|
- * | libcore | Low level audio, video, windowing and input. | SDL2, SDL2_mixer, SDL2_ttf, SDL2_image |
- * | libui   | Minimalist UI routines to draw interfaces    | libcore                                |
- * | librpg  | Group of modules related to RPG games        | libcore, libui                         |
- *
- * ## Thread safety and reentrancy
- *
- * The core API is **not** thread-safe at all. Any module must always be used in
- * a single thread unless you really know what you're doing.
- *
- * Most of the API is reentrant though except the some modules which use global
- * objects.
- *
- * \note This may change in the future.
- */
--- a/doxygen/page-faq.c	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,67 +0,0 @@
-/**
- * \page faq FAQ
- * \tableofcontents
- *
- * # Why not creating a game engine?
- *
- * Game engines are usually too generic, too complex and do too much things.
- * Lots of them also use scripting language which require another learning curve
- * to be used.
- *
- * Molko's Adventure is a solo tactical 2D RPG and its core is especially
- * designed for that gameplay. Thus the code stay simple to understand and to
- * follow. Coupling a general purpose game engine with a game design is
- * sometimes more complicated than writing small code.
- *
- * However, game engines are still interesting for people who already know how
- * to use them and feel confident with them.
- *
- * # Why no prefix like "ma_" or "MA_"?
- *
- * See also question above.
- *
- * The purpose of Molko's Adventure is not to provide a drop-in reusable library
- * to create RPG games. It is highly coupled with the gameplay of the original
- * game. Thus we wanted to keep the codebase extremely simple and minimalist
- * without adding bunch of genericity.
- *
- * The core API isn't meant to be installed system wide (possible, but not
- * recommended), instead users are encouraged to copy the core code and to adapt
- * to their gameplay.
- *
- * A simple example: if someone wants to create a game and would like to allow
- * only three playable entities at a time, it should simply edit appropriates
- * structures and everything is adapted. Then, structures and array can stay
- * static without dynamic allocations.
- *
- * # Why C instead of <FOO>?
- *
- * C is an awesome language. It still has its place in the industry especially
- * in low-level, kernel and game design.
- *
- * Games are usually designed without OO in mind using simple procedural codes
- * and lots of data. In C, writing code makes easier to understand what's
- * happening under the hood without having to check if functions will generate
- * dynamic allocations or not.
- *
- * However, we also love modernity and as such, C11 is the minimal requirement
- * to build and run Molko's Adventure.
- *
- * \note The code does not make any assumption about the platform it runs, it
- *       expects to have a fully conformant C11 implementation. Microsoft MSVC
- *       is known to **not** support this C version.
- * 
- * # Can I make a MMORPG with that?
- *
- * Not easily.
- *
- * This core API is really tied to a unique solo RPG adventure and therefore it
- * does not separate logic from rendering.
- *
- * Also, note that creating a server-client game is really different in terms of
- * architecture than a local solo game. Most of the logic part is done server
- * side and requires much more code to analyze to avoid cheats, lag,
- * synchronisation and many other stuff than a local game does not require.
- *
- * There are no plans to create a network oriented core API anytime soon.
- */
--- a/doxygen/page-howto-error.c	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,76 +0,0 @@
-/**
- * \page howto-error Howto: error handling
- * \tableofcontents
- *
- * How error handling is used within the API and the user code.
- *
- * # Synopsis
- *
- * Error handling is always a complicated task in the software development. In
- * Molko's Adventure there is three kinds of errors:
- *
- * 1. Programming error.
- * 2. Recoverable error at runtime.
- * 3. Unexpected error at runtime.
- *
- * # Kind of errors
- *
- * ## Assertions
- *
- * One of the easiest errors to detect are about programming errors. In the
- * Molko's Adventure API they are usually detected at runtime when you use a
- * function with preconditions unmet. In that case standard C `assert` is used.
- *
- * For example, it happens when you:
- *
- * - Pass a NULL pointer where the function expects non-NULL,
- * - Pass invalid arguments such as out of bounds indicies.
- *
- * Always read carefully preconditions that are annotated through the
- * documentation.
- *
- * ## Recoverable errors
- *
- * Next, come recoverable errors. Those arise when you may expect a failure from
- * the API and can do something else.
- *
- * For example, it happens when you:
- *
- * - Open a font file that is invalid,
- * - Open a music file that is no longer on the disk.
- *
- * In these situations, the API indicates usually by a return code that the
- * function was unable to complete correctly (and you can use \ref error to
- * retrieve the specified error). In some case, you *MUST* not ignore the return
- * value because if the function takes an input as argument it will be kept
- * untouched. For example, the \ref texture_new function may fail to create a
- * texture and in that case it is left untouched.
- *
- * ## Unexpected errors
- *
- * Finally, come what we call unexpected errors. Those happen while they are not
- * supposed to.
- *
- * For example, it happens when there is a severe issue either in the kernel,
- * graphics or any other library that aren't raised by the API itself.
- *
- * This includes (but not limited to):
- *
- * - A rendering error (caused by an internal issue).
- *
- * In these situations, the API calls the function \ref panic which definitely
- * calls the \ref panic_handler. The default implementation prints an error and
- * exit with a code of 1. User may pass a custom function but should quit the
- * game because the API does not take care of deallocating data before calling
- * panic.
- *
- * # Error handling in Molko's Adventure API
- *
- * The following table shows what is used and when.
- *
- * |         | `assert`           | Booleans            | panic                                     | Notes                             |
- * |---------|--------------------|---------------------|-------------------------------------------|-----------------------------------|
- * | libcore | Programming errors | As much as possible | Only in memory utilities from util.h      | Never called from libcore itself. |
- * | libui   | Programming errors | When applicable     | Mostly in rendering errors                | None.                             |
- * | librpg  | Programming errors | When applicable     | Mostly in rendering errors                | None.                             |
- */
--- a/doxygen/page-howto-initialization.c	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,39 +0,0 @@
-/**
- * \page howto-init Howto: initialization
- * \tableofcontents
- *
- * Howto initialize the core.
- *
- * \section synopsis Synopsis
- *
- * Before using the core, you need to initialize the subsystems and internal
- * backend API.
- *
- * \warning Even non-rendering modules requires initialization and some of them
- *          even require a window to be open.
- *
- * \section usage Usage
- *
- * The following table summarize the functions to be used at the beginning and
- * the end of your game.
- *
- * | System  | Init function    | Close function     | Remarks                |
- * |---------|------------------|--------------------|------------------------|
- * | General | sys_init         | sys_finish         | Required for most API  |
- * | Window  | window_init      | window_finish      | Required by some parts |
- *
- * All init functions set an error code if any and you're encouraged to test the
- * result and check the error if any.
- *
- * \section example Example
- *
- * Init the core and create a window of Full HD resolution. The function \ref
- * panic will all the panic handler.
- *
- * \code
- * if (!sys_init())
- * 	panic();
- * if (!window_init("My Awesome Game", 1920, 1080))
- * 	panic();
- * \endcode
- */
--- a/doxygen/page-howto-ownership.c	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,120 +0,0 @@
-/**
- * \page howto-ownership Howto: ownership and memory management
- * \tableofcontents
- *
- * How memory and ownership is used within Molko's Adventure API.
- *
- * # Synopsis
- *
- * In C, memory management can be a cumbersome issue and a major common complain
- * when it comes to leak.
- *
- * As such, the API itself does not use dynamic allocations in most of the case.
- * Instead it is kept to the user responsability to handle storage of data. In
- * that manner the code stays simpler, stronger and more flexible. The API
- * itself does not have to deal with memory management and deallocation, it only
- * expect data from user and work with that.
- *
- * You can imagine a situation with a DVD player and some movies on DVDs. You
- * have one DVD player where you put some DVDs inside but the DVD player never
- * make its own copy, it simply reads your disc and you get it back afterwards.
- *
- * Following this philosophy, the Molko's Adventure API for this scenario would
- * look like this:
- *
- * ```c
- * struct dvd_player player;
- * struct dvd dvd;
- *
- * dvd_open(&dvd, "/dev/sr0");
- *
- * dvd_player_turn_on();
- * dvd_player_insert(&player, &dvd);
- * dvd_player_play(&player);
- * dvd_player_turn_off();
- * ```
- *
- * # Memory handling
- *
- * ## Arrays
- *
- * Some modules in the API may require an array. Depending on the situation they
- * can be passed as parameter or are usually of a fixed reasonable size in
- * structures.
- *
- * They are always annotated with a macro to let the user flexibility over it if
- * necessary.
- *
- * Example, a player has a set of spells.
- *
- * ```c
- * #define PLAYER_SPELL_MAX (16)
- *
- * struct player {
- *     struct spell *spells[PLAYER_SPELL_MAX];
- * };
- * ```
- *
- * ## Strings
- *
- * When dealing with strings, they are almost always referenced and not copied
- * unless explicitly required. As such, no allocation/deallocation required
- * either.
- *
- * ```c
- * struct player {
- *     const char *name; // Not allocated, no deallocation
- * ```
- *
- * # Ownership
- *
- * Alongside the memory handling comes the ownership. Related to the DVD
- * scenario explained above, not having to *own* a resource within a structure
- * means no allocation/deallocation required.
- *
- * Also, since C does not have a scoped mechanism, all fields in structured are
- * publicly available and to avoid allocating them on the heap they are always
- * declared to the user even if they need internal data.
- *
- * As a documentation notice, fields are always annotated using (XYZ) prefix 
- * with some symbols to indicate whether user is allowed to touch or not.
- *
- * The letter *X* defines the following restriction
- *
- * - `+`: The property is readable/editable by the user,
- * - `-`: The property is readable by the user,
- * - `*`: The property is not meant to be used directly by the user.
- *
- * The letter *Y* can be set to `&` in that case means it is only referenced
- * and is not an owned property (usually a non-owning pointer). Which means
- * user is responsible for deallocation if required.
- *
- * The finall letter *Z* can be set to `?` which means it is optional (like a
- * nullable pointer).
- *
- * Examples:
- *
- * ```c
- * struct foo {
- *     int x;                // (+) Position in x.
- *     int y;                // (+) Position in y.
- *     struct theme *th;     // (+&?) Theme to use.
- *     unsigned int elapsed; // (-) Elapsed time since last frame.
- *     struct texture text;  // (*) Texture used for rendering.
- * };
- * ```
- *
- * Within this structure, the fields `x` and `y` are completely accessible to
- * the user for both reading/writing. The field `th` is an optional non-owning
- * pointer to a theme which is also readable/writable. The field `elapsed` is
- * readable but should not be modified. Finally, the field `text` is private
- * and should not be touched by the user.
- *
- * # Memory handling in Molko's Adventure API
- *
- * |         | Dynamic allocation? | Notes                                                   |
- * |---------|---------------------|---------------------------------------------------------|
- * | libcore | None                | The util.h provides convenient allocators for the user. |
- * | libui   | None                |                                                         |
- * | librpg  | In map.h module     | Maps are big chunk of data.                             |
- */
--- a/doxygen/page-portability.c	Fri Nov 27 13:32:52 2020 +0100
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,34 +0,0 @@
-/**
- * \page portability Portability
- * \tableofcontents
- *
- * A note about portability in Molko's Adventure API.
- *
- * # C standard used
- *
- * The code is based mostly written in C99 with a subset of C11. The following
- * features from C11 are required:
- *
- * - `<stdnoreturn.h>` header.
- *
- * # POSIX
- *
- * A few routines from the POSIX specification are also used:
- *
- * - `<sys/stat.h>` header.
- * - `read(2)` function.
- * - `open(2)` function.
- * - `getopt(3)`,
- * - `fmemopen(3)`.
- *
- * Efforts are ongoing to provide fallback implementations for systems that lack
- * those functionalities.
- *
- * # System tested
- *
- * - macOS (10.15 and later),
- * - Linux (glibc and musl variants),
- * - FreeBSD, NetBSD and OpenBSD.
- *
- * Windows is currently not supported right now but will be in the future.
- */