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.

Installation

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

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.

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.

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

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


Although the CodeChat Editor allows 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.

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.

Mathematics

The CodeChat Editor uses MathJax to support typeset mathematics. Place the delimiters $ or \\( and \\) immediately before and after in-line mathematics; place $$ or \\\[ and \\\] 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\)
$$a^2$$	$$a^2$$
\\\[a^2\\\]	\[a^2\]

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

Escaping

Markdown recognizes several characters common in mathematical expressions; these must be backslash escaped when used in math expressions to avoid problems. The following characters should be escaped: *, _, \, [, ], <.

Wrong source	Wrong rendered	Correct source	Correctly Rendered
${a}_1, b_{2}$	${a}1, b{2}$	${a}\_1, b\_{2}$	${a}_1, b_{2}$
$a*1, b*2$	$a1, b2$	$a\*1, b\*2$	$a*1, b*2$
$[a](b)$	$a$	$\[a\](b)$	$[a](b)$
$3 <a> b$	$3 b$	$3 \<a> b$	$3 &lt;a&gt; b$
$a \; b$	$a ; b$	$a \\; b$	$a \; b$

Diagrams

Graphviz

The CodeChat Editor contains rudimentary support for diagrams created by Graphviz. For example,

Source	Rendered
<graphviz-graph graph="digraph { A -> B }"></graphviz-graph>

To edit these diagrams, use an HTML entity encoder/decoder and a Graphviz editor such as Edotor.

Mermaid

The CodeChat Editor contains rudimentary support for diagrams created by Mermaid. For example,

Source	Rendered
<wc-mermaid>graph TD; A --> B;</wc-mermaid>	graph TD; A --> B;

To edit these diagrams, use an HTML entity encoder/decoder and the Mermaid live editor.

PlantUML

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

Source	Rendered


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.

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) 2022 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).