Disseminate

Document Processing

• Features: Basic
• Features: Advanced
• Quickstart

Installation

• MacOS (Homebrew)
• MacOS (Pip)
• Linux (Pip)

Markup Language

• Header
  • Entries
  • Includes
  • Inheritance
  • Additional Notes
• Tags
• Macros

Projects

• Documents
• Templates

Interfaces

• Command-line

Development

• API Documentation
• Release Notes

• Index

Header

Headers contain useful meta information on the document and sub-documents, which may impact how the document, sub-documents and tags are rendered.

Headers are optionally present at the start of a disseminate document. Headers are enclosed by 3 or more hyphens (’-‘).

---
title: Disseminate Headers
author: Justin L Lorieau
template: component
targets: html, tex, pdf
include:
  part1/introduction.dm
  part1/cakes.dm
  part1/tarts.dm
---

Since documents can include sub-documents, the context of a parent document is copied over to the sub-documents, which in turn, can overwrite these values.

Entries

Basic Entries

title

The project’s title

examples

title: My First Document

short

The document’s short title

examples

short: First

author

The document’s author

examples

author: Justin L Lorieau

targets

The document target formats

values

html, tex, pdf, epub, txt

examples

targets: html, tex, pdf

template

The template to use in rendering the document

values

• articles/basic

• books/novel

• books/tufte

• default

• reports/basic

examples

template: book/tufte

include

The sub-documents to include in a project

notes

See the section on Includes.

Render Options

doc_id

The unique document identifier, which may be used to reference labels in other documents.

examples

doc_id: chapters-chap1-dm

label_fmts

The formats for labels in rendering the document.

examples

label_fmts:
   document: "@label.title"
   ref_document: "@label.title"
   heading: "@label.tree_number."
   heading_part: "Part @label.part_number. "
   heading_chapter': "Chapter @label.chapter_number. "

label_resets

Specify which label kinds reset the counters f9r other label kinds.

examples

A project may need to have the the chapter, section and subsection numbers reset every time there is a new part. To achieve this sort of reset, the following entry would be entered in the heading of the root document.

label_resets:
   part: chapter, section, subsection

relative_links

If True (default), html links are referenced relative to the document’s path. If False, links are absolute.

examples

relative_links: True

base_url

If absolute links are used and relative_links is False, then the base_url string will be prepended to links.

examples

base_url: /{target}/{subpath}

process_paragraphs

A list of context entries for which paragraphs should be processed

notes

By default, automated paragraph processing is enabled for the body entry.

examples

process_paragraphs: body

Includes

Sub-documents can be included in the header. Sub-documents may represent parts of books, chapters or sections. Sub-documents can be furthermore nested to form projects with multiple sub-levels. The include statement lists the sub-documents directly subordinate to a document.

include

Sub-documents to include in the document tree

notes

Sub-documents and their paths are listed one per line with at least two spaces before each entry. The paths are relative to the current document.

examples

include:
  part1/introduction.dm
  part1/cakes.dm
  part1/tarts.dm

A project consists of one root document and, possibly, one more included documents. It is alternatively known as a document tree.

A root document is the first document in a project, and it is not included by any other document.

A child document is a document that was included by a document.

A parent document is the document that was included by a document.

Inheritance

Most header entries from parent documents are available to child documents. If child documents specify their own version of these entries, then these values will be overwritten.

For example, a parent document might specify a title entry in the header. If the parent document includes a child document, then the title entry will be the same for the child document, unless the child document’s header also specifies a title entry, in which case this entry will be used.

For this reason, it is useful to specify settings for an entire project in the header of the root document, then to overwrite these values (if needed) in the child document headers.

From a technical perspective, header entries are loaded into the context for a document. The context is a Python dictionary that holds the variables needed to render a document.

Additional Notes

How do I include quotations in header entries?

Quotations within a sentence or string will not be removed

example

title: This is my "test" title

However, quotations on the end of a sentence or string will be removed. To include these quotations, simply add the quotation mark twice on each side of the entry.

example

title: ""This is my test title""

In the above example, the title will be "This is my test title" with the double quotations.