Installation
Markup Language
Projects
Interfaces
Development
Command-line¶
The command-line interface (CLI) is used to render disseminate documents and to preview rendered html documents with a built-in web server.
Disseminate is invoked on the command line through the dm command.
The disseminate main CLI includes the following help option:
$ dm --help
Usage: dm [OPTIONS] COMMAND [ARGS]...
Disseminate Document Processor
Options:
--version Show the version and exit.
--debug Show debugging information
--help Show this message and exit.
Commands:
build Build a disseminate project
init Initialize a new template project
preview Preview documents with a local webserver
setup Setup and configuration options
Disseminate includes a series of sub-commands.
init¶
The init sub-command initializes and lists template projects to start
a new project in disseminate.
The init help presents the following options.
$ dm init --help
Usage: dm init [OPTIONS] [NAMES]...
Initialize a new template project
Options:
-o, --out-dir DIRECTORY the directory to create the project starter
--info Show detailed information on the specified project
starter
-l, --list List the available project starters
--help Show this message and exit.
The list of project starter templates can be listed.
$ dm init articles/basic/article1 - A basic article template articles/basic/essay1 - A basic essay template books/novel/novel1 - A novel template that includes chapters (not parts) books/novel/novel2 - A novel template that includes parts and chapters books/tufte/textbook1 - A textbook template that includes chapters (not parts) books/tufte/textbook2 - A textbook template that includes parts and chapters reports/basic/report1 - A basic report template
The template names are listed in red. Detailed information on a project starter
template can be listed with the --info flag. In the following example,
the detailed information for the books/tufte/textbook1 project starter
template is listed.
$ dm init books/tufte/textbook1 Textbook #1 (books/tufte/textbook1) Description A textbook template that includes chapters (not parts) A textbook is typically a project with multiple documents that may include the following heading types: - @part - @chapter - @section - @subsection - @subsubsection Template books/tufte Files src/textbook.dm src/chap1/chapter1.dm src/chap2/chapter2.dm
A new project is initialized with the init command and the template name.
$ dm books/tufte/textbook1
build¶
The build sub-command compiles the disseminate source to the target
formats.
The build help presents the following optional arguments:
$ dm build --help
Usage: dm build [OPTIONS]
Build a disseminate project
Options:
-i, --in-path PATH the directory or file path for a project root
document
-o, --out-dir DIRECTORY the target directory for the generated output
documents
-p, --progress
--help Show this message and exit.
preview¶
The preview sub-command runs a web server on the local computer (localhost)
to present the source and target format files of disseminate projects.
The web server is started as follows:
$ dm preview
[2020-11-13 07:59:40 -0600] [25806] [INFO] Goin' Fast @ http://127.0.0.1:8899
[2020-11-13 07:59:40 -0600] [25806] [INFO] Starting worker [25806
The preview sub-command help presents the following optional arguments:
$ dm preview --help
Usage: dm preview [OPTIONS]
Preview documents with a local webserver
Options:
-i, --in-path PATH the directory or file path for a project root document
-p, --port INTEGER The port to listen to for the webserver [default: 8899]
--debug Show debugging information
--help Show this message and exit.
setup¶
--check¶
Disseminate uses external software for various conversion and compilation tasks.
The --check function reports whether these software dependencies are
installed and available to disseminate.
$ dm setup --check Checking required dependencies for 'python' [ PASS ] Checking alternative dependencies for 'executables' [ PASS ] Checking dependency 'python3.6' [ PASS ] Checking dependency 'python3.7' [ PASS ] Checking dependency 'python3.8' [ PASS ] Checking dependency 'python3.9' [MISSING ] Checking required dependencies for 'packages' [ PASS ] Checking dependency 'regex>=2018.11.22' [ PASS ] Checking dependency 'jinja2>=2.10' [ PASS ] Checking dependency 'lxml>=4.3.0' [ PASS ] Checking dependency 'python-slugify>=2.0.1' [ PASS ] Checking dependency 'pdfCropMargins>=0.1.4' [ PASS ] Checking dependency 'click>=7.0' [ PASS ] Checking dependency 'sanic>=19.0' [ PASS ] Checking dependency 'pygments >=2.6' [ PASS ] Checking dependency 'pandas>=0.25' [ PASS ] Checking dependency 'diskcache>=4.1' [ PASS ] Checking dependency 'pathvalidate>=2.2' [ PASS ] Checking required dependencies for 'image external deps' [ PASS ] Checking alternative dependencies for 'executables' [ PASS ] Checking dependency 'asy' [ PASS ] Checking dependency 'convert' [ PASS ] Checking dependency 'pdf2svg' [ PASS ] Checking dependency 'pdf-crop-margins' [ PASS ] Checking dependency 'rsvg-convert' [ PASS ] Checking required dependencies for 'pdf' [ PASS ] Checking required dependencies for 'executables' [ PASS ] Checking alternative dependencies for 'compilers' [ PASS ] Checking dependency 'pdflatex' [ PASS ] Checking dependency 'xelatex' [ PASS ] Checking dependency 'lualatex' [ PASS ] Checking alternative dependencies for 'package_managers' [ PASS ] Checking dependency 'kpsewhich' [ PASS ] Checking required dependencies for 'packages' [ PASS ] Checking dependency 'graphicx' [ PASS ] Checking dependency 'caption' [ PASS ] Checking dependency 'amsmath' [ PASS ] Checking dependency 'mathtools' [ PASS ] Checking dependency 'bm' [ PASS ] Checking dependency 'easylist' [ PASS ] Checking dependency 'fancyvrb' [ PASS ] Checking dependency 'hyperref' [ PASS ] Checking dependency 'enumitem' [ PASS ] Checking dependency 'geometry' [ PASS ] Checking dependency 'xcolor' [ PASS ] Checking alternative dependencies for 'fonts' [ PASS ] Checking dependency 'ecrm1200' [ PASS ] Checking alternative dependencies for 'classes' [ PASS ] Checking dependency 'article' [ PASS ] Checking dependency 'report' [ PASS ] Checking dependency 'tufte-book' [ PASS ]
--list-signals¶
Disseminate uses signals and receivers for modular and decoupled processing of documents, tags and other objects. The list of signals and attached receivers can be listed with the following command:
$ dm setup --list-signals 1. tag_created A signal emitted when a tag is created. Receivers take a tag parameter. Receivers: a. process_hash - A receiver to create a hash for the contents of tags. order: 50 b. process_macros - A receiver for replacing macros in pre-parsed tag strings. order: 100 c. process_content - A receiver to parse the contents of tags into sub-tags. order: 200 d. process_typography - A receiver to parse the typography of tags. order: 300 e. process_paragraphs - A receiver to parse the paragraphs of tags. order: 400 2. add_file Add a file dependency to a target builder. Takes parameters, context, in_ext, target and use_cache. Receivers: a. add_file - Add a file to the target builder. order: 1000 3. document_onload Signal sent when a document is loaded. Receivers take a document or document context parameter. Receivers: a. reset_document - Reset the context and managers for a document on load. order: 100 b. load_document - Load the document text file into the document context. order: 200 c. process_headers - Process header strings for entries in a context by loading them into the context. order: 1000 d. reset_label_manager - Reset the label manager in the context on document load. order: 1050 e. process_document_label - A context processor to set the document label in the label manager. order: 1100 f. process_tags - Convert context entries into tags for entries listed the process_context_tags' context entry. order: 10000 4. ref_label_dependencies A notification emitter. Receivers: a. add_ref_labels - Find and add the labels associated with Ref tags for all tags in the context. order: 1000 5. document_tree_updated Signal sent when a root document or one of its sub-documents was re-loaded. Takes a root document as a parameter. Receivers: a. add_target_builders - Add target builders to a document context order: 2000 b. set_navigation_labels - Set the navigation labels in the context of all documents in a document tree. order: 10000 6. find_builder Given a document context and a target, find the corresponding target builder. Receivers: a. find_builder - Find a target builder in a document context, or None if None was found. order: 1000 7. document_created Signal sent after document creation. Receivers take a document parameter. 8. document_deleted Signal sent before a document is deleted. Receivers take a document parameter. Receivers: a. delete_document - Reset the context and managers for a document on document deletion. order: 100 9. document_build Signal sent when a document's targets are being built to their final target files. Receivers take a document parameter. Receivers: a. build - Build a document tree's targets (and subdocuments) using the target builders. order: 1000 10. document_build_needed Signal sent to evaluate whether a build is needed. Takes a document as a parameter and returns True or False Receivers: a. build_needed - Evaluate whether any of the target builders need to be build order: 1000