src/fsm/log/* three files created in this dir: manager.c, oper.c and appendix.c

These three files contain all the functions needed for the log to be init, build and published. The most important function is in the 'manager' file: fsm_add_log (int severity, int source, const char *file_source, const char *function_source, const char *string_value) Any event to be reported must call this function.
include/fsm.h: prepares the building of a log and create src/readme.doc
2024-11-08 13:18:31 +01:00 · 2024-11-08 12:27:38 +01:00
6 changed files with 752 additions and 2 deletions
--- a/include/fsm.h
+++ b/include/fsm.h
@ -0,0 +1,299 @@
+/**
+ * @file
+ * FSM (Finite State Machine) header
+ *
+ * This file is part of Gem-graph.
+ *
+ * @cond LICENSE
+ * Copyright © 2021 Libre en Communs <contact@a-lec.org>
+ * Copyright © 2021-2024 Adrien Bourmault <neox@a-lec.org>
+ * Copyright © 2021-2024 Jean Sirmai <jean@a-lec.org>
+ *
+ * This program is free software: you can redistribute it and/or modify it under
+ * the terms of the GNU Affero General Public License as published by the Free
+ * Software Foundation, either version 3 of the License, or (at your option) any
+ * later version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ * @endcond
+ *
+ *
+ * In this commit, the FSM (Finite State Machine) header only lists all the
+ * structures that the log needs. Other fsm functions will be introduced in
+ * subsequent commits. @see readme.docs and this text below.
+ *
+ * ---
+ *
+ * The two structures and the two enums listed below will stay in the fsm header.
+ *
+ * All functions but the last one are now in dedicated files.
+ *
+ * The most important function: fsm_add_log() is in the file:
+ * /src/fsm/log/manager.c
+ *
+ * This file contains the declaration of the log with the static attribute,
+ * which forces all the functions that read or write it to be in it.
+ * Forcing all functions that read or write to the log to be grouped together
+ * help to prevent uncontrolled operations.
+ *
+ * All events sent to the log must pass through this function, which allows them
+ * to be filtered before being published in the log.
+ *
+ * ---
+ *
+ * Here's how the procedure works.
+ * A message is send to the fsm_add_log() function for each documented event.
+ * If there are too many events, this is the only function that allows you to
+ * apply one or more filters before publication. This allows you to select the
+ * events of interest, which can vary depending on the type of session.
+ * These filters can operate on any the following five parameters:
+ * severity, source, file_source, function_source, string_value.
+ * They can be combined using any logical operators and parentheses.
+ *
+ * 'severity' is one of the following pre-defined values:
+ * FATAL  -  ERROR  -  WARN  -  INFO  -  DEBUG  -  TRACE
+ *
+ * 'source' is a pre-defined value (typically a name of a structure) that can be
+ * associated to each event. It can be set to 'NULL'.
+ *
+ * file_source, function_source and string_value are three strings.
+ *
+ * ---
+ *
+ * The four most important executive functions needed by the log are in the
+ * dedicated file: /src/fsm/log/oper.c:
+ *
+ * NB: fsm_clear_log() is designed to close what was initiated by fsm_init_log().
+ * As, in this commit, fsm_publish_log() is the last instruction and no memory
+ * leaks are detected, the use of fsm_clear_log() is not required.
+ *
+ * - fsm_init_log()
+ * - fsm_publish_log()
+ * - fsm_clear_log()
+ * - fsm_add_log_event()
+ * .
+ *
+ * A typical list would also feature the following three functions
+ * but in the case of a log, their usefulness remains to be demonstrated.
+ * These functions are therefore apart in the file /src/fsm/log/appendix.c
+ *
+ * - fsm_get_log_length()
+ * - fsm_seek_log()
+ * - fsm_remove_log()
+ * .
+ *
+ */
+
+
+#pragma once
+
+/******************************************************************************/
+/*                         L O G   /   J O U R N A L                          */
+/******************************************************************************/
+
+/**
+ * The 'severity' enum conforms to canonical log levels:
+ * FATAL, ERROR, WARN, INFO, DEBUG, TRACE
+ *
+ * https://betterstack.com/community/guides/logging/logging-best-practices/
+ * https://en.wikipedia.org/wiki/Syslog
+ *
+ * All logs must contain at least one item from this enum and only one.
+ * This item can not be set to NULL.
+ *
+ * @see fsm_add_log()
+ */
+enum fsm_enum_log_severity {
+    FATAL,  /**< (or CRITICAL) an unrecoverable failure that prevents the whole
+                 application from doing any further useful work */
+    ERROR,  /**< an irremediable situation that hinders the execution of a
+                 specific operation within the application */
+    WARN,   /**< something unexpected has occurred, but the application can
+                 continue to function normally for the time being */
+    INFO,   /**< (or MESSAGE) a significant event occurs while the system is
+                 operating normally */
+    DEBUG,  /**< a description of system states in sufficient detail to give
+                 developers clues as to the cause of an error */
+    TRACE   /**< provides a systematic overview of code execution but comes at
+                 a cost in terms of performance */
+};
+
+/**
+ * A list of structures or states that may be involved in program events.
+ *
+ * All logs must contain at least one item from this list or the value NULL.
+ *
+ * Only some main items of this list are commented on today. Further comments
+ * will depend on its usage and structure which are just beginning to evolve.
+ *
+ * NB  about PAGE:  user_tree and selected_rule are two vertical panes which it
+ * is a good idea to place next to each other on the rules page so that you can
+ * switch between them more easily or have a parallel view of the two.
+ *
+ * @see fsm_add_log()
+ */
+enum fsm_enum_log_source {
+    AUTO_NOTIFICATION, /**< (not a source) */
+    DESTINATION, /**< SOURCE, TARGET */ SOURCE, TARGET,
+    FSM_CONTENT, /**< LOG, FSM, PREFER */ LOG, FSM, PREFER,
+    SRC_CONTENT, /**< MAIN, APP, WIDGETS, SIGNAL */ MAIN, APP, WIDGETS, SIGNAL,
+    WINDOW, /**< MAIN, DIALOG, MODAL, TEXT */
+        MAIN_WINDOW, DIALOG_WINDOW, MODAL_WINDOW, TEXT_WINDOW,
+    TOPBAR, /**< LEFT, CENTER, RIGHT */ TOPBAR_LEFT, TOPBAR_CENTER, TOPBAR_RIGHT,
+    PAGE, /**< SYNTH, STATE, RULES, [USER TREE], [SELECTED_RULE], MEASURES, RESULTS */
+        SYNTH_PAGE, STATE_PAGE, RULES_PAGE, MEASURES_PAGE, RESULTS_PAGE,
+    SYNTHESIS, /**< GLAREA, CAMERA, CONTROLS, RESULTS (duplicates from other pages) */
+        SYNTH_GLAREA, SYNTH_CAMERA, SYNTH_CONTROLS, SYNTH_RESULTS,
+    SYNTH_DATA, /**< SYNTH_TIME_DEP_RESULTS, SYNTH_TIME_INDEP_RESULTS */
+        SYNTH_TIME_DEP_RESULTS, SYNTH_TIME_INDEP_RESULTS,
+    STATE_VIEW, /**< TOP, BOTTOM, GLAREA, CAMERA */
+        STATE_TOP, STATE_BOTTOM, STATE_GLAREA, STATE_CAMERA,
+    SINGLE_RULE, /**< RULE_GEOMETRY, RULE_ALGEBRA */
+    RULE_GEOMETRY, /**< VIEW_BEFORE, VIEW_AFTER, RULE_GLAREA, RULE_CAMERA */
+        VIEW_BEFORE, VIEW_AFTER, RULE_GLAREA, RULE_CAMERA,
+    RULE_ALGEBRA, /**< LIST_CONDITIONS, LIST_ASSIGNMENTS, IDENTITY */
+        RULE_LIST_CONDITION, RULE_LIST_ASSIGNMENTS, RULE_IDENTITY,
+    TREE_RULES, /**< TREE, COMPARE, USE */
+        RULES_TREE, RULES_COMPARE, RULES_USE,
+    MEASURES, /**< TOOLS, ACTIVITY, DISPLAY */
+        MEASURES_TOOLS, MEASURES_ACTIVITY, MEASURES_DISPLAY,
+    RESULTS, /**< TIME_DEPPENDENT, TIME_INDEPENDENT */
+        TIME_DEP_RESULTS, TIME_INDEP_RESULTS,
+    GTK_WIDGETS, /**< LABEL, BUTTON, SCROLL, GLAREA, SLIDER, EXPANDER,...
+        * (non limitative) */
+        WIDGET, BUTTON, SCROLL, GLAREA, TEXT, LABEL, TREE, SLIDER, EXPANDER,
+        ENTRY, SLIDER_X, SLIDER_Y, SLIDER_Z, SLIDER_A, SLIDER_B, SLIDER_C,
+    OTHERS, /**< fsm possible states:  [EXEC / EDIT], [STATE / RULES / DATA],
+        * (non limitative) */
+        ON_SWITCH_EXEC_EDIT, ON_SWITCH_STATE_RULES_DATA,
+};
+
+//-----------------------------------------------------------------------------
+
+/**
+ * Structure of a log unit.
+ *
+ * @callergraph
+ * @see fsm_log_struct
+ */
+typedef struct  fsm_log_struct_unit
+                {
+                    long yy_dd_mm; /**< * date of the event reported in the log */
+                    long usec;     /**< * with microseconds precision */
+                    const char *file_source;     /**< * emitter file */
+                    const char *function_source; /**< * emitter function */
+                    const char *string_value;    /**< * any event descriptors */
+                    struct fsm_log_struct_unit *prev; /**< * chained list */
+                    struct fsm_log_struct_unit *next; /**< * chained list */
+                }
+                fsm_log_struct_unit;
+
+
+/**
+ * Two links towards the previous and the next unit are required to initialize
+ * and manage a double-chained list.
+ *
+ * @callgraph
+ * @see fsm_log_struct_unit
+ *
+ * @callergraph
+ * @see fsm_init_log()
+ * @see fsm_publish_log()
+ * @see fsm_clear_log()
+ * @see fsm_add_log_event()
+ * @see fsm_get_log_length()
+ * @see fsm_seek_log()
+ * @see fsm_remove_log()
+ */
+typedef struct {
+                    fsm_log_struct_unit *first; /**< * required */
+                    fsm_log_struct_unit *last;  /**< * required */
+               }
+               fsm_log_struct;
+
+//-----------------------------------------------------------------------------
+
+void fsm_init_log      (fsm_log_struct *jj);
+void fsm_publish_log   (fsm_log_struct jj);
+void fsm_clear_log     (fsm_log_struct *jj);
+
+void fsm_add_log_event (fsm_log_struct *jj,
+                        const char *file_source,
+                        const char *function_source,
+                        const char *string_value);
+
+int  fsm_get_log_length(fsm_log_struct jj);
+void fsm_seek_log      (fsm_log_struct jj,
+                        long usec,
+                        const char *file_source,
+                        const char *function_source,
+                        const char *string_value);
+long fsm_remove_log    (fsm_log_struct *jj,
+                        const char *file_source,
+                        const char *function_source,
+                        const char *string_value);
+
+
+/**
+ * @brief (1) This comment is not a duplicate: it will be displaced in the file:
+ * src/log/manager.c in next commits.
+ *
+ * It will be mandatory for any event to call the function fsm_add_log()
+ * to be published in the journal and it is here and only here that filters will
+ * be found.
+ *
+ * --
+ *
+ * @details The fsm_struct_journal (gg_logs) will be a static instance in a
+ * dedicated file: src/log/manager.c
+ * Therefore, all the functions that read or write it will be in this file.
+ * This is to avoid uncontrolled operations on it.
+ *
+ * While the program is running, messages will be sent to the fsm_add_log()
+ * function for each documented event.
+ * If there are too many events, this is the only function that allows you to
+ * apply one or more filters before publication. This allows you to select the
+ * events of interest, which can vary depending on the type of session.
+ *
+ * These filters can operate on any of the following five parameters:
+ * severity, source, file_source, function_source, string_value .
+ * They can be combined using any logical operators and parentheses.
+ *
+ * --
+ *
+ * @since 2024-08
+  *
+ * @callgraph
+ * @see fsm_add_log_event() insertion into the log list
+ *
+ * @callergraph @see Almost all functions will have to report events and will
+ *              therefore call fsm_add_log().
+ * @see main()  will send the first and last messages.
+ *
+ *
+ * @param severity:  one of the following pre-defined values
+ *
+ *        FATAL  -  ERROR  -  WARN  -  INFO  -  DEBUG  -  TRACE
+ *
+ * @param source: a pre-defined value (a name of a structure) that can be
+ * associated to each event. It can be set to 'NULL'.
+ *
+ * @param *file_source        the name of the file that emits the event
+ * @param *function_source    the function that emits the event
+ * @param *string_value       any value that better specifies the event
+ *
+ * @see fsm_enum_log_severity
+ * @see fsm_enum_log_source
+ */
+void fsm_add_log (int severity,
+                  int source,
+                  const char *file_source,
+                  const char *function_source,
+                  const char *string_value);
+
--- a/src/fsm/log/appendix.c
+++ b/src/fsm/log/appendix.c
@ -0,0 +1,112 @@
+/**
+ * @file
+ *
+ * This file is part of Gem-graph. The log (or journal) stores chronologically
+ * the events during a session run   (rules exec, mainly)
+ *
+ * This file groups some functions that a typical list should implement but whose
+ * utility remains to evaluate in the case of a log list.
+ *
+ * @cond LICENSE
+ * Copyright © 2021 Libre en Communs <contact@a-lec.org>
+ * Copyright © 2021-2024 Adrien Bourmault <neox@a-lec.org>
+ * Copyright © 2021-2024 Jean Sirmai <jean@a-lec.org>
+ *
+ * This program is free software: you can redistribute it and/or modify it under
+ * the terms of the GNU Affero General Public License as published by the Free
+ * Software Foundation, either version 3 of the License, or (at your option) any
+ * later version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ * @endcond
+ */
+
+#include <stdio.h>
+#include <stdlib.h>
+#include "../../../include/fsm.h"
+
+/**
+ * remove an event;
+ * the removal is a pop back
+ *
+ * @since 2024-09
+ *
+ * @param *jj
+ * @param *file_source
+ * @param *function_source
+ * @param *string_value
+ *
+ * @returns the removed event date microseconds
+ */
+long fsm_remove_log (fsm_log_struct *jj,
+                     const char *file_source,
+                     const char *function_source,
+                     const char *string_value)
+{
+    long usec;
+    fsm_log_struct_unit *tmp = jj->last;
+    if (! tmp) return -1;
+    usec = tmp->usec;
+    jj->last = tmp->prev;
+    if (jj->last) jj->last->next = NULL;
+    else jj->first = NULL;
+    free (tmp);
+    return usec;
+}
+
+
+
+/**
+ * get log length
+ *
+ * @since 2024-09
+ *
+ * @param *jj
+ * @returns log length
+ */
+int fsm_get_log_length (fsm_log_struct jj)
+{
+    fsm_log_struct_unit *a_unit = jj.first;
+    int nb = 0;
+    while (a_unit)
+    {
+        nb ++;
+        a_unit = a_unit->next;
+    }
+    return nb;
+}
+
+
+/**
+ * seek for an event
+ *
+ * @since 2024-09
+ *
+ * @param *jj
+ * @param usec
+ * @param *file_source
+ * @param *function_source
+ * @param *string_value
+ */
+void fsm_seek_log (fsm_log_struct jj,
+                   long usec,
+                   const char *file_source,
+                   const char *function_source,
+                   const char *string_value)
+{
+    fsm_log_struct_unit *a_unit = jj.first;
+    int nb = 0;
+    while (a_unit)
+    {
+        if (usec == a_unit->usec) nb++;
+        a_unit = a_unit->next;
+    }
+    if (nb > 0)  printf ("> date (usec) %ld found %d times in journal\n", usec, nb);
+    else         printf ("> date (usec) %ld not found in journal\n", usec);
+}
--- a/src/fsm/log/manager.c
+++ b/src/fsm/log/manager.c
@ -0,0 +1,104 @@
+/**
+ * @file
+ * @brief fsm (Finite State Machine) log manager
+ *
+ * This file is part of Gem-graph.
+ *
+ * @details
+ * The log (journal) is created, edited and published from here.
+ * This file contains only (1) the static fsm_log_struct gg_logs
+ * and (2) the function fsm_add_log() that all calls must pass through to send a
+ * message to the log.
+ *
+ * @cond LICENSE
+ * Copyright © 2021 Libre en Communs <contact@a-lec.org>
+ * Copyright © 2021-2024 Adrien Bourmault <neox@a-lec.org>
+ * Copyright © 2021-2024 Jean Sirmai <jean@a-lec.org>
+ *
+ * This program is free software: you can redistribute it and/or modify it under
+ * the terms of the GNU Affero General Public License as published by the Free
+ * Software Foundation, either version 3 of the License, or (at your option) any
+ * later version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ * @endcond
+ */
+
+#include "../../../include/fsm.h"
+
+
+/*******************************************************************************
+ *                      L O G   /   J O U R N A L                              *
+*******************************************************************************/
+
+/**
+ * The fsm_struct_journal (gg_logs) is a static instance in the file
+ * /src/fsm/log/manager.c
+ * Therefore, all the functions that read or write it are in this file.
+ * This helps to avoid uncontrolled operations.
+ */
+static fsm_log_struct gg_logs;
+
+
+/**
+ * @brief It is mandatory for any event to call this function to be published in
+ * the journal.
+ *
+ * @details The fsm_struct_journal (gg_logs) is a static instance in the file
+ * /src/fsm/log/manager.c
+ * Therefore, all the functions that read or write it will be in this file.
+ * This is to avoid uncontrolled operations on it.
+ *
+ * A message is send to the log for each documented event.
+ *
+ * If there are too many events, one or several filters can be applied
+ * here (and only here) before publication, to select only some events
+ * of interest (during debugging, for example).
+ *
+ * These filters can operate on any the following five parameters:
+ * severity, source, file_source (text), function_source (text),
+ * string_value (text).
+ *
+ * They can be combined using any logical operators and parentheses.
+ *
+ * @since 2024-08
+ *
+ * @callgraph
+ * @see fsm_add_log_event()
+ *
+ * @callergraph
+ * see fsm_init()
+ *
+ * @param severity:  one of the following pre-defined values
+ *
+ *        FATAL  -  ERROR  -  WARN  -  INFO  -  DEBUG  -  TRACE
+ *
+ * @param source: a pre-defined value (a name of a structure) that can be
+ * associated to each event. It can be set to 'NULL'.
+ *
+ * @param *file_source        the name of the file that emits the event
+ * @param *function_source    the function that emits the event
+ * @param *string_value       any value that better specifies the event
+ *
+ * @see fsm_enum_log_severity
+ * @see fsm_enum_log_source
+ */
+void fsm_add_log (int severity,
+                  int source,
+                  const char *file_source,
+                  const char *function_source,
+                  const char *string_value)
+{
+    if
+    (
+        severity  <  TRACE
+    // &&  source == RULE_CONDITION
+    )
+    fsm_add_log_event (&gg_logs, file_source, function_source, string_value);
+}
--- a/src/fsm/log/oper.c
+++ b/src/fsm/log/oper.c
@ -0,0 +1,153 @@
+/**
+ * @file
+ *
+ * This file is part of Gem-graph.
+ *
+ * The log (journal) stores chronologically the events during a session.
+ *
+ * This file contains the executive functions needed to init the log, add an
+ * event and publish the log.
+ *
+ * The log presentation is:
+ * [date - rank - source file - source function - value]
+ *
+ * Today, the log is simply printed in the console using glib/g_message();
+ * It will be printed in chronological order in a file.
+ *
+ * @cond LICENSE
+ * Copyright © 2021 Libre en Communs <contact@a-lec.org>
+ * Copyright © 2021-2024 Adrien Bourmault <neox@a-lec.org>
+ * Copyright © 2021-2024 Jean Sirmai <jean@a-lec.org>
+ *
+ * This program is free software: you can redistribute it and/or modify it under
+ * the terms of the GNU Affero General Public License as published by the Free
+ * Software Foundation, either version 3 of the License, or (at your option) any
+ * later version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ * @endcond
+ */
+
+
+#include <time.h>
+#include <sys/time.h>
+#include <stdio.h>
+#include <stdlib.h>
+#include <glib.h>
+#include "../../../include/fsm.h"
+
+
+/**
+ * init the log: a double chained list
+ *
+ * first and last records are set to NULL
+ *
+ * @since 2024-09
+ *
+ * @param *jj
+ */
+void fsm_init_log (fsm_log_struct *jj)
+{
+    jj->first = NULL;
+    jj->last = NULL;
+}
+
+
+/**
+ * removes all the log content and free each unit
+ *
+ * @since 2024-09
+ *
+ * @param *jj
+ */
+void fsm_clear_log (fsm_log_struct *jj)
+{
+   fsm_log_struct_unit *tmp;
+   fsm_log_struct_unit *a_unit = jj->first;
+   while(a_unit)
+   {
+     tmp = a_unit;
+     a_unit = a_unit->next;
+     free (tmp);
+   }
+   jj->first = NULL;
+   jj->last = NULL;
+}
+
+
+/**
+ * add an event
+ *
+ * *new_unit = malloc (sizeof(fsm_log_struct_unit));
+ *
+ * warn: is never free (as new log units are never removed)
+ *
+ * @since 2024-09
+ *
+ * @param *jj
+ * @param *file_source
+ * @param *function_source
+ * @param *string_value
+ */
+void fsm_add_log_event (fsm_log_struct *jj,
+                  const char *file_source,
+                  const char *function_source,
+                  const char *string_value)
+{
+    struct timeval tv;
+    gettimeofday (&tv, NULL);
+    fsm_log_struct_unit *new_unit = malloc (sizeof(fsm_log_struct_unit));
+    if (! new_unit) exit (EXIT_FAILURE);
+
+    new_unit->yy_dd_mm = tv.tv_sec;
+    new_unit->usec = tv.tv_usec;
+    new_unit->file_source = file_source;
+    new_unit->function_source = function_source;
+    new_unit->string_value = string_value;
+
+    new_unit->next = jj->first;
+    new_unit->prev = NULL;
+    if (jj->first) jj->first->prev = new_unit;
+    else jj->last = new_unit;
+    jj->first = new_unit;
+}
+
+
+#define LOG_MAX_LENGTH 255 /**< arbitrary */
+
+/**
+ * publish all the logs chronologically (using the g_lib function: g_message)
+ *
+ * today, simply printed in the console;  TODO: print in a file
+ *
+ * @since 2024-09
+ *
+ * @param *jj
+ */
+void fsm_publish_log (fsm_log_struct jj)
+{
+    fsm_log_struct_unit *a_unit = jj.last;
+    char buf [LOG_MAX_LENGTH];
+    int nb = 0;
+    while (a_unit)
+    {
+        strftime(buf, sizeof(buf), "%D %T", localtime(&a_unit->yy_dd_mm));
+        g_message ("%s + %-6ld  %6d    %-32s %-38s %-50s",
+                   buf,
+                   a_unit->usec,
+                   nb,
+                   a_unit->file_source,
+                   a_unit->function_source,
+                   a_unit->string_value);
+        a_unit = a_unit->prev;
+        nb ++;
+    }
+}
+
+
--- a/src/main.c
+++ b/src/main.c
@ -3,7 +3,7 @@
 *
 * Gem-graph main file
 *
- * This file is part of Gem-graph.
+ * This file is part of Gem-graph. It contains only the main() function.
 *
 * @cond LICENSE
 * Copyright © 2021 Libre en Communs <contact@a-lec.org>
@ -23,6 +23,23 @@
 * You should have received a copy of the GNU Affero General Public License
 * along with this program.  If not, see <http://www.gnu.org/licenses/>.
 * @endcond
+ *
+ * ---
+ *
+ * The main() function will **initialise** the log, the finite state machine (fsm),
+ * the application and the windows and **close** all the elements it opened
+ * before the end of program execution.
+ * In this commit, it does not implement g_application_activate() and has no
+ * handlers connected to the 'activate' signal (which triggers an error message).
+ *
+ * The default values of the fsm initial state will be specified in:
+ * src/fsm/dispatch(). They are user preference and, in accordance, the overview
+ * page of the current model will be displayed as they specify it in:
+ * src/widget/main_window/designer/widget_design_main_window().
+ *
+ * About code organization, see src/readme.dox
+ *
+ * ---
 */

 #include <gtk-4.0/gtk/gtk.h>
@ -32,9 +49,11 @@ int main (int argc, char **argv)
  GtkApplication *app;
  int status;

-  app = gtk_application_new ("org.jean.GTK4_GG_hack", G_APPLICATION_DEFAULT_FLAGS);
+  app = gtk_application_new ("org.gem-graph", G_APPLICATION_DEFAULT_FLAGS);
+
  //g_signal_connect (app, "activate", G_CALLBACK (on_main_window_activation), NULL);
  //g_signal_connect (app, "activate", G_CALLBACK (on_dialog_window_activation), NULL);
+
  status = g_application_run (G_APPLICATION (app), argc, argv);
  g_object_unref (app);

--- a/src/readme.docs.c
+++ b/src/readme.docs.c
@ -0,0 +1,63 @@
+/**
+ * @file
+ * Gem-graph-client src/readme.docs file
+ *
+ *  This file is part of Gem-graph.
+ *
+ * @cond LICENSE
+ * Copyright © 2021 Libre en Communs <contact@a-lec.org>
+ * Copyright © 2021-2024 Adrien Bourmault <neox@a-lec.org>
+ * Copyright © 2021-2024 Jean Sirmai <jean@a-lec.org>
+ *
+ * This program is free software: you can redistribute it and/or modify it under
+ * the terms of the GNU Affero General Public License as published by the Free
+ * Software Foundation, either version 3 of the License, or (at your option) any
+ * later version.
+ *
+ * This program is distributed in the hope that it will be useful, but WITHOUT
+ * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
+ * FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
+ * details.
+ *
+ * You should have received a copy of the GNU Affero General Public License
+ * along with this program.  If not, see <http://www.gnu.org/licenses/>.
+ * @endcond
+ *
+ * @details
+ * The code files are all located in the src (sources) directory.
+ *
+ * They are divided according to several *types of organisation*:
+ *
+ * - *hierarchical*: the widgets that give the windows their appearance are
+ *    organised in the form of a tree.
+ *    Windows are the first level of depth.
+ *    Next come the windows contents: the title bars and the pages.
+ *    The pages are designed to occupy the windows space below the title bars.
+ *    Each of these pages has its own hierarchical structure: it can be divided
+ *    into horizontal or vertical strips, which can themselves be divided in the
+ *    same way, with varying levels of depth right down to the last containers
+ *    which contain lists of widgets such as buttons, bars, entries or images.
+ *
+ * - *list*: the main *sections* of the fsm (finite state machine) constitute
+ *   a list of at least four elements, each of which defines a set of possible
+ *   states :
+ *   -# execute or edit (managing the appropriate tools states in both cases)
+ *   -# measure, operate on data, prepare displayable results
+ *   -# user preferences
+ *   -# desired state of windows and widgets
+ *
+ *   The state of the fsm is uniquely defined at all times by all the parameters
+ *   listed in these sections. All program actions depend on this state.
+ *
+ * - *transversal*: the other functions that must be easily accessible by all
+ *   the previous functions. They are therefore all located at the root.
+ *   These are the functions that manage graphics, callbacks and utilities.
+ *   Although 'transversal', the log is part of the fsm.
+ *
+ * ---
+ *
+ * @see
+ * Model–view–controller || Model–view–viewmodel || Action–domain–responder ||
+ * Multitier_architecture https://en.wikipedia.org/wiki/Multitier_architecture
+ * (presentation, logic, data)
+ */