{"id":15381019,"url":"https://github.com/tani/papyrus","last_synced_at":"2025-08-03T21:38:54.693Z","repository":{"id":97698908,"uuid":"92268969","full_name":"tani/papyrus","owner":"tani","description":"A Literate Programming Tool: Common Lisp + Markdown / Org mode / POD","archived":false,"fork":false,"pushed_at":"2025-03-03T05:54:58.000Z","size":187,"stargazers_count":50,"open_issues_count":1,"forks_count":3,"subscribers_count":5,"default_branch":"main","last_synced_at":"2025-04-07T22:11:47.138Z","etag":null,"topics":["common-lisp","literate-programming","markdown","org-mode"],"latest_commit_sha":null,"homepage":"","language":"Nix","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/tani.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null},"funding":{"github":"tani"}},"created_at":"2017-05-24T08:29:31.000Z","updated_at":"2025-03-04T12:12:32.000Z","dependencies_parsed_at":"2024-05-29T18:37:09.186Z","dependency_job_id":"3232ed7a-1441-48fc-8ec2-c769f0ba848f","html_url":"https://github.com/tani/papyrus","commit_stats":{"total_commits":81,"total_committers":2,"mean_commits":40.5,"dds":"0.24691358024691357","last_synced_commit":"145c63d50ff13ce89a8963d6d1f7cef655415f54"},"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/tani/papyrus","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tani%2Fpapyrus","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tani%2Fpapyrus/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tani%2Fpapyrus/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tani%2Fpapyrus/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/tani","download_url":"https://codeload.github.com/tani/papyrus/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/tani%2Fpapyrus/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":263472279,"owners_count":23471812,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["common-lisp","literate-programming","markdown","org-mode"],"created_at":"2024-10-01T14:25:23.314Z","updated_at":"2025-07-04T08:05:16.518Z","avatar_url":"https://github.com/tani.png","language":"Nix","readme":"\n    (defpackage #:papyrus/README\n      (:use #:cl))\n    (in-package #:papyrus/README)\n    (named-readtables:in-readtable papyrus:md-syntax)\n\n# Papyrus\n\nA literate programming tool for Common Lisp + Markdown / Org mode / POD \n\n## About This Project\n\n### Philosophy\n\n*Papyrus* is the name of a programming style as well as the name of a tool\nwith which to implement it. The author of *papyrus* developed it to do\nliterate programming in LISP better than WEB, developed by Donald Knuth.\nWEB and it's derived softwares are used in various programming languages.\nThey require developers compiling with them to obtain the source code.\nIt is required in order to do literate programming in C and Pascal, but isn't\nin Common Lisp because Common Lisp has the reader macro which changes the\nsource code when the system reads it.\n\n```mermaid\nflowchart TB\n  subgraph Knuth's system\n  WEB -- CTANGLE --\u003e Pascal\n  WEB -- CWEAVE --\u003e TeX\n  end\n  subgraph Our system\n  Papyrus -- reader macro --\u003e CommonLisp\n  Papyrus --- Markdown\n  end\n```\n\n*Papyrus* makes your markdown executable with the reader macro of Common Lisp.\nFor example, the author wrote this document with *Papyrus*. You can execute it\nby running `ros run -l papyrus.asd -e '(require :papyrus)' -l README.md -q`.\nHow about this? Let's make your project more beautiful and useful!\n\n```lisp\n(princ \"Hello, Papyrus!\")\n```\n\n### Copyright\n\nCopyright (c) 2019 -- 2024 TANIGUCHI Masaya All Rights Reserved\n\n### License\n\nMIT. See the [license texts](./LICENSE).\n\n### Precaution\n\nThis is a new project. Please send me your feedback if you find any issues.\n\n- [Project home](https://github.com/tani/papyrus)\n\n## Tutorials\n\nIn *Papyrus*, you can write any text like the following,\nand make the file extension `md`. Also, you can write with Markdown,\nespecially CommonMark whose specification can be found at\n[commonmark.org](https://commonmark.org). *Papyrus* only evaluates codeblocks\n*after* `(enable-md-syntax)` that are enclosed by ` ```lisp ` and ` ``` `.\nThe indented codeblock *before* `(enable-md-syntax)` is important, as this codeblock\nspecifies the required packages. Please do not forget it.\n\n        (defpackage #:tutorial\n          (:use #:cl)\n          (:export #:hello))\n        (in-package #:tutorial)\n        (named-readtables:in-readtable papyrus:md-syntax)\n\n    # My First Document\n\n    This is my first document.\n    This will say \"Hello, world!\".\n\n    ```lisp\n    (defun hello ()\n      (princ \"Hello, world!\"))\n    ```\n\nIf you try this tutorial, save it as `tutorial.md`, as this is the filename\nused in this section. Now, there are two ways to generate the document,\n**REPL** and **ASDF**. The following are quick tutorials for each. For more\ninformation, please see the **Reference** section.\n\n### REPL\n\nA REPL is a good environment to experiment with your *Papyrus* documents. We\ncan load them and test the behaivor quickly and it is convenient to use them\nwith *SLIME*.\n\n#### Installation\n\n*Papyrus* is available in QuickLisp.\nTo install Just type,\n\n    \u003e (ql:quickload :papyrus)\n\nOr, you can install *Papyrus* with [Roswell](https://github.com/roswell/roswell).\n\n    $ ros install tani/papyrus\n\nNext you can load document as follows:\n\n    \u003e (require :papyrus)\n    nil\n    \u003e (load #p\"tutorial.md\")\n    nil\n    \u003e (tutorial:hello)\n    Hello, World!\n\n### ASDF\n\nLet's write a small project whose files are the following.\n\n    tutorial.asd\n    tutorial.md\n\n`tutorial.md` is the file written in the **REPL** section, and\n`tutorial.asd` is this:\n\n    (defclass md (cl-source-file)\n      ((type :initform \"md\")))\n\n    (defclass org (cl-source-file)\n      ((type :initform \"org\")))\n\n    (defclass pod (cl-source-file)\n      ((type :initform \"pod\")))\n\n    (defsystem tutorial\n      :version \"0.1\"\n      :author \"Your name\"\n      :license \"MIT\"\n      :depends-on (#:papyrus #:named-readtables)\n      :components ((:md \"tutorial\"))\n      :description \"A Literate Programming Framework\")\n\nNow that you have both files, `tutorial.md` and `tutorial.asd`,\nyou will be able to load this system like this.\n\n    \u003e (load #p\"tutorial.asd\")\n    nil\n    \u003e (require :tutorial)\n    nil\n    \u003e (tutorial:hello)\n    Hello, World!\n\nOf course, users of your project won't need to load anything else.\n\n## Reference\n\n### `enable-md-syntax`\n\nThis is a readtable defined for Markdown.\nThe codeblock enclosed by ` ```lisp ` and ` ``` ` is evaluated.\n\n        (defpackage #:sample\n          (:use #:cl)\n          (:export #:sample-function))\n        (in-package #:sample)\n        (named-readtables:in-readtable papyrus:md-syntax)\n\n    # Sample\n\n    This is a sample code. The following function just says \"Hello, world!\"\n\n    ```lisp\n    (defun sample-function () (princ \"Hello, world!\"))\n    ```\n\n### `enable-org-syntax`\n\nThis is a readtable for org-mode.\nThe codeblock enclosed by ` #+BEGIN_SRC lisp :tangle yes ` and ` #+END_SRC ` is evaluated.\nUnlike Markdown, any `#+CL:` tags are ignored when rendering the content to HTML.\n\n    #+CL:* * (defpackage #:sample\n    #+CL:* *   (:use #:cl)\n    #+CL:* *   (:export #:sample-function))\n    #+CL:* * (in-package #:sample)\n    #+CL:* * (named-readtables:in-readtable papyrus:org-syntax)\n\n    This is a sample code. The following function just says \"Hello, world!\"\n\n    #+BEGIN_SRC lisp :tangle yes\n    (defun sample-function () (princ \"Hello, world!\"))\n    #+END_SRC\n\n### `enable-pod-syntax`\n\nThis is a readtable defined by `named-readtables` for POD.\nThe codeblock outside of `=pod` and `=cut` is evaluated.\nThis syntax is similar to Perl's POD.\n\n    (defpackage #:sample\n      (:use #:cl)\n      (:export #:sample-function))\n    (in-package #:sample)\n    (named-readtables:in-readtable papyrus:pod-syntax)\n\n    =pod\n\n    This is a sample code. The following function just says \"Hello, world!\"\n\n    =cut\n\n    (defun sample-function () (princ \"Hello, world!\"))\n\n## Appendix\n\n### Nix overlays\n- [nix flakes without any frameworks.](https://github.com/tani/nix-common-lisp?tab=readme-ov-file#overlays)\n  ```nix\n  inputs = {\n    nixpkgs.url = \"github:nixos/nixpkgs/nixpkgs-unstable\";\n    flake-parts.url = \"github:hercules-ci/flake-parts\";\n    papyrus = {\n      url = \"github:tani/papyrus\";\n      inputs.nixpkgs.follows = \"nixpkgs\";\n    };\n  };\n  ```\n  ```nix\n  let\n      pkgs = import nixpkgs {\n        inherit system;\n        overlays = [\n          inputs.papyrus.overlays.default\n        ];\n      };\n  ```\n- [flake-parts](https://flake.parts/overlays.html?highlight=overlays#consuming-an-overlay)\n  ```nix\n  inputs = {\n    nixpkgs.url = \"github:nixos/nixpkgs/nixpkgs-unstable\";\n    flake-parts.url = \"github:hercules-ci/flake-parts\";\n    papyrus = {\n      url = \"github:tani/papyrus\";\n      inputs.nixpkgs.follows = \"nixpkgs\";\n    };\n  };\n  ```\n  ```nix\n    perSystem = { system, ... }: {\n      _module.args.pkgs = import inputs.nixpkgs {\n        inherit system;\n        overlays = [\n          inputs.papyrus.overlays.default\n        ];\n        config = { };\n      };\n    };\n  ```\n### Emacs Lisp\n\n### Recommended way\n\nTry to use [polymode](https://github.com/vspinu/polymode)\n\n    (require 'poly-markdown)\n    (add-to-list 'auto-mode-alist '(\"\\\\.md\" . poly-markdown-mode))\n\n### Old way\n\nIf you use emacs, there is `mmm-mode` which highlights the syntax of lisp\ncodeblocks in Markdown, but SLIME doesn't works well in `mmm-mode`.\n\n    (require 'mmm-mode)\n    (setq mmm-global-mode 'maybe)\n    (set-face-background 'mmm-default-submode-face nil)\n    (mmm-add-mode-ext-class nil \"\\\\.md?\\\\'\" 'lisp-markdown)\n    (mmm-add-classes\n     '((lisp-markdown\n        :submode lisp-mode\n        :front \"```lisp\"\n        :back \"```\")))\n","funding_links":["https://github.com/sponsors/tani"],"categories":["Online editors ##"],"sub_categories":["Third-party APIs"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftani%2Fpapyrus","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ftani%2Fpapyrus","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ftani%2Fpapyrus/lists"}