beginning litterate programming

README.org

@@ -1,7 +1,9 @@
 [[file:https://cdn.rawgit.com/syl20bnr/spacemacs/442d025779da2f62fc86c2082703697714db6514/assets/spacemacs-badge.svg]]
 
 #+TITLE: Conlanging layer
-#+author: Lucien “P’undrak” Cartier-Tilet
+#+AUTHOR: Lucien “P’undrak” Cartier-Tilet
+#+PROPERTY: header-args :noweb yes :exports code
+#+PROPERTY: header-args:dot :tangle no :exports code
 
 [[img/conlang_flag.png]]
 
@@ -10,7 +12,10 @@
   - [[#features][Features]]
   - [[#graphviz-trees][Graphviz trees]]
 - [[#install][Install]]
-- [[#key-bindings][Key bindings]]
+- [[#licence][Licence]]
+- [[#documentation][Documentation]]
+  - [[#functionalities][Functionalities]]
+    - [[#graphviz-trees-generation][Graphviz trees generation]]
 
 * Description
   This layer adds features for conlanging.
@@ -83,19 +88,84 @@
   You can then reload your configuration file with ~SPC f e R~, or restart Emacs
   with ~SPC q r~ or ~SPC q R~.
 
-* Key bindings
+* Licence
+  All the code included in this  repository is licensed under the GPLv3 license.
+  See [[file:LICENCE]].
 
-  | Key Binding   | Description                                                           |
+* Documentation
-  |---------------+-----------------------------------------------------------------------|
+  The following  is the  documentation of  the source  code of  the ~conlanging~
-  | ~SPC m l e l~ | (org-mode only) Translate Eittlandic transliteration into LaTeX runes |
+  layer. It is divided  in two main parts, describing the two  main files of the
-  | ~SPC m l e r~ | (org-mode only) Translate Eittlandic transliteration into runes       |
+  layer: ~funcs.el~  and ~keybindings.el~. First  of all, let’s  simply describe
-  | ~SPC m l m L~ | (org-mode only) Translate Mattér transliteration into LaTeX runes     |
+  the ~layer.el~ file.
-  | ~SPC m l m l~ | (org-mode only) Translate Mattér transliteration into native latin    |
+  #+BEGIN_SRC emacs-lisp :tangle layers.el
-  | ~SPC m l m r~ | (org-mode only) Translate Mattér transliteration into runes           |
+    (configuration-layer/declare-layer 'conlanging)
-  | ~SPC o l e o~ | Open Eittlandic file                                                  |
+  #+END_SRC
-  | ~SPC o l h o~ | Open Hjelp file                                                       |
+
-  | ~SPC o l m o~ | Open Mattér file                                                      |
+  And that’s enough for the ~layer.el~ file! Now, onto the ~funcs.el~ file.
-  | ~SPC o l n o~ | Open Proto-Ñyqy file                                                  |
+
-  | ~SPC o l o~   | Open the working conlanging directory                                 |
+** Functionalities
-  | ~SPC o l O~   | Open the root conlanging directory                                    |
+   :PROPERTIES:
-  | ~SPC o l t o~ | Open Proto-Tãso file                                                  |
+   :HEADER-ARGS: :tangle funcs.el
+   :END:
+   Here will be  detailed the functionalities of the ~conlanging~  layer. It can
+   be divided in several parts.
+
+*** Graphviz trees generation
+    As described above, it is possible to create graphviz trees from Elisp trees
+    made from  lists. This feature is  coded in two functions:  one that creates
+    the tree itself, and one that  generates nodes. The first one that generates
+    nodes is declared  as a private function (actually, it’s  just prefixed with
+ ~conlanging//~ following Spacemacs’ [[https://www.spacemacs.org/doc/CONVENTIONS.html#spacemacs-core-and-layer][naming convention]]).
+    #+BEGIN_SRC emacs-lisp
+      (defun conlanging//declare-node (t-node-text t-node-generation)
+        "Declares a node in the graphviz source code. The node’s identifier will be
+      `t-node-generation', and it will bear the label `t-node-text'."
+        (format "%d[label=\"%s\"];" t-node-generation
+                t-node-text))
+    #+END_SRC
+
+    This can result in a graphviz node declared like so:
+    #+BEGIN_SRC dot
+      231[label="This is a label"];
+    #+END_SRC
+
+    All nodes generated by the function have  a unique identifier in the form of
+    a number, and its content is only defined by its label. By default, the tree
+    created from  the graphviz  code gives a  tree from top  to bottom  with the
+    label not surrounded by anything. Let’s declare our whole function:
+    #+BEGIN_SRC emacs-lisp
+      (defun conlanging/tree-to-dot (t-tree &optional t-current-generation t-previous-generation)
+        "Translates an Elisp t-tree with any number of children per node
+      to a corresponding graphviz file that can be executed from dot.
+      Arguments:
+      - `t-tree': t-tree to convert
+      - `t-current-generation': generation number, incremented when
+        changing from a node to another node from the same generation,
+        multiplied by 10 when going from a node to one of its children.
+      - `t-previous-generation': generation number from previous named
+        node"
+        (cond
+         ((null t-previous-generation) ;; first call
+          (concat "graph{graph[dpi=300];node[shape=plaintext];graph[bgcolor=\"transparent\"];"
+                  (conlanging//declare-node (car t-tree) 0)
+                  (conlanging/tree-to-dot (cdr t-tree) 1 0)
+                  "}"))
+         ((null t-tree) "") ;; last call in this branch
+         ((atom (car t-tree)) ;; '("text" () () ()) manage the label
+          (concat (conlanging//declare-node (car t-tree)
+                                            t-current-generation)
+                  ;; make link
+                  (concat (number-to-string t-previous-generation) " -- "
+                          (number-to-string t-current-generation) ";")
+                  (conlanging/tree-to-dot (cdr t-tree)
+                                          (+ 1
+                                             (* 10 t-current-generation))
+                                          t-current-generation)))
+         ((listp (car t-tree)) ;; '(() () ()) manage the branches
+          (concat (conlanging/tree-to-dot (car t-tree) ;; child of current node
+                                          t-current-generation
+                                          t-previous-generation)
+                  (conlanging/tree-to-dot (cdr t-tree)
+                                          (+ 1 t-current-generation)
+                                          t-previous-generation)))))
+    #+END_SRC