Pikchr

Unixy Pikchr command-line preprocessor for any Markdown formatter (C)
Login
Hierarchical

Unixy Pikchr command-line preprocessor for any Markdown formatter (C)

(1) By Michael Thornburgh (zenomt) on 2023-08-06 22:10:51 [source]

hello friends. i only recently discovered Pikchr after long thinking something like it needed to exist (and it turns out it does!). i particularly appreciate how easy it is to integrate into other tools.

as near as i can tell, however, none of the existing integrations or tools take the form of a pic(1)-like Unix filter/preprocessor that reads (for example) Markdown+Pikchr and writes Markdown+SVG for further processing by insert your favorite Markdown formatter. so i wrote one. :) it's super straightforward and nearly (but not entirely) trivial, so i'm surprised that one doesn't exist already. if i missed one out in the wild, please correct me.

https://github.com/zenomt/pikchr-cmd

in the spirit of pic(1), it searches its standard input for Pikchr start & end delimiters, transforming each delimited diagram into an inline SVG (inside a <div> to style the max-width), and copies everything else verbatim to the standard output. for simplicity, delimiters must be at the beginning of a line (not indented as allowed by Markdown) and have exactly three tildes or backticks. PIC delimiters (.PS and .PE) are also recognized.

it's just one C file to compile with pikchr.c, and requires POSIX regular expressions (that is, regcomp(3) and regexec(3)) which should already be in your standard library.

Markdown+Pikchr Source pikchr Preprocessor (main.c) Markdown+SVG Intermediate Any Markdown Formatter HTML+SVG Output C API Pikchr Formatter (pikchr.c) 
arrow right 225% "Markdown+Pikchr" "Source"
Tool: box rad 5px "pikchr" mono "Preprocessor" "(main.c)" mono fit
arrow same "Markdown+SVG" "Intermediate"
box same "Any Markdown" "Formatter" fit
arrow same "HTML+SVG" "Output"
arrow <-> down from Tool.s; "C API" ljust at 4pt right of last arrow
box with .n at last arrow.s same "Pikchr" "Formatter" "(pikchr.c)" mono fit

sadly i discovered that GitHub suppresses inline SVGs when browsing a repo's Markdown files, though they appear properly in GitHub Pages.

-michael thornburgh

(2) By Stephan Beal (stephan) on 2023-08-07 00:50:06 in reply to 1 [link] [source]

https://github.com/zenomt/pikchr-cmd

Just FYI: a link to your project was added to the "external projects" list on the home page. If its description is wrong, please post a proposed replacement.

(3) By Michael Thornburgh (zenomt) on 2023-08-07 00:55:27 in reply to 2 [link] [source]

awesome, thanks! i hope folks find it useful.

(4) By Michael Thornburgh (zenomt) on 2023-08-09 16:04:31 in reply to 2 [link] [source]

If its description is wrong, please post a proposed replacement.

while the description is technically correct, i think it doesn't quite convey what i think is the most important aspect for a one-liner elevator pitch. instead how about:

pikchr-cmd, by Michael Thornburgh, is a command-line Pikchr preprocessor tool for use with any Markdown formatter.

(adjust capitalization as you like for Pikchr and Markdown :) )

(5) By Stephan Beal (stephan) on 2023-08-09 16:38:48 in reply to 4 [link] [source]

... is a command-line Pikchr preprocessor tool for use with any Markdown formatter.

It's changed now.

(adjust capitalization as you like for Pikchr and Markdown :) )

Apparently the project's standard is to capitalize both. Good catch.

(6) By Michael Thornburgh (zenomt) on 2023-08-12 23:15:43 in reply to 1 [link] [source]

i've made a few additions to improve the tool's utility:

  • start and end delimiters now consist of 3 or more consecutive tildes or backticks (though delimiters still need to start at the beginning of a line, so the tool doesn't need to implement a complete Markdown parser and so it's possible to include delimited Pikchr source in a code block)
  • "svg-only" (no enclosing DIV with max-width) can be selected per-diagram with a start-delimiter modifier
  • the "requote" modifier signals to include the original Pikchr source in an indented code block in the output (with or without the start and end delimiters according to the "delimiters" modifier) after the compiled SVG
  • arbitrary other modifiers can be added in the start delimiter to be used as names/tags, and can be matched with the -N command-line option for extracting and compiling a specific diagram from the input document; this is useful for the GitHub case where an SVG can only be used in an external IMG reference but you'd still like the Pikchr source in the original document for plain-text consumption