Installation

Markup Language

Projects

Interfaces

Command-line

Development

Index

Features: Basic¶

1) Header and Body¶

Documents can optionally have a header, and they can optionally have a body.

---
title: This is my title
---
This is @i{my} body

The header is placed at the start of the document between --- delimiters, and the body follows. The header follows a YAML format and the body follows the disseminate format.

2) Document Trees¶

Projects can be as simple as one document, or it can be a book comprising multiple parts and chapters. Documents are included in the header of the root document.

src/main.dm¶

---
title: Fundamentals of NMR Spectroscopy
author: Justin L Lorieau
include:
    part1/part1.dm
    part2/part2.dm
---

And each document can contain its own documents.

src/part1/part1.dm¶

---
part: Solution NMR
include:
    chapter1/chapter1.dm
    chapter2/chapter2.dm
---

Values set in the parent document (e.g. author carry over to the subdocuments)

3) Uniform Language¶

All tags use the same format. The following shows three valid tags.

@chapter
@chapter{My First Chapter}
@chapter[id=first-chapter]{My First Chapter}

All tags start with the @ character and are followed by a keyword– chapter in this case. Any keyword is allowed, but only a subset have special functionality.

The contents of the tag are written between the ‘{‘ and ‘}’ curly braces. The tag contents represent what will be rendered. The contents are optional and may be retrieved from the header values.

The attributes of the tag are written between the ‘[‘ and ‘]’ square brackets. The tag attributes represent how a tag will be rendered. The attributes are also optional, and they can be key-value pairs (e.g. [width=1in] or positional (e.g. [nolabel]).

Additionally, tags can be arbritrarily nested, changing how the are rendered. For example, the following @figure tag includes an image and a caption.

@figure{
    @img[width=25%]{figures/fig1.svg}
    @caption{This is my first figure}
    }

4) Macros¶

Combinations of text and tags may be repeated frequently in a project. Macros can be used to simplify these blocks of text.

---
@H2O: H@sub{2}O
---
My favorite molecule is @H2O.

In this example, the @H2O macro is replaced with the text block H@sub{2}O.

5) Templates and Typography¶

A top priority for disseminate is the production of documents that follow good typographical style. This objective is important in improving the readability and aesthetics of documents.

First, the templates aim to follow good typographical rules. Templates are specified in the header of a document or in the header of a root document, if a project has multiple subdocuments.

---
templates: books/tufte
---

In this example, the final document is rendered using the Tufte book format.

Second, typographic elements are automicatically converted, such as opening and closing double quotes, en-dashes and em-dashes and ellipses.

6) Internal Labels¶

Labels to other documents, chapters, sections, figures and tables are handled consistently. Each of these content elements can have a label identifier specified.

@figure[id=intro-figure]{
    img{figures/fig1.png}
}

In this case, the label identifier is specified by the id attribute, and this figure’s identifier is intro-figure.

References to labels are done with the @ref tag.

In @ref{intro-figure}, the introductory figure is shown.

The @ref tag accepts the label identifier, and it will automatically render the label in the format specified by the template.

Label identifiers must be unique for each document. If a non-unique identifier is used for 2 or more documents, then the document doc_id must be prepended with a semi-colon.

In @ref{chapters-chap1-dm:intro-figure}, the introductory figure is shown.

The doc_id is automatically generated by converting path delimiters (/ and \) and periods (.) to dashes. The doc_id above was generated for the sub-document located at chapters/chap1.dm.

Alternatively, a unique doc_id can be specified in the header of a given document.

---
doc_id: introduction
---

7) Multiple Target Formats¶

Disseminate renders to multiple target formats. The target formats are specified in the header.

---
targets: html, tex, pdf, epub
---

In this case, the document will render in html, tex, pdf and epub formats.

8) Automatic Conversions¶

Disseminate includes builders to convert files to the formats needed for various targets, like html, tex, pdf and epub.

---
targets: html, tex, pdf
---
@img{media/figs/fig1.svg}

In the above example, the fig1.svg image is converted to pdf format when rendered in tex and pdf formats, and it is inserted directly for the html format.

When multiple conversion format options exist, image formats in vector graphic formats (pdf, svg) are favored.

9) Inline Plots and Diagrams¶

One of the major objectives for disseminate is to include raw data and methodology for rendering plots and diagrams, rather than insert these as simple images. Tags can convert plots and diagram input files or these can be inserted directly inline.

@asy{figures/diagram.asy}

@asy{
    size(200);
    draw(unitcircle);
}

In the above example, the first tag renders an asymptote diagram from the source file at figures/diagram.asy. The second tag uses the asymptote source code directly. These are converted to svg format for html and epub target formats, and they are converted to pdf format for tex and pdf target formats.

10) Equations¶

Equations are written in LaTeX format. For tex and pdf target formats, the equations are inserted directly, but for html and epub target formats, these are rendered as svg images.

This is my @eq{y = mx + b} linear equation.

Equations are rendered as vector graphi images in html and epub, instead of using a javascript library because the pages should render properly when javascript is disabled, the libraries only support a subset of LaTeX’s math functionality, and javascript might not render properly in some target formats, like epub. Rendered equations have access to an extended set of LaTeX packages, including amsmath and mathtools.

Disseminate

Document Processing