The geneva Reference Manual

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

The geneva Reference Manual

This is the geneva Reference Manual, generated automatically by Declt version 4.0 beta 2 "William Riker" on Mon Aug 15 04:41:10 2022 GMT+0.

Table of Contents


1 Introduction

Open Geneva

Geneva is the portable document preparation system. It follows the principle Write once, read anywhere. Geneva enables the creation and archival of truly portable documents by isolating document content and structure from document presentation.

Geneva achieves this by introducing a generic but well defined document structure independent from its stored representation. In addition to classic document features such as paragraphs, listings, sections, tables and text markup, Geneva defines a generic media type for embedding arbitrary content and enable extensibility in a plug-in oriented way.

Open Geneva is the reference implementation of Geneva written in Common Lisp. It implements Geneva and defines a diverse toolchain composed of input interfaces and presentation backends. Its input interfaces, such as the plain text oriented Mk2 markup language and the Geneva API, are user and programmer facing frontends to document authoring. Its presentation backends render documents to several targets including web, print and plain text media.

Documentation

Dependencies


2 Systems

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


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

2.1 geneva

Core of the Geneva document preparation system. Provides data structures and syntax sugar.

Author

Max Rottenkolber <max@mr.gy>

License

GNU AGPL

Dependencies
  • split-sequence (system).
  • named-readtables (system).
Source

geneva.asd.

Child Components

3 Files

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


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

3.1 Lisp


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

3.1.1 geneva/geneva.asd

Source

geneva.asd.

Parent Component

geneva (system).

ASDF Systems

geneva.


3.1.2 geneva/geneva.lisp

Source

geneva.asd.

Parent Component

geneva (system).

Packages

3.1.3 geneva/normalize.lisp

Dependency

geneva.lisp (file).

Source

geneva.asd.

Parent Component

geneva (system).

Internals

3.1.4 geneva/struct.lisp

Dependency

geneva.lisp (file).

Source

geneva.asd.

Parent Component

geneva (system).

Public Interface
Internals

3.1.5 geneva/macros.lisp

Dependencies
Source

geneva.asd.

Parent Component

geneva (system).

Public Interface

3.1.6 geneva/syntax.lisp

Dependencies
Source

geneva.asd.

Parent Component

geneva (system).

Public Interface

syntax (special variable).

Internals

make-markup-reader (function).


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

3.1.7 geneva/utilities.lisp

Dependencies
Source

geneva.asd.

Parent Component

geneva (system).

Packages

geneva.utilities.

Public Interface
Internals

document-index-2 (function).


4 Packages

Packages are listed by definition order.


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

4.1 geneva.macros

Macros and reader macros to help with procedural creation of Geneva documents.

Source

geneva.lisp.

Use List
  • common-lisp.
  • editor-hints.named-readtables.
  • geneva.
Public Interface
Internals

make-markup-reader (function).


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

4.2 geneva.utilities

Shared utility functions used by various components of Geneva.

Source

utilities.lisp.

Use List
  • common-lisp.
  • geneva.
  • split-sequence.
Public Interface
Internals

document-index-2 (function).


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

4.3 geneva

Geneva core package. Exports functions to programatically create
and inspect _Geneva documents_.

In Open Geneva a _document_ is represented as a _list_ of _document elements_. A _document element_ can be obtained using the element constructors {make-paragraph}, {make-listing}, {make-table}, {make-media} and {make-section}. In order to ensure integrity, it is recommended to use {make-document} to produce _documents_.

_Rich text_ is represeted as a _list_ of _text tokens_. A _text token_ may be a _string_ or an object obtained using the text token constructors {make-bold}, {make-italic}, {make-fixed-width} and {make-url}.

_Document elements_ and _text tokens_ can be inspected using the readers {content-type} and {content-values}.

_Documents_ and _document elements_ are printable and readable using the Common Lisp printer and reader.

*Exceptional Situations:*

All functions external to this _package_ validate their parameters and will signal an _error_ of _type_ {type-error} on mismatch.

*See Also:*

+ [Geneva Document Specification](geneva-document.html)
+ [Open Geneva User Manual](open-geneva.html)

Source

geneva.lisp.

Use List
  • common-lisp.
  • split-sequence.
Used By List
Public Interface
Internals

5 Definitions

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


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

5.1 Public Interface


Next: , Previous: , Up: Public Interface   [Contents][Index]

5.1.1 Special variables

Special Variable: *default-index-caption*

Default caption for indexes.

Package

geneva.utilities.

Source

utilities.lisp.

Special Variable: *index-headers-p*

Controls wether headers are numbered.

Package

geneva.utilities.

Source

utilities.lisp.

Special Variable: *index-p*

Controls wether an index is rendered.

Package

geneva.utilities.

Source

utilities.lisp.

Special Variable: syntax

*Description:*

Readtable containing reader macros for markup literals. Defines {#B}, {#I}, {#F} and {#U} to be expanded to code generating Geneva markup at read-time using _make-bold_, _make-italic_, _make-fixed-width_ and _make-url_ respectively.

*Notes:*

This readtable is registered as _geneva.macros:syntax_. In
order to use it invoke {named-readtable}’s {in-readtable} like so:

#code#
(in-readtable geneva.macros:syntax)
#

*Examples:*

#code#
#b"bold string" ≡ (geneva:make-bold "bold string")
#i"italic string" ≡ (geneva:make-italic "italic string") #f"fixed-width string" ≡ (geneva:make-fixed-width "fixed-width string") #u"url string" ≡ (geneva:make-url "url string")
#

*See Also:*

+ Named-Readtables ({editor-hints.named-readtables})

Package

geneva.macros.

Source

syntax.lisp.


5.1.2 Macros

Macro: document (&rest content)

*Arguments and Values:*

_document_—_forms_ which evaluate to Geneva _elements_.

*Description:*

{section} returns a Geneva _docuent_ with _content_ as if by {geneva:make-document}.

*Notes:*

#code#
(document {content}*) ≡ (make-document (list {content}*)) #

Package

geneva.macros.

Source

macros.lisp.

Macro: listing (&rest items)

*Arguments and Values:*

_items_—_forms_ which evaluate to Geneva _rich text_.

*Description:*

{listing} returns a Geneva listing of _items_ as if by {geneva:make-listing}.

*Notes:*

#code#
(listing {items}*) ≡ (make-listing (list {items}*)) #

Package

geneva.macros.

Source

macros.lisp.

Macro: media ((&rest description) url)

*Arguments and Values:*

_description_—_forms_ which evaluate to Geneva _text tokens_.

_url_—a _form_ which evaluates to a _string_ designating an URL.

*Description:*

{media} returns a Geneva _media element_ for _url_ with _description_ as if by {geneva:make-media}.

*Notes:*

#code#
(media ({description}*) {url})
≡ (make-media (list {description}*) {url})
#

Package

geneva.macros.

Source

macros.lisp.

Macro: paragraph (&rest text)

*Arguments and Values:*

_text_—_forms_ which evaluate to Geneva _text tokens_.

*Description:*

{paragraph} returns a Geneva paragraph made up of _text_ as if by {geneva:make-paragraph}.

*Notes:*

#code#
(paragraph {text}*) ≡ (make-paragraph (list {text}*))
#

Package

geneva.macros.

Source

macros.lisp.

Macro: plaintext ((&rest description) plaintext)

*Arguments and Values:*

_description_—_forms_ which evaluate to Geneva _text tokens_.

_plaintext_—a _form_ which evaluates to a _string_.

*Description:*

{plaintext} returns a Geneva _plaintext element_ for _plaintext_ with _description_ as if by {geneva:make-plaintext}.

*Notes:*

#code#
(plaintext ({description}*) {plaintext})
≡ (make-plaintext (list {description}*) {plaintext})
#

Package

geneva.macros.

Source

macros.lisp.

Macro: section ((&rest header) &rest content)

*Arguments and Values:*

_header_—_forms_ which evaluate to Geneva _text tokens_.

_content_—_forms_ which evaluate to Geneva _elements_.

*Description:*

{section} returns a Geneva _section element_ with _header_ and _content_ as if by {geneva:make-section}.

*Notes:*

#code#
(section ({header}*) {body}*)
≡ (make-section (list {header}*) (list {body}*))
#

Package

geneva.macros.

Source

macros.lisp.

Macro: table ((&rest description) &rest rows)

*Arguments and Values:*

_description_—_forms_ which evaluate to Geneva _text tokens_.

_rows_—a list of column lists containing _forms_ which evaluate to Geneva _text tokens_.

*Description:*

{table} returns a Geneva table with _rows_ and _description_ as if by {geneva:make-table}.

*Examples:*

#code#
(table ("10° Celsius in various units.")
(("Fahrenheit") ((prin1-to-string (+ (* 1.8 10) 32)))) (("Kelvin") ((prin1-to-string (+ 10 273.15)))))
≡ (make-table (list "10° Celsius in various units.")
(list (list "Fahrenheit")
(list (prin1-to-string (+ (* 1.8 10) 32)))) (list (list "Kelvin")
(list (prin1-to-string (+ 10 273.15)))))
#

Package

geneva.macros.

Source

macros.lisp.


Previous: , Up: Public Interface   [Contents][Index]

5.1.3 Ordinary functions

Function: align-string (string alignment &optional columns)

Return aligned copy of STRING with respect to COLUMNS. Possible values for ALIGNMENT are :RIGHT and :CENTER.

Package

geneva.utilities.

Source

utilities.lisp.

Function: content-type (content)

*Arguments and Values:*

_content_—an _element_ or a _text token_.

*Description*:

{content-type} returns a _keyword_ denoting the type of _content_ which may be one of {:paragraph}, {:listing}, {:table}, {:plaintext}, {:media}, {:section}, {:plain}, {:bold}, {:italic}, {:fixed-width} or {:url}.

Package

geneva.

Source

struct.lisp.

Function: content-values (content)

*Arguments and Values:*

_content_—an _element_ or a _text token_.

*Description*:

{content-values} returns the components of _content_. The returned values are the _normalized_ forms of their respective content constructor’s arguments and therefore depend on the type of _content_.

Package

geneva.

Source

struct.lisp.

Function: descend-level (level)

Returns the next deeper LEVEL.

Package

geneva.utilities.

Source

utilities.lisp.

Function: document-index (document)

Returns section hierarchy on DOCUMENT.

Package

geneva.utilities.

Source

utilities.lisp.

Function: incf-level (level)

Increment LEVEL by one.

Package

geneva.utilities.

Source

utilities.lisp.

Function: level-string (level)

Return string representation for LEVEL.

Package

geneva.utilities.

Source

utilities.lisp.

Function: make-bold (string)

*Arguments and Values:*

_string_—a _string_.

*Description*:

{make-bold} returns a _text token_ of type {:bold} for _string_.

Package

geneva.

Source

struct.lisp.

Function: make-document (elements)

*Arguments and Values:*

_elements_—a _list_ of _document elements_.

*Description*:

{make-document} returns a _document_ consisting of _elements_.

Package

geneva.

Source

struct.lisp.

Function: make-fixed-width (string)

*Arguments and Values:*

_string_—a _string_.

*Description*:

{make-fixed-width} returns a _text token_ of type {:fixed-width} for _string_.

Package

geneva.

Source

struct.lisp.

Function: make-italic (string)

*Arguments and Values:*

_string_—a _string_.

*Description*:

{make-italic} returns a _text token_ of type {:bold} for _string_.

Package

geneva.

Source

struct.lisp.

Function: make-listing (items)

*Arguments and Values:*

_items_—a _list_ of _rich text_ sequences.

*Description*:

{make-listing} returns a _document element_ of type {:listing} with _items_.

Package

geneva.

Source

struct.lisp.

Function: make-media (description url)

*Arguments and Values:*

_description_—a _rich text_ sequence.

_url_—a _string_.

*Description*:

{make-media} returns a _document element_ of type {:media} with _description_ and _url_.

Package

geneva.

Source

struct.lisp.

Function: make-paragraph (text)

*Arguments and Values:*

_text_—a _rich text_ sequence.

*Description*:

{make-paragraph} returns _document element_ of type {:paragraph} with _text_.

Package

geneva.

Source

struct.lisp.

Function: make-plaintext (description plaintext)

*Arguments and Values:*

_description_—a _rich text_ sequence.

_plaintext_—a _string_.

*Description*:

{make-plaintext} returns a _document element_ of type {:plaintext} with _description_ and _plaintext_.

Package

geneva.

Source

struct.lisp.

Function: make-section (header elements)

*Arguments and Values:*

_header_—a _rich text_ sequence.

_elements_—a _list_ of _document elements_.

*Description*:

{make-section} returns a _document element_ of type {section} with _header_ and _elements_.

Package

geneva.

Source

struct.lisp.

Function: make-table (description rows)

*Arguments and Values:*

_description_—a _rich text_ sequence.

_rows_—a two dimensional list of _rich text_ sequences.

*Description*:

{make-table} returns a _document element_ of type {:table} with _description_ and _rows_.

Package

geneva.

Source

struct.lisp.

Function: make-url (string &optional url)

*Arguments and Values:*

_string_—a _string_.

_url_—a _string_.

*Description*:

{make-url} returns a _text token_ of type {:url} for _string_. If _url_ is given then _string_ is used as the label, otherwise _string_ is both label and URL.

Package

geneva.

Source

struct.lisp.

Function: null-level ()

Returns the root level.

Package

geneva.utilities.

Source

utilities.lisp.

Function: text-string (text)

Return TEXT string without markup.

Package

geneva.utilities.

Source

utilities.lisp.

Function: wrap-string (string &optional columns)

Return copy of STRING with spaces replaced by newlines so that lines do not exceed COLUMNS characters when possible. COLUMNS defaults to 72.

Package

geneva.utilities.

Source

utilities.lisp.


5.2 Internals


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

5.2.1 Special variables

Special Variable: *whitespace*

Characters considered whitespace.

Package

geneva.

Source

normalize.lisp.


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

5.2.2 Ordinary functions

Function: assert-content (thing)

Assert that thing is a valid element or text token. On failure signal a TYPE-ERROR.

Package

geneva.

Source

struct.lisp.

Function: assert-element (thing)

Assert that THING is a valid element. On failure signal a TYPE-ERROR.

Package

geneva.

Source

struct.lisp.

Function: assert-rich-text (thing)

Assert that THING is a valid rich text sequence. On failure signal a TYPE-ERROR.

Package

geneva.

Source

struct.lisp.

Function: assert-text-token (thing)

Assert that THING is a valid text token. On failure signal a TYPE-ERROR.

Package

geneva.

Source

struct.lisp.

Function: document-index-2 (document level)

Base function for DOCUMENT-INDEX.

Package

geneva.utilities.

Source

utilities.lisp.

Function: join-strings (text)

Join :PLAIN text tokens in TEXT.

Package

geneva.

Source

normalize.lisp.

Function: make-markup (type &rest strings)

Make markup of TYPE for STRINGS. Signal a TYPE-ERROR if STRINGS are not of type string.

Package

geneva.

Source

struct.lisp.

Function: make-markup-reader (constructor)

Returns function that reads string literal and applies CONSTRUCTOR.

Package

geneva.macros.

Source

syntax.lisp.

Function: make-object (type description &rest content)

Make an object of TYPE for DESCRIPTION text and CONTENT. Assert that DESCRIPTION is a valid rich text sequence.

Package

geneva.

Source

struct.lisp.

Function: normalize-plaintext (string)

Remove leading and ending whitespace, global indent and whitespace line-suffixes from plaintext STRING .

Package

geneva.

Source

normalize.lisp.

Function: normalize-text (text)

Remove empty markup and join adjacent strings in TEXT, then remove superfluous whitespace.

Package

geneva.

Source

normalize.lisp.

Function: normalize-text-item (item &key trim)

Normalize *WHITESPACE* in text ITEM and optionally TRIM :LEFT or :RIGHT.

Package

geneva.

Source

normalize.lisp.

Function: normalize-text-whitespace (text)

Remove obsoltete whitespace from TEXT.

Package

geneva.

Source

normalize.lisp.

Function: normalize-whitespace (string &key trim)

Normalize *WHITESPACE* in STRING and optionally TRIM :LEFT, :RIGHT or :BOTH.

Package

geneva.

Source

normalize.lisp.

Function: position-non-whitespace-item (text &optional from-end)

Get position of first non-whitespace item in TEXT and maybe start FROM-END.

Package

geneva.

Source

normalize.lisp.

Function: remove-empty-markup (text)

Remove empty markup from TEXT.

Package

geneva.

Source

normalize.lisp.

Function: trim-whitespace-items (text)

Remove whitespace from start and end of TEXT.

Package

geneva.

Source

normalize.lisp.

Function: trim-whitespace-suffixes (lines)

Trim whitespace suffixes from LINE.

Package

geneva.

Source

normalize.lisp.


Appendix A Indexes


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

A.1 Concepts


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

A.2 Functions

Jump to:   A   C   D   F   I   J   L   M   N   P   R   S   T   W  
Index Entry  Section

A
align-string: Public ordinary functions
assert-content: Private ordinary functions
assert-element: Private ordinary functions
assert-rich-text: Private ordinary functions
assert-text-token: Private ordinary functions

C
content-type: Public ordinary functions
content-values: Public ordinary functions

D
descend-level: Public ordinary functions
document: Public macros
document-index: Public ordinary functions
document-index-2: Private ordinary functions

F
Function, align-string: Public ordinary functions
Function, assert-content: Private ordinary functions
Function, assert-element: Private ordinary functions
Function, assert-rich-text: Private ordinary functions
Function, assert-text-token: Private ordinary functions
Function, content-type: Public ordinary functions
Function, content-values: Public ordinary functions
Function, descend-level: Public ordinary functions
Function, document-index: Public ordinary functions
Function, document-index-2: Private ordinary functions
Function, incf-level: Public ordinary functions
Function, join-strings: Private ordinary functions
Function, level-string: Public ordinary functions
Function, make-bold: Public ordinary functions
Function, make-document: Public ordinary functions
Function, make-fixed-width: Public ordinary functions
Function, make-italic: Public ordinary functions
Function, make-listing: Public ordinary functions
Function, make-markup: Private ordinary functions
Function, make-markup-reader: Private ordinary functions
Function, make-media: Public ordinary functions
Function, make-object: Private ordinary functions
Function, make-paragraph: Public ordinary functions
Function, make-plaintext: Public ordinary functions
Function, make-section: Public ordinary functions
Function, make-table: Public ordinary functions
Function, make-url: Public ordinary functions
Function, normalize-plaintext: Private ordinary functions
Function, normalize-text: Private ordinary functions
Function, normalize-text-item: Private ordinary functions
Function, normalize-text-whitespace: Private ordinary functions
Function, normalize-whitespace: Private ordinary functions
Function, null-level: Public ordinary functions
Function, position-non-whitespace-item: Private ordinary functions
Function, remove-empty-markup: Private ordinary functions
Function, text-string: Public ordinary functions
Function, trim-whitespace-items: Private ordinary functions
Function, trim-whitespace-suffixes: Private ordinary functions
Function, wrap-string: Public ordinary functions

I
incf-level: Public ordinary functions

J
join-strings: Private ordinary functions

L
level-string: Public ordinary functions
listing: Public macros

M
Macro, document: Public macros
Macro, listing: Public macros
Macro, media: Public macros
Macro, paragraph: Public macros
Macro, plaintext: Public macros
Macro, section: Public macros
Macro, table: Public macros
make-bold: Public ordinary functions
make-document: Public ordinary functions
make-fixed-width: Public ordinary functions
make-italic: Public ordinary functions
make-listing: Public ordinary functions
make-markup: Private ordinary functions
make-markup-reader: Private ordinary functions
make-media: Public ordinary functions
make-object: Private ordinary functions
make-paragraph: Public ordinary functions
make-plaintext: Public ordinary functions
make-section: Public ordinary functions
make-table: Public ordinary functions
make-url: Public ordinary functions
media: Public macros

N
normalize-plaintext: Private ordinary functions
normalize-text: Private ordinary functions
normalize-text-item: Private ordinary functions
normalize-text-whitespace: Private ordinary functions
normalize-whitespace: Private ordinary functions
null-level: Public ordinary functions

P
paragraph: Public macros
plaintext: Public macros
position-non-whitespace-item: Private ordinary functions

R
remove-empty-markup: Private ordinary functions

S
section: Public macros

T
table: Public macros
text-string: Public ordinary functions
trim-whitespace-items: Private ordinary functions
trim-whitespace-suffixes: Private ordinary functions

W
wrap-string: Public ordinary functions

Jump to:   A   C   D   F   I   J   L   M   N   P   R   S   T   W