Learn Ducktype

Learn by Example

This page was written in Ducktype. Read the source markup for this page to learn Ducktype from real-world examples.

In this tutorial, you will learn how to create a simple multiple-page Ducktype document by creating a document for the fictitious Beanstalk application. This tutorial closely follows the Ten Minute Tour for Mallard XML. It does not assume you know XML, though some of the links to further conceptual information use the XML syntax.

Ducktype is a compact or lightweight syntax for Mallard. A Ducktype page can be directly converted to a Mallard page. A Ducktype document is a Mallard document, with all the structure and navigation that comes with Mallard. It simply uses a different syntax. Some tools even allow making a Mallard document with a mix of Ducktype and Mallard XML files, though this tutorial does not cover that.

A Ducktype document is composed of multiple independent pages. Each page is kept in a separate file, and a processing tool aggregates them together, automatically creating links and navigational aids. There are two primary types of pages: topic pages and guide pages. Topic pages present some piece of information to the reader. This might be a tutorial, a conceptual overview, reference material, or any other type of content. Guide pages serve as the navigational glue between topics, helping readers find and explore content.

First Page

Begin making a Ducktype document by writing the front page in any text editor. Generally, the front page of any document will be a guide page, as its purpose is to help users navigate to other content. In Ducktype, the front page of any document is always named index.duck.

index.duck

= Beanstalk Help
  [type=guide]

This simple example is a valid Ducktype guide page. Taken alone, it is also a valid Ducktype document.

Every page starts with a title, denoted with a leading equals sign and space. Following the title, you can add a list of attributes on an indented line surrounded by square brackets. Here we have set the type attribute to guide, indicating the page is a guide page.

The type attribute is very common in Mallard and Ducktype, so Ducktype provides a shorthand syntax for it. Just omit the type= part. (There are a few other attribute shorthands, some of which will be covered in this tutorial.)

index.duck

= Beanstalk Help
  [guide]

View Your Document

You now have a simple document, but you can only view the raw markup in a text editor. To view formatted output, you first need to convert your document to XML, then process it with a Mallard processing tool. Some tools can do this in a single step, but we'll do it in two steps.

To convert Ducktype to Mallard, use the ducktype tool, part of the mallard-ducktype package. mallard-ducktype is available on the Pythin Package Index (PyPI). Use the pip3 command to install it.

pip3 install mallard-ducktype

To convert a Ducktype page to a Mallard page, call ducktype and pass the Ducktype page as n argument.

ducktype index.duck

This will output a Mallard XML file called index.page.

The Gnome help viewer Yelp has native support for Mallard XML. You can view the document by calling yelp from the command line and passing it the full path to the directory containing the generated page file. For example, if you have placed index.page in /home/drake/mydocument/, enter this at the command line:

yelp /home/drake/mydocument/

Alternatively, you can build static HTML pages using the yelp-build tool, part of the yelp-tools package:

yelp-build html *.page

The yelp-tools package contains various utilities to help you build and manage your documentation. See http://yelp.io/tools/ for more information.

Another Page

Unless you're creating a simple set of instructions for a friend or colleague, you probably want to have multiple pages in your document. Add another page to the document by creating a new file:

planting.duck

= Planting Beans
  [topic]

Notice that the type attribute is "guide" in index.duck and "topic" in planting.duck. Since index.duck is a guide page, it can have links inserted automatically to other pages. In Mallard and Ducktype, guides don't have to specify which pages they link to. Instead, pages can specify that guides should link to them. Do this by adding a link element to planting.duck:

planting.duck

= Planting Beans
  [topic]
@link[guide xref=index]

The link element here is a type of informational element. Informational elements can follow headings and block elements. They start with an at sign and have a name, then possibly an attribute list and content. In this case, the link element has two attributes: type and xref. The xref element is also very common, so Ducktype has a shorthand notation for it.

planting.duck

= Planting Beans
  [topic]
@link[guide >index]

The link element specifies that this page should be linked to from the guide page index, which we created above.

Convert both pages to Ducktype, then to HTML:

ducktype *.duck
yelp-build *.page

You'll see that the front page now has a link to this new page. This is one of the unique features of Mallard and Ducktype. Rather than requiring pages to specify everything they link to, Mallard allows pages to insert themselves into other guide pages. This makes it possible to add pages for plugins and additional functionality without modifying the original source pages.

Another Guide

You can add additional guide pages to your document. This allows you to organize content to match what your readers are looking for. Add a guide page to link to ways you can use magic beans.

uses.duck

= Bean Uses
  [guide]
@link[guide >index]
@link[topic >planting]

Like planting.duck, this page has a guide link to index. If you convert all the pages to HTML again, you'll see that the front page now has two links.

This page adds a new type of link. Topic links are the inverse of guide links. When a guide page has a topic link to another page, it's as if the other page had a guide link to the guide page. Despite the name, topic links can link to topic pages or guide pages.

If you view the “Planting Beans” page, you'll see it has links at the top and bottom to both “Beanstalk Help” and “Bean Uses”. Adding a page to a guide is like adding it to a section in a traditional linear document, except that pages can be linked to from multiple guides. This allows you to provide multiple ways to navigate to a page to better match how your readers are thinking.

Add Content

Currently, there's no real content in planting.duck. Add content to explain to the user how to plant magic beans. The following example shows a basic paragraph and a list.

planting.duck

= Planting Beans
  [topic]
@link[guide >index]

By the end of this page, you will be able to plant your magic
beans and nurture them into a bean sprout.

* Dig a hole 5cm deep.
* Place your magic beans in the hole.
* Fill the hole with clean dirt and pat it level.
* Water daily.

Paragraphs in Ducktype are implicit and separated by blank lines. List items are introduced with an asterisk and a space.

This example creates a simple list element. Mallard actually has a more specific element for a list of steps: the steps element. You can use steps instead using the Ducktype block element notation.

planting.duck

= Planting Beans
  [topic]
@link[guide >index]

By the end of this page, you will be able to plant your magic
beans and nurture them into a bean sprout.

[steps]
* Dig a hole 5cm deep.
* Place your magic beans in the hole.
* Fill the hole with clean dirt and pat it level.
* Water daily.

Add Blocks

We've seen paragraphs and lists, and gotten a glimpse of other block elements. Let's explore block elements further. Mallard provides a handful of semantic block elements for things like notes, figures, and code snippets. Ducktype allows you to use all of these elements with block annotations. Try adding a note to one of your pages:

[note]
This is a simple note with a single line of content.

Ducktype also allows you to nest content using indentation. To create a note with two paragraphs, indent both paragraphs. The amount of indentation doesn't matter, as long as you're consistent. We prefer two-space indentation though.

[note]
  This is a simple note and this is the first paragraph.

  This is another paragraph in that note.

Nesting isn't just limited to paragraphs. You can nest any block elements as deeply as you want. For example, you could add a list inside of a note.

[note]
  Remember the three virtues of a programmer:

  * Laziness
  * Impatience
  * Hubris

Earlier we added attributes to headers and informational elements. We can do the same thing with block elements by putting the attributes inside the square brackets.

[note style=tip]
  This is a tip. It will probably be styled differently.

Like type and xref, the style attribute is very common in Mallard, and so it gets a shorthand notation. Use a leading dot to indicate a style hint.

[note .tip]
  This is a tip. It will probably be styled differently.
© 2018 Shaun McCance
Powered by
Mallard