Add doc-splitter to the helper toolbox

This helper tool uses BBEdit's Preview Windows to preview Markdown syntax in your rustdocs. It has the following components:

- A binary Preview Filter
- The source for the filter, written in Rust, as a binary in the toolbox
- The Preview CSS that uses the classes outputted by the filter

Contents/Preview CSS/Rust Documentation.css

@@ -0,0 +1,72 @@
+/*
+ * These styles are a poor imitation of the standard rustdoc styles. They should
+ * contain just enough to look more-or-less like rustdoc’s output, but large
+ * parts of the official stylesheet aren’t relevant, and I’m not even sure if
+ * I’m allowed to distribute its webfonts! So this will have to do.
+ */
+
+body {
+    padding: 0;
+    margin: 0;
+    font: 16px/1.4 Georgia;  /* Georgia is like Source Serif Pro, right? */
+}
+
+.docs pre, .docs code, .docs span {
+    font-family: Monaco;  /* Monaco is like Source Code Pro, right? */
+    font-size: 12px;
+}
+
+.docs {
+    padding: 20px 20px 10px 20px;
+    color: #333;
+}
+
+.docs.module {
+    background-color: #F7F3F7;
+    border-bottom: 1px solid #D8CAD8;
+}
+
+/*
+ * We want to keep the docs above a piece of code close to that code in the
+ * preview, as docs usually refer to the code below them.
+ */
+
+.code {
+    border-top: 1px solid #BDC3C7;
+    border-bottom: 1px solid #BDC3C7;
+    background-color: #ECF0F1;
+
+    font-size: 10px;
+    font-family: Monaco;
+    color: #666;
+
+    padding: 10px 20px;
+    margin: 0em;
+}
+
+p:last-child {
+    padding: 0;
+    margin: 0;
+}
+
+/*
+ * The headings have borders below them, just like rustdoc!
+ */
+
+h2 {
+    font-size: 1.4em;
+}
+
+h3 {
+    font-size: 1.3em;
+}
+
+h1, h2, h3 {
+    font-family: "Helvetica Neue";  /* Helvetica is like Fira Sans, right? */
+    border-bottom: 1px solid #ddd;
+
+    color: #000;
+    font-weight: 500;
+    margin: 20px 0 15px 0;
+    padding-bottom: 6px;
+}

Makefile

@@ -1,7 +1,7 @@
 all:
 	xcodebuild -configuration Release
 	cp -r build/Release/Rust.bblm Contents/"Language Modules"
-	cd helper-tool; cargo build --release; cp target/release/impl-generator ../Contents/Resources/impl-generator
+	cd helper-tool; cargo build --release; cp target/release/impl-generator ../Contents/Resources/impl-generator; cp target/release/doc-splitter ../Contents/"Preview Filters"/"Rust Markdown"
 
 clean:
 	rm -r build; cd helper-tool; cargo clean

helper-tool/Cargo.lock

@@ -2,9 +2,19 @@
 name = "rust-bbedit-helpers"
 version = "0.1.0"
 dependencies = [
+ "hoedown 3.0.3 (registry+https://github.com/rust-lang/crates.io-index)",
  "regex 0.1.41 (registry+https://github.com/rust-lang/crates.io-index)",
 ]
 
+[[package]]
+name = "advapi32-sys"
+version = "0.1.2"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "winapi 0.2.5 (registry+https://github.com/rust-lang/crates.io-index)",
+ "winapi-build 0.1.1 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
 [[package]]
 name = "aho-corasick"
 version = "0.3.0"
@@ -13,6 +23,30 @@ dependencies = [
  "memchr 0.1.3 (registry+https://github.com/rust-lang/crates.io-index)",
 ]
 
+[[package]]
+name = "bitflags"
+version = "0.3.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+
+[[package]]
+name = "gcc"
+version = "0.3.20"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "advapi32-sys 0.1.2 (registry+https://github.com/rust-lang/crates.io-index)",
+ "winapi 0.2.5 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
+[[package]]
+name = "hoedown"
+version = "3.0.3"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+dependencies = [
+ "bitflags 0.3.3 (registry+https://github.com/rust-lang/crates.io-index)",
+ "gcc 0.3.20 (registry+https://github.com/rust-lang/crates.io-index)",
+ "libc 0.1.8 (registry+https://github.com/rust-lang/crates.io-index)",
+]
+
 [[package]]
 name = "libc"
 version = "0.1.8"
@@ -41,3 +75,13 @@ name = "regex-syntax"
 version = "0.2.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 
+[[package]]
+name = "winapi"
+version = "0.2.5"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+
+[[package]]
+name = "winapi-build"
+version = "0.1.1"
+source = "registry+https://github.com/rust-lang/crates.io-index"
+

helper-tool/Cargo.toml

@@ -3,10 +3,16 @@ name = "rust-bbedit-helpers"
 version = "0.1.0"
 authors = ["Ben S <ogham@bsago.me>"]
 
+[[bin]]
+name = "doc-splitter"
+path = "src/doc-splitter.rs"
+test = true
+
 [[bin]]
 name = "impl-generator"
 path = "src/impl-generator.rs"
 test = true
 
 [dependencies]
-regex = "*"
+regex = "0.1"
+hoedown = "3.0"

helper-tool/src/doc-splitter.rs

@@ -0,0 +1,87 @@
+extern crate hoedown;
+use hoedown::{Markdown, Html, Render, Extension};
+use hoedown::renderer::html::{self, HARD_WRAP};
+
+use std::io::{self, BufRead};
+
+
+fn main() {
+    let extensions: Extension =
+        hoedown::AUTOLINK |
+        hoedown::FENCED_CODE |
+        hoedown::FOOTNOTES |
+        hoedown::NO_INTRA_EMPHASIS |
+        hoedown::STRIKETHROUGH |
+        hoedown::SUPERSCRIPT |
+        hoedown::TABLES;
+
+    let stdin = io::stdin();
+    let mut buffer = String::new();
+    let mut was_doc = false;
+    let mut was_module_comment = false;
+
+    let mut flags = html::Flags::all();
+    flags.remove(HARD_WRAP);
+
+    let print_markdown = |buf: &str, mod_comment: bool| {
+        let doc = Markdown::new(buf.trim_right()).extensions(extensions);
+        let mut html = Html::new(flags, 0);
+
+        let classes = match mod_comment {
+            true  => "docs module",
+            false => "docs",
+        };
+
+        println!("<div class=\"{}\">{}</div>", classes, html.render(&doc).to_str().unwrap());
+    };
+
+    let print_code = |buf: &str| {
+        println!("<pre class=\"code\">{}</pre>", buf.trim_right().replace("<", "&lt;").replace(">", "&gt;"));
+    };
+
+    for line in stdin.lock().lines() {
+        let line = line.unwrap();
+
+        let mut slice = &line[..];
+        let mut is_doc = false;
+
+        if let Some(first_char) = line.find(|c: char| !c.is_whitespace()) {
+            let line = &line[first_char ..];
+            if line.starts_with("//! ") || line.starts_with("/// ") {
+                slice = &slice[4 + first_char ..];
+                is_doc = true;
+            }
+            else if line.starts_with("//!") || line.starts_with("///") {
+                slice = &slice[3 + first_char ..];
+                is_doc = true;
+            }
+
+        }
+
+        if !buffer.trim().is_empty() {
+            if is_doc && !was_doc {
+                print_code(&*buffer);
+                buffer.clear();
+            }
+            else if !is_doc && was_doc {
+                print_markdown(&*buffer, was_module_comment);
+                buffer.clear();
+            }
+        }
+
+        buffer.push_str(slice);
+        buffer.push('\n');
+
+        was_doc = is_doc;
+        was_module_comment = line.starts_with("//!");
+    }
+
+    if !was_doc {
+        print_code(&*buffer);
+        buffer.clear();
+    }
+    else {
+        print_markdown(&*buffer, false);
+        buffer.clear();
+    }
+}