README.md

Generate documentation for EMMO

This directory contains the needed templates, introductory text and figures for generating the full EMMO documentation using ontodoc. Since the introduction is written in markdown, pandoc is required for both pdf and html generation.

For a standalone html documentation including all inferred relations, enter this directory and run:

ontodoc --template=emmo.md --format=html emmo-inferred emmo.html

Pandoc options may be adjusted with the files pandoc-options.yaml and pandoc-html-options.yaml.

Similarly, for generating pdf documentation, enter this directory and run:

ontodoc --template=emmo.md emmo-inferred emmo.pdf

By default, we have configured pandoc to use xelatex for better unicode support. It is possible to change these settings in pandoc-options.yaml and pandoc-pdf-options.yaml.

Content of this directory

ontodoc templates with introductory text and document layout

• emmo.md: Main template for EMMO. It includes the other templates.
• introduction.md: Introductory text.
• relations.md: Introduction and sections for Relations chapter.
• classes.md: Introduction and sections for Classes.
• figs: Figures used in the introduction.

pandoc configuration files

• emmodoc-meta.yaml: Metadata for EMMO, like title, authers, abstract, etc.
• pandoc-options.yaml: General pandoc options.
• pandoc-html-options.yaml: Additional pandoc options for html generation.
• pandoc-pdf-options.yaml: Additional pandoc options for pdf generation.
• pandoc-html.css: css file used for html generation.
• pandoc-template.html: Modified copy of the standard pandoc html template with a small adjustment for the author list.
• pandoc-template.tex: Modified copy of the standard pandoc latex template with a small adjustment for the author list.

Using this example as a starting point for documenting your own ontology

For simple html documentation, you can skip all input files and simply run ontodoc as

ontodoc --format=simple-html YOUR_ONTO.owl YOUR_ONTO.html

It is also possible to include ontodoc templates using the --template option for adding additional information and structure the document. In this case the template may only contain ontodoc pre-processer directives and inline html, but not markdown.

In order to produce output in pdf (or any other output format supported by pandoc), you can write your ontodoc template in markdown (with ontodoc pre-processer directives) and follow these steps to get started:

• Copy all the files starting with pandoc- to a new directory.
• Create a metadata YAML file for your ontology. You can use emmodoc-meta.yaml as a template.
• Update pandoc-options.yaml. Especially change:
  • input-files to the name of your new yaml metadata file.
  • logo to the path of your logo (or remove it).
  • titlegraphic to the path of your title figure (or remove it).
• Optionally add ontodoc template files with additional information about your ontology and document layout.

That should be it. Good luck!