Skip to content

README.md

Latest commit

 

History

History
355 lines (276 loc) · 12.2 KB

README.md

File metadata and controls

355 lines (276 loc) · 12.2 KB
Raw

Welcome to the CodeChat Editor

The CodeChat Editor is a GUI-based programmer's word processor / Jupyter for software developers. This document describes its basic features and use. In contrast, the style guide provides strategies for effectively employing the CodeChat Editor to improve the software development process.

<iframe width="560" height="315" src="https://www.youtube.com/embed/videoseries?si=QNrYCiTLVCpxpAbD&list=PLOJAqFa3UI2FJncc-OBRPhh17NJXQP6ve" allowfullscreen="allowfullscreen" frameborder="0" ></iframe>

Full manual

Read the manual rendered using the CodeChat Editor, since this documentation doesn't correctly render on GitHub.

Installation

Install the CodeChat Editor extension for Visual Studio code. For developers, see building from source.

Accessibility

When using the CodeChat Editor Client, the accessibility features change depending on context (code block or dock block). In a code block, press Esc then press tab/shift-tab to navigate. In a doc block, tab alone navigates; to view all doc block keyboard shortcuts press Alt+0 (Windows, Linux) or ⌥0 (MacOS).

Structure

The CodeChat Editor divides source code into code blocks and documentation (doc) blocks. These blocks are separated by newlines; the image below shows the style guide on the left in the Visual Studio Code (VSCode) text editor, while the right pane shows the same text from style guide in the CodeChat Editor (using the VSCode extension). Specifically, this screenshot shows:

  • ❶: a doc block. Doc blocks must have one space after the comment delimiter.
  • ❷: a code block. Comments on the same line as code are not interpreted as doc blocks.
  • ❸: varying indents before a doc block.
  • ❹: Markdown in a doc block; see a brief overview of Markdown.

Image showing code blocks and doc blocks in Visual Studio Code

See the style guide for more examples.

Editing

Edits may be made either in the IDE hosting the CodeChat Editor, or within the CodeChat Editor window itself. Edits made in one place are transferred to the other after a short delay.

Navigation

Switching documents in the IDE likewise switches the document shown in the CodeChat Editor. Likewise, following hyperlinks in the CodeChat Editor to a local file loads that file in the IDE, as well as showing it in the Editor.

Projects

The CodeChat Editor can either display a single file, or a project. In a project, the table of contents is displayed on the left, while a file within the project is displayed on the right. To create a project, simply place a file named toc.md at the root of your project [2]; its contents define the table of contents. See the new project template for a simple example.

References to other files

The CodeChat Editor supports hyperlinks to any recognized file type; to refer to another source file, simply insert a hyperlink to it. For example,

Source Rendered
[docs/style_guide.cpp](docs/style_guide.cpp) Style guide
[LICENSE.md](LICENSE.md) License

As usual, hyperlinks are relative to the current file; to refer to the style guide, use docs/style_guide.cpp, since this file resides in the docs/ subdirectory:

README.md (this file)
LICENSE.md
docs/
  style_guide.cpp
  monitor.png

Cross-references

Any HTML element with an id can be the target of either a hyperlink or a cross-reference. If the id resides in a file within a project, then any file in that same project can refer to that id using a hyperlink or cross-reference. For example:

Source Rendered
[Style guide](#cc-nNZ6Gs2uWD) Style guide
<xref ref="cc-nNZ6Gs2uWD"></xref>

Alpha feature: first view the style guide to make the link above work. Opening the link doesn't (yet) work.

In projects, each id must be unique throughout the entire project. To simplify the creation of unique ids, items assigned an id="*" with be replaced with a unique id, such as id=cc-DscjSxRZHF. This autogenerated id isn't automatically saved; you must make an edit to its containing file in the Client to save the resulting id.

Gathering fragments

Often, closely-related routines must be scattered across the source tree. For example, a client's HTTP request and the corresponding server-side endpoint which responds to that request are usually placed in separate files, even though these are tightly coupled. The CodeChat Editor therefore supports gathering these scattered fragments into one central location to better explain the code. To do so:

  1. In a doc block preceding a code fragment to gather, add a <fragment id="some_unique_id"></fragment>. Do this for each fragment to gather. By default, a fragment includes the doc block it was placed in along with the next code/doc block. To include additional content, add the following attribute: <fragment id="some_unique_id" following="number_of_following_code/doc_blocks_to_include"></fragment>. For example, the starting ID for the websocket connection between the CodeChat Server (written in Rust) and the CodeChat Client (written in TypeScript) both have <fragment> tags.
  2. In a doc block or a Markdown file, place an HTML element with both an id and a data-gather attribute, such as <h4 id="another_unique_id" data-gather="some_unique_id1 some_unique_id2 ...">Gathered code</h4>. Below the the result of a gather tag for these fragments:

Starting websocket ID

Alpha feature: first view webserver.rs and CodeChatEditorFramework.mts. Opening the link doesn't (yet) work.

Images

Likewise, the path to local images is relative to the current file's location (see the preceding diagram for the location of monitor.png). For example [1],

Source Rendered
![Monitor icon](docs/monitor.png) Monitor icon

The CodeChat Editor disallows drag-and-drop of images, the result is a mess -- the image data is embedded directly in the source file. Avoid this; instead, place images in a separate file, then reference them as shown above.

Mathematics

The CodeChat Editor uses MathJax to support typeset mathematics. Place the delimiters $ immediately before and after in-line mathematics; place $$ immediately before and after displayed mathematics. For example,

Source Rendered
$x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$ $x = \frac{-b \pm \sqrt{b^2 - 4ac}}{2a}$
$$a^2$$ $$a^2$$

See Latex Mathematics for the syntax used to write mathematics expressions.

Diagrams

Mermaid

The CodeChat Editor supports diagrams created by Mermaid. For example,

Source Rendered 
```mermaid
graph TD; A --> B;
```
 
graph TD; A --> B;
Loading

Graphviz

The CodeChat Editor supports diagrams created by Graphviz. For example,

Source Rendered 
```graphviz
digraph { A -> B }
```
 
digraph { A -> B }

Several on-line tools, such as Edotor, provide a focused editing experience.

PlantUML

PlantUML transforms a hyperlink to a user-defined diagram directly to an SVG; for example,

Source Rendered
![Sample PlantUML diagram](https://www.plantuml.com/plantuml/svg/ SoWkIImgAStDuNBAJrBGjLDmpCbCJbMmKiX8pSd9vt98pKi1IW80) Sample PlantUML diagram

To edit these diagrams, paste the URL into the PlantUML web server, click Decode URL, edit, then copy and paste the SVG URL back to this file.

Drawing programs

Images files produced by drawing programs can be included, as long as they can be saved in a web-compatible format (PNG, SVG, JPG, GIF, etc.). For example, the draw.io editor embeds source data into the resulting image, so the image below can be directly edited by that package:

Research capture

The VS Code extension can record dissertation study capture events when a participant explicitly opts in. See the capture token setup guide for more information.

Supported languages

  • C/C++
  • C#
  • CSS
  • Go
  • HTML
  • Java/Kotlin
  • JavaScript/ECMAScript and TypeScript
  • JSON with comments (JSON5)
  • Markdown
  • MATLAB
  • Python
  • Rust
  • Shell scripts (.sh)
  • SQL
  • Swift
  • TOML
  • VHDL
  • Verilog/SystemVerilog
  • Vlang
  • YAML

Issues and feature requests

Please report issues and provide suggestions for improvement using the Github page for this project. Contributions to the code are welcome and encouraged!

License

Copyright (C) 2025 Bryan A. Jones.

This file is part of the CodeChat Editor.

The CodeChat Editor is free software: you can redistribute it and/or modify it under the terms of the GNU General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.

The CodeChat Editor 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 General Public License for more details.

You should have received a copy of the GNU General Public License along with the CodeChat Editor. If not, see https://www.gnu.org/licenses/.

Notes

  1. The image used comes from Monitor icons created by prettycons - Flaticon.
  2. Note that the filename for the table of contents is lowercase; while the acronym is TOC, requiring upper-case naming can cause confusion when moving files between case-insensitive filesystems (Windows) and case-sensitive filesystems (Linux/OS X).