Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

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

Pikchr Command-Line Tool
https://github.com/zenomt/pikchr-cmd

composable markdown pikchr tool

Last synced: 4 months ago
JSON representation

Pikchr Command-Line Tool

Awesome Lists containing this project

README 

        
Pikchr Command-Line Tool

========================

[This preprocessor tool][repo] reads text from the standard input, replacing

suitably-delimited [Pikchr][] (a [PIC][]-like diagram language) diagram

descriptions with inline [Scalable Vector Graphics (SVG)][SVG], and writes

to the standard output.  It’s [intended to be composed][Unix] with your

favorite Markdown processor, but can be used standalone or with other markup

languages or workflows too.



This tool uses the [C reference implementation of Pikchr by Richard Hipp][DRH]

which is included here for convenience (as permitted by its generous license).






Markdown+Pikchr

Source



pikchr

Preprocessor

(main.c)



Markdown+SVG

Intermediate



Any Markdown

Formatter



HTML+SVG

Output



 C API



Pikchr

Formatter

(pikchr.c)






    ``` pikchr @usage requote delimiters x-current-color

    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 height Tool.height

    arrow same "HTML+SVG" "Output"

    arrow <-> down from Tool.south " C API" ljust

    box same "Pikchr" "Formatter" "(pikchr.c)" mono fit

    ```



GitHub doesn’t allow inline SVGs, so here’s the above diagram as an external

image reference (see Example 3 below):






Example 1: Pipeline



    $ pikchr < file.md | Markdown.pl > file.html



Example 2: Intermediate file



    $ pikchr < README.md.in > README.md

    $ Markdown.pl < README.md > README.html



Example 3: Compile the diagram in `README.md.in` that is tagged with modifier

“`@usage`” to a separate SVG file called `usage.svg`



    $ pikchr -q -b -N @usage < README.md.in > usage.svg



Delimiters

----------

A Pikchr diagram starts with a line beginning with any of the following strings

_without indentation_:



* Three or more consecutive `GRAVE ACCENT` backtick (`)

  characters, optional whitespace, the characters `pikchr`, and

  whitespace or end-of-line; for example

   - ```` pikchr

* Three or more consecutive `TILDE` (`~`) characters, optional whitespace,

  the characters `pikchr`, and whitespace or end-of-line; for example

   - `~~~pikchr`

* The three characters `.PS` and whitespace or end-of-line (that is, the

  traditional [PIC][] start delimiter)

   - `.PS`



and ends with the next line that is any of the following strings

_without indentation_ (or the end of the file):



* Three or more consecutive backtick characters and optional whitespace; for example

   - ```

* Three or more consecutive `TILDE` characters and optional whitespace; for example

   - `~~~~`

* The three characters `.PE` and optional whitespace (that is, the traditional

  [PIC][] end delimiter)

   - `.PE`



Anything not between a pair of start and end delimiters is copied to the

standard output unchanged.



Note that generic Markdown [fenced code blocks][fenced] can begin with three

or more consecutive `TILDE` (`~`) or backtick (`) characters

optionally indented by up to three spaces, and continue to a fence of the

same type (tilde or backtick), optionally indented by up to three spaces, and

_at least as long_. For simplicity, when looking for Pikchr diagrams, this

tool doesn’t require the end delimiter to be of the same type or to be at

least as long as the start delimiter. This tool doesn’t recognize indented

start and end delimiters in order to easily accommodate displaying Pikchr

code itself by using an indented fenced code block.



### Start Delimiter Modifiers



Any number of whitespace-delimited modifier strings can follow the start

delimiter prefix on the same line. Modifiers can change the behavior of the

Pikchr formatter for just that diagram. Unrecognized modifiers are ignored,

but can be matched by the `-N` command-line option (use `-h` to see all of

the available options). The following modifiers are recognized:



* `svg-only`: Output the `` tag without wrapping it in a `
`. By default

  (unless command-line option `-b` is given) each diagram is enclosed in a

  `
` styled with `max-width` set to the diagram’s width, so it won’t

  expand to the width of the page (which is usually not desired).

* `requote`: Output the Pikchr source of this diagram in an indented code block

  after the compiled diagram.

* `delimiters`: If requoting, include the start and end delimiter lines. The

  default is to not include the start and end delimiters in a requote.

* `x-current-color`: Experimental, output CSS `currentColor` instead of

  `rgb(0,0,0)` for numeric color value 0 (black, the default marking

  color in diagrams). The diagram will be painted in the SVG element’s

  inherited foreground color instead of the default black, which may enable

  naturally adapting to different page themes or dark mode. Note that only

  color value 0 is affected. To force black, set the color to a positive

  number less than 0.5.



Building

--------



    $ git clone https://github.com/zenomt/pikchr-cmd

    $ cd pikchr-cmd

    $ make all

    $ ./pikchr -h



Command Line Options

--------------------

The following command line options are recognized:



* -c aClass  

  Add attribute class="aClass" to all generated `` tags.

* -a arbitrary-attributes  

  Add _arbitrary-attributes_ string to all generated `` tags.

* `-b`  

  “Bare SVG mode”: don’t enclose generated SVG elements in a `
`. By default a `
` wrapper is used to apply a `max-width` style to the diagram to keep it from expanding to the full window width. Use this option to manually style the diagram’s displayed size with your own DIV or when generating a standalone SVG file. This can also be enabled per-diagram with the `svg-only` modifier.

* `-p`  

  Generate plaintext error messages. The default is to output HTML-formatted errors.

* `-d`  

  Enable “dark mode” in the Pikchr formatter.

* `-q`  

  “Quiet mode”: don’t copy non-diagram input to the output. Use this option when generating a standalone SVG file.

* `-Q`  

  Remove all Pikchr diagrams from the output.

* -n num  

  Only translate diagram number _num_ to SVG. Diagrams are numbered starting from 1.  This is usually used along with `-q` and `-b` when generating a standalone SVG file. Note that this method is brittle, consider using `-N` instead.

* -N mod-string  

  Only translate diagrams that have _mod-string_ as one of their [start delimiter modifiers](#start-delimiter-modifiers). This is usually used along with `-q` and `-b` when generating a standalone SVG file (in which case _mod-string_ should be unique).

* `-h`  

  Show the help message describing these options and quit.



  [repo]: https://github.com/zenomt/pikchr-cmd

  [SVG]: https://www.w3.org/Graphics/SVG/

  [DRH]: https://github.com/drhsqlite/pikchr

  [Pikchr]: https://pikchr.org/

  [PIC]: https://en.wikipedia.org/wiki/PIC_(markup_language)

  [fenced]: https://spec.commonmark.org/0.30/#fenced-code-blocks

  [Unix]: https://en.wikipedia.org/wiki/Unix_philosophy