The common-html Reference Manual

Table of Contents

Next: , Previous: , Up: (dir)   [Contents][Index]

The common-html Reference Manual

This is the common-html Reference Manual, version 0.1, generated automatically by Declt version 2.3 "Robert April" on Wed Mar 14 03:45:47 2018 GMT+0.


Next: , Previous: , Up: Top   [Contents][Index]

1 Introduction

CommonHTML

Build Status Coverage Status

An HTML parser/emitter for CommonDoc.

Usage

(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:

(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
  2. Overview
  3. History
  4. Motivation
  5. 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.


Next: , Previous: , Up: Top   [Contents][Index]

2 Systems

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


Previous: , Up: Systems   [Contents][Index]

2.1 common-html

Maintainer

Fernando Borretti <eudoxiahp@gmail.com>

Author

Fernando Borretti <eudoxiahp@gmail.com>

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

Description

An HTML parser/emitter for CommonDoc.

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
Source

common-html.asd (file)

Component

src (module)


Next: , Previous: , Up: Top   [Contents][Index]

3 Modules

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


Previous: , Up: Modules   [Contents][Index]

3.1 common-html/src

Parent

common-html (system)

Location

src/

Components

Next: , Previous: , Up: Top   [Contents][Index]

4 Files

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


Previous: , Up: Files   [Contents][Index]

4.1 Lisp


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.1 common-html.asd

Location

common-html.asd

Systems

common-html (system)


Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.2 common-html/src/package.lisp

Parent

src (module)

Location

src/package.lisp

Packages

Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.3 common-html/src/template.lisp

Dependency

package.lisp (file)

Parent

src (module)

Location

src/template.lisp

Exported Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.4 common-html/src/emitter.lisp

Dependency

template.lisp (file)

Parent

src (module)

Location

src/emitter.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

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

Dependency

emitter.lisp (file)

Parent

src (module)

Location

src/multi-emit.lisp

Exported Definitions
Internal Definitions

Next: , Previous: , Up: Lisp files   [Contents][Index]

4.1.6 common-html/src/toc.lisp

Dependency

multi-emit.lisp (file)

Parent

src (module)

Location

src/toc.lisp

Exported Definitions

Previous: , Up: Lisp files   [Contents][Index]

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

Dependency

toc.lisp (file)

Parent

src (module)

Location

src/common-html.lisp

Exported Definitions

html (class)


Next: , Previous: , Up: Top   [Contents][Index]

5 Packages

Packages are listed by definition order.


Next: , Previous: , Up: Packages   [Contents][Index]

5.1 common-html

Main interface.

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions

html (class)


Next: , Previous: , Up: Packages   [Contents][Index]

5.2 common-html.toc

Utilities for building an HTML table of contents.

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions

Next: , Previous: , Up: Packages   [Contents][Index]

5.3 common-html.emitter

Emit HTML5 from a CommonDoc document.

Source

package.lisp (file)

Use List
Exported Definitions
Internal Definitions

Next: , Previous: , Up: Packages   [Contents][Index]

5.4 common-html.multi-emit

Source

package.lisp (file)

Use List
Exported Definitions
Internal Definitions

Previous: , Up: Packages   [Contents][Index]

5.5 common-html.template

Document templates.

Source

package.lisp (file)

Use List

common-lisp

Exported Definitions

Next: , Previous: , Up: Top   [Contents][Index]

6 Definitions

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


Next: , Previous: , Up: Definitions   [Contents][Index]

6.1 Exported definitions


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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 (file)

Special Variable: *image-format-control*

A format control string to render image URLs.

Package

common-html.emitter

Source

emitter.lisp (file)

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 (file)

Special Variable: *section-tree*

A map of section references to parent section references.

Package

common-html.multi-emit

Source

multi-emit.lisp (file)

Special Variable: *template*

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

Package

common-html.template

Source

template.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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 (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

6.1.3 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 (file)

Function: node-to-html-string NODE

Return an HTML string from a node.

Package

common-html.emitter

Source

emitter.lisp (file)

Function: node-to-stream NODE STREAM

Emit a node into a stream.

Package

common-html.emitter

Source

emitter.lisp (file)

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 (file)

Function: template DOCUMENT CHILDREN-STRING

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

Package

common-html.template

Source

template.lisp (file)

Function: template-section DOCUMENT SECTION CONTENT-STRING

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

Package

common-html.template

Source

template.lisp (file)


Next: , Previous: , Up: Exported definitions   [Contents][Index]

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 (file)

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 (file)

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 (file)

Methods
Method: render-section (TEMPLATE template) (DOCUMENT document) (SECTION section) CONTENT-STRING

The simplest section template.


Previous: , Up: Exported definitions   [Contents][Index]

6.1.5 Classes

Class: html ()

CommonDoc HTML format class.

Package

common-html

Source

common-html.lisp (file)

Direct superclasses

document-format (class)

Direct methods
  • emit-document (method)
  • emit-document (method)
Class: template ()

A template.

Package

common-html.template

Source

template.lisp (file)

Direct superclasses

standard-object (class)

Direct methods

Previous: , Up: Definitions   [Contents][Index]

6.2 Internal definitions


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.1 Special variables

Special Variable: *current-section-id*
Package

common-html.multi-emit

Source

multi-emit.lisp (file)

Special Variable: *output-stream*

The stream the HTML will be written to.

Package

common-html.emitter

Source

emitter.lisp (file)

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 (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.2 Macros

Macro: define-emitter (NODE CLASS) &rest BODY

Define an emitter method.

Package

common-html.emitter

Source

emitter.lisp (file)

Macro: define-simple-emitter CLASS TAG-NAME

Define a simple emitter.

Package

common-html.emitter

Source

emitter.lisp (file)

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 (file)


Next: , Previous: , Up: Internal definitions   [Contents][Index]

6.2.3 Functions

Function: assign-container SECTION CONTAINER
Package

common-html.multi-emit

Source

multi-emit.lisp (file)

Function: emit-metadata HASH-TABLE

Print HTML attributes.

Package

common-html.emitter

Source

emitter.lisp (file)

Function: print-attribute KEY VALUE

Print a key value pair as HTML.

Package

common-html.emitter

Source

emitter.lisp (file)


Previous: , Up: Internal definitions   [Contents][Index]

6.2.4 Generic functions

Generic Function: emit NODE

Create an HTML representation of a CommonDoc document.

Package

common-html.emitter

Source

emitter.lisp (file)

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 (file)

Method: emit-node (NODE content-node) &key DIRECTORY DOC DEPTH MAX-DEPTH

Emit a content node.

Source

multi-emit.lisp (file)

Method: emit-node (NODE document-node) &key DIRECTORY DOC DEPTH MAX-DEPTH

Emit a document node.

Source

multi-emit.lisp (file)


Previous: , Up: Top   [Contents][Index]

Appendix A Indexes


Next: , Previous: , Up: Indexes   [Contents][Index]

A.1 Concepts

Jump to:   C   F   L   M  
Index Entry  Section

C
common-html.asd: The common-html<dot>asd file
common-html/src: The common-html/src module
common-html/src/common-html.lisp: The common-html/src/common-html<dot>lisp file
common-html/src/emitter.lisp: The common-html/src/emitter<dot>lisp file
common-html/src/multi-emit.lisp: The common-html/src/multi-emit<dot>lisp file
common-html/src/package.lisp: The common-html/src/package<dot>lisp file
common-html/src/template.lisp: The common-html/src/template<dot>lisp file
common-html/src/toc.lisp: The common-html/src/toc<dot>lisp file

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

L
Lisp File, common-html.asd: The common-html<dot>asd file
Lisp File, common-html/src/common-html.lisp: The common-html/src/common-html<dot>lisp file
Lisp File, common-html/src/emitter.lisp: The common-html/src/emitter<dot>lisp file
Lisp File, common-html/src/multi-emit.lisp: The common-html/src/multi-emit<dot>lisp file
Lisp File, common-html/src/package.lisp: The common-html/src/package<dot>lisp file
Lisp File, common-html/src/template.lisp: The common-html/src/template<dot>lisp file
Lisp File, common-html/src/toc.lisp: The common-html/src/toc<dot>lisp file

M
Module, common-html/src: The common-html/src module

Jump to:   C   F   L   M  

Next: , Previous: , Up: Indexes   [Contents][Index]

A.2 Functions

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

A
assign-container: Internal functions

D
define-emitter: Internal macros
define-simple-emitter: Internal macros

E
emit: Internal generic functions
emit: Internal generic functions
emit: Internal generic functions
emit: Internal generic functions
emit: Internal generic functions
emit: Internal generic functions
emit: Internal generic functions
emit: Internal generic functions
emit: Internal generic functions
emit: Internal generic functions
emit: Internal generic functions
emit: Internal generic functions
emit: Internal generic functions
emit: Internal generic functions
emit: Internal generic functions
emit: Internal generic functions
emit: Internal generic functions
emit: Internal generic functions
emit: Internal generic functions
emit: Internal generic functions
emit: Internal generic functions
emit: Internal generic functions
emit: Internal generic functions
emit: Internal generic functions
emit: Internal generic functions
emit: Internal generic functions
emit: Internal generic functions
emit: Internal generic functions
emit: Internal generic functions
emit-metadata: Internal functions
emit-node: Internal generic functions
emit-node: Internal generic functions
emit-node: Internal generic functions
emit-node: Internal generic functions

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

G
Generic Function, emit: Internal generic functions
Generic Function, emit-node: Internal generic functions
Generic Function, multi-emit: Exported generic functions
Generic Function, render: Exported generic functions
Generic Function, render-section: Exported generic functions

M
Macro, define-emitter: Internal macros
Macro, define-simple-emitter: Internal macros
Macro, with-tag: Internal macros
Macro, with-template: Exported macros
Method, emit: Internal generic functions
Method, emit: Internal generic functions
Method, emit: Internal generic functions
Method, emit: Internal generic functions
Method, emit: Internal generic functions
Method, emit: Internal generic functions
Method, emit: Internal generic functions
Method, emit: Internal generic functions
Method, emit: Internal generic functions
Method, emit: Internal generic functions
Method, emit: Internal generic functions
Method, emit: Internal generic functions
Method, emit: Internal generic functions
Method, emit: Internal generic functions
Method, emit: Internal generic functions
Method, emit: Internal generic functions
Method, emit: Internal generic functions
Method, emit: Internal generic functions
Method, emit: Internal generic functions
Method, emit: Internal generic functions
Method, emit: Internal generic functions
Method, emit: Internal generic functions
Method, emit: Internal generic functions
Method, emit: Internal generic functions
Method, emit: Internal generic functions
Method, emit: Internal generic functions
Method, emit: Internal generic functions
Method, emit: Internal generic functions
Method, emit-node: Internal generic functions
Method, emit-node: Internal generic functions
Method, emit-node: Internal generic functions
Method, multi-emit: Exported generic functions
Method, render: Exported generic functions
Method, render-section: Exported generic functions
multi-emit: Exported generic functions
multi-emit: Exported generic functions
multi-file-toc: Exported functions

N
node-to-html-string: Exported functions
node-to-stream: Exported functions

P
print-attribute: Internal functions

R
render: Exported generic functions
render: Exported generic functions
render-section: Exported generic functions
render-section: Exported generic functions

S
single-file-toc: Exported functions

T
template: Exported functions
template-section: Exported functions

W
with-tag: Internal macros
with-template: Exported macros

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

Next: , Previous: , Up: Indexes   [Contents][Index]

A.3 Variables

Jump to:   *  
S  
Index Entry  Section

*
*current-section-id*: Internal special variables
*document-section-format-control*: Exported special variables
*image-format-control*: Exported special variables
*multi-emit*: Exported special variables
*output-stream*: Internal special variables
*section-depth*: Internal special variables
*section-tree*: Exported special variables
*template*: Exported special variables

S
Special Variable, *current-section-id*: Internal special variables
Special Variable, *document-section-format-control*: Exported special variables
Special Variable, *image-format-control*: Exported special variables
Special Variable, *multi-emit*: Exported special variables
Special Variable, *output-stream*: Internal special variables
Special Variable, *section-depth*: Internal special variables
Special Variable, *section-tree*: Exported special variables
Special Variable, *template*: Exported special variables

Jump to:   *  
S  

Previous: , Up: Indexes   [Contents][Index]

A.4 Data types

Jump to:   C   H   P   S   T  
Index Entry  Section

C
Class, html: Exported classes
Class, template: Exported classes
common-html: The common-html system
common-html: The common-html package
common-html.emitter: The common-html<dot>emitter package
common-html.multi-emit: The common-html<dot>multi-emit package
common-html.template: The common-html<dot>template package
common-html.toc: The common-html<dot>toc package

H
html: Exported classes

P
Package, common-html: The common-html package
Package, common-html.emitter: The common-html<dot>emitter package
Package, common-html.multi-emit: The common-html<dot>multi-emit package
Package, common-html.template: The common-html<dot>template package
Package, common-html.toc: The common-html<dot>toc package

S
System, common-html: The common-html system

T
template: Exported classes

Jump to:   C   H   P   S   T