aboutsummaryrefslogtreecommitdiff
diff options
context:
space:
mode:
authorThomas "Cakeisalie5" Touhey <thomas@touhey.fr>2017-09-09 03:15:54 +0200
committerThomas "Cakeisalie5" Touhey <thomas@touhey.fr>2017-09-09 03:15:54 +0200
commit1e368f199f41bb68fd89667111253c2337ad1cce (patch)
treeb15b3b71f27196f9a48e9e2d75b582cbf440a297
parent6f97401007b2f5fd016d59caf53460be835a011b (diff)
Continued converting to documentation.
-rw-r--r--arch/all/compiler-gcc/bits/types/exact.h15
-rw-r--r--arch/all/compiler-gcc/bits/types/ptr.h4
-rw-r--r--arch/all/compiler-gcc/roles.yml2
l---------arch/all/core-sh/docs1
-rw-r--r--arch/all/core/BITS.md152
-rw-r--r--arch/all/core/README.md7
l---------arch/all/core/docs1
-rw-r--r--arch/casiowin/fxlib/README.md7
-rw-r--r--arch/casiowin/monochromelib/README.md10
-rw-r--r--copyright.yml1
-rw-r--r--docs/all/core-sh/bits.en.md (renamed from arch/all/core-sh/COMPILER.md)22
-rw-r--r--docs/all/core-sh/index.en.md (renamed from arch/all/core-sh/README.md)7
-rw-r--r--docs/all/core/bits.en.md158
-rw-r--r--docs/all/core/index.en.md11
-rw-r--r--docs/casiowin/monochromelib/index.en.md5
-rw-r--r--docs/contributing.en.md8
16 files changed, 206 insertions, 205 deletions
diff --git a/arch/all/compiler-gcc/bits/types/exact.h b/arch/all/compiler-gcc/bits/types/exact.h
index e60fd5e..78dd2fc 100644
--- a/arch/all/compiler-gcc/bits/types/exact.h
+++ b/arch/all/compiler-gcc/bits/types/exact.h
@@ -28,28 +28,25 @@
* The fact that you are presently reading this means you have had knowledge of
* the CeCILL-C license and that you accept its terms.
* ************************************************************************* */
-typedef __INT8_TYPE__ __int8_t;
-typedef __UINT8_TYPE__ __uint8_t;
-typedef __INT16_TYPE__ __int16_t;
-typedef __UINT16_TYPE__ __uint16_t;
-typedef __INT32_TYPE__ __int32_t;
-typedef __UINT32_TYPE__ __uint32_t;
+#define __int8_t __INT8_TYPE__
+#define __uint8_t __UINT8_TYPE__
+#define __int16_t __INT16_TYPE__
+#define __uint16_t __UINT16_TYPE__
+#define __int32_t __INT32_TYPE__
+#define __uint32_t __UINT32_TYPE__
-#define __INT8_WIDTH ( 8)
#define __INT8_MIN __INT8_C(-128)
#define __INT8_MAX __INT8_C(+127)
#define __UINT8_MIN __UINT8_C( 0)
#define __UINT8_MAX __UINT8_C( 255)
#define __PRI8 "hh"
-#define __INT16_WIDTH ( 16)
#define __INT16_MIN __INT16_C(-32768)
#define __INT16_MAX __INT16_C(+32767)
#define __UINT16_MIN __UINT16_C( 0)
#define __UINT16_MAX __UINT16_C( 65535)
#define __PRI16 "h"
-#define __INT32_WIDTH ( 32)
#define __INT32_MIN __INT32_C(-2147483648)
#define __INT32_MAX __INT32_C(+2147483647)
#define __UINT32_MIN __UINT32_C(0)
diff --git a/arch/all/compiler-gcc/bits/types/ptr.h b/arch/all/compiler-gcc/bits/types/ptr.h
index 00eade1..571015a 100644
--- a/arch/all/compiler-gcc/bits/types/ptr.h
+++ b/arch/all/compiler-gcc/bits/types/ptr.h
@@ -28,8 +28,8 @@
* The fact that you are presently reading this means you have had knowledge of
* the CeCILL-C license and that you accept its terms.
* ************************************************************************* */
-typedef __int32_t __intptr_t;
-typedef __uint32_t __uintptr_t;
+#define __intptr_t __int32_t
+#define __uintptr_t __uint32_t
#define __INTPTR_WIDTH __INT32_WIDTH
#define __INTPTR_MIN __INT32_MIN
diff --git a/arch/all/compiler-gcc/roles.yml b/arch/all/compiler-gcc/roles.yml
index 101b7c1..5e904b6 100644
--- a/arch/all/compiler-gcc/roles.yml
+++ b/arch/all/compiler-gcc/roles.yml
@@ -1,3 +1,5 @@
+%YAML 1.2
+---
bits:
types:
exact.h: Exact-width integer types for GCC.
diff --git a/arch/all/core-sh/docs b/arch/all/core-sh/docs
new file mode 120000
index 0000000..ff1b9c8
--- /dev/null
+++ b/arch/all/core-sh/docs
@@ -0,0 +1 @@
+../../../docs/all/core-sh \ No newline at end of file
diff --git a/arch/all/core/BITS.md b/arch/all/core/BITS.md
deleted file mode 100644
index b015cde..0000000
--- a/arch/all/core/BITS.md
+++ /dev/null
@@ -1,152 +0,0 @@
-# Extending libcarrot to another compiler/architecture/platform.
-This core module includes bits which define the compiler, architecture or
-platform specific macros and types, so the core can centralize all of the
-standard headers.
-
-This file is a description of all of these specific subheaders.
-
-Some higher-level modules (architecture and platform modules for compiler
-headers, platform modules for architecture headers) can set these headers and
-expect other headers instead.
-**Read the higher modules documentation before you implement these!**
-
-## Compiler-specific headers
-### `bits/compiler.h` -- check the compiler.
-This header checks if the compiler can be used with the other compiler-specific
-headers, and define the `__<COMPILER>_PREREQ(major, minor)` macro, which
-evaluates at compile-time, as 1 if we are indeed using this compiler and the
-current version is at least `major.minor`, or as 0 otherwise.
-
-It should also define the attributes, if an implementation of it exists with
-the compiler. Attributes are those things you append to your element's
-declaration and/or definition to produce more warnings, assumptions or other
-cool things. The name is inspired from GCC's implementation, in which the
-utility for this is called `__attribute__`. The attributes will be used like
-this for functions:
-
- extern __my_attr void bake_bread(int bread);
-
- __my_attr void bake_bread(int bread)
- {
- /* ... */
- }
-
-Here are the different attributes you can set:
-
-- `__inline`: force the inlining of a function;
-- `__pure`: produce a value out of others, with no side effect whatsoever;
-- `__wur`: warn if the result is unused (might have side effects);
-- `__malloc`: is a memory allocation function;
-- `__deprecated`: this function or element should not be used;
-- `__noreturn`: the function doesn't return (makes a long jump);
-- `__nothrow`: the function won't throw (C++ thingy);
-- `__unroll_loops`: should unroll the loops with constant number of passes
- if possible;
-- `__nonnull(index, name)`:
- an argument with name `name` and index `index` (starting from 1) should not
- have an invalid pointer value;
-- `__printf_format(format_index, args_index)`:
- the function is a printf-like function, where `format_index` is the index
- (starting from 1) of the format string, and `args_index` is the index
- (also starting from 1) of the `...`;
-
-You can also set some utilities among these:
-
-- `likely(expr)`, `unlikely(expr)`:
- optimize the branching structure for a likely or unlikely condition.
-
-### `bits/endian.h` -- endianness identification.
-This header defines the `__BYTE_ORDER` macro, which can expand to those values:
-
-- `__LITTLE_ENDIAN`: the architecture is little endian;
-- `__BIG_ENDIAN`: the architecture is big endian;
-- `__PDP_ENDIAN`: the architecture is PDP endian.
-
-### `bits/stdarg.h` -- ISO variable argument lists.
-This header defines the ISO C-like `stdarg.h` internal macros:
-
-- `__stdarg_va_start(ap, param)`;
-- `__stdarg_va_end(ap)`;
-- `__stdarg_va_arg(ap, arg_type)`;
-- `__stdarg_va_copy(dest, src)`.
-
-### `bits/types.h` -- architecture types.
-This subheader should define the following types (**N** represents 8, 16 or 32):
-
-- `__intN_t`, `__uintN_t`:
- signed and unsigned integer type with width `N`;
-- `__int_leastN_t`, `__uint_leastN_t`:
- signed and unsigned integer type with at least `N` as the width, such that
- no integer type with lesser size has at least the specified width;
-- `__int_fastN_t`, `__uint_fastN_t`:
- signed and unsigned fastest integer type with a width of at least `N`.
-- `__intptr_t`, `__uintptr_t`:
- signed and unsigned integer type which are exactly the same width as
- a pointer;
-- `__intmax_t`, `__uintmax_t`:
- signed and unsigned greatest-width integer type;
-
-For each of the **signed version of the types**, it should also define the
-following macros, leading to constant expressions (where `<type>` represents
-the all caps type without the `__` prefix and the `_t` suffix,
-e.g. `INT_FAST8` for `__int_fast8_t`, and `<suffix>` represents the type suffix,
-so what's after `__int_` and before the `_t` for the `__intN_t`,
-`__int_leastN_t` and `__int_fastN_t` types, `PTR` for `__intptr_t`, and
-`MAX` for `__intmax_t`):
-
-- `__<type>_WIDTH`: the number of bits of the type
- (e.g. `16` for a 16-bit type);
-- `__<type>_MIN`: the minimum of the signed version of the type;
-- `__<type>_MAX`: the maximum of the signed version of the type;
-- `__U<type>_MIN`: the minimum of the unsigned version of the type
- (usually 0 with a suffix);
-- `__U<type>_MAX`: the maximum of the unsigned version of the type;
-- `__PRI<suffix>`: the `printf`/`scanf` type prefix.
-
-The `__int_fastN_t`/`__uint_fastN_t` types should also have the
-`__INT<N>_C`/`__UINT<N>_C` macros defined, plus the `__INTMAX_C`/`__UINTMAX_C`
-macros, which should return the values with the eventual prefix/suffix.
-
-For example, for `__int_least32_t`:
-
- typedef char __int32_t;
- typedef unsigned char __uint32_t;
-
- #define __INT32_WIDTH ( 32)
- #define __INT32_MIN (-2147483647-1)
- #define __INT32_MAX (+2147483647)
- #define __UINT32_MAX ( 4294967295)
- #define __PRI32 "l"
-
- #define __INT32_C(_X) _X ## L
- #define __UINT32_C(_X) _X ## UL
-
-You should also define:
-
-- `__CHAR_BIT`: the char bit;
-- `__CHAR_IS_SIGNED`: 1 if the char bit is signed by default,
- 0 if it isn't;
-
-And the following constants for `char` (`CHAR`), `short` (`SHRT`),
-`int` (`INT`), `long` (`LONG`) and `long long` (`LLONG`):
-
-- `__<type>_WIDTH`: the number of bits of the type;
-- `__<type>_MIN`: the minimum value of the signed version of the type;
-- `__<type>_MAX`: the maximum value of the signed version of the type;
-- `__U<type>_MIN`: the minimum value of the unsigned version of the type;
-- `__U<type>_MAX`: the maximum value of the unsigned version of the type.
-
-## Architecture-specific headers
-### `bits/byteswap.h` -- byteswap utilities.
-This header can define the `__bswap_16` and `__bswap_32` macros, optimized
-for the platform. If the architecture also provides the `bswap_16` function,
-it should define the `__BYTESWAP_SUB16` macro, and if it provides the `bswap_32`
-function, it should define the `__BYTESWAP_SUB32` macro.
-
-### `bits/setjmp.h` -- long jumps.
-This header defines the `jmp_buf` type for `setjmp.h`.
-
-## Platform-specific headers
-### `bits/time.h` -- platform-specific time constants.
-This header must define the `CLOCKS_PER_SEC` constant, which corresponds
-to the number of ticks per second.
diff --git a/arch/all/core/README.md b/arch/all/core/README.md
deleted file mode 100644
index d7987ca..0000000
--- a/arch/all/core/README.md
+++ /dev/null
@@ -1,7 +0,0 @@
-# `all/core` -- The core libc.
-## Introduction
-This is the platform-independent libc core. It aims at being C89, C99 and C11
-compliant, using the standard C macros.
-
-The platform-specific macros and types are taken from the
-`cdefs/arch.h`/`cdefs/arch/*` headers, defined in the `core-<platform>` modules.
diff --git a/arch/all/core/docs b/arch/all/core/docs
new file mode 120000
index 0000000..3513ac8
--- /dev/null
+++ b/arch/all/core/docs
@@ -0,0 +1 @@
+../../../docs/all/core/ \ No newline at end of file
diff --git a/arch/casiowin/fxlib/README.md b/arch/casiowin/fxlib/README.md
deleted file mode 100644
index 7a5b8f0..0000000
--- a/arch/casiowin/fxlib/README.md
+++ /dev/null
@@ -1,7 +0,0 @@
-# `casiowin/fxlib` -- a compatibility layer for programs using CASIO's fxlib
-In the Software Development Kit (SDK) CASIO published in 2006 for the
-fx-9860G, there is a lib, called `fx9860_library.lib`. The main header
-of this library is `fxlib.h`, which gave its "public" name to the library.
-
-This module is basically the interactions with the CASIOWIN system (most are
-unsecure system calls, as the user applications are run in privileged mode).
diff --git a/arch/casiowin/monochromelib/README.md b/arch/casiowin/monochromelib/README.md
deleted file mode 100644
index e515116..0000000
--- a/arch/casiowin/monochromelib/README.md
+++ /dev/null
@@ -1,10 +0,0 @@
-# `casiowin/monochromelib` -- an adaptation of PierrotLL's MonochromeLib.
-In 2011, for [Gravity Duck][gduck], PierrotLL made a graphics library for the
-fx-9860G, that he then posted independently and called
-the [MonochromeLib][homepage].
-
-This module is a portage of what he did (also including the header from
-libmonochrome, the first portage on Linux of this library).
-
-[homepage]: http://www.planet-casio.com/Fr/logiciels/voir_un_logiciel_casio.php?showid=86
-[gduck]: http://www.planet-casio.com/Fr/programmes/programme1795-last-gravity-duck-pierrotll-a7.html
diff --git a/copyright.yml b/copyright.yml
index 41a03e6..03d31a4 100644
--- a/copyright.yml
+++ b/copyright.yml
@@ -10,6 +10,7 @@ files:
- 'tools/*.py'
- 'tools/**/*.py'
- 'tools/Internals/locales/*.yml'
+- 'docs'
copyright:
- [2017, Thomas "Cakeisalie5" Touhey, thomas@touhey.fr]
license: free
diff --git a/arch/all/core-sh/COMPILER.md b/docs/all/core-sh/bits.en.md
index 9da9b0e..3497eef 100644
--- a/arch/all/core-sh/COMPILER.md
+++ b/docs/all/core-sh/bits.en.md
@@ -1,21 +1,19 @@
-# Compiler support of the SuperH architecture
-## Introduction
-Your compiler supports the SuperH architecture? That's great, not every one
-does! Once you have done everything that's described in the `COMPILER.md`
-file of the `all/core` module, these are the few things you should define.
+---
+title:
+---
+Your C/C++ compiler supports the SuperH architecture? That's great, not
+every one does! Once you have fulfilled
+[the requirements for the core module][c], here is what you shall define in
+your compiler's specific headers.
-Our required macros are based on the ones the Renesas/Hitachi C/C++ Compiler
-uses, mainly because it's what people have been using the most for this
-architecture.
-
-## CPU type
+# CPU type
You shall define the `_SH` macro, and exactly one of these macros,
representing your platform:
_SH1, _SH2, _SH2A, _SH2E, _SH2AFPU, _SH3, _SH3DSP,
_SH4, _SH4A, _SHALDSP, _SH5
-## DSP-C interface
+# DSP-C interface
The DSP-C interface from the original Hitachi compiler is optional and has to
be enabled using an option, `-dspc`. If your compiler currently supports
fixed-point types, the `_DSPC` macro should be defined, otherwise, not.
@@ -28,3 +26,5 @@ Then, if they are not already defined, it should define the following macros:
- `__circ`: modulo adressing qualifier;
- `__X`: X memory data qualifier;
- `__Y`: Y memory data qualifier.
+
+[c]: [all/core]bits
diff --git a/arch/all/core-sh/README.md b/docs/all/core-sh/index.en.md
index 4095ec5..d8128c5 100644
--- a/arch/all/core-sh/README.md
+++ b/docs/all/core-sh/index.en.md
@@ -1,5 +1,8 @@
-# `all/core-sh` -- SuperH-specific parts of the core libc.
-## Introduction
+---
+title: SuperH-specific parts of the core libc.
+chapters:
+- bits
+---
SuperH (also named SH, or J-core) is a 32-bit RISC architecture developed
by Hitachi (later bought by Renesas) from the 90s. Among the users are
Sega (Sega Saturn, Sega 32X, Dreamcast) and CASIO (calculators such as the
diff --git a/docs/all/core/bits.en.md b/docs/all/core/bits.en.md
new file mode 100644
index 0000000..ddf893e
--- /dev/null
+++ b/docs/all/core/bits.en.md
@@ -0,0 +1,158 @@
+---
+title: Bits used by the core libc.
+---
+For compiler, architecture or platform specific content, this module includes
+a few header bits. Please define them in your compiler, architecture and
+platform default modules.
+
+# Compiler-specific headers
+## `compiler.h` — compiler identification and additional features.
+This header bit defines the compiler identification macro, usually
+`__<COMPILER>_PREREQ(major, minor)`, as 1 if we are indeed using a compiler
+that is compatible with this version of the compiler, or 0 if this version
+doesn't exist or the current compiler or version of the compiler
+aren't compatible.
+
+It also defines some non-standard attributes the headers can use to generate
+warnings or optimized code. The attributes are usually used this way:
+
+ extern __my_attr void bake_bread(int bread);
+
+ __my_attr void bake_bread(int bread)
+ {
+ /* ... */
+ }
+
+Here are the different attributes you can set:
+
+- `__inline`: force the inlining of a function;
+- `__pure`: produce a value out of others, with no side effect whatsoever;
+- `__wur`: warn if the result is unused (might have side effects);
+- `__malloc`: is a memory allocation function;
+- `__deprecated`: this function or element should not be used;
+- `__noreturn`: the function doesn't return (makes a long jump);
+- `__nothrow`: the function won't throw (C++ thingy);
+- `__unroll_loops`: should unroll the loops with constant number of passes
+ if possible;
+- `__nonnull(index, name)`:
+ an argument with name `name` and index `index` (starting from 1) should not
+ have an invalid pointer value;
+- `__printf_format(format_index, args_index)`:
+ the function is a printf-like function, where `format_index` is the index
+ (starting from 1) of the format string, and `args_index` is the index
+ (also starting from 1) of the `...`;
+
+The header bit can also define some utilities:
+
+- `likely(expr)`, `unlikely(expr)`:
+ optimize the branching structure for a likely or unlikely condition.
+
+Don't set the macros that your compiler won't support, they will be reset.
+
+## `endian.h` — endianness identification.
+This header bit defines the `__BYTE_ORDER` macro, which can expand to
+those values:
+
+- `__LITTLE_ENDIAN`: the architecture is little endian;
+- `__BIG_ENDIAN`: the architecture is big endian;
+- `__PDP_ENDIAN`: the architecture is PDP endian.
+
+## `stdarg.h` — ISO C variable argument lists.
+This header bit defines the ISO C type `__stdarg_va_list`, and the
+following macros:
+
+- `__stdarg_va_start(ap, param)`
+- `__stdarg_va_end(ap)`
+- `__stdarg_va_arg(ap, arg_type)`
+- `__stdarg_va_copy(dest, src)`
+
+## `alloca.h` — static memory allocation.
+This header bit, if provided, can define the `alloca(size)` macro.
+
+## `types/primitive.h` — details about primitive types.
+For each one of the `char` (`CHAR`), `short` (`SHRT`), `int` (`INT`),
+`long` (`LONG`) and `long long` (`LLONG`) types, the following macros
+should be provided in this header bit:
+
+- `__<TYPE>_WIDTH`: the bit width of the type;
+- `__<TYPE>_MIN`: the minimum value of the signed version of the type;
+- `__<TYPE>_MAX`: the maximum value of the signed version of the type;
+- `__U<TYPE>_MIN`: the minimum value of the unsigned version of the type;
+- `__U<TYPE>_MAX`: the maximum value of the unsigned version of the type.
+
+In addition, the following macros should be provided in this header bit:
+
+- `__CHAR_IS_SIGNED`: whether the `char` type is signed by default (1)
+ or not (0).
+
+## `types/exact.h` — exact-width integer types.
+This header bit provides the types and type details for the exactly 8-bit,
+16-bit and 32-bit integer types, using these macros:
+
+- `__int<N>_t`: signed version of the exactly N-bit integer type;
+- `__uint<N>_t`: unsigned version of the exactly N-bit integer type;
+- `__INT<N>_MIN`: the minimum value for the signed version of the type;
+- `__INT<N>_MAX`: the maximum value for the signed version of the type;
+- `__UINT<N>_MIN`: the minimum value for the unsigned version of the type;
+- `__UINT<N>_MAX`: the maximum value for the unsigned version of the type;
+- `__PRI<N>`: the string prefix for printf (e.g. `"hh"` for `char`).
+
+## `types/least.h` — least-width integer types.
+This header bit provides the types and type details for the least 8-bit,
+16-bit and 32-bit integer types, using these macros:
+
+- `__int_least<N>_t`: signed version of the least N-bit integer type;
+- `__uint_least<N>_t`: unsigned version of the least N-bit integer type;
+- `__INT_LEAST<N>_WIDTH`: the bit width of the type (e.g. 32);
+- `__INT_LEAST<N>_MIN`: the minimum value for the signed version of the type;
+- `__INT_LEAST<N>_MAX`: the maximum value for the signed version of the type;
+- `__INT<N>_C(num)`: cast a number to the signed version of the type;
+- `__UINT_LEAST<N>_MIN`: the minimum value for the unsigned version
+ of the type;
+- `__UINT_LEAST<N>_MAX`: the maximum value for the unsigned version
+ of the type;
+- `__UINT<N>_C(num)`: cast a number to the unsigned version of the type;
+- `__PRILEAST<N>`: the string prefix for printf.
+
+## `types/fast.h` — fast least-width integer types.
+This header bit provides the types and type details for the fast 8-bit,
+16-bit and 32-bit integer types, using these macros:
+
+- `__int_fast<N>_t`: signed version of the least N-bit integer type;
+- `__uint_fast<N>_t`: unsigned version of the least N-bit integer type;
+- `__INT_FAST<N>_WIDTH`: the bit width of the type (e.g. 32);
+- `__INT_FAST<N>_MIN`: the minimum value for the signed version of the type;
+- `__INT_FAST<N>_MAX`: the maximum value for the signed version of the type;
+- `__UINT_FAST<N>_MIN`: the minimum value for the unsigned version
+ of the type;
+- `__UINT_FAST<N>_MAX`: the maximum value for the unsigned version
+ of the type;
+- `__PRIFAST<N>`: the string prefix for printf.
+
+## `types/max.h` — maximum-width integer types.
+This header bit provides the types and type details for the maximum-width
+integer types, using these macros:
+
+- `__intmax_t`: signed version of the maximum integer type;
+- `__uintmax_t`: unsigned version of the maximum integer type;
+- `__INTMAX_WIDTH`: the bit width of the type;
+- `__INTMAX_MIN`: the minimum value of the signed version of the type;
+- `__INTMAX_MAX`: the maximum value of the signed version of the type;
+- `__INTMAX_C(num)`: cast a number to the signed version of the type;
+- `__UINTMAX_MIN`: the minimum value of the unsigned version of the type;
+- `__UINTMAX_MAX`: the maximum value of the unsigned version of the type;
+- `__UINTMAX_C(num)`: cast a number to the unsigned version of the type;
+- `__PRIMAX`: the string prefix for printf.
+
+# Architecture-specific headers
+## `byteswap.h` — byteswap utilities.
+This header bit can define the `__bswap_16` and `__bswap_32` macros, optimized
+for the platform.
+
+## `setjmp.h` — long jumps.
+This header bit defines the `jmp_buf` type for `setjmp.h`.
+
+# Platform-specific headers.
+## `time.h` — time constants.
+This header bit defines the `CLOCKS_PER_SEC` constant, which corresponds to
+the number of ticks per second.
diff --git a/docs/all/core/index.en.md b/docs/all/core/index.en.md
new file mode 100644
index 0000000..a53dfee
--- /dev/null
+++ b/docs/all/core/index.en.md
@@ -0,0 +1,11 @@
+---
+title: The core libc module.
+chapters:
+- bits
+---
+This is the platform-independant libc core. It aims at being C89, C99 and C11
+compliant, using the standard C macros.
+
+The platform-specific macros and types are taken from the header bits,
+which are usually defined by `core-<arch>`, `compiler-<comp>` and
+the platform default modules.
diff --git a/docs/casiowin/monochromelib/index.en.md b/docs/casiowin/monochromelib/index.en.md
index 114d480..23086a9 100644
--- a/docs/casiowin/monochromelib/index.en.md
+++ b/docs/casiowin/monochromelib/index.en.md
@@ -7,7 +7,8 @@ chapters:
- bmp
---
MonochromeLib is a graphics library for the CASIO fx-9860G made by PierrotLL
-in 2011. It replaced the graphics part of CASIO's fxlib, published in 2006
+in 2011 for the game [Gravity Duck][gduck].
+It replaced the graphics part of CASIO's fxlib, published in 2006
along with the CASIO fx-9860G SDK, which the community found to be inefficient.
It was originally published as a simple source and header file to include in
@@ -18,3 +19,5 @@ use of the double buffering technique mandatory. This technique consists of
making all drawing operations in some video memory (VRAM) before copying it
on the real screen. This prevents screen flickering, and any under
construction image to be displayed.
+
+[gduck]: http://www.planet-casio.com/Fr/programmes/programme1795-last-gravity-duck-pierrotll-a7.html
diff --git a/docs/contributing.en.md b/docs/contributing.en.md
index 23b4006..406f1d5 100644
--- a/docs/contributing.en.md
+++ b/docs/contributing.en.md
@@ -45,11 +45,11 @@ should follow the project's coding style; see [Coding style](coding).
# Roles file (top comments)
**The top comment of each source/include file is NOT hand-written**,
it is generated by a script, `tools/updatesource.py`, which reads the
-copyright lines and the licences from the machine-readable copyright
-information files `copyright.yml`, and the short description of each file
-from the roles files `roles.yml` present in each module root.
+copyright and licences from the machine-readable copyright information files
+(see [Licensing](licensing)), and the short description of each file
+from the roles files `roles.yml` present in every module root.
-See the section about roles files in `FORMATS.md`.
+TODO: detail the role files here?
# C/C++ headers and header bits
libcarrot uses a C superpreprocessor, which role is to: