From 9e1e22061ad347a97ae1b92603cb45663c97ddc9 Mon Sep 17 00:00:00 2001
From: Edoardo La Greca
Date: Mon, 5 May 2025 20:14:24 +0200
Subject: add documentation syntax

---
 doc/README | 51 ++++++++++++++++++++++++++++++++++++++++++++++++++-
 1 file changed, 50 insertions(+), 1 deletion(-)

diff --git a/doc/README b/doc/README
index 8b60404..3c73417 100644
--- a/doc/README
+++ b/doc/README
@@ -1,8 +1,57 @@
+=============
 Documentation
 =============
 
 In this directory you'll find pretty much all the documentation that needs to 
-be provided in addition to what the code and its comments tell already.
+be provided in addition to what the code and its comments can tell you already.
 
 If you have a question, head to FAQ.
 
+
+Rules while writing
+===================
+
+All documentation (i.e. all files in this directory, including this) must follow these rules:
+
+- All lines must fold to 80 characters and lines must break in a space character, not within words. A reasonable exception is made for URLs, which are kept whole.
+- For better clarity and consistency, documentation must use a common markup language. The markup language of choice is a subsect of the syntactic structures offered by `reStructuredText`_.
+
+The allowed subset of reStructuredText only consists of the following. Each of them must be used whenever it's possible and appropriate.
+
+- paragraphs
+- some inline markup:
+	- emphasis
+	- strong emphasis
+	- inline literals
+- section titles (up to 4 nested)
+- bullet, enumerated, and definition lists
+- literal blocks
+- block quotes
+- grid and simple tables
+- footnotes (and their inline references)
+- citations (and their inline references)
+- hyperlink targets (and their inline references) except for anonymous hyperlinks and indirect hyperlink references
+- standalone hyperlinks (only on their own line)
+
+Every syntactic structure which is only (or mainly) useful to the text when it's rendered or processed through a program has been stripped off. Elements which hurt readability when read as plain text have also been removed.
+
+As for section titles, it is strongly advised to use them with the following styles, in the following order::
+
+	=========
+	Section 1
+	=========
+	
+	Section 2
+	=========
+	
+	Section 3
+	---------
+	
+	Section 4
+	~~~~~~~~~
+
+and to keep two empty lines above each section title, with an exception for the first section title which should occur only once at the beginning of the document.
+
+
+.. _reStructuredText: https://docutils.sourceforge.io/rst.html
+
-- 
cgit v1.2.3