The pandocl Reference Manual

This is the pandocl Reference Manual, version 0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 17:30:35 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 pandocl

A universal document converter.

Maintainer

Fernando Borretti <>

Author

Fernando Borretti <>

Home Page
Source Control

(GIT )

Bug Tracker
License

MIT

Long Description

# Pandocl

A document converter built on [CommonDoc][cdoc].

# Usage

## Converting

The ‘convert‘ function takes two required arguments: The pathname of the input
and the pathname of the output. Two optional keyword arguments, ‘:input-format‘
and ‘:output-format‘, can be used to specify the format when the pathname is not enough to guess. It returns the parsed document.

“‘lisp
CL-USER> (pandocl:convert #p"input.tex" #p"output.html")
#<COMMON-DOC:DOCUMENT "My Document">

CL-USER> (pandocl:emit #p"input.tex" #p"output.html"
:input-format :vertex
:output-format :html)
#<COMMON-DOC:DOCUMENT "My Document">
“‘

## Parsing

The ‘parse‘ function takes a pathname and optionally an input format (Otherwise
it guesses it from the pathname) and returns a CommonDoc document.

“‘lisp
CL-USER> (pandocl:parse #p"path/to/doc.tex")
#<COMMON-DOC:DOCUMENT "My Document">

CL-USER> (pandocl:parse #p"path/to/doc.tex" :format :vertex)
#<COMMON-DOC:DOCUMENT "My Document">
“‘

## Emitting

The ‘emit‘ function takes a document, a pathname to write it to, and optionally
a format for the output (Otherwise it tries to guess from the pathname). It
takes an extra two keyword arguments, ‘:if-exists‘ and ‘:if-does-not-exist‘,
which control behaviour when opening the file (See [with-open-file][w-o-f]). The function returns the document.

“‘lisp
CL-USER> (pandocl:emit doc #p"path/to/output.html")
#<COMMON-DOC:DOCUMENT "My Document">

CL-USER> (pandocl:emit doc #p"path/to/output.html" :format :html) #<COMMON-DOC:DOCUMENT "My Document">
“‘

# Formats

## Supported

Supported input formats:

* [‘:vertex‘](https://github.com/CommonDoc/vertex)
* [‘:scriba‘](https://github.com/CommonDoc/scriba)

Supported output formats:

* [‘:html‘](https://github.com/CommonDoc/common-html)

## File extensions

When Pandocl tries to guess which format to use from a pathname type, it uses
the following rules:

* ‘.tex‘: VerTeX
* ‘.scr‘: Scriba
* ‘.html‘: HTML

[cdoc]: https://github.com/CommonDoc/common-doc
[w-o-f]: http://www.lispworks.com/documentation/HyperSpec/Body/m_w_open.htm#with-open-file

# License

Copyright (c) 2015 Fernando Borretti

Licensed under the MIT License.

Version

0.1

Dependencies
  • common-doc (system).
  • common-doc-contrib (system).
  • vertex (system).
  • scriba (system).
  • parenml (system).
  • thorn (system).
  • common-html (system).
Source

pandocl.asd.

Child Component

src (module).


3 Modules

Modules are listed depth-first from the system components tree.


3.1 pandocl/src

Source

pandocl.asd.

Parent Component

pandocl (system).

Child Component

pandocl.lisp (file).


4 Files

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


4.1 Lisp


4.1.1 pandocl/pandocl.asd

Source

pandocl.asd.

Parent Component

pandocl (system).

ASDF Systems

pandocl.


4.1.2 pandocl/src/pandocl.lisp

Source

pandocl.asd.

Parent Component

src (module).

Packages

pandocl.

Public Interface
Internals

5 Packages

Packages are listed by definition order.


5.1 pandocl

Source

pandocl.lisp.

Use List

common-lisp.

Public Interface
Internals

6 Definitions

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


6.1 Public Interface


6.1.1 Ordinary functions

Function: convert (input-pathname output-pathname &key input-format output-format if-exists if-does-not-exist)

Convert a file to another format.

Package

pandocl.

Source

pandocl.lisp.

Function: emit (document pathname &key format if-exists if-does-not-exist)

Dump a document to a file, optionally specifying an output format.

Package

pandocl.

Source

pandocl.lisp.

Function: guess-format (pathname)

Try to guess the CommonDoc format from a pathname, or signal unknown-file-extension.

Package

pandocl.

Source

pandocl.lisp.

Function: parse (pathname &key format)

Parse a document from a file, optionally specifying an input format.

Package

pandocl.

Source

pandocl.lisp.

Function: parse-string (string format)

Parse a string, necessarily specifying an input format.

Package

pandocl.

Source

pandocl.lisp.


6.1.2 Conditions

Condition: pandocl-error

The base class of Pandocl-related errors.

Package

pandocl.

Source

pandocl.lisp.

Direct superclasses

condition.

Direct subclasses
Condition: unknown-file-extension

Signalled when Pandocl tries to guess a file format from a file extension and fails.

Package

pandocl.

Source

pandocl.lisp.

Direct superclasses

pandocl-error.

Direct methods

extension.

Direct slots
Slot: extension

The file extension.

Initargs

:extension

Readers

extension.

Writers

This slot is read-only.

Condition: unsupported-format

Signalled when a user-specified format is not known.

Package

pandocl.

Source

pandocl.lisp.

Direct superclasses

pandocl-error.

Direct methods

format-name.

Direct slots
Slot: format-name

The name of the format.

Initargs

:format-name

Readers

format-name.

Writers

This slot is read-only.


6.2 Internals


6.2.1 Special variables

Special Variable: +format-class-map+

A plist of format names to classes.

Package

pandocl.

Source

pandocl.lisp.

Special Variable: +format-extension-map+

A list of file extensions to format names.

Package

pandocl.

Source

pandocl.lisp.

Special Variable: +supported-input-formats+

A list of supported input formats.

Package

pandocl.

Source

pandocl.lisp.

Special Variable: +supported-output-formats+

A list of supported output formats.

Package

pandocl.

Source

pandocl.lisp.


6.2.2 Ordinary functions

Function: check-supported-format (format-name list)
Package

pandocl.

Source

pandocl.lisp.

Function: check-supported-input-format (format-name)

If the input format is not supported, raise unsupported-format.

Package

pandocl.

Source

pandocl.lisp.

Function: check-supported-output-format (format-name)

If the output format is not supported, raise unsupported-format.

Package

pandocl.

Source

pandocl.lisp.

Function: find-format (format-name)

Find the class corresponding to a format name.

Package

pandocl.

Source

pandocl.lisp.


6.2.3 Generic functions

Generic Reader: extension (condition)
Package

pandocl.

Methods
Reader Method: extension ((condition unknown-file-extension))
Source

pandocl.lisp.

Target Slot

extension.

Generic Reader: format-name (condition)
Package

pandocl.

Methods
Reader Method: format-name ((condition unsupported-format))
Source

pandocl.lisp.

Target Slot

format-name.


Appendix A Indexes


A.1 Concepts