diff --git a/README.org b/README.org index 33c7e59..5a92be8 100644 --- a/README.org +++ b/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 | - |---------------+-----------------------------------------------------------------------| - | ~SPC m l e l~ | (org-mode only) Translate Eittlandic transliteration into LaTeX runes | - | ~SPC m l e r~ | (org-mode only) Translate Eittlandic transliteration into runes | - | ~SPC m l m L~ | (org-mode only) Translate Mattér transliteration into LaTeX runes | - | ~SPC m l m l~ | (org-mode only) Translate Mattér transliteration into native latin | - | ~SPC m l m r~ | (org-mode only) Translate Mattér transliteration into runes | - | ~SPC o l e o~ | Open Eittlandic file | - | ~SPC o l h o~ | Open Hjelp file | - | ~SPC o l m o~ | Open Mattér file | - | ~SPC o l n o~ | Open Proto-Ñyqy file | - | ~SPC o l o~ | Open the working conlanging directory | - | ~SPC o l O~ | Open the root conlanging directory | - | ~SPC o l t o~ | Open Proto-Tãso file | +* Documentation + The following is the documentation of the source code of the ~conlanging~ + layer. It is divided in two main parts, describing the two main files of the + layer: ~funcs.el~ and ~keybindings.el~. First of all, let’s simply describe + the ~layer.el~ file. + #+BEGIN_SRC emacs-lisp :tangle layers.el + (configuration-layer/declare-layer 'conlanging) + #+END_SRC + + And that’s enough for the ~layer.el~ file! Now, onto the ~funcs.el~ file. + +** Functionalities + :PROPERTIES: + :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