Merge pull request #1 from Licenser/docgen

Use markdown images by default with switchable alternative back to html `img` tags
darach · May 16, 2022 · b5207e8 · b5207e8
2 parents a89b0c9 + 98bc1db
commit b5207e8
Show file tree

Hide file tree

Showing 5 changed files with 55 additions and 9 deletions.
diff --git a/lalrpop-docgen/examples/README.md b/lalrpop-docgen/examples/README.md
@@ -87,3 +87,18 @@ $ npm start
 
 Then browse over to a [docusaurus](http://localhost:3000) Site
 
+## Notes
+
+If the target environment for your markdown renders the SVG images incorrectly
+and shows scaling issues of the SVG railroad diagrams, then changing the code
+generation to use HTML `img` tags instead of markdown image tags may be a quick
+fix.
+
+Using our example above, we add a flag to switch to HTML img tags:
+
+
+```shell
+lalrpop-docgen --railroad-mode img -mp docs/prolog -me docs/epilog  -gc Deploy,Query,Script ~/code/oss/tremor-rs
+```
+
+
diff --git a/lalrpop-docgen/src/api.rs b/lalrpop-docgen/src/api.rs
@@ -99,7 +99,13 @@ impl Configuration {
         self
     }
 
-    /// Optional url prefix for SVG img reference HTML tags
+    /// Optional url style for svg reference 
+    pub fn set_railroad_mode(&mut self, mode: String) -> &mut Configuration {
+        self.session.railroad_mode= mode;
+        self
+    }
+
+    /// Optional url prefix for svg reference
     pub fn set_railroad_prefix(&mut self, prefix: String) -> &mut Configuration {
         self.session.railroad_prefix = prefix;
         self

diff --git a/lalrpop-docgen/src/main.rs b/lalrpop-docgen/src/main.rs
@@ -33,6 +33,7 @@ Options:
     -e,   --ebnf            Generate equivalent EBNF for input grammar(s).
     -r,   --railroad        Generate railroad diagrams for input grammar(s).
     -rc,  --railroad-css    Provide a custom CSS stylesheet for railroad diagrams.
+    -rm,  --railroad-mode   Style for SVG links - can be one of `img`, `generic`
     -rp,  --railroad-prefix Prefix for generated SVG resource file img src references.
     -m,   --markdown        Generate markdown files for input grammar(s).
                             Markdown enables EBNF and Railroad generation.
@@ -53,6 +54,7 @@ struct Args {
     flag_ebnf: bool,
     flag_railroad: bool,
     flag_railroad_css: Option<PathBuf>,
+    flag_railroad_mode: Option<String>,
     flag_railroad_prefix: Option<String>,
     flag_markdown: bool,
     flag_markdown_prolog: Option<PathBuf>,
@@ -95,6 +97,7 @@ fn parse_args(mut args: Arguments) -> Result<Args, Box<dyn std::error::Error>> {
         flag_ebnf: args.contains(["-e", "--ebnf"]),
         flag_railroad: args.contains(["-r", "--railroad"]),
         flag_railroad_css: args.opt_value_from_fn(["-rc", "--railroad-css"], PathBuf::from_str)?,
+        flag_railroad_mode: args.opt_value_from_str(["-rp", "--railroad-mode"])?,
         flag_railroad_prefix: args.opt_value_from_str(["-rp", "--railroad-prefix"])?,
         flag_markdown: args.contains(["-m", "--markdown"]),
         flag_markdown_prolog: args
@@ -188,6 +191,10 @@ fn main() -> Result<(), Box<dyn Error>> {
         config.set_railroad_css(railroad_css);
     }
 
+    if let Some(ref railroad_mode) = args.flag_railroad_mode {
+        config.set_railroad_mode(railroad_mode.to_string());
+    }
+
     if let Some(ref railroad_prefix) = args.flag_railroad_prefix {
         config.set_railroad_prefix(railroad_prefix.to_string());
     }

diff --git a/lalrpop-docgen/src/railroad.rs b/lalrpop-docgen/src/railroad.rs
@@ -214,6 +214,27 @@ impl LalrpopToRailroad {
         false
     }
 
+    fn svg_to_ref(&self, name: &str, width: i64, height: i64) -> String {
+        match self.session.railroad_mode.as_str() {
+            "img" =>
+                format!(
+                    r#"<img src="{}svg/{}.svg" alt="{}" width="{}" height="{}"/>"#,
+                    self.session.railroad_prefix,
+                    name.to_ascii_lowercase(),
+                    name.to_ascii_lowercase(),
+                    width,
+                    height,
+                ),
+           _otherwise =>
+                format!(
+                    "![{}]({}svg/{}.svg)",
+                    name.to_string(),
+                    self.session.railroad_prefix,
+                    name.to_ascii_lowercase(),
+                ),
+        }
+    }
+
     fn to_diagram(&mut self, rule: &NonterminalData) -> (String, (String, String)) {
         let name = rule.name.to_string();
         let mut alts: Vec<Box<dyn RailroadNode>> = vec![];
@@ -244,14 +265,7 @@ impl LalrpopToRailroad {
                 .text(&self.css),
         );
 
-        let diagram_ref = format!(
-            r#"<img src="{}svg/{}.svg" alt="{}" width="{}" height="{}"/>"#,
-            self.session.railroad_prefix,
-            name.to_ascii_lowercase(),
-            name,
-            dia.width(),
-            dia.height()
-        );
+        let diagram_ref = self.svg_to_ref(&name, dia.width(), dia.height());
         let diagram_svg = dia.to_string();
         (name, (diagram_ref, diagram_svg))
     }

diff --git a/lalrpop-docgen/src/session.rs b/lalrpop-docgen/src/session.rs
@@ -32,6 +32,9 @@ pub struct Session {
     /// Optional custom CSS for railroad diagrams
     pub railroad_css: Option<path::PathBuf>,
 
+    /// Optional SVG img reference style 
+    pub railroad_mode: String,
+
     /// Optional SVG img reference prefix
     pub railroad_prefix: String,
 
@@ -63,6 +66,7 @@ impl Session {
             epilog_dir: None,
             epilog_not_found_is_err: true,
             railroad_css: None,
+            railroad_mode: "".to_string(),
             railroad_prefix: "".to_string(),
             grammar_cuts: None,
             emit_ebnf: true,