Docs: correct problems.

bjones1 · bjones1 · commit 16d5ef0fdbb7 · 2025-12-18T15:55:01.000-06:00
diff --git a/docs/design.md b/docs/design.md
@@ -26,27 +26,20 @@ These form a set of high-level requirements to guide the project.
   <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.
-
   * 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 anything (see
@@ -59,17 +52,20 @@ These form a set of high-level requirements to guide the project.
 * <a id="authoring-support"></a>Provide
   [authoring 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 link's
     destination (the heading text at the link's destination; a figure/table
     caption, etc.).
+
   * Auto-generated back links: anchors support auto-generated links back to all
     their referents, which can be used for footnotes, endnotes, citations, and
     indices. To enable this, all forward links must include an anchor and
     optionally the text to display at the target.
+
   * TOC support which:
+
     * Given some file(s), expands to a nested list of headings in the file(s).
       Authors may specify the depth of headings to include.
     * Show the filesystem, optionally not including files that are linked in th
@@ -82,42 +78,53 @@ These form a set of high-level requirements to guide the project.
       the currently viewed file, and tracks headings within the current file.
   * A gathering element: given an anchor, it shows the context of all hyperlinks
     to this anchor.
+
     * If the hyperlink is a heading, the context extends to the next same-level
       heading;
     * If the hyperlink is a start of context, the context ends at the end of
       context or end of file, whichever comes first.
     * Otherwise, the context extends to the following code block.
   * A report view: an extended gathering element that operates more like a
     query, producing nested, hierarchical results from the codebase.
+
   * Headings can be collapsed, which code code and doc blocks until the next
     same-level heading.
+
   * A sequencing/path element: given a starting hyperlink, it produces prev/next
     icons to show a startup/shutdown sequence, etc.
+
   * A graph view: shows the entire document as a directed graph of hyperlinks.
+
   * An inlined output mode, like Jupyter: includes graphs and console output
     produced by executing the code.
+
   * Graphical code views:
+
     * Present a case statement as a state machine.
     * Present if/else statements as a truth table.
     * Visualize data structures.
     * More?
   * Interactive learning support: multiple choice, fill-in-th-blank, short/long
     answer, coding problem, etc. from Runestone or similar.
+
   * Autogenerated anchors for all anchors (headings, hyperlinks, etc.)
+
   * Hyperlinks to identifiers in code (use
     [ctags](https://github.com/universal-ctags/ctags)); perhaps auto-generate
     headings for these identifiers?
+
   * An API view; show only parts of the code that's
     exported/publicly-accessible.
+
   * Substitutions.
+
   * Files/anchors can be freely moved without breaking links. This requires 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
@@ -153,17 +160,50 @@ whitespace and optionally succeeded by whitespace. At least one whitespace
 character must separate the opening comment delimiter from the doc block text.
 Some examples in C:
 
-<pre>void foo(); // This is not a doc block, because these comments are preceded<br>void bar(); // by non-whitespace characters. Instead, they're a code block.<br>//This is not a doc block, because these inline comments lack<br>//whitespace after the opening comment delimiter //. They're also a code block.<br>/*This is not a doc block, because this block comment lacks<br>  whitespace after the opening comment delimiter /*. It's also a code block. */<br>/* This is not a doc block, because non-whitespace <br>   characters follow the closing comment delimiter. <br>   It's also a code block. */ void food();<br><br>// This is a doc block. It has no whitespace preceding the inline<br>// comment delimiters and one character of whitespace following it.<br>  // This is also a doc block. It has two characters of whitespace <br>  // preceding the comment delimiters and one character of whitespace following it.<br>/* This is a doc block. Because it's based on<br>   a block comment, a single comment can span multiple lines. */<br>/* This is also a doc block, even without the visual alignment<br>or a whitespace before the closing comment delimiter.*/<br>  /* This is a doc block<br>     as well. */</pre>
+```c
+void foo(); // This is not a doc block, because these comments are preceded
+void bar(); // by non-whitespace characters. Instead, they're a code block.
+//This is not a doc block, because these inline comments lack
+//whitespace after the opening comment delimiter //. They're also a code block.
+/*This is not a doc block, because this block comment lacks
+  whitespace after the opening comment delimiter /*. It's also a code block. */
+/* This is not a doc block, because non-whitespace
+   characters follow the closing comment delimiter.
+   It's also a code block. */ void food();
+
+// This is a doc block. It has no whitespace preceding the inline
+// comment delimiters and one character of whitespace following it.
+  // This is also a doc block. It has two characters of whitespace
+  // preceding the comment delimiters and one character of whitespace following it.
+/* This is a doc block. Because it's based on
+   a block comment, a single comment can span multiple lines. */
+/* This is also a doc block, even without the visual alignment
+or a whitespace before the closing comment delimiter.*/
+  /* This is a doc block
+     as well. */
+```
 
 Doc blocks are differentiated by their indent: the whitespace characters
 preceding the opening comment delimiter. Adjacent doc blocks with identical
 indents are combined into a single, larger doc block.
 
-<pre>// This is all one doc block, since only the preceding<br>//   whitespace (there is none) matters, not the amount of <br>// whitespace following the opening comment delimiters.<br>  // This is the beginning of a different doc<br>  // block, since the indent is different.<br>    // Here's a third doc block; inline and block comments<br>    /* combine as long as the whitespace preceding the comment<br>delimiters is identical. Whitespace inside the comment doesn't affect<br>       the classification. */<br>// These are two separate doc blocks,<br>void foo();<br>// since they are separated by a code block.</pre>
-
-### <a id="implementation-programming-language-support"></a>\[Programming language
+```c
+// This is all one doc block, since only the preceding
+//   whitespace (there is none) matters, not the amount of
+// whitespace following the opening comment delimiters.
+  // This is the beginning of a different doc
+  // block, since the indent is different.
+    // Here's a third doc block; inline and block comments
+    /* combine as long as the whitespace preceding the comment
+delimiters is identical. Whitespace inside the comment doesn't affect
+       the classification. */
+// These are two separate doc blocks,
+void foo();
+// since they are separated by a code block.
+```
+
+### <a id="implementation-programming-language-support"></a>\[Programming language support\](index.md#programming-language-support)
 
-support\](index.md#programming-language-support)
 
 Initial targets come from the Stack Overflow Developer Survey 2022's section on
 [programming, scripting, and markup languages](https://survey.stackoverflow.co/2022/#section-most-popular-technologies-programming-scripting-and-markup-languages)
