Clean: No longer need to explicitly call page_init() on the Client.

       Improve docs.
       Wrap test.

Author: bjones1

client/src/CodeChatEditor-test.mts

@@ -29,7 +29,7 @@ import "mocha/mocha.js";
 import "mocha/mocha.css";
 import { EditorView } from "@codemirror/view";
 import { ChangeSpec, EditorState, EditorSelection } from "@codemirror/state";
-import { exportedForTesting, page_init } from "./CodeChatEditor.mjs";
+import { exportedForTesting } from "./CodeChatEditor.mjs";
 import { CodeMirror, CodeMirrorDocBlockTuple } from "./shared_types.mjs";
 import {
     DocBlockPlugin,
@@ -40,7 +40,9 @@ import {
 // Otherwise, including [CodeChatEditor.mts](CodeChatEditor.mts) elsewhere would
 // double-define everything (producing complaints about two attempts to define
 // each web component).
-export { page_init };
+//
+// Nothing needed at present.
+//
 // Provide convenient access to all functions tested here.
 const { codechat_html_to_markdown } = exportedForTesting;
 

client/src/CodeChatEditor.mts

@@ -171,42 +171,12 @@ turndownService.use(gfm);
 
 // Page initialization
 // -------------------
-//
-// Load the dynamic content into the static page.
-export const page_init = () => {
-    on_dom_content_loaded(async () => {
-        // Intercept links in this document to save before following the link.
-        /// @ts-ignore
-        navigation.addEventListener("navigate", on_navigate);
-        const ccb = document.getElementById("CodeChat-sidebar") as
-            | HTMLIFrameElement
-            | undefined;
-        /// @ts-ignore
-        ccb?.contentWindow?.navigation.addEventListener(
-            "navigate",
-            on_navigate,
-        );
-        document.addEventListener("click", on_click);
-        // Provide basic error reporting for uncaught errors.
-        window.addEventListener("unhandledrejection", on_error);
-        window.addEventListener("error", on_error);
-
-        window.CodeChatEditor = {
-            open_lp,
-            on_save,
-            scroll_to_line,
-            show_toast,
-            allow_navigation: false,
-        };
-    });
-};
-
 export const set_is_dirty = (value: boolean = true) => {
     is_dirty = value;
 };
 
-// This is copied
-// from[MDN](https://developer.mozilla.org/en-US/docs/Web/API/Document/DOMContentLoaded_event#checking_whether_loading_is_already_complete).
+// This is copied from
+// [MDN](https://developer.mozilla.org/en-US/docs/Web/API/Document/DOMContentLoaded_event#checking_whether_loading_is_already_complete).
 export const on_dom_content_loaded = (on_load_func: () => void) => {
     if (document.readyState === "loading") {
         // Loading hasn't finished yet.
@@ -586,6 +556,32 @@ export const on_error = (event: Event) => {
     console.error(event);
 };
 
+// Load the dynamic content into the static page. Place this last, since we need
+// functions above defined before assigning them to the `CodeChatEditor`
+// namespace.
+on_dom_content_loaded(async () => {
+    // Intercept links in this document to save before following the link.
+    /// @ts-ignore
+    navigation.addEventListener("navigate", on_navigate);
+    const ccb = document.getElementById("CodeChat-sidebar") as
+        | HTMLIFrameElement
+        | undefined;
+    /// @ts-ignore
+    ccb?.contentWindow?.navigation.addEventListener("navigate", on_navigate);
+    document.addEventListener("click", on_click);
+    // Provide basic error reporting for uncaught errors.
+    window.addEventListener("unhandledrejection", on_error);
+    window.addEventListener("error", on_error);
+
+    window.CodeChatEditor = {
+        open_lp,
+        on_save,
+        scroll_to_line,
+        show_toast,
+        allow_navigation: false,
+    };
+});
+
 // Testing
 // -------
 //

client/src/CodeChatEditorFramework.mts

@@ -26,13 +26,11 @@
 // Imports
 // -------
 //
-// ### JavaScript/TypeScript
-//
-// #### Third-party
+// ### Third-party
 import ReconnectingWebSocket from "./third-party/ReconnectingWebSocket.cjs";
 import { show_toast as show_toast_core } from "./show_toast.mjs";
 
-// #### Local
+// ### Local
 import { assert } from "./assert.mjs";
 import {
     CodeChatForWeb,
@@ -91,7 +89,7 @@ class WebSocketComm {
 
     // A promise to serialize calls to and from the Client. This is important: a
     // `CurrentFile` requires the Client to save, then switch to a new web page.
-    // If an `Update` comes in, it should be applied after the `CurrentFile` is
+    // If an `Update` comes in, it should be applied after the `CurrentFile` has
     // finished executing.
     promise = Promise.resolve();
 
@@ -123,7 +121,7 @@ class WebSocketComm {
         // Handle websocket messages.
         this.ws.onmessage = (event: MessageEvent) => {
             // Parse the received message, which must be a single element of a
-            // dictionary representing a `JointMessage`.
+            // dictionary representing an `EditorMessage`.
             const joint_message = JSON.parse(event.data) as EditorMessage;
             const { id, message } = joint_message;
             console_log(
@@ -160,10 +158,11 @@ class WebSocketComm {
                         if (contents !== undefined) {
                             // I'd prefer to use a system-maintained value to
                             // determine the ready state of the iframe, such as
-                            // `readyState`. However, this value only applies to
-                            // the initial load of the iframe; it doesn't change
-                            // when the iframe's `src` attribute is changed. So,
-                            // we have to track this manually instead.
+                            // [readyState](https://developer.mozilla.org/en-US/docs/Web/API/Document/readyState).
+                            // However, this value only applies to the initial
+                            // load of the iframe; it doesn't change when the
+                            // iframe's `src` attribute is changed. So, we have
+                            // to track this manually instead.
                             if (!this.is_loading) {
                                 // Wait until after the DOM is ready, since we
                                 // rely on content set in
@@ -297,6 +296,8 @@ class WebSocketComm {
         callback: () => void = () => 0,
     ) => {
         const id = this.ws_id;
+        // The Client gets every third ID -- the IDE gets another third, while
+        // the Server gets the final third.
         this.ws_id += 3;
         // Add in the current filename to the message, if it's an `Update`.
         if (typeof message == "object" && "Update" in message) {
@@ -321,6 +322,9 @@ class WebSocketComm {
 
     // This is called by the Client when the user navigates to another webpage.
     current_file = (url: URL) => {
+        // TODO: should we delay execution of user navigation until all previous
+        // actions have finished, or ignore them and immediately perform the
+        // user navigation?
         this.promise = this.promise.finally(() => {
             if (url.host === window.location.host) {
                 // If this points to the Server, then tell the IDE to load a new

docs/design.md

@@ -26,20 +26,27 @@ These form a set of high-level requirements to guide the project.
 *   View source code as <a id="vision-code-blocks-and-doc-blocks"></a>[code
     blocks and doc blocks](index.md#code-blocks-and-doc-blocks). Doc blocks are
     lines of source which contain only correctly-formatted comments.
+
 *   Provide support for a <a id="vision-programming-language-support"></a>[wide
     variety of programming languages](index.md#programming-language-support).
+
 *   Provide integration with a <a id="vision-ide-integration"></a>[wide variety
     of IDEs/text editors](index.md#ide-integration).
-*   Load a document from source code, allow edits in a GUI, then save it
-    back to source code.
+
+*   Load a document from source code, allow edits in a GUI, then save it back to
+    source code.
+
     *   Provide word processor GUI tools (insert hyperlink, images, headings,
         change font, etc.) for doc blocks.
     *   Provide text editor/IDE tools (syntax highlighting, line numbers, show
         linter feedback) for code blocks.
 *   Zero build: eliminate the traditional project build process -- make it
     almost instantaneous.
+
 *   Doc block markup should be readable and well-known: markdown.
+
 *   Support both a single-file mode and a project mode.
+
     *   A project is a specific directory tree, identified by the presence of a
         TOC. A TOC is just a plain Markdown file with a specific name. A better
         term: not a TOC, but a navigation pane, since the TOC can contain
@@ -50,8 +57,9 @@ These form a set of high-level requirements to guide the project.
         *   Numbering comes from the current page's location within the TOC.
             Pages not in the TOC aren't numbered.
 *   <a id="authoring-support"></a>Provide [authoring
-    support](index.md#authoring-support), which allows authors to easily
-    create book/project-like features. In particular:
+    support](index.md#authoring-support), which allows authors to easily create
+    book/project-like features. In particular:
+
     *   Counters for numbering figures, tables, equations, etc. All counters are
         page-local (no global counters).
     *   Auto-titled links: the link text is automatically derived from the
@@ -108,9 +116,9 @@ These form a set of high-level requirements to guide the project.
         all anchors to be globally unique. HTML allows upper/lowercase ASCII
         plus the hyphen and underscore for IDs, meaning that a 5-character
         string provides >250 million unique anchors.
-
 *   Make picking a file/anchor easy: provide a searchable, expanded TOC listing
     every anchor.
+
 *   Provide edit and view options. (Rely on an IDE to edit raw source.)
 
 ### Nice to have features

docs/style_guide.cpp

@@ -183,17 +183,12 @@ double accurate_g(
 // Properly configuring the text editor used with the CodeChat Editor
 // significantly improves the authoring process. Recommended settings:
 //
-// *   Enable word wrap:
-//     [vscode](https://learn.microsoft.com/en-us/visualstudio/ide/reference/how-to-manage-word-wrap-in-the-editor?view=vs-2022)
-// *   Use spaces, not tabs​, for indentation:
-//     [vscode](https://code.visualstudio.com/docs/editor/codebasics#_indentation)
-// *   Enable auto-save:
-//     [vscode](https://code.visualstudio.com/docs/editor/codebasics#_save-auto-save)
+// *   Enable word wrap: [vscode](https://learn.microsoft.com/en-us/visualstudio/ide/reference/how-to-manage-word-wrap-in-the-editor?view=vs-2022)
+// *   Use spaces, not tabs​, for indentation: [vscode](https://code.visualstudio.com/docs/editor/codebasics#_indentation)
+// *   Enable auto-save: [vscode](https://code.visualstudio.com/docs/editor/codebasics#_save-auto-save)
 // *   Auto-reload enabled​: default in vscode
-// *   On save, remove trailing whitespace​:
-//     [vscode](https://stackoverflow.com/a/53663494/16038919)
-// *   Use a spell checker:
-//     [vscode](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker)
+// *   On save, remove trailing whitespace​: [vscode](https://stackoverflow.com/a/53663494/16038919)
+// *   Use a spell checker: [vscode](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker)
 // *   On a big monitor, place your IDE side by side with the CodeChat Editor.
 //
 // Common problems

server/src/lexer/pest/parser_design.md

@@ -18,7 +18,9 @@ In particular, a language-specific grammar must provide:
     inline_comment | block_comment }`. However, languages which lack an inline
     comment (such as CSS) or a block comment (such as Python) would contain only
     the appropriate comment type.
+
 *   Inline comment definitions:
+
     *   Opening inline delimiter(s) supported by the language. Three inline
         comment delimiters must be defined for a language. For C, this is:
 

server/src/translation.rs

@@ -415,7 +415,8 @@ pub async fn translation_task(
 
                 // Leave space for a server message during the init phase.
                 let mut id: f64 = INITIAL_MESSAGE_ID + MESSAGE_ID_INCREMENT;
-                // The source code, provided by the IDE. It will use whatever the IDE provides for EOLs, which is stored in `eol` below.
+                // The source code, provided by the IDE. It will use whatever
+                // the IDE provides for EOLs, which is stored in `eol` below.
                 let mut source_code = String::new();
                 let mut code_mirror_doc = String::new();
                 // The initial state will be overwritten by the first `Update`
@@ -547,7 +548,8 @@ pub async fn translation_task(
                                                         SimpleHttpResponse::Err(SimpleHttpResponseError::Io(err)),
                                                         None,
                                                     ),
-                                                    // There's no file, so return empty contents, which will be ignored.
+                                                    // There's no file, so return empty
+                                                    // contents, which will be ignored.
                                                     "".to_string()
                                                 ),
                                                 Ok(mut fc) => {
@@ -560,7 +562,8 @@ pub async fn translation_task(
                                                             use_pdf_js,
                                                         )
                                                         .await,
-                                                        // If the file is binary, return empty contents, which will be ignored.
+                                                        // If the file is binary, return empty
+                                                        // contents, which will be ignored.
                                                         option_file_contents.unwrap_or("".to_string())
                                                     )
                                                 }
@@ -837,7 +840,8 @@ pub async fn translation_task(
                                                     &cfw)
                                                 {
                                                     Ok(new_source_code) => {
-                                                        // Correct EOL endings for use with the IDE.
+                                                        // Correct EOL endings for use with the
+                                                        // IDE.
                                                         let new_source_code_eol = eol_convert(new_source_code, &eol);
                                                         let ccfw = if sync_state == SyncState::InSync && allow_source_diffs {
                                                             Some(CodeChatForWeb {

server/src/webserver.rs

@@ -750,7 +750,8 @@ pub async fn file_to_response(
     {
         if is_current_file || is_toc {
             source_to_codechat_for_web_string(
-                // Ensure we work with Unix-style (LF only) files, since other line endings break the translation process.
+                // Ensure we work with Unix-style (LF only) files, since other
+                // line endings break the translation process.
                 &file_contents_text.replace("\r\n", "\n"),
                 file_path,
                 is_toc,
@@ -896,10 +897,7 @@ pub async fn file_to_response(
                     <meta name="viewport" content="width=device-width, initial-scale=1">
                     <title>{name} - The CodeChat Editor</title>
                     {MATHJAX_TAGS}
-                    <script type="module">
-                        import {{ page_init }} from "/{codechat_editor_js}"
-                        page_init()
-                    </script>
+                    <script type="module">import "/{codechat_editor_js}"</script>
                     <link rel="stylesheet" href="/{codehat_editor_css}">
                     {sidebar_css}
                 </head>