From 82cf29e251685de8ea6c14fff5d1b1b3d7001fe5 Mon Sep 17 00:00:00 2001 From: Lars Wirzenius Date: Sat, 13 Aug 2022 16:14:33 +0300 Subject: feat! drop support to act as a Pandoc filter When we change Subplot to take a YAML file instead of a Markdown file as input, it doesn't make sense to act as a Pandoc filter anymore: Pandoc doesn't understand our YAML file. In any case, I seem to have been the only user ever of that feature, so it won't really bother anyone else. Even so, we should treat this as a breaking change. "subplot docgen" still works as before. Sponsored-by: author --- src/bin/subplot-filter.rs | 16 ------------ src/bin/subplot.rs | 60 ++------------------------------------------ subplot.md | 64 ++++++++++++++++------------------------------- 3 files changed, 23 insertions(+), 117 deletions(-) delete mode 100644 src/bin/subplot-filter.rs diff --git a/src/bin/subplot-filter.rs b/src/bin/subplot-filter.rs deleted file mode 100644 index 6c01241..0000000 --- a/src/bin/subplot-filter.rs +++ /dev/null @@ -1,16 +0,0 @@ -use anyhow::Result; -use std::io::{self, Read, Write}; -use subplot::{Document, Style}; - -fn main() -> Result<()> { - let mut buffer = String::new(); - let mut stdin = io::stdin(); - stdin.read_to_string(&mut buffer)?; - let basedir = std::path::Path::new("."); - let style = Style::default(); - let mut doc = Document::from_json(&basedir, vec![], &buffer, style, None)?; - doc.typeset(); - let bytes = doc.ast()?.into_bytes(); - io::stdout().write_all(&bytes)?; - Ok(()) -} diff --git a/src/bin/subplot.rs b/src/bin/subplot.rs index 5e802b4..759b70b 100644 --- a/src/bin/subplot.rs +++ b/src/bin/subplot.rs @@ -13,8 +13,8 @@ use time::{format_description::FormatItem, macros::format_description, OffsetDat use clap::{CommandFactory, FromArgMatches, Parser}; use std::convert::TryFrom; use std::ffi::OsString; -use std::fs::{self, write, File}; -use std::io::{Read, Write}; +use std::fs::{self, write}; +use std::io::Write; use std::path::{Path, PathBuf}; use std::process::{self, Command}; use std::time::UNIX_EPOCH; @@ -53,7 +53,6 @@ impl Toplevel { #[derive(Debug, Parser)] enum Cmd { Extract(Extract), - Filter(Filter), Metadata(Metadata), Docgen(Docgen), Codegen(Codegen), @@ -65,7 +64,6 @@ impl Cmd { fn run(&self) -> Result<()> { match self { Cmd::Extract(e) => e.run(), - Cmd::Filter(f) => f.run(), Cmd::Metadata(m) => m.run(), Cmd::Docgen(d) => d.run(), Cmd::Codegen(c) => c.run(), @@ -76,7 +74,6 @@ impl Cmd { fn doc_path(&self) -> Option<&Path> { match self { Cmd::Extract(e) => e.doc_path(), - Cmd::Filter(f) => f.doc_path(), Cmd::Metadata(m) => m.doc_path(), Cmd::Docgen(d) => d.doc_path(), Cmd::Codegen(c) => c.doc_path(), @@ -193,59 +190,6 @@ impl Extract { } } -#[derive(Debug, Parser)] -/// Filter a pandoc JSON document. -/// -/// This filters a pandoc JSON document, applying Subplot's formatting rules and -/// image conversion support. -/// -/// If input/output filename is provided, this operates on STDIN/STDOUT. -struct Filter { - #[clap(name = "INPUT", long = "input", short = 'i', parse(from_os_str))] - /// Input file (uses STDIN if omitted) - input: Option, - - #[clap(name = "OUTPUT", long = "output", short = 'o', parse(from_os_str))] - /// Output file (uses STDOUT if omitted) - output: Option, - - #[clap(name = "BASE", long = "base", short = 'b', parse(from_os_str))] - /// Base directory (defaults to dir of input if given, or '.' if using STDIN) - base: Option, -} - -impl Filter { - fn doc_path(&self) -> Option<&Path> { - self.input.as_deref().and_then(Path::parent) - } - - fn run(&self) -> Result<()> { - let mut buffer = String::new(); - if let Some(filename) = &self.input { - File::open(filename)?.read_to_string(&mut buffer)?; - } else { - std::io::stdin().read_to_string(&mut buffer)?; - } - let basedir = if let Some(path) = &self.base { - path.as_path() - } else if let Some(path) = &self.input { - path.parent().unwrap_or_else(|| Path::new(".")) - } else { - Path::new(".") - }; - let style = Style::default(); - let mut doc = Document::from_json(basedir, vec![], &buffer, style, None)?; - doc.typeset(); - let bytes = doc.ast()?.into_bytes(); - if let Some(filename) = &self.output { - File::create(filename)?.write_all(&bytes)?; - } else { - std::io::stdout().write_all(&bytes)?; - } - Ok(()) - } -} - #[derive(Debug, Parser)] /// Extract metadata about a document /// diff --git a/subplot.md b/subplot.md index f99b326..ca791d5 100644 --- a/subplot.md +++ b/subplot.md @@ -138,7 +138,7 @@ Subplot actually consists mainly of two separate programs: **subplot docgen** for generating output documents, and **subplot codegen** for generating the test program. There are a couple of additional tools (**subplot metadata** for reporting meta data about a Subplot document, and -**subplot-filter** for doing the document generation as a Pandoc filter). +**subplot extract** for extracting embedded files from a subplot document. Thus a more detailed architecture view is shown below. @@ -3007,13 +3007,17 @@ and is not referenced as an external image. ~~~scenario given file pikchr.md and an installed subplot -when I run pandoc --filter subplot-filter pikchr.md -o pikchr.html +when I run subplot docgen pikchr.md -o pikchr.html then file pikchr.html matches regex /src="data:image/svg\+xml;base64,/ ~~~ The sample input file **pikchr.md**: ~~~~~~~~{#pikchr.md .file .markdown .numberLines} +--- +title: Pikchr test +... + This is an example markdown file that embeds a simple Pikchr diagram. ~~~pikchr @@ -3046,13 +3050,17 @@ HTML output, not referenced as an external image. given file dot.md and file b.yaml and an installed subplot -when I run pandoc --filter subplot-filter dot.md -o dot.html +when I run subplot docgen dot.md -o dot.html then file dot.html matches regex /src="data:image/svg\+xml;base64,/ ~~~ The sample input file **dot.md**: ~~~~~~~~{#dot.md .file .markdown .numberLines} +--- +title: Dot test +... + This is an example Markdown file, which embeds a diagram using dot markup. ~~~dot @@ -3088,13 +3096,17 @@ the HTML output, not referenced as an external image. given file plantuml.md and file b.yaml and an installed subplot -when I run pandoc --filter subplot-filter plantuml.md -o plantuml.html +when I run subplot docgen plantuml.md -o plantuml.html then file plantuml.html matches regex /src="data:image/svg\+xml;base64,/ ~~~ The sample input file **plantuml.md**: ~~~~~~~~{#plantuml.md .file .markdown .numberLines} +--- +title: Plantuml test +... + This is an example Markdown file, which embeds a diagram using PlantUML markup. @@ -3169,13 +3181,17 @@ HTML output, not referenced as an external image. given file roadmap.md and file b.yaml and an installed subplot -when I run pandoc --filter subplot-filter roadmap.md -o roadmap.html +when I run subplot docgen roadmap.md -o roadmap.html then file roadmap.html matches regex /src="data:image/svg\+xml;base64,/ ~~~ The sample input file **roadmap.md**: ~~~~~~~~{#roadmap.md .file .markdown .numberLines} +--- +title: Roadmap test +... + This is an example Markdown file, which embeds a roadmap. ~~~roadmap @@ -3270,44 +3286,6 @@ This content is foobarish ~~~~~~~~ -## Using as a Pandoc filter - -Subplot can be used as a Pandoc _filter_, which means Pandoc can allow -Subplot to modify the document while it is being converted or typeset. -This can useful in a variety of ways, such as when using Pandoc to -improve Markdown processing in the [ikiwiki][] blog engine. - -[ikiwiki]: http://ikiwiki.info/ - -The way filters work is that Pandoc parses the input document into an -abstract syntax tree, serializes that into JSON, gives that to the -filter (via the standard input), gets a modified abstract syntax tree -(again as JSON, via the filter's standard output). - -Subplot supports this via the **subplot-filter** executable. It is built -using the same internal logic as Subplot's docgen. The interface is -merely different to be usable as a Pandoc filter. - -This scenarios verifies that the filter works at all. More -importantly, it does that by feeding the filter a Markdown file that -does not have a YAML metadata block. For the ikiwiki use case, that's -what the input files are like. - -~~~scenario -given file justdata.md -and an installed subplot -when I run pandoc --filter subplot-filter justdata.md -o justdata.html -then file justdata.html matches regex /does not have a YAML metadata/ -~~~ - -The input file **justdata.md**: - -~~~~~~~~{#justdata.md .file .markdown .numberLines} -This is an example Markdown file. -It does not have a YAML metadata block. -~~~~~~~~ - - ## Extract embedded files `subplot extract` extracts embedded files from a subplot file. -- cgit v1.2.1