Skip to content

Document generation usage

RaESL enables you to convert an ESL specification into a display document such as PDF, Markdown or even Word. It uses Typst under the hood in recent versions and Pandoc and LaTeX in older versions. Since these documents are generated from your spec, they are guaranteed to be up-to-date and consistent with your content.

From a Python script, you can call the conversion using the following snippet:

1
2
3
4
5
6
from raesl.render import Context, Document

pdf_path = generated / "pump.pdf"

doc = Document(context=Context(), title="Pump example", graph=pump_example_graph)
doc.compile(pdf_path)

Which results in this PDF. You can supply any number of (positional) ESL file and directory paths just like you can with the ESL compiler.

Customizing the generated document

There are several ways to further customize the display document. Lets review a fully fledged example:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
from raesl.l10n import get_locale
from raesl.render import Context, Document

pdf_path = generated / "pump.pdf"
doc = Document(
    context=Context(
        l10n=get_locale("en"), # Or try "nl" or "nl-nl" to be specific.
    ), # rendering settings
    graph=pump_example_graph,  # e.g. your ESL graph.
    title="Pump example",
    prologue=pump_prologue,  # e.g. "prologue.md"
    epilogue=pump_epilogue,  # e.g. "epilogue.md"
)
doc.compile(pdf_path)

which results in this PDF file.

Document file formats

Internally your specification is converted to Markdown. A lightweight typesetting language often rendered to HTML pages. Setting the output path to something with the .pdf extension changes the format to PDF. Similarly, the .md extension changes the format to Markdown.

Including a prologue or epilogue

You can provide your own prologue or epilogue as files in a Pandoc Markdown format which will be rendered before and after the main content, respectively. The prologue is put after the frontmatter and the epilogue is placed before the automatically generated appendices.

Document language

You can change the generated document's language by changing the l10n argument to the Context. Currently, Dutch (nl) and English (en) are supported.

Note

Please keep in mind that all your variable and component names will not be translated during this conversion.

Note

You can make the output a little less verbatim by adding articles (Dutch: lidwoorden) before component names separated by an underscore _. All underscores are replaced by spaces in the generated output text.