Cross link between grammar and railroad diagrams

When reviewing a production in the grammar, one often wants to quickly
find the corresponding railroad diagram, and when reviewing a railroad
diagram, one often wants to quickly find the corresponding production
in the grammar.

Let's make this easy by linking each production in the grammar to the
corresponding railroad diagram, and from the name of each railroad
diagram to the corresponding production in the grammar.

When clicking on a production in the grammar, we'll automatically
display the railroad diagrams if those are not already displayed.

Author: traviscross

mdbook-spec/src/grammar.rs

@@ -309,7 +309,18 @@ fn render_names(
     };
 
     let markdown_link_map = updated_link_map(render_markdown::markdown_id);
-    if let Err(e) = grammar.render_markdown(&names, &markdown_link_map, &mut output, for_summary) {
+    // Modify the link map so that it contains the exact destination needed to
+    // link to the railroad productions, and to accommodate the summary
+    // chapter.
+    let railroad_link_map = updated_link_map(render_railroad::railroad_id);
+
+    if let Err(e) = grammar.render_markdown(
+        &names,
+        &markdown_link_map,
+        &railroad_link_map,
+        &mut output,
+        for_summary,
+    ) {
         warn_or_err!(
             diag,
             "grammar failed in chapter {:?}: {e}",
@@ -319,21 +330,23 @@ fn render_names(
 
     output.push_str(
         "\n\
-         <button class=\"grammar-toggle\" type=\"button\" \
-            title=\"Toggle grammar display\" \
-            onclick=\"toggle_grammar()\">\
+         <button class=\"grammar-toggle-railroad\" type=\"button\" \
+            title=\"Toggle railroad display\" \
+            onclick=\"toggle_railroad()\">\
             Show Railroad\
          </button>\n\
          </div>\n\
          <div class=\"grammar-railroad grammar-hidden\">\n\
          \n",
     );
 
-    // Modify the link map so that it contains the exact destination needed to
-    // link to the railroad productions, and to accommodate the summary
-    // chapter.
-    let railroad_link_map = updated_link_map(render_railroad::railroad_id);
-    if let Err(e) = grammar.render_railroad(&names, &railroad_link_map, &mut output, for_summary) {
+    if let Err(e) = grammar.render_railroad(
+        &names,
+        &railroad_link_map,
+        &markdown_link_map,
+        &mut output,
+        for_summary,
+    ) {
         warn_or_err!(
             diag,
             "grammar failed in chapter {:?}: {e}",

mdbook-spec/src/grammar/render_markdown.rs

@@ -14,16 +14,16 @@ impl Grammar {
         &self,
         names: &[&str],
         link_map: &HashMap<String, String>,
+        rr_link_map: &HashMap<String, String>,
         output: &mut String,
         for_summary: bool,
     ) -> anyhow::Result<()> {
         let mut iter = names.into_iter().peekable();
         while let Some(name) = iter.next() {
-            let prod = match self.productions.get(*name) {
-                Some(p) => p,
-                None => bail!("could not find grammar production named `{name}`"),
+            let Some(prod) = self.productions.get(*name) else {
+                bail!("could not find grammar production named `{name}`");
             };
-            prod.render_markdown(link_map, output, for_summary);
+            prod.render_markdown(link_map, rr_link_map, output, for_summary);
             if iter.peek().is_some() {
                 output.push_str("\n");
             }
@@ -45,14 +45,23 @@ impl Production {
     fn render_markdown(
         &self,
         link_map: &HashMap<String, String>,
+        rr_link_map: &HashMap<String, String>,
         output: &mut String,
         for_summary: bool,
     ) {
+        let dest = rr_link_map
+            .get(&self.name)
+            .map(|path| path.to_string())
+            .unwrap_or_else(|| format!("missing"));
         write!(
             output,
-            "<span class=\"grammar-text grammar-production\" id=\"{id}\">{name}</span> → ",
+            "<span class=\"grammar-text grammar-production\" id=\"{id}\" \
+               onclick=\"show_railroad()\"\
+             >\
+               [{name}]({dest})\
+             </span> → ",
             id = markdown_id(&self.name, for_summary),
-            name = self.name
+            name = self.name,
         )
         .unwrap();
         self.expression.render_markdown(link_map, output);

mdbook-spec/src/grammar/render_railroad.rs

@@ -14,6 +14,7 @@ impl Grammar {
         &self,
         names: &[&str],
         link_map: &HashMap<String, String>,
+        md_link_map: &HashMap<String, String>,
         output: &mut String,
         for_summary: bool,
     ) -> anyhow::Result<()> {
@@ -22,7 +23,7 @@ impl Grammar {
                 Some(p) => p,
                 None => bail!("could not find grammar production named `{name}`"),
             };
-            prod.render_railroad(link_map, output, for_summary);
+            prod.render_railroad(link_map, md_link_map, output, for_summary);
         }
         Ok(())
     }
@@ -41,16 +42,17 @@ impl Production {
     fn render_railroad(
         &self,
         link_map: &HashMap<String, String>,
+        md_link_map: &HashMap<String, String>,
         output: &mut String,
         for_summary: bool,
     ) {
-        let mut dia = self.make_diagram(false, link_map);
+        let mut dia = self.make_diagram(false, link_map, md_link_map);
         // If the diagram is very wide, try stacking it to reduce the width.
         // This 900 is somewhat arbitrary based on looking at productions that
         // looked too squished. If your diagram is still too squished,
         // consider adding more rules to shorten it.
         if dia.width() > 900 {
-            dia = self.make_diagram(true, link_map);
+            dia = self.make_diagram(true, link_map, md_link_map);
         }
         writeln!(
             output,
@@ -67,12 +69,17 @@ impl Production {
         &self,
         stack: bool,
         link_map: &HashMap<String, String>,
+        md_link_map: &HashMap<String, String>,
     ) -> Diagram<Box<dyn Node>> {
         let n = self.expression.render_railroad(stack, link_map, false);
+        let dest = md_link_map
+            .get(&self.name)
+            .map(|path| path.to_string())
+            .unwrap_or_else(|| format!("missing"));
         let seq: Sequence<Box<dyn Node>> =
             Sequence::new(vec![Box::new(SimpleStart), n.unwrap(), Box::new(SimpleEnd)]);
         let vert = VerticalGrid::<Box<dyn Node>>::new(vec![
-            Box::new(Comment::new(self.name.clone())),
+            Box::new(Link::new(Comment::new(self.name.clone()), dest)),
             Box::new(seq),
         ]);
 

theme/reference.css

@@ -626,7 +626,7 @@ main > .rule {
 }
 
 /* The toggle button. */
-.grammar-toggle {
+.grammar-toggle-railroad {
     width: 120px;
     padding: 5px 0px;
     border-radius: 5px;

theme/reference.js

@@ -23,12 +23,17 @@ function spec_toggle_tests(rule_id) {
     }
 }
 
-function toggle_grammar() {
+function toggle_railroad() {
     const grammarRailroad = get_railroad();
     set_railroad(!grammarRailroad);
     update_railroad();
 }
 
+function show_railroad() {
+    set_railroad(true);
+    update_railroad();
+}
+
 function get_railroad() {
     let grammarRailroad = null;
     try {
@@ -58,7 +63,7 @@ function update_railroad() {
             element.classList.add('grammar-hidden');
         }
     });
-    const buttons = document.querySelectorAll('.grammar-toggle');
+    const buttons = document.querySelectorAll('.grammar-toggle-railroad');
     buttons.forEach(button => {
         if (grammarRailroad) {
             button.innerText = "Hide Railroad";