This is the common-html Reference Manual, version 0.1, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Feb 26 16:06:00 2024 GMT+0.
The main system appears first, followed by any subsystem dependency.
common-htmlAn HTML parser/emitter for CommonDoc.
Fernando Borretti <eudoxiahp@gmail.com>
Fernando Borretti <eudoxiahp@gmail.com>
(GIT git@github.com:CommonDoc/common-html.git)
MIT
# CommonHTML
[](https://travis-ci.org/CommonDoc/common-html)
[](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.
0.1
common-doc (system).
plump (system).
anaphora (system).
alexandria (system).
src (module).
Modules are listed depth-first from the system components tree.
common-html/srccommon-html (system).
package.lisp (file).
template.lisp (file).
emitter.lisp (file).
multi-emit.lisp (file).
toc.lisp (file).
common-html.lisp (file).
Files are sorted by type and then listed depth-first from the systems components trees.
common-html/common-html.asdcommon-html/src/package.lispcommon-html/src/template.lispcommon-html/src/emitter.lispcommon-html/src/multi-emit.lispcommon-html/src/toc.lispcommon-html/src/common-html.lispcommon-html/src/template.lisppackage.lisp (file).
src (module).
*template* (special variable).
render (generic function).
render-section (generic function).
template (function).
template (class).
template-section (function).
with-template (macro).
common-html/src/emitter.lisptemplate.lisp (file).
src (module).
*document-section-format-control* (special variable).
*image-format-control* (special variable).
node-to-html-string (function).
node-to-stream (function).
*output-stream* (special variable).
*section-depth* (special variable).
define-emitter (macro).
define-simple-emitter (macro).
emit (generic function).
emit-metadata (function).
print-attribute (function).
with-tag (macro).
common-html/src/multi-emit.lispemitter.lisp (file).
src (module).
*multi-emit* (special variable).
*section-tree* (special variable).
multi-emit (method).
*current-section-id* (special variable).
assign-container (function).
emit-node (method).
emit-node (method).
emit-node (method).
common-html/src/toc.lispmulti-emit.lisp (file).
src (module).
multi-file-toc (function).
single-file-toc (function).
common-html/src/common-html.lisptoc.lisp (file).
src (module).
emit-document (method).
emit-document (method).
html (class).
Packages are listed by definition order.
common-html.emitterEmit HTML5 from a CommonDoc document.
anaphora.
common-doc.
common-lisp.
*document-section-format-control* (special variable).
*image-format-control* (special variable).
node-to-html-string (function).
node-to-stream (function).
*output-stream* (special variable).
*section-depth* (special variable).
define-emitter (macro).
define-simple-emitter (macro).
emit (generic function).
emit-metadata (function).
print-attribute (function).
with-tag (macro).
common-html.multi-emitcommon-doc.
common-lisp.
*multi-emit* (special variable).
*section-tree* (special variable).
multi-emit (generic function).
*current-section-id* (special variable).
assign-container (function).
emit-node (generic function).
common-html.templateDocument templates.
common-lisp.
*template* (special variable).
render (generic function).
render-section (generic function).
template (function).
template (class).
template-section (function).
with-template (macro).
common-html.tocUtilities for building an HTML table of contents.
common-lisp.
multi-file-toc (function).
single-file-toc (function).
Definitions are sorted by export status, category, package, and then by lexicographic order.
A format control string used to render document+section links.
A format control string to render image URLs.
Whether we are in multi-file emission or not. nil by default.
A map of section references to parent section references.
The template that will be used by template and template-section.
Execute ‘body‘ with the template set to ‘template‘.
Generate and HTML table of contents for a multi-file document.
Return an HTML string from a node.
Emit a node into a stream.
Generate and HTML table of contents for a single-file document.
Like render, only using the *template* special variable.
Like render-section, but uses the *template* special variable.
document) directory &key max-depth) ¶Render a document instance and its children (As an HTML string) into an HTML string.
Render a section of a document into an HTML string.
html) (node document-node) stream) ¶Render a node to HTML stream.
common-doc.format.
html) (doc document) stream) ¶Render a document to HTML stream.
common-doc.format.
The stream the HTML will be written to.
The depth of ‘section‘ classes. Used to produce header numbers, e.g. ‘h1, ‘h3‘.
Define an emitter method.
Define a simple emitter.
Execute body after opening and before closing a tag.
Print HTML attributes.
Print a key value pair as HTML.
Create an HTML representation of a CommonDoc document.
document)) ¶Emit a full document.
section)) ¶Emit a section.
cell)) ¶row)) ¶Emit a row.
table)) ¶Emit a table.
figure)) ¶Emit a figure.
image)) ¶Emit an image.
definition-list)) ¶ordered-list)) ¶unordered-list)) ¶definition)) ¶Emit a definition list item.
list-item)) ¶web-link)) ¶Emit a web link.
document-link)) ¶Emit a document link.
block-quote)) ¶inline-quote)) ¶code-block)) ¶Emit a code block.
subscript)) ¶superscript)) ¶code)) ¶strikethrough)) ¶underline)) ¶italic)) ¶bold)) ¶paragraph)) ¶text-node)) ¶Emit a text node.
content-node)) ¶The generic emitter for content nodes.
list)) ¶Emit a list.
section) &key directory doc depth max-depth) ¶Emit a section node.
content-node) &key directory doc depth max-depth) ¶Emit a content node.
document-node) &key directory doc depth max-depth) ¶Emit a document node.
| Jump to: | A D E F G M N P R S T W |
|---|
| Jump to: | A D E F G M N P R S T W |
|---|
| Jump to: | *
S |
|---|
| Jump to: | *
S |
|---|
| Jump to: | C E F H M P S T |
|---|
| Jump to: | C E F H M P S T |
|---|