Candidate

1.0 (2017-09-30)

Fences

Fences contain lines that are not parsed for block or inline markup, allowing you to write content without escaping.

Notes

  • A fence begins with an indented line that starts with [[[. The leading indent before the fence delimiter is significant, as if the first line of the contained content had that indent.

  • The line with the opening fence delimiter may have additional content, which is processed as if it were on its own line.

  • A fence ends with a line that contains only ]]], possibly with leading and trailing whitespace.

  • As a special case, if the line containing the fence delimiter ends with ]]], it is a single-line fence. Except for single-line fences, closing fence delimiters must not have content before them.

Examples

Use a fence to avoid having to escape characters:

[code]
  [[[
  [Desktop Entry]
  Name=Help
  Exec=yelp %u
  ]]]

The fence content doesn’t have to be indented, as long as the opening delimiter is correctly indented:

[code]
  [[[
[Desktop Entry]
Name=Help
Exec=yelp %u
]]]

You can also use a fence on a single line:

[code]
  [[[[Desktop Entry]]]]
  Name=Help
  Exec=yelp %u

Specification

Fences may appear anywhere block content is expected.

A fence begins with an indented line that starts with [[[. The leading indent before the opening delimiter is taken as the outer indent of the fence. This indentation is significant. The content of the fence is inserted at the same depth as if its lines all had that leading indent.

The line containing the opening fence delimiter may have additional content. If it contains non-whitespace content, then everything after the fence, including whitespace between the fence delimiter and the non-whitespace content, is taken as the first line of the fence. Otherwise, the line after the opening fence delimiter is the first line.

Lines within the fence do not need to be indented to the outer indent off the fence. The fence itself keeps the content correctly nested. However, the writer may choose to indent the fence content, and the indentation will be trimmed.

The leading spaces of the first line sets the indentation trim level of the fence. All lines within the fence will have at most that number of leading spaces removed. Note that some lines may have fewer leading space characters, especially blank lines. Those lines will simply have all leading spaces removed.

A fence ends with a line that contains only ]]], possibly with leading or trailing whitespace. The line with the closing fence delimiter does not add any content to the fence.

Additionally, if the line with the opening fence delimiter ends with ]]], then that is the closing fence delimiter. The content between the opening and closing delimiters is taken as a single-line fence. Single-line fences are the only case where there may be other content on the line with the closing fence delimiter.

No block or inline parsing is done within a fence. However, comments are still recognized in fences. Comment parsing takes priority over all other types of syntax in Ducktype.

© 2017 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