Refactor Mongoose documentation

PUBLISHED_FROM=e9a4e5c7b4a1d03b93a2a79e29de19e60e919929

docs/overview/build-options/disabling-flags.md

@@ -0,0 +1,11 @@
+---
+title: Disabling flags
+---
+
+- `MG_DISABLE_HTTP_WEBSOCKET` disable HTTP + WebSocket protocol support
+- `MG_DISABLE_HTTP_DIGEST_AUTH` disable HTTP Digest (MD5) authorisation support
+- `MG_DISABLE_MQTT` disable MQTT support
+- `MG_DISABLE_SHA1` disable SHA1 support (used by WebSocket)
+- `MG_DISABLE_MD5` disable MD5 support (used by HTTP auth)
+- `MG_DISABLE_SOCKETPAIR` disable `mg_broadcast()` API
+- `MG_DISABLE_HTTP_KEEP_ALIVE` useful for embedded systems to save resources

docs/overview/build-options/enabling-flags.md

@@ -0,0 +1,11 @@
+---
+title: Enabling flags
+---
+
+- `MG_ENABLE_SSL` Enable OpenSSL support
+- `MG_ENABLE_IPV6` Enable IPV6 support
+- `MG_ENABLE_THREADS` enable `mg_start_thread()` API
+- `MG_ENABLE_MQTT_BROKER` enable MQTT broker
+- `MG_ENABLE_DNS_SERVER` enable DNS server
+- `MG_ENABLE_COAP` enable CoAP protocol
+- `MG_ENABLE_GETADDRINFO` enable `getaddrinfo()` in `mg_resolve2()`

docs/overview/build-options/intro.md

@@ -0,0 +1,22 @@
+---
+title: Build Options
+items:
+  - { type: file, name: enabling-flags.md }
+  - { type: file, name: disabling-flags.md }
+  - { type: file, name: platform-spec.md }
+  - { type: file, name: tunables.md }
+---
+
+Mongoose source code ships in a single .c file that contains functionality
+for all supported protocols (modules). Modules can be disabled at compile
+time which reduces the executable's size. That can be done by setting preprocessor
+flags. Also, some preprocessor flags can be used to tune internal Mongoose
+parameters.
+
+To set a preprocessor flag during compile time, use the `-D <PREPROCESSOR_FLAG>`
+compiler option. For example, to disable both MQTT and CoAP,
+compile the application `my_app.c` like this (assumed UNIX system):
+
+```
+  $ cc my_app.c mongoose.c -D MG_DISABLE_MQTT -D MG_DISABLE_COAP
+```

docs/overview/build-options/platform-spec.md

@@ -0,0 +1,10 @@
+---
+title: Platform specific
+---
+
+Mongoose tries to detect the target platform whenever possible, but in some cases you have
+to explicitly declare some peculiarities of your target, such as:
+
+- `MG_LWIP`: use LWIP networking stack
+- `MG_CC3200`: enable workarounds for the TI CC3200 target.
+- `MG_ESP8266`: enable workarounds for the ESP8266 target, add `RTOS_SDK` to specify the RTOS SDK flavour.

docs/overview/build-options/tunables.md

@@ -0,0 +1,11 @@
+---
+title: Tunables
+---
+
+- `MG_MALLOC`, `MG_CALLOC`, `MG_REALLOC`, `MG_FREE` allow you to a use custom
+  memory allocator, e.g. `-DMG_MALLOC=my_malloc`
+- `MG_USE_READ_WRITE` when set replaces calls to `recv` with `read` and `send` with `write`,
+  thus enabling to add any kind of file descriptor (files, serial devices) to an event manager.
+- `MG_SSL_CRYPTO_MODERN`, `MG_SSL_CRYPTO_OLD` - choose either "Modern" or "Old" ciphers
+  instead of the default "Intermediate" setting.
+  See [this article](https://wiki.mozilla.org/Security/Server_Side_TLS#Recommended_configurations) for details.