Grammar by Example

Version 6.1.0

In this article

GBE teaches the syntax of MDDDL files and demonstrates the capabilities of MigraDoc. GBE was developed a long time ago when we thought that writing MDDDL code was the way to go. Nowadays we focus on creating documents from C# code, but we still use the same capabilities, just with a different syntax. GBE still is a good introduction to MigraDoc, but syntax is slightly different when used from C# code.

MigraDoc DDL, the MigraDoc Document Description Language (MDDDL), is a text based serialization of a MigraDoc document.

Grammar by Example (GBE) is a collection of MDDDL files, a tutorial to MigraDoc, written in MigraDoc DDL. You can create PDF files from GBE to read them easily.

How to get GBE

To obtain Grammar by Example, download the source code and download the assets.

Download the source code
Download assets

To find GBE, open the assets folder in your source directory and then go to archives/grammar-by-example/GBE. There you will find a folder GBE-DLL containing the MDDDL source code files and a folder ReferencePDFs containing several versions of PDF files created from those MDDDL files.

The file with the name !index.pdf is a good starting point because it has links to all the other PDF files with a short description of their contents.

How to use GBE

After opening the file !index.pdf from any folder under ReferencePDFs, you will see an overview of the available GBE samples for areas like Document, Section, Paragraph, Shape, Image, Table and many more.

Each sample PDF file will show code snippets of MDDDL and will also show the resulting effect.

The GBE files give a great demonstration of what can be achieved with MigraDoc.

From MDDDL to .NET

The GBE samples show how effects can be achieved using MDDDL.

Here is a sample using MDDDL:

\image("logo_e.gif")[Height = "1cm"]

Everything that can be set using MDDDL can also be set using .NET and the classes from the MigraDoc Document Object Model.

Here’s how it looks in C#:

var image = new Image("logo_e.gif");
image.Height = "1cm";

Using object initializers, your code can look like this:

var image = new Image("logo_e.gif")
{
    Height = "1cm"
};
Important

MDDDL was invented around 1999 and is currently still only ANSI encoded. We will fix this in version 6.2.

Highlights

Shapes

MigraDoc provides the Shape class for special image objects with special layout features: Shapes can be used like normal objects in the body of the document, but they can also be used as overlays with absolute or relative positions.

The following MigraDoc classes are derived from the Shape class:

  • Chart
  • Barcode
  • Image
  • TextFrame

Set WrapFormat.Style of any of these classes to WrapStyle.None or WrapStyle.Through to create an overlay object that is ignored during in regular layout process.

Note that it is up to you to ensure that overlay objects do not hide vital information.

Shapes will not break to the next page, so their contents must be small enough to fit on a single page.

Textframes

The TextFrame class is derived from the Shape class described above.

See the file TextFrame-Layout.mdddl and the PDFs generated from it for further details about the usage of the TextFrame class.