The common-html Reference Manual

This is the common-html Reference Manual, version 0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Sun Sep 15 04:50:51 2024 GMT+0.

Table of Contents


1 Introduction


2 Systems

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


2.1 common-html

An HTML parser/emitter for CommonDoc.

Maintainer

Fernando Borretti <>

Author

Fernando Borretti <>

Home Page

https://github.com/CommonDoc/common-html

Source Control

(GIT git@github.com:CommonDoc/common-html.git)

Bug Tracker

https://github.com/CommonDoc/common-html/issues

License

MIT

Long Description

# CommonHTML

[![Build Status](https://travis-ci.org/CommonDoc/common-html.svg)](https://travis-ci.org/CommonDoc/common-html)
[![Coverage Status](https://coveralls.io/repos/CommonDoc/common-html/badge.svg?branch=master)](https://coveralls.io/r/CommonDoc/common-html?branch=master)

An HTML parser/emitter for [CommonDoc](https://github.com/CommonDoc/common-doc).

# Usage

“‘lisp
(defvar node
(doc
(document
(:title "My Document"
:creator "me"
:keywords (list "test" "test1"))
(paragraph
()
(text-node
(:text "test"))))))

(common-html.emitter:node-to-html-string node) ;; => "<p>test</p>"
“‘

## Attributes

CommonHTML let’s you customize the HTML output by inserting attributes (such as
class names or data attributes) in node metadata. All CommonDoc nodes hold
optional metadata, as key-value pairs. Every pair where the key starts with
‘html:‘ will be emitted with this prefix removed.

So, for instance, if a node has a metadata pair like ‘"html:class" =>
"theorem"‘, the resulting HTML for that node will have ‘class="theorem"‘.

# Multi-file emission

Normally, a document is emitted into HTML as a single file. You can also perform
Texinfo/Sphinx style emission, where a document is broken up into sections, and
each section (Up to a certain depth, or any depth) is emitted as a different
file.

To emit a document into multiple files, simply do:

“‘lisp
(common-html.multi-emit:multi-emit doc #p"output-directory/")
“‘

An optional keyword argument, ‘:max-depth‘, can be provided to choose at what
section depth to stop emitting each section in a different file. For instance,
if you have a document that looks like this:

1. Intro
1. Overview
2. History
1. Motivation
2. Tutorial

Emitting it with the default ‘:max-depth‘ of ‘nil‘ will produce 5 files, while
emitting it with a ‘:max-depth‘ of 2 will produce four files: One for each of
the Intro, Overview and Tutorial subsections, and another for both the History
section and its Motivation subsection.

## How it Works

Multi-part file emission can be complicated.

First, some obvious choices, and how CommonHTML chooses:

1. Should the directory structure of the HTML output mirror that of the
sections? Or should all HTML files be emitted within the same directory?
Answer: For simplicity (Users might not expect or want nested files), all
HTML files are emitted into the same directory.

2. What should the name of the resulting HTML files be? The pure name of the
section? The result of calling ‘common-doc.util:string-to-slug‘ on the
section? Or an autogenerated ID? Answer: The first option might produce
invalid pathnames, and the last option is an inconceivable abomination, so we
just go with slugifying the section text.

# License

Copyright (c) 2014-2015 Fernando Borretti

Licensed under the MIT License.

Version

0.1

Dependencies
  • common-doc (system).
  • plump (system).
  • anaphora (system).
  • alexandria (system).
Source

common-html.asd.

Child Component

src (module).


3 Modules

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


3.1 common-html/src

Source

common-html.asd.

Parent Component

common-html (system).

Child Components

4 Files

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


4.1 Lisp


4.1.1 common-html/common-html.asd

Source

common-html.asd.

Parent Component

common-html (system).

ASDF Systems

common-html.


4.1.2 common-html/src/package.lisp

Source

common-html.asd.

Parent Component

src (module).

Packages

4.1.3 common-html/src/template.lisp

Dependency

package.lisp (file).

Source

common-html.asd.

Parent Component

src (module).

Public Interface

4.1.4 common-html/src/emitter.lisp

Dependency

template.lisp (file).

Source

common-html.asd.

Parent Component

src (module).

Public Interface
Internals

4.1.5 common-html/src/multi-emit.lisp

Dependency

emitter.lisp (file).

Source

common-html.asd.

Parent Component

src (module).

Public Interface
Internals

4.1.6 common-html/src/toc.lisp

Dependency

multi-emit.lisp (file).

Source

common-html.asd.

Parent Component

src (module).

Public Interface

4.1.7 common-html/src/common-html.lisp

Dependency

toc.lisp (file).

Source

common-html.asd.

Parent Component

src (module).

Public Interface

5 Packages

Packages are listed by definition order.


5.1 common-html.emitter

Emit HTML5 from a CommonDoc document.

Source

package.lisp.

Use List
  • anaphora.
  • common-doc.
  • common-lisp.
Public Interface
Internals

5.2 common-html.multi-emit

Source

package.lisp.

Use List
  • common-doc.
  • common-lisp.
Public Interface
Internals

5.3 common-html.template

Document templates.

Source

package.lisp.

Use List

common-lisp.

Public Interface

5.4 common-html

Main interface.

Source

package.lisp.

Use List

common-lisp.

Public Interface

html (class).


5.5 common-html.toc

Utilities for building an HTML table of contents.

Source

package.lisp.

Use List

common-lisp.

Public Interface

6 Definitions

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


6.1 Public Interface


6.1.1 Special variables

Special Variable: *document-section-format-control*

A format control string used to render document+section links.

Package

common-html.emitter.

Source

emitter.lisp.

Special Variable: *image-format-control*

A format control string to render image URLs.

Package

common-html.emitter.

Source

emitter.lisp.

Special Variable: *multi-emit*

Whether we are in multi-file emission or not. nil by default.

Package

common-html.multi-emit.

Source

multi-emit.lisp.

Special Variable: *section-tree*

A map of section references to parent section references.

Package

common-html.multi-emit.

Source

multi-emit.lisp.

Special Variable: *template*

The template that will be used by template and template-section.

Package

common-html.template.

Source

template.lisp.


6.1.2 Macros

Macro: with-template ((template &rest args) &rest body)

Execute ‘body‘ with the template set to ‘template‘.

Package

common-html.template.

Source

template.lisp.


6.1.3 Ordinary functions

Function: multi-file-toc (doc &key max-depth)

Generate and HTML table of contents for a multi-file document.

Package

common-html.toc.

Source

toc.lisp.

Function: node-to-html-string (node)

Return an HTML string from a node.

Package

common-html.emitter.

Source

emitter.lisp.

Function: node-to-stream (node stream)

Emit a node into a stream.

Package

common-html.emitter.

Source

emitter.lisp.

Function: single-file-toc (doc &key max-depth)

Generate and HTML table of contents for a single-file document.

Package

common-html.toc.

Source

toc.lisp.

Function: template (document children-string)

Like render, only using the *template* special variable.

Package

common-html.template.

Source

template.lisp.

Function: template-section (document section content-string)

Like render-section, but uses the *template* special variable.

Package

common-html.template.

Source

template.lisp.


6.1.4 Generic functions

Generic Function: multi-emit (doc directory &key max-depth)
Package

common-html.multi-emit.

Methods
Method: multi-emit ((doc document) directory &key max-depth)
Source

multi-emit.lisp.

Generic Function: render (template document content-string)

Render a document instance and its children (As an HTML string) into an HTML string.

Package

common-html.template.

Source

template.lisp.

Methods
Method: render ((template template) (document document) content-string)

The simplest template.

Generic Function: render-section (template document section content-string)

Render a section of a document into an HTML string.

Package

common-html.template.

Source

template.lisp.

Methods
Method: render-section ((template template) (document document) (section section) content-string)

The simplest section template.


6.1.5 Standalone methods

Method: emit-document ((html html) (node document-node) stream)

Render a node to HTML stream.

Package

common-doc.format.

Source

common-html.lisp.

Method: emit-document ((html html) (doc document) stream)

Render a document to HTML stream.

Package

common-doc.format.

Source

common-html.lisp.


6.1.6 Classes

Class: html

CommonDoc HTML format class.

Package

common-html.

Source

common-html.lisp.

Direct superclasses

document-format.

Direct methods
Class: template

A template.

Package

common-html.template.

Source

template.lisp.

Direct methods

6.2 Internals


6.2.1 Special variables

Special Variable: *current-section-id*
Package

common-html.multi-emit.

Source

multi-emit.lisp.

Special Variable: *output-stream*

The stream the HTML will be written to.

Package

common-html.emitter.

Source

emitter.lisp.

Special Variable: *section-depth*

The depth of ‘section‘ classes. Used to produce header numbers, e.g. ‘h1, ‘h3‘.

Package

common-html.emitter.

Source

emitter.lisp.


6.2.2 Macros

Macro: define-emitter ((node class) &body body)

Define an emitter method.

Package

common-html.emitter.

Source

emitter.lisp.

Macro: define-simple-emitter (class tag-name)

Define a simple emitter.

Package

common-html.emitter.

Source

emitter.lisp.

Macro: with-tag ((tag-name node &key attributes self-closing-p) &rest body)

Execute body after opening and before closing a tag.

Package

common-html.emitter.

Source

emitter.lisp.


6.2.3 Ordinary functions

Function: assign-container (section container)
Package

common-html.multi-emit.

Source

multi-emit.lisp.

Function: emit-metadata (hash-table)

Print HTML attributes.

Package

common-html.emitter.

Source

emitter.lisp.

Function: print-attribute (key value)

Print a key value pair as HTML.

Package

common-html.emitter.

Source

emitter.lisp.


6.2.4 Generic functions

Generic Function: emit (node)

Create an HTML representation of a CommonDoc document.

Package

common-html.emitter.

Source

emitter.lisp.

Methods
Method: emit ((doc document))

Emit a full document.

Method: emit ((section section))

Emit a section.

Method: emit ((node cell))
Method: emit ((row row))

Emit a row.

Method: emit ((table table))

Emit a table.

Method: emit ((fig figure))

Emit a figure.

Method: emit ((image image))

Emit an image.

Method: emit ((node definition-list))
Method: emit ((node ordered-list))
Method: emit ((node unordered-list))
Method: emit ((definition definition))

Emit a definition list item.

Method: emit ((node list-item))
Method: emit ((link web-link))

Emit a web link.

Method: emit ((ref document-link))

Emit a document link.

Method: emit ((node block-quote))
Method: emit ((node inline-quote))
Method: emit ((code code-block))

Emit a code block.

Method: emit ((node subscript))
Method: emit ((node superscript))
Method: emit ((node code))
Method: emit ((node strikethrough))
Method: emit ((node underline))
Method: emit ((node italic))
Method: emit ((node bold))
Method: emit ((node paragraph))
Method: emit ((node text-node))

Emit a text node.

Method: emit ((node content-node))

The generic emitter for content nodes.

Method: emit ((list list))

Emit a list.

Generic Function: emit-node (node &key directory doc depth max-depth)
Package

common-html.multi-emit.

Methods
Method: emit-node ((section section) &key directory doc depth max-depth)

Emit a section node.

Source

multi-emit.lisp.

Method: emit-node ((node content-node) &key directory doc depth max-depth)

Emit a content node.

Source

multi-emit.lisp.

Method: emit-node ((node document-node) &key directory doc depth max-depth)

Emit a document node.

Source

multi-emit.lisp.


Appendix A Indexes


A.1 Concepts


A.2 Functions

Jump to:   A   D   E   F   G   M   N   P   R   S   T   W  
Index Entry  Section

A
assign-container: Private ordinary functions

D
define-emitter: Private macros
define-simple-emitter: Private macros

E
emit: Private generic functions
emit: Private generic functions
emit: Private generic functions
emit: Private generic functions
emit: Private generic functions
emit: Private generic functions
emit: Private generic functions
emit: Private generic functions
emit: Private generic functions
emit: Private generic functions
emit: Private generic functions
emit: Private generic functions
emit: Private generic functions
emit: Private generic functions
emit: Private generic functions
emit: Private generic functions
emit: Private generic functions
emit: Private generic functions
emit: Private generic functions
emit: Private generic functions
emit: Private generic functions
emit: Private generic functions
emit: Private generic functions
emit: Private generic functions
emit: Private generic functions
emit: Private generic functions
emit: Private generic functions
emit: Private generic functions
emit: Private generic functions
emit-document: Public standalone methods
emit-document: Public standalone methods
emit-metadata: Private ordinary functions
emit-node: Private generic functions
emit-node: Private generic functions
emit-node: Private generic functions
emit-node: Private generic functions

F
Function, assign-container: Private ordinary functions
Function, emit-metadata: Private ordinary functions
Function, multi-file-toc: Public ordinary functions
Function, node-to-html-string: Public ordinary functions
Function, node-to-stream: Public ordinary functions
Function, print-attribute: Private ordinary functions
Function, single-file-toc: Public ordinary functions
Function, template: Public ordinary functions
Function, template-section: Public ordinary functions

G
Generic Function, emit: Private generic functions
Generic Function, emit-node: Private generic functions
Generic Function, multi-emit: Public generic functions
Generic Function, render: Public generic functions
Generic Function, render-section: Public generic functions

M
Macro, define-emitter: Private macros
Macro, define-simple-emitter: Private macros
Macro, with-tag: Private macros
Macro, with-template: Public macros
Method, emit: Private generic functions
Method, emit: Private generic functions
Method, emit: Private generic functions
Method, emit: Private generic functions
Method, emit: Private generic functions
Method, emit: Private generic functions
Method, emit: Private generic functions
Method, emit: Private generic functions
Method, emit: Private generic functions
Method, emit: Private generic functions
Method, emit: Private generic functions
Method, emit: Private generic functions
Method, emit: Private generic functions
Method, emit: Private generic functions
Method, emit: Private generic functions
Method, emit: Private generic functions
Method, emit: Private generic functions
Method, emit: Private generic functions
Method, emit: Private generic functions
Method, emit: Private generic functions
Method, emit: Private generic functions
Method, emit: Private generic functions
Method, emit: Private generic functions
Method, emit: Private generic functions
Method, emit: Private generic functions
Method, emit: Private generic functions
Method, emit: Private generic functions
Method, emit: Private generic functions
Method, emit-document: Public standalone methods
Method, emit-document: Public standalone methods
Method, emit-node: Private generic functions
Method, emit-node: Private generic functions
Method, emit-node: Private generic functions
Method, multi-emit: Public generic functions
Method, render: Public generic functions
Method, render-section: Public generic functions
multi-emit: Public generic functions
multi-emit: Public generic functions
multi-file-toc: Public ordinary functions

N
node-to-html-string: Public ordinary functions
node-to-stream: Public ordinary functions

P
print-attribute: Private ordinary functions

R
render: Public generic functions
render: Public generic functions
render-section: Public generic functions
render-section: Public generic functions

S
single-file-toc: Public ordinary functions

T
template: Public ordinary functions
template-section: Public ordinary functions

W
with-tag: Private macros
with-template: Public macros


A.4 Data types

Jump to:   C   E   F   H   M   P   S   T  
Index Entry  Section

C
Class, html: Public classes
Class, template: Public classes
common-html: The common-html system
common-html: The common-html package
common-html.asd: The common-html/common-html․asd file
common-html.emitter: The common-html․emitter package
common-html.lisp: The common-html/src/common-html․lisp file
common-html.multi-emit: The common-html․multi-emit package
common-html.template: The common-html․template package
common-html.toc: The common-html․toc package

E
emitter.lisp: The common-html/src/emitter․lisp file

F
File, common-html.asd: The common-html/common-html․asd file
File, common-html.lisp: The common-html/src/common-html․lisp file
File, emitter.lisp: The common-html/src/emitter․lisp file
File, multi-emit.lisp: The common-html/src/multi-emit․lisp file
File, package.lisp: The common-html/src/package․lisp file
File, template.lisp: The common-html/src/template․lisp file
File, toc.lisp: The common-html/src/toc․lisp file

H
html: Public classes

M
Module, src: The common-html/src module
multi-emit.lisp: The common-html/src/multi-emit․lisp file

P
Package, common-html: The common-html package
Package, common-html.emitter: The common-html․emitter package
Package, common-html.multi-emit: The common-html․multi-emit package
Package, common-html.template: The common-html․template package
Package, common-html.toc: The common-html․toc package
package.lisp: The common-html/src/package․lisp file

S
src: The common-html/src module
System, common-html: The common-html system

T
template: Public classes
template.lisp: The common-html/src/template․lisp file
toc.lisp: The common-html/src/toc․lisp file