Adds index to all large filesHEADmaster

8 files changed, 187 insertions, 104 deletions

diff --git a/README.md b/README.md
index 7175615..8a2ed66 100644
--- a/README.md
+++ b/README.md
@@ -71,7 +71,7 @@ This project includes a native data visualizer that plots live simulation data.
 A generic set of plots is configured by default for all VM architectures. Each
 architecture may expand on these by configuring its own set of plots within
 `arch/{arch}/plots.cpp`. Once a simulation has been created (i.e., exists in
-${HOME}/.salis), you may launch the data server with:
+`${HOME}/.salis`), you may launch the data server with:
 ```console
 user@host$ ./salis.py server -n world-1 -o
 ```
@@ -89,10 +89,10 @@ user@host$ ./salis.py client -o -i ${SERVER_IP}
 - SQLite
 - Zlib
 
-## Dependencies for curses UI
+## Dependencies (curses UI)
 - NCurses
 
-## Dependencies for data client
+## Dependencies (data client)
 - GLFW
 - GLU
 - ImGui
diff --git a/anc/v1/55a.asm b/anc/v1/55a.asm
index aa95f07..297d3ee 100644
--- a/anc/v1/55a.asm
+++ b/anc/v1/55a.asm
@@ -1,7 +1,15 @@
-; begin marker
+; index
+; [section] begin gene
+; [section] measure gene
+; [section] allocation gene
+; [section] copy gene
+; [section] split gene
+; [section] end gene
+
+; [section] begin gene
 loka
 
-; measure yourself
+; [section] measure gene
 adrb
 keya
 adrf
@@ -13,7 +21,7 @@ subn
 nop1
 nop1
 
-; allocate child
+; [section] allocation gene
 lokb
 notn
 nop3
@@ -35,7 +43,7 @@ allf
 nop1
 nop2
 
-; copy yourself
+; [section] copy gene
 lokd
 load
 nop0
@@ -53,7 +61,7 @@ nop1
 jmpb
 keyd
 
-; split child
+; [section] split gene
 splt
 popn
 nop3
@@ -62,5 +70,5 @@ nop1
 jmpb
 keyb
 
-; end marker
+; [section] end gene
 loka
diff --git a/arch/v1/arch.c b/arch/v1/arch.c
index b200e5e..cb52bf7 100644
--- a/arch/v1/arch.c
+++ b/arch/v1/arch.c
@@ -1,6 +1,15 @@
 // Based on the original salis-v1 VM architecture:
 // https://git.pauloliver.dev/salis-v1/about/
 
+// index
+// [section] macros & enums
+// [section] globals
+// [section] main architecture functions
+// [section] data aggregation functions
+
+// ----------------------------------------------------------------------------
+// [section] macros & enums
+// ----------------------------------------------------------------------------
 #define INST_EVENT_ARRAYS(core) \
     INST_EVENT_ARRAY(core, 0, pop) /* instruction population */ \
     INST_EVENT_ARRAY(core, 1, exe) /* instruction executions */ \
@@ -17,9 +26,15 @@ enum {
 #undef INST
 };
 
+// ----------------------------------------------------------------------------
+// [section] globals
+// ----------------------------------------------------------------------------
 thrd_t g_arch_eva_thrds[CORES][ARCH_EVENT_ARRAYS_COUNT];
 struct DeflateParams g_arch_eva_deflate_params[CORES][ARCH_EVENT_ARRAYS_COUNT];
 
+// ----------------------------------------------------------------------------
+// [section] main architecture functions
+// ----------------------------------------------------------------------------
 #if defined(COMMAND_NEW)
 void arch_core_init(struct Core *core) {
     assert(core);
@@ -851,7 +866,7 @@ const char *arch_mnemonic(uint8_t inst) {
 }
 
 // ----------------------------------------------------------------------------
-// Data aggregation functions
+// [section] data aggregation functions
 // ----------------------------------------------------------------------------
 #if defined(COMMAND_NEW)
 void arch_push_data_header(void) {
diff --git a/core/client.cpp b/core/client.cpp
index 2ca419a..d541129 100644
--- a/core/client.cpp
+++ b/core/client.cpp
@@ -1,26 +1,25 @@
-// [SECTION] Includes
-// [SECTION] Defines
-// [SECTION] Status enum
-// [SECTION] String comparator declaration
-// [SECTION] Trace declarations
-// [SECTION] Plot declarations
-// [SECTION] Plots
-// [SECTION] Heatmap colormap
-// [SECTION] Global variables
-// [SECTION] String comparator definition
-// [SECTION] Trace (base) definition
-// [SECTION] TraceNamed definition
-// [SECTION] TraceHeatmap definition
-// [SECTION] Plot (base) definition
-// [SECTION] PlotLines definition
-// [SECTION] PlotStacked definition
-// [SECTION] PlotHeatmap definition
-// [SECTION] Data functions
-// [SECTION] GUI functions
-// [SECTION] Main functions
+// index
+// [section] includes
+// [section] macros & enums
+// [section] string comparator declaration
+// [section] trace declarations
+// [section] plot declarations
+// [section] plots
+// [section] global variables
+// [section] string comparator definition
+// [section] Trace (base) definition
+// [section] TraceNamed definition
+// [section] TraceHeatmap definition
+// [section] Plot (base) definition
+// [section] PlotLines definition
+// [section] PlotStacked definition
+// [section] PlotHeatmap definition
+// [section] data functions
+// [section] gui functions
+// [section] main functions
 
 // ----------------------------------------------------------------------------
-// [SECTION] Includes
+// [section] includes
 // ----------------------------------------------------------------------------
 #include <arpa/inet.h>
 #include <GL/glu.h>
@@ -41,7 +40,7 @@
 #include "logger.c"
 
 // ----------------------------------------------------------------------------
-// [SECTION] Defines
+// [section] macros & enums
 // ----------------------------------------------------------------------------
 #define COLOR_BLACK ImVec4(0.f, 0.f, 0.f, 1.f)
 #define FONT_SIZE 12.f
@@ -75,9 +74,6 @@
 #define DEFVAL_HM_LEFT 0l
 #define DEFVAL_HM_PIXEL_COUNT 0x400l // must equal HM_PIXEL_COUNT in server.c
 
-// ----------------------------------------------------------------------------
-// [SECTION] Status enum
-// ----------------------------------------------------------------------------
 enum Status {
     STATUS_STOPPED,
     STATUS_RUNNING,
@@ -86,14 +82,14 @@ enum Status {
 };
 
 // ----------------------------------------------------------------------------
-// [SECTION] String comparator declaration
+// [section] string comparator declaration
 // ----------------------------------------------------------------------------
 struct StringComparator {
     bool operator()(const char *a, const char *b) const;
 };
 
 // ----------------------------------------------------------------------------
-// [SECTION] Trace declarations
+// [section] trace declarations
 // ----------------------------------------------------------------------------
 template <class T>
 struct Trace : public std::vector<T> {
@@ -134,7 +130,7 @@ struct TraceHeatmap : public TraceNamed<T> {
 };
 
 // ----------------------------------------------------------------------------
-// [SECTION] Plot declarations
+// [section] plot declarations
 // ----------------------------------------------------------------------------
 typedef int (*AxisFormatter)(double value, char *buff, int size, void *data);
 
@@ -201,7 +197,7 @@ private:
 };
 
 // ----------------------------------------------------------------------------
-// [SECTION] Plots
+// [section] plots
 // ----------------------------------------------------------------------------
 #include "plots.cpp"
 
@@ -282,23 +278,7 @@ std::array g_core_plots_heatmaps = std::to_array<PlotHeatmap>({
 });
 
 // ----------------------------------------------------------------------------
-// [SECTION] Heatmap colormap
-// ----------------------------------------------------------------------------
-std::array g_hm_colormap = std::to_array<ImVec4>({
-    {0.000f, 0.000f, 0.016f, 1.f},
-    {0.106f, 0.047f, 0.255f, 1.f},
-    {0.290f, 0.047f, 0.420f, 1.f},
-    {0.471f, 0.110f, 0.427f, 1.f},
-    {0.647f, 0.173f, 0.376f, 1.f},
-    {0.812f, 0.267f, 0.275f, 1.f},
-    {0.929f, 0.412f, 0.145f, 1.f},
-    {0.984f, 0.608f, 0.024f, 1.f},
-    {0.969f, 0.820f, 0.239f, 1.f},
-    {0.988f, 1.000f, 0.643f, 1.f},
-});
-
-// ----------------------------------------------------------------------------
-// [SECTION] Global variables
+// [section] global variables
 // ----------------------------------------------------------------------------
 GLFWwindow *g_window;
 ImGuiIO *g_imgui_io;
@@ -355,17 +335,30 @@ std::vector<Plot *> g_plots;
 Trace<double> g_x_axis_double;
 Trace<double> g_zero_trace;
 
+std::array g_hm_colormap = std::to_array<ImVec4>({
+    {0.000f, 0.000f, 0.016f, 1.f},
+    {0.106f, 0.047f, 0.255f, 1.f},
+    {0.290f, 0.047f, 0.420f, 1.f},
+    {0.471f, 0.110f, 0.427f, 1.f},
+    {0.647f, 0.173f, 0.376f, 1.f},
+    {0.812f, 0.267f, 0.275f, 1.f},
+    {0.929f, 0.412f, 0.145f, 1.f},
+    {0.984f, 0.608f, 0.024f, 1.f},
+    {0.969f, 0.820f, 0.239f, 1.f},
+    {0.988f, 1.000f, 0.643f, 1.f},
+});
+
 PFNGLCOPYIMAGESUBDATAPROC glCopyImageSubData;
 
 // ----------------------------------------------------------------------------
-// [SECTION] String comparator definition
+// [section] string comparator definition
 // ----------------------------------------------------------------------------
 bool StringComparator::operator()(const char *a, const char *b) const {
     return strcmp(a, b) < 0;
 }
 
 // ----------------------------------------------------------------------------
-// [SECTION] Trace (base) definition
+// [section] Trace (base) definition
 // ----------------------------------------------------------------------------
 template <class T>
 Trace<T>::Trace() : std::vector<T>() {}
@@ -430,7 +423,7 @@ void Trace<T>::trim_spec(int64_t multiplier) {
 }
 
 // ----------------------------------------------------------------------------
-// [SECTION] TraceNamed definition
+// [section] TraceNamed definition
 // ----------------------------------------------------------------------------
 template <class T>
 TraceNamed<T>::TraceNamed(const char *name, const char *label) : m_name(name), m_label(label) {}
@@ -446,7 +439,7 @@ const char *TraceNamed<T>::get_label() const {
 }
 
 // ----------------------------------------------------------------------------
-// [SECTION] TraceHeatmap definition
+// [section] TraceHeatmap definition
 // ----------------------------------------------------------------------------
 template <class T>
 TraceHeatmap<T>::TraceHeatmap(const char *name, const char *name_fmt) : TraceNamed<T>(name, name_fmt) {}
@@ -469,7 +462,7 @@ void TraceHeatmap<T>::validate() const {
 #endif
 
 // ----------------------------------------------------------------------------
-// [SECTION] Plot (base) definition
+// [section] Plot (base) definition
 // ----------------------------------------------------------------------------
 Plot::Plot(const char *name, const char *section) : m_visible(true), m_name(name), m_section(section) {}
 
@@ -531,7 +524,7 @@ void Plot::render_post(const ImVec2 &frame_size) {
 }
 
 // ----------------------------------------------------------------------------
-// [SECTION] PlotLines definition
+// [section] PlotLines definition
 // ----------------------------------------------------------------------------
 PlotLines::PlotLines(const char *name, const char *section, std::vector<const char *> trace_keys) : Plot(name, section), m_trace_keys(trace_keys) {}
 
@@ -549,7 +542,7 @@ void PlotLines::render_internal(const ImVec2 &frame_size) {
 }
 
 // ----------------------------------------------------------------------------
-// [SECTION] PlotStacked definition
+// [section] PlotStacked definition
 // ----------------------------------------------------------------------------
 PlotStacked::PlotStacked(const char *name, const char *section, std::vector<const char *> trace_keys) : Plot(name, section), m_trace_keys(trace_keys), m_trace_states(trace_keys.size(), true), m_trace_totals(), m_trace_normals(trace_keys.size()), m_needs_reset(true) {}
 
@@ -651,7 +644,7 @@ void PlotStacked::render_internal(const ImVec2 &frame_size) {
 }
 
 // ----------------------------------------------------------------------------
-// [SECTION] PlotHeatmap definition
+// [section] PlotHeatmap definition
 // ----------------------------------------------------------------------------
 PlotHeatmap::PlotHeatmap(const char *name, const char *section, const char *trace_key) : Plot(name, section), m_trace_key(trace_key), m_tex_scale_pow(-1.f), m_tex_scale_high(0.f), m_tex_rendered_last(0), m_rows_rendered(0), m_tex_id(0), m_tex_render(), m_needs_reset(true) {}
 
@@ -797,7 +790,7 @@ void PlotHeatmap::render_post(const ImVec2 &frame_size) {
 }
 
 // ----------------------------------------------------------------------------
-// [SECTION] Data functions
+// [section] data functions
 // ----------------------------------------------------------------------------
 int64_t data_max_hm_pixel_pow(void) {
     return (int64_t)floor(log2((double)(MVEC_SIZE - g_hm_left) / (double)g_hm_pixel_count));
@@ -987,7 +980,7 @@ void data_stop_fetching(void) {
 }
 
 // ----------------------------------------------------------------------------
-// [SECTION] GUI functions
+// [section] gui functions
 // ----------------------------------------------------------------------------
 void gui_render_data_input(const char *label, int64_t *target) {
     assert(target);
@@ -1276,7 +1269,7 @@ void gui_render(void) {
 }
 
 // ----------------------------------------------------------------------------
-// [SECTION] Main functions
+// [section] main functions
 // ----------------------------------------------------------------------------
 void app_sig_handler(int signo) {
     (void)signo;
diff --git a/core/salis.c b/core/salis.c
index 3740f3c..9f9a3d0 100644
--- a/core/salis.c
+++ b/core/salis.c
@@ -1,3 +1,19 @@
+// index
+// [section] includes
+// [section] macros & enums
+// [section] structs
+// [section] globals
+// [section] architecture forward declarations
+// [section] memory vector functions
+// [section] mutator functions
+// [section] process functions
+// [section] core functions
+// [section] salis functions
+// [section] architecture & ui includes
+
+// ----------------------------------------------------------------------------
+// [section] includes
+// ----------------------------------------------------------------------------
 #include <assert.h>
 #include <sqlite3.h>
 #include <stdbool.h>
@@ -12,6 +28,9 @@
 #include "compress.c"
 #include "sql.c"
 
+// ----------------------------------------------------------------------------
+// [section] macros & enums
+// ----------------------------------------------------------------------------
 #define INST_CAP 0x80
 #define INST_MASK 0x7f
 #define IPC_FLAG 0x80
@@ -24,6 +43,9 @@
     EVENT_ARRAY(core, 2, bev) /* birth events array */
 #define EVENT_ARRAYS_COUNT 3
 
+// ----------------------------------------------------------------------------
+// [section] structs
+// ----------------------------------------------------------------------------
 struct Proc {
 #define PROC_FIELD(type, name) type name;
     PROC_FIELDS
@@ -71,7 +93,9 @@ struct Core {
     uint8_t tgap[THREAD_GAP];
 };
 
-// Globals
+// ----------------------------------------------------------------------------
+// [section] globals
+// ----------------------------------------------------------------------------
 struct Core g_cores[CORES];
 uint64_t g_steps;
 uint64_t g_syncs;
@@ -84,7 +108,9 @@ char g_asav_pbuf[AUTOSAVE_NAME_LEN];
 thrd_t g_eva_thrds[CORES][EVENT_ARRAYS_COUNT];
 struct DeflateParams g_eva_deflate_params[CORES][EVENT_ARRAYS_COUNT];
 
-// Each architecture must define these functions
+// ----------------------------------------------------------------------------
+// [section] architecture forward declarations
+// ----------------------------------------------------------------------------
 #if defined(COMMAND_NEW)
 void arch_core_init(struct Core *core);
 #endif
@@ -122,7 +148,7 @@ void arch_push_data_header(void);
 void arch_push_data_line(void);
 
 // ----------------------------------------------------------------------------
-// Memory vector functions
+// [section] memory vector functions
 // ----------------------------------------------------------------------------
 #if defined(MVEC_LOOP)
 uint64_t mvec_loop(uint64_t addr) {
@@ -282,7 +308,7 @@ uint64_t mvec_get_owner(const struct Core *core, uint64_t addr) {
 }
 
 // ----------------------------------------------------------------------------
-// Mutator functions
+// [section] mutator functions
 // ----------------------------------------------------------------------------
 #if defined(COMMAND_NEW)
 uint64_t muta_smix(uint64_t *seed) {
@@ -333,7 +359,7 @@ void muta_cosmic_ray(struct Core *core) {
 }
 
 // ----------------------------------------------------------------------------
-// Process functions
+// [section] process functions
 // ----------------------------------------------------------------------------
 void proc_new(struct Core *core, const struct Proc *proc) {
     assert(core);
@@ -402,7 +428,7 @@ struct Proc *proc_fetch(struct Core *core, uint64_t pix) {
 }
 
 // ----------------------------------------------------------------------------
-// Core functions
+// [section] core functions
 // ----------------------------------------------------------------------------
 #if defined(COMMAND_NEW) || defined(COMMAND_LOAD)
 void core_save(FILE *f, const struct Core *core) {
@@ -621,7 +647,7 @@ void core_step(struct Core *core) {
 }
 
 // ----------------------------------------------------------------------------
-// Main salis functions
+// [section] salis functions
 // ----------------------------------------------------------------------------
 #if defined(COMMAND_NEW) || defined(COMMAND_LOAD)
 void salis_save(const char *path) {
@@ -1071,13 +1097,10 @@ void salis_free(void) {
 }
 
 // ----------------------------------------------------------------------------
-// Architecture
+// [section] architecture & ui includes
 // ----------------------------------------------------------------------------
 #include "arch.c"
 
-// ----------------------------------------------------------------------------
-// UI
-// ----------------------------------------------------------------------------
 #if defined(COMMAND_NEW) || defined(COMMAND_LOAD)
 #include "ui.c"
 #endif
diff --git a/core/server.c b/core/server.c
index 82b6da5..9a06825 100644
--- a/core/server.c
+++ b/core/server.c
@@ -1,3 +1,15 @@
+// index
+// [section] includes
+// [section] macros
+// [section] structs
+// [section] globals
+// [section] event array render function
+// [section] sql callbacks
+// [section] main functions
+
+// ----------------------------------------------------------------------------
+// [section] includes
+// ----------------------------------------------------------------------------
 #include <arpa/inet.h>
 #include <assert.h>
 #include <json-c/json.h>
@@ -12,14 +24,14 @@
 #include "sql.c"
 
 // ----------------------------------------------------------------------------
-// Defines
+// [section] macros
 // ----------------------------------------------------------------------------
 #define BACKLOG 10
 #define EVA_SIZE (sizeof(uint64_t) * MVEC_SIZE)
 #define MAX_HM_PIXEL_COUNT 0x400 // must equal DEFVAL_HM_PIXEL_COUNT in client.cpp
 
 // ----------------------------------------------------------------------------
-// Declarations
+// [section] structs
 // ----------------------------------------------------------------------------
 struct Socket {
     int fd;
@@ -43,13 +55,13 @@ struct RenderContext {
 };
 
 // ----------------------------------------------------------------------------
-// Globals
+// [section] globals
 // ----------------------------------------------------------------------------
 struct json_object *g_response_header;
 size_t g_blob_count;
 
 // ----------------------------------------------------------------------------
-// Event array render function
+// [section] event array render function
 // ----------------------------------------------------------------------------
 int eva_render(void *data) {
     assert(data);
@@ -101,7 +113,7 @@ int eva_render(void *data) {
 }
 
 // ----------------------------------------------------------------------------
-// SQL callbacks
+// [section] sql callbacks
 // ----------------------------------------------------------------------------
 void sql_callback_add_column_name(sqlite3_stmt *sql_stmt, void *data) {
     assert(sql_stmt);
@@ -168,7 +180,7 @@ void sql_callback_add_data(sqlite3_stmt *sql_stmt, void *data) {
 }
 
 // ----------------------------------------------------------------------------
-// Main functions
+// [section] main functions
 // ----------------------------------------------------------------------------
 void sig_handler(int signo) {
     (void)signo;
diff --git a/salis.py b/salis.py
index 4e0044e..f247426 100755
--- a/salis.py
+++ b/salis.py
@@ -1,5 +1,16 @@
 #!/usr/bin/env -S PYTHONDONTWRITEBYTECODE=1 python
 
+# index
+# [section] argument parser
+# [section] build class
+# [section] logging
+# [section] options dict formatter
+# [section] source options
+# [section] source architecture variables
+# [section] ancestor assembler
+# [section] compiler flags
+# [section] build and launch
+
 import ctypes
 import json
 import os
@@ -15,7 +26,7 @@ from tempfile import TemporaryDirectory
 from types import SimpleNamespace
 
 # ------------------------------------------------------------------------------
-# Argument parser
+# [section] argument parser
 # ------------------------------------------------------------------------------
 prog = sys.argv[0]
 epilog = f"Use '-h' to show command arguments; e.g. '{prog} new -h'"
@@ -92,7 +103,7 @@ for (name, sub_parsers, _), kwargs in options.items():
 args = parser.parse_args()
 
 # ------------------------------------------------------------------------------
-# Build class
+# [section] build class
 # ------------------------------------------------------------------------------
 class Build:
     def __init__(self, path, log, library=False, cpp=False):
@@ -148,7 +159,7 @@ class Build:
         if code != 0: raise RuntimeError(f"Binary returned code: {code}")
 
 # ------------------------------------------------------------------------------
-# Logging
+# [section] logging
 # ------------------------------------------------------------------------------
 log_logs = []
 log_ns = SimpleNamespace()
@@ -168,7 +179,7 @@ for log_level, log_msg in log_logs:
     getattr(log, log_level)(log_msg)
 
 # ------------------------------------------------------------------------------
-# Options dict formatter
+# [section] options dict formatter
 # ------------------------------------------------------------------------------
 fmt_h2u = lambda field: field.replace("-", "_")
 fmt_u2h = lambda field: field.replace("_", "-")
@@ -189,7 +200,7 @@ def fmt_opts(opts):
     return json.dumps(opts_out, indent=2)
 
 # ------------------------------------------------------------------------------
-# Source configuration
+# [section] source options
 # ------------------------------------------------------------------------------
 log.info(f"Called '{prog} {args.command}' with the following options: {fmt_opts(vars(args))}")
 ns = SimpleNamespace()
@@ -283,14 +294,14 @@ if args.command == "client":
     log.info(f"Confirmed server and client are running against the same git hash: {server_hash}")
 
 # ------------------------------------------------------------------------------
-# Architecture variables
+# [section] source architecture variables
 # ------------------------------------------------------------------------------
 arch_path = os.path.join("arch", args.arch, "vars.py")
 log.info(f"Loading architecture variables from: {arch_path}")
 arch_vars = runpy.run_path(arch_path, init_globals=globals())
 
 # ------------------------------------------------------------------------------
-# Assembler
+# [section] ancestor assembler
 # ------------------------------------------------------------------------------
 anc_path = os.path.join("anc", args.arch, f"{args.anc}.asm")
 
@@ -323,7 +334,7 @@ anc_repr = f"{{{",".join(map(str, anc_bytes))}}}"
 log.info(f"Compiled ancestor file '{anc_path}' into byte array: {anc_repr}")
 
 # ------------------------------------------------------------------------------
-# Compiler flags
+# [section] compiler flags
 # ------------------------------------------------------------------------------
 def pop_ui_vars():
     ns.ui_path = os.path.join("ui", args.ui, "vars.py")
@@ -431,7 +442,7 @@ if args.command == "client":
     ns.b.links.add("-lm")
 
 # ------------------------------------------------------------------------------
-# Build and launch executable
+# [section] build and launch
 # ------------------------------------------------------------------------------
 ns.b.build()
 ns.b.exec()
diff --git a/ui/curses/ui.c b/ui/curses/ui.c
index 950f109..9d253a3 100644
--- a/ui/curses/ui.c
+++ b/ui/curses/ui.c
@@ -1,6 +1,26 @@
+// index
+// [section] includes
+// [section] macros & enums
+// [section] globals
+// [section] gfx functions
+// [section] tui functions
+// [section] process page functions
+// [section] world page functions
+// [section] ipc page functions
+// [section] log page functions
+// [section] main print functions
+// [section] event functions
+// [section] main functions
+
+// ----------------------------------------------------------------------------
+// [section] includes
+// ----------------------------------------------------------------------------
 #include <curses.h>
 #include <locale.h>
 
+// ----------------------------------------------------------------------------
+// [section] macros & enums
+// ----------------------------------------------------------------------------
 #define LOG_LINE_COUNT 1024
 #define PANE_AND_MARGIN_WIDTH (PANE_WIDTH + 2)
 #define PANE_WIDTH 27
@@ -42,7 +62,9 @@ enum {
     PAIR_WARN = 12,
 };
 
-// GFX globals
+// ----------------------------------------------------------------------------
+// [section] globals
+// ----------------------------------------------------------------------------
 uint64_t g_gfx_vsiz; // zoom level
 uint64_t *g_gfx_inst; // instruction channel
 uint64_t *g_gfx_mall; // allocated state channel
@@ -52,7 +74,6 @@ uint64_t *g_gfx_mb1s; // selected organism's memory block #2 channel
 uint64_t *g_gfx_ipas; // selected organism's IP channel
 uint64_t *g_gfx_spas; // selected organism's SP channel
 
-// UI globals
 bool g_exit;
 bool g_running;
 unsigned g_core;
@@ -90,7 +111,7 @@ const wchar_t *g_zoomed_symbols = (
 );
 
 // ----------------------------------------------------------------------------
-// GFX functions
+// [section] gfx functions
 // ----------------------------------------------------------------------------
 void gfx_init(uint64_t vsiz) {
     assert(vsiz);
@@ -312,7 +333,7 @@ void gfx_render(const struct Core *core, uint64_t pos, uint64_t zoom, uint64_t p
 }
 
 // ----------------------------------------------------------------------------
-// TUI functions
+// [section] tui functions
 // ----------------------------------------------------------------------------
 void tui_line_buff_free(void) {
     if (g_line_buff) {
@@ -431,7 +452,7 @@ void tui_print_core(int l) {
 }
 
 // ----------------------------------------------------------------------------
-// Process page functions
+// [section] process page functions
 // ----------------------------------------------------------------------------
 int tui_proc_pair(uint64_t pix) {
     if (pix == g_proc_selected) {
@@ -591,7 +612,7 @@ void tui_print_process(int l) {
 }
 
 // ----------------------------------------------------------------------------
-// World page functions
+// [section] world page functions
 // ----------------------------------------------------------------------------
 void tui_world_resize(void) {
     assert(g_wrld_zoom);
@@ -745,7 +766,7 @@ void tui_print_world(int l) {
 }
 
 // ----------------------------------------------------------------------------
-// IPC page functions
+// [section] ipc page functions
 // ----------------------------------------------------------------------------
 void tui_print_ipc_field(int l, uint64_t i, int color) {
     uint8_t iinst = g_cores[g_core].iviv[i];
@@ -801,7 +822,7 @@ void tui_print_ipc(int l) {
 }
 
 // ----------------------------------------------------------------------------
-// Log page functions
+// [section] log page functions
 // ----------------------------------------------------------------------------
 void tui_info_impl(const char *format, ...) {
     assert(format);
@@ -877,7 +898,7 @@ void tui_print_log(int l) {
 }
 
 // ----------------------------------------------------------------------------
-// Main print function
+// [section] main print functions
 // ----------------------------------------------------------------------------
 void tui_print(void) {
     int l = 1;
@@ -931,7 +952,7 @@ void tui_print(void) {
 }
 
 // ----------------------------------------------------------------------------
-// Control function
+// [section] event functions
 // ----------------------------------------------------------------------------
 void ev_vscroll(int ev) {
     switch (g_page) {
@@ -1295,7 +1316,7 @@ void ev_handle(void) {
 }
 
 // ----------------------------------------------------------------------------
-// Main functions
+// [section] main functions
 // ----------------------------------------------------------------------------
 void init(void) {
     setlocale(LC_ALL, "");