Candidate

1.0 (2018-08-20)

Titles, Lists, and Tables

Ducktype provides shorthand syntax for block titles, list items, and tables cells using leading periods, hyphens, and asterisks.

Notes

  • List items and table cells can be written with regular block elements or with the shorthand syntax detailed here.

  • . A leading period and space creates a block title element.

  • * A leading asterisk and space creates:

    • An item element in a list or steps element.

    • The content of an item element in a terms element.

    • An item element in a tree element or tree item.

    • A td element in a tr element.

    • Otherwise, an item element with an implicit list element.

  • - A leading hyphen and space creates:

    • A title element with an implicit item item in a terms element.

    • Another title element in a terms item element without non-title content.

    • A th element in a tr element.

    • Otherwise, a title element with an implicit item element and an implicit terms element.

Examples

Create a simple list:

* First list item
* Second list item
<list>
  <item><p>First list item</p></item>
  <item><p>Second list item</p></item>
</list>

Nest lists with indentation:

* First list item
  * First subitem
  * Second subitem
* Second list item
<list>
  <item>
    <p>First list item</p>
    <list>
      <item><p>First subitem</p></item>
      <item><p>Second subitem</p></item>
    </list>
  </item>
  <item><p>Second list item</p></item>
</list>

Give the list a title:

[list]
. My List Title
* First list item
* Second list item
<list>
  <title>My List Title</title>
  <item><p>First list item</p></item>
  <item><p>Second list item</p></item>
</list>

Use an explicit block declaration to add attributes to the list:

[list numbered]
* First list item
* Second list item
<list type="numbered">
  <item><p>First list item</p></item>
  <item><p>Second list item</p></item>
</list>

Use an explicit block declaration to use a steps element:

[steps]
* First step
* Second step
<steps>
  <item><p>First step</p></item>
  <item><p>Second step</p></item>
</steps>

Create a terms list:

[terms]
- First term
* First term definition

- Second term
* Second term definition
<terms>
  <item>
    <title>First term</title>
    <p>First term definition</p>
  </item>
  <item>
    <title>Second term</title>
    <p>Second term definition</p>
  </item>
</terms>

Create a terms list with multiple titles on each item:

[terms]
- First term #1
- First term #2
* First term definition

- Second term #1
- Second term #2
* Second term definition
<terms>
  <item>
    <title>First term #1</title>
    <title>First term #2</title>
    <p>First term definition</p>
  </item>
  <item>
    <title>Second term #1</title>
    <title>Second term #2</title>
    <p>Second term definition</p>
  </item>
</terms>

Create a tree list:

[tree]
* First item
  * Subitem #1
  * Subitem #2
* Second item
  * Second item subitem
    * Subsubitem
<tree>
  <item>First item
    <item>Subitem #1</item>
    <item>Subitem #2</item>
  </item>
  <item>First item
    <item>Second item subitem
      <item>Subsubitem</item>
    </item>
  </item>
</tree>

Create a basic table:

[table]
[tr]
* One
* Two
[tr]
* Three
* Four
<table>
  <tr>
    <td><p>One</p></td>
    <td><p>Two</p></td>
  </tr>
  <tr>
    <td><p>Three</p></td>
    <td><p>Four</p></td>
  </tr>
</table>

Create a table with header cells:

[table]
[tr]
- Odd
- Even
[tr]
* One
* Two
[tr]
* Three
* Four
<table>
  <tr>
    <th><p>Odd</p></th>
    <th><p>Even</p></th>
  </tr>
  <tr>
    <td><p>One</p></td>
    <td><p>Two</p></td>
  </tr>
  <tr>
    <td><p>Three</p></td>
    <td><p>Four</p></td>
  </tr>
</table>

Specification

If an indented line starts with a period (U+002E), an asterisk (U+002A), or a hyphen (U+002D), followed by a space (U+0020), then that line is using a block shorthand notation. In each of these cases, the leading character and space create one or more block declarations, and the rest of the line begins the block content.

If the indented line starts with a period and a space, it is shorthand for a block title. It is handled as if the period and space were replaced with [title], a newline, and enough spaces to indent two more spaces than the indentation of the period.

If the indented line starts with an asterisk and a space:

  • If the current element is a list or steps element, it is shorthand for an item element. It is handled as if the asterisk and space were replaced with [item], a newline, and enough space to indent two more spaces than the indentation of the asterisk.

  • If the current element is an item element in a terms element (possibly created with the hyphen shorthand described below), then the rest of the line begins the block content of the item, effectively ending the list of title elements. This shorthand creates an inner indent for the item of two more than indentation of the asterisk, allowing you to add multiple paragraphs or other block elements.

  • If the current element is a tr element, it is shorthand for a td element. It is handled as if the asterisk and space were replaced with [td], a newline, and enough space to indent two more spaces than the indentation of the asterisk.

  • Otherwise, a list element is implicitly created, and the line is treated as a list item as in the first step.

If the indented line starts with a hyphen and a space:

  • If the current element is a tr element, it is shorthand for a th element. It is handled as if the asterisk and space were replaced with [th], a newline, and enough space to indent two more spaces than the indentation of the asterisk.

  • If the current element is an item element in a terms element, and that element does not yet have non-title content, it is shorthand for a title element. Note that items in terms elements can have multiple titles.

  • If the current element is a terms element, it is shorthand for an item element and a title element. The item element can have more titles. The non-title content of the item element starts with an asterisk, as described above.

  • Otherwise, a terms element is implicitly created, and the line is treated like an item and title as in the first case.

© 2018 Shaun McCance
cc-by-sa 3.0 (us)

This work is licensed under a Creative Commons Attribution-Share Alike 3.0 United States License.

As a special exception, the copyright holders give you permission to copy, modify, and distribute the example code contained in this document under the terms of your choosing, without restriction.

Powered by
Mallard