Readme

Introduction

WARNING: This package is in early development! ob-penrose provides Org-Babel integration for Penrose. My goal with ob-penrose is to create a convenient and expressive interface for people interested in writing diagram-dense material, especially in the literate programming style.

Penrose is a platform that enables people to create beautiful diagrams just by typing notation in plain text. The goal is to make it easy for non-experts to create and explore high-quality diagrams and provide deeper insight into challenging technical concepts. We aim to democratize the process of creating visual intuition.

Installation

This package is not yet on MELPA.

Steps

Install Penrose’s CLI roger. See Penrose documentation.

Shell

npm install -g @penrose/roger

Install ob-penrose. Steps for Doom Emacs:

In package.el

(package! ob-penrose :recipe (:host github :repo "weavermarquez/ob-penrose" :files ("ob-penrose.el")))

In config.el

(use-package! ob-penrose :after org :defer t)

You’re now ready to use ob-penrose!

Usage

Using the files from Penrose’s Set Theory / Venn Diagram example:

create venn.domain and venn.style in or under your current working directory.
- In this repo, the =demo= folder has these files already.

In an Org Mode file, create a code block like so, then press Ctrl-C to execute the block.

#+begin_src penrose :file owo.svg :domain demo/venn.domain :style demo/venn.style
Set A, B, C, D, E, F, G

IsSubset(B, A)
IsSubset(C, A)
IsSubset(D, B)
IsSubset(E, B)
IsSubset(F, C)
IsSubset(G, C)

Not(Intersecting(E, D))
Not(Intersecting(F, G))
Not(Intersecting(B, C))

AutoLabel All
#+end_src

Project Roadmap

Hotfixes

Add Documentation for Non-Doom Emacs

Features for v0.2 / v0.3

Draw Inspiration from
- org-download
- ob-plantuml
Variables for automatic SVG size / resizing inside org buffer
Option to transform to PNG
Integrate penrose emacs modes for writing.
Integrate with org-special-blocks-extra?
delete edebug info in Commentary
define file extensions in FileExts
Identify how org variables might be used with Penrose

Hopeful Features:

Users can intersperse pieces of Substance, Style, and Domain code.
- When users execute on a source block, they have the option of either drawing from the entire set of blocks within a scope or only from blocks defined above.
- A scope of blocks can span multiple files.
- A scope of blocks can have complex dependency relations, esp. for inheritance.
- Potential mechanisms:
  - INCLUDE in Org Key Words (per buffer or per subtree); :session; noweb; named references to source blocks; emacs lisp data representations
Users can create “small multiple” diagrams (i.e., create a number of diagrams with different variations)
- roger trios has a potential synergy with data features (e.g. Table variables)
Users can invoke built-in, general-purpose Domains and Styles instead of providing their own files.
- Defined through Emacs Lisp in ob-penrose?
Org Export (HTML, LaTeX) are adjusted to be appropriate for the backend.
- HTML could invoke the JS libraries provided by Penrose
- LaTeX uses the roger flag for TeX svgs.
Fill out FSF copyright assignment to add to core org-babel https://orgmode.org/request-assign-future.txt

Other Notes

For local development… if I’m not using doom package!, then:
- eval buffer
- elisp:(add-to-list ‘org-babel-load-languages ‘(penrose . t)) to register to org-babel

Some complementary packages on the way

ob-clingo / ob-asp for Answer Set Programming
penrose-mode …?

sebeaumont/ob-penrose