Learn Ducktype Source
This is the source markup for Learn Ducktype. It is written in Ducktype.
@namespace e http://projectmallard.org/experimental/ @namespace xi http://www.w3.org/2001/XInclude = Learn Ducktype [topic .tutorial] @link[guide >index group=ducktype] @revision[version=0.1 date=2018-08-20 status=incomplete] @credit[author copyright] @name Shaun McCance @email firstname.lastname@example.org @years 2018 [-] FIXME [-] @xi:include[>>../../cc-by-sa-3-0.xml]] @desc Create a multiple-page Mallard document without XML. [note .pmo-source] . Learn by Example This page was written in Ducktype. $link[>ducktype-src](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 $app(Beanstalk) application. This tutorial closely follows the $link[>tenminutes] 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 $em(compact) or $em(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: $link[>/1.1/mal_page#topic](topic pages) and $link[>/1.1/mal_page#guide](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 [#first] 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 $file(index.duck). [listing] . $file(index.duck) [code] = 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 $code(type) attribute to $code(guide), indicating the page is a guide page. The $code(type) attribute is very common in Mallard and Ducktype, so Ducktype provides a shorthand syntax for it. Just omit the $code(type=) part. (There are a few other attribute shorthands, some of which will be covered in this tutorial.) [listing] . $file(index.duck) [code] = Beanstalk Help $[$e:hi(guide)] == View Your Document [#view] 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 $cmd(ducktype) tool, part of the $sys(mallard-ducktype) package. $sys(mallard-ducktype) is available on the Pythin Package Index (PyPI). Use the $cmd(pip3) command to install it. [screen] pip3 install mallard-ducktype To convert a Ducktype page to a Mallard page, call $cmd(ducktype) and pass the Ducktype page as an argument. [screen] ducktype index.duck This will output a Mallard XML file called $file(index.page). The Gnome help viewer $app(Yelp) has native support for Mallard XML. You can view the document by calling $cmd(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 $file(index.page) in $file(/home/drake/mydocument/), enter this at the command line: [screen] yelp /home/drake/mydocument/ Alternatively, you can build static HTML pages using the $cmd(yelp-build) tool, part of the $sys(yelp-tools) package: [screen] yelp-build html *.page The $sys(yelp-tools) package contains various utilities to help you build and manage your documentation. See $link[>>http://yelp.io/tools/] for more information. == Another Page [#topic] 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: [listing] . $file(planting.duck) [code] = Planting Beans $[topic] Notice that the $code(type) attribute is $code("guide") in $file(index.duck) and $code("topic") in $file(planting.duck). Since $file(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 $file(planting.duck): [listing] . $file(planting.duck) [code] = Planting Beans $[topic] $e:hi(@link[guide xref=index]) The $code(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 $code(link) element has two attributes: $code(type) and $code(xref). The $code(xref) element is also very common, so Ducktype has a shorthand notation for it. [listing] . $file(planting.duck) [code] = Planting Beans $[topic] @link[guide $e:hi(>index)] The $code(link) element specifies that this page should be linked to from the guide page $code(index), which we created above. Convert both pages to Ducktype, then to HTML: [screen] 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 [#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. [listing] . $file(uses.duck) [code] = Bean Uses $[guide] @link[guide >index] @link[topic >planting] Like $file(planting.duck), this page has a guide link to $code(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 [#content] Currently, there's no real content in $file(planting.duck). Add content to explain to the user how to plant magic beans. The following example shows a basic paragraph and a list. [listing] . $file(planting.duck) [code] = Planting Beans $[topic] @link[guide >index] $e:hi(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 $code(list) element. Mallard actually has a more specific element for a list of steps: the $code(steps) element. You can use $code(steps) instead using the Ducktype block element notation. [listing] . $file(planting.duck) [code] = 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. $e:hi([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 [#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 $link[>/1.1/mal_block](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: [code] $[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. [code] $[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. [code] $[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. [code] $[note style=tip] This is a tip. It will probably be styled differently. Like $code(type) and $code(xref), the $code(style) attribute is very common in Mallard, and so it gets a shorthand notation. Use a leading dot to indicate a style hint. [code] $[note $e:hi(.tip)] This is a tip. It will probably be styled differently. [-- FIXME: This is an unsatisfactory end for the Ducktype tutorial. It's fine for XML, where people know the syntax and they can just go look at the element reference. Write more, or do followup tutorials? --] [-- <section id="learnmore"> <title>Read More and Explore</title> <p>Using the information in this tutorial, you can create a simple Mallard document with any number of pages. Mallard offers more features that allow you to create richer documents with more useful links. Try adding more content and additional pages to your document.</p> <p>To learn more, read more of the <link xref="index">Mallard tutorials</link>. Or read the <link xref="/1.1/index">Mallard language specification</link> to see a complete list of what Mallard offers.</p> </section> </page> --]