a little more reorg

Put stuff people messing with Teliva apps are likely to need above the C
interface.

The state of documentation for Teliva app creators is still quite poor.
All they really have to go on is the example apps.

1 files changed, 84 insertions, 79 deletions

diff --git a/src/teliva.h b/src/teliva.h
index 50b1b0e..6c93653 100644
--- a/src/teliva.h
+++ b/src/teliva.h
@@ -1,36 +1,10 @@
 #ifndef __TELIVA_H__
 #define __TELIVA_H__
 
-/* Each category of primitives below shows a few options from high to low
- * levels of abstraction.
- * (Lower levels aren't complete or well-designed, just what code outside
- * teliva.c needs.) */
+/*** Some details for Teliva apps to be aware of. */
 
-/* Integrate with Lua VM */
-extern char** Argv;
-extern int handle_image(lua_State* L, char** argv, int n);
-
-extern int load_editor_buffer_to_current_definition_in_image(lua_State* L);
-extern void save_to_current_definition_and_editor_buffer(lua_State* L, const char* definition);
-extern void save_editor_state(int rowoff, int coloff, int cy, int cx);
-
-/* Standard UI elements */
-extern void render_trusted_teliva_data(lua_State* L);
-
-extern void draw_menu_item(const char* key, const char* name);
-
-extern void draw_string_on_menu(const char* s);
-
-extern int menu_column;
-
-/* Error reporting */
-
-extern const char* Previous_error;
-extern int report_in_developer_mode(lua_State* L, int status);
-
-extern void render_previous_error(void);
-
-// Some names for hotkeys beyond those provided by ncurses.
+/* Some names for hotkeys beyond those provided by ncurses. */
+/* TODO: expose these in the curses wrappers. */
 
 enum KEY_ACTION {
   KEY_NULL = 0,
@@ -57,78 +31,78 @@ enum KEY_ACTION {
 };
 
 
-// Colors (experimental)
-// Primary goal here: Keep text readable regardless of OS, terminal emulator
-// and color scheme. Unfortunately I don't yet have a good answer, so this
-// approach may yet change. Current approach:
-//  - Hardcode colors so that we can be sure we use legible combinations of
-//    foreground and background.
-//  - Use only the terminal palette in the range 16-255.
-//    - Not all terminals may support more than 256 colors. (I'm not yet sure
-//      everyone has even 256 colors. If you don't, please let me know:
-//      http://akkartik.name/contact)
-//    - Many terminals provide color schemes which give the ability to tweak
-//      colors 0-15. This makes it hard to assume specific combinations are
-//      legible. I'm hoping most terminal emulators don't tend to encourage
-//      messing with colors 16-255. (Please let me know if you know of
-//      counter-examples.)
-//
-// For now, you have to edit these values if you want to adjust colors in the
-// editing environment. Check out https://www.robmeerman.co.uk/unix/256colours
-// for a map of available colors.
-
-// Toggle between a few color schemes
+/* Colors (experimental)
+ * Primary goal here: Keep text readable regardless of OS, terminal emulator
+ * and color scheme. Unfortunately I don't yet have a good answer, so this
+ * approach may yet change. Current approach:
+ *  - Hardcode colors so that we can be sure we use legible combinations of
+ *    foreground and background.
+ *  - Use only the terminal palette in the range 16-255.
+ *    - Not all terminals may support more than 256 colors. (I'm not yet sure
+ *      everyone has even 256 colors. If you don't, please let me know:
+ *      http://akkartik.name/contact)
+ *    - Many terminals provide color schemes which give the ability to tweak
+ *      colors 0-15. This makes it hard to assume specific combinations are
+ *      legible. I'm hoping most terminal emulators don't tend to encourage
+ *      messing with colors 16-255. (Please let me know if you know of
+ *      counter-examples.)
+ *
+ * For now, you have to edit these values if you want to adjust colors in the
+ * editing environment. Check out https://www.robmeerman.co.uk/unix/256colours
+ * for a map of available colors. */
+
+/* Toggle between a few color schemes */
 #define COLOR_SCHEME 0
 #if COLOR_SCHEME == 0
-// Light color scheme.
+/* Light color scheme. */
 enum color {
-  COLOR_FOREGROUND = 238,                     // almost black
-  COLOR_BACKGROUND = 253,                     // almost white
-  COLOR_FADE = 244,                           // closer to background
+  COLOR_FOREGROUND = 238,                     /* almost black */
+  COLOR_BACKGROUND = 253,                     /* almost white */
+  COLOR_FADE = 244,                           /* closer to background */
   COLOR_MENU_ALTERNATE = 248,
   COLOR_SELECTABLE_FOREGROUND = 238,
   COLOR_SELECTABLE_BACKGROUND = 250,
   COLOR_ERROR_FOREGROUND = COLOR_BACKGROUND,
-  COLOR_ERROR_BACKGROUND = 124,               // deep red
-  COLOR_LUA_COMMENT = 27,                     // blue
-  COLOR_LUA_KEYWORD = 172,                    // orange
-  COLOR_LUA_CONSTANT = 31,                    // cyan
+  COLOR_ERROR_BACKGROUND = 124,               /* deep red */
+  COLOR_LUA_COMMENT = 27,                     /* blue */
+  COLOR_LUA_KEYWORD = 172,                    /* orange */
+  COLOR_LUA_CONSTANT = 31,                    /* cyan */
   COLOR_MATCH_FOREGROUND = COLOR_BACKGROUND,
-  COLOR_MATCH_BACKGROUND = 28,                // green
+  COLOR_MATCH_BACKGROUND = 28,                /* green */
 };
 #elif COLOR_SCHEME == 1
-// Dark color scheme.
+/* Dark color scheme. */
 enum color {
-  COLOR_FOREGROUND = 253,                     // almost white
-  COLOR_BACKGROUND = 238,                     // almost black
-  COLOR_FADE = 244,                           // closer to background
+  COLOR_FOREGROUND = 253,                     /* almost white */
+  COLOR_BACKGROUND = 238,                     /* almost black */
+  COLOR_FADE = 244,                           /* closer to background */
   COLOR_MENU_ALTERNATE = 244,
   COLOR_SELECTABLE_FOREGROUND = 238,
   COLOR_SELECTABLE_BACKGROUND = 250,
   COLOR_ERROR_FOREGROUND = COLOR_FOREGROUND,
-  COLOR_ERROR_BACKGROUND = 124,               // deep red
-  COLOR_LUA_COMMENT = 39,                     // blue
-  COLOR_LUA_KEYWORD = 172,                    // orange
-  COLOR_LUA_CONSTANT = 37,                    // cyan
+  COLOR_ERROR_BACKGROUND = 124,               /* deep red */
+  COLOR_LUA_COMMENT = 39,                     /* blue */
+  COLOR_LUA_KEYWORD = 172,                    /* orange */
+  COLOR_LUA_CONSTANT = 37,                    /* cyan */
   COLOR_MATCH_FOREGROUND = COLOR_BACKGROUND,
-  COLOR_MATCH_BACKGROUND = 28,                // green
+  COLOR_MATCH_BACKGROUND = 28,                /* green */
 };
 #elif COLOR_SCHEME == 2
-// Solarized dark.
+/* Solarized dark. */
 enum color {
-  COLOR_FOREGROUND = 250,                     // almost white
-  COLOR_BACKGROUND = 24,                      // dark blue-green
-  COLOR_FADE = 246,                           // closer to background
+  COLOR_FOREGROUND = 250,                     /* almost white */
+  COLOR_BACKGROUND = 24,                      /* dark blue-green */
+  COLOR_FADE = 246,                           /* closer to background */
   COLOR_MENU_ALTERNATE = 244,
   COLOR_SELECTABLE_FOREGROUND = 250,
   COLOR_SELECTABLE_BACKGROUND = 31,
   COLOR_ERROR_FOREGROUND = 250,
-  COLOR_ERROR_BACKGROUND = 124,               // deep red
-  COLOR_LUA_COMMENT = 45,                     // light blue
-  COLOR_LUA_KEYWORD = 172,                    // orange
-  COLOR_LUA_CONSTANT = 37,                    // cyan
+  COLOR_ERROR_BACKGROUND = 124,               /* deep red */
+  COLOR_LUA_COMMENT = 45,                     /* light blue */
+  COLOR_LUA_KEYWORD = 172,                    /* orange */
+  COLOR_LUA_CONSTANT = 37,                    /* cyan */
   COLOR_MATCH_FOREGROUND = COLOR_FOREGROUND,
-  COLOR_MATCH_BACKGROUND = 125,               // magenta
+  COLOR_MATCH_BACKGROUND = 125,               /* magenta */
 };
 #endif
 
@@ -141,8 +115,39 @@ enum color_pair {
   COLOR_PAIR_LUA_KEYWORD = 5,
   COLOR_PAIR_LUA_CONSTANT = 6,
   COLOR_PAIR_MATCH = 7,
-  COLOR_PAIR_MENU = 254,  // reserved for teliva; apps shouldn't use it
-  COLOR_PAIR_ERROR = 255,  // reserved for teliva; apps shouldn't use it
+  COLOR_PAIR_MENU = 254,  /* reserved for teliva; apps shouldn't use it */
+  COLOR_PAIR_ERROR = 255,  /* reserved for teliva; apps shouldn't use it */
 };
 
+/*** C Interface */
+
+/* Each category of primitives below shows a few options from high to low
+ * levels of abstraction.
+ * (Lower levels aren't complete or well-designed, just what code outside
+ * teliva.c needs.) */
+
+/* Integrate with Lua VM */
+extern char** Argv;
+extern int handle_image(lua_State* L, char** argv, int n);
+
+extern int load_editor_buffer_to_current_definition_in_image(lua_State* L);
+extern void save_to_current_definition_and_editor_buffer(lua_State* L, const char* definition);
+extern void save_editor_state(int rowoff, int coloff, int cy, int cx);
+
+/* Standard UI elements */
+extern void render_trusted_teliva_data(lua_State* L);
+
+extern void draw_menu_item(const char* key, const char* name);
+
+extern void draw_string_on_menu(const char* s);
+
+extern int menu_column;
+
+/* Error reporting */
+
+extern const char* Previous_error;
+extern int report_in_developer_mode(lua_State* L, int status);
+
+extern void render_previous_error(void);
+
 #endif