The papyrus Reference Manual

Table of Contents

The papyrus Reference Manual

This is the papyrus Reference Manual, version 0.1, generated automatically by Declt version 3.0 "Montgomery Scott" on Tue Apr 28 12:38:08 2020 GMT+0.

1 Introduction

(in-package #:cl-user)
(defpackage #:papyrus.README
  (:use :cl :papyrus :named-readtables))
(in-package #:papyrus.README)
(in-readtable :papyrus)

Papyrus

A literate programming tool

Table of Contents

1. About This Project
   1. Philosophy
   2. Copyright
   3. License
   4. Precautions
2. Tutorials
   1. REPL
   2. ASDF
3. Reference
   1. Papyrus
4. Appendix
   1. FAQ
   2. Emacs Lisp

About This Project

Philosophy

Papyrus is the name of a programming style as well as the name of a tool with which to implement it. The author of papyrus developed it to do literate programming in LISP better than WEB, developed by Donald Knuth. WEB and it's derived softwares are used in various programming languages. They require developers compiling with them to obtain the source code. It is required in order to do literate programming in C and Pascal, but isn't in Common Lisp because Common Lisp has the reader macro which changes the source code when the system reads it.

Papyrus makes your markdown executable with the reader macro of Common Lisp. For example, the author wrote this document with Papyrus. You can execute it by running ros run -l papyrus.asd -e '(require :papyrus)' -l README.md -q. How about this? Let's make your project more beautiful and useful!

(princ "Hello, Papyrus!")

Copyright

Copyright (c) 2019 Fernado Garcia Borges All Rights Reserved

License

MIT. See the license texts.

Precaution

This is a new project. Please send me your feedback if you find any issues.

• Project home

Tutorials

In Papyrus, you can write any text but you have to write a title (# ) at the top of the document, like the following, and make the file extension .md. Also, you can write with Markdown, especially CommonMark whose specification can be found at commonmark.org. Papyrus only evaluates codeblocks after the title (# ) that are enclosed by ```lisp and ```. The indented codeblock before the title (# ) is important, as this codeblock specifies the required packages. Please do not forget it.

    (in-package :cl-user)
    (defpackage :tutorial
      (:use :cl :papyrus :named-readtables)
      (:export :hello)
    (in-package :tutorial)
    (in-readtable :papyrus)

# My First Document

This is my first document.
This will say "Hello, world!".

```lisp
(defun hello ()
  (princ "Hello, world!"))
```

If you try this tutorial, save it as tutorial.md, as this is the filename used in this section. Now, there are two ways to generate the document, REPL and ASDF. The following are quick tutorials for each. For more information, please see the Reference section.

REPL

A REPL is a good environment to experiment with your Papyrus documents. We can load them and test the behaivor quickly and it is convenient to use them with SLIME.

Installation

Papyrus is available in QuickLisp. To install Just type,

> (ql:quickload :papyrus)

Or, you can install Papyrus with Roswell.

$ ros install asciian/papyrus

Next you can load document as follows:

> (require :papyrus)
nil
> (load #p"tutorial.md")
nil
> (tutorial:hello)
Hello, World!

ASDF

Let's write a small project whose files are the following.

tutorial.asd
tutorial.md

tutorial.md is the file written in the REPL section, and tutorial.asd is this:

(in-package :cl-user)
(defpackage tutorial-asd
  (:use :cl :asdf))
(in-package :tutorial-asd)

(defclass papyrus (cl-source-file)
  ((type :initform "md")))

(defsystem tutorial
  :version "0.1"
  :author "Your name"
  :license "MIT"
  :depends-on (:papyrus :named-readtables)
  :components ((:papyrus "tutorial"))
  :description "A Literate Programming Framework")

Now that you have both files, tutorial.md and tutorial.asd, you will be able to load this system like this.

> (load #p"tutorial.asd")
nil
> (require :tutorial)
nil
> (tutorial:hello)
Hello, World!

Of course, users of your project won't need to load anything else.

Reference

papyrus

This is a readtable defined by named-readtables. You can use this with named-readtable:in-readtable like this document.

    (in-package #:cl-user)
    (defpackage #:sample
      (:use :cl :named-readtables :papyrus)
      (:export #:sample-function))
    (in-package :sample)
    (in-readtable :papyrus)

# Sample

This is a sample code. The following function just says "Hello, world!"

```lisp
(defun sample-function () (princ "Hello, world!"))
```

Appendix

Emacs Lisp

Recommended way

Try to use polymode

(require 'poly-markdown)
(add-to-list 'auto-mode-alist '("\\.md" . poly-markdown-mode))

Old way

If you use emacs, there is mmm-mode which highlights the syntax of lisp codeblocks in Markdown, but SLIME doesn't works well in mmm-mode.

(require 'mmm-mode)
(setq mmm-global-mode 'maybe)
(set-face-background 'mmm-default-submode-face nil)
(mmm-add-mode-ext-class nil "\\.md?\\'" 'lisp-markdown)
(mmm-add-classes
 '((lisp-markdown
    :submode lisp-mode
    :front "```lisp"
    :back "```")))

2 Systems

The main system appears first, followed by any subsystem dependency.

2.1 papyrus

Author

asciian

License

MIT

Description

A Literate Programming Tool

Version

0.1

Dependency

named-readtables

Source

papyrus.asd (file)

Component

papyrus.lisp (file)

3 Files

Files are sorted by type and then listed depth-first from the systems components trees.

3.1 Lisp

3.1.1 papyrus.asd

Location

papyrus.asd

Systems

papyrus (system)

Packages

papyrus-asd

3.1.2 papyrus/papyrus.lisp

Parent

papyrus (system)

Location

papyrus.lisp

Packages

papyrus

Internal Definitions

papyrus-reader (function)

4 Packages

Packages are listed by definition order.

4.1 papyrus-asd

Source

papyrus.asd

Use List

• asdf/interface
• common-lisp

4.2 papyrus

Source

papyrus.lisp (file)

Use List

• editor-hints.named-readtables
• common-lisp

Internal Definitions

papyrus-reader (function)

5 Definitions

Definitions are sorted by export status, category, package, and then by lexicographic order.

5.1 Internal definitions

5.1.1 Functions

Function: papyrus-reader S A B

Package

papyrus

Source

papyrus.lisp (file)

Appendix A Indexes

A.1 Concepts

A.2 Functions

A.3 Variables

A.4 Data types