((p "Attributes allows to modify the way how material is presented." " " "Alternatively, they provide additional information to markup elements." " " "To some degree, attributes are similar to " (a (@ (href . "https://html.spec.whatwg.org/multipage/dom.html#global-attributes") (rel . "external")) "HTML attributes") ".") (p "Typical use cases for attributes are to specify the (natural) " (a (@ (href . "00001007050100")) "language") " for a text region, to specify the " (a (@ (href . "00001007050200")) "programming language") " for highlighting program code, or to make white space visible in plain text.") (p "Attributes are specified within curly brackets " (code "{...}") "." " " "Of course, more than one attribute can be specified." " " "Attributes are separated by a sequence of space characters or by a comma character.") (p "An attribute normally consists of an optional key and an optional value." " " "The key is a sequence of letters, digits, a hyphen-minus (" (@L (@H "“") (kbd "-") (@H "”")) ", U+002D, and a low line / underscore (" (@L (@H "“") (kbd "_") (@H "”")) ", U+005D)." " " "It can be empty." " " "The value is a sequence of any character, except space and the right curly bracket (" (@L (@H "“") (kbd "}") (@H "”")) ", U+007D)." " " "If the value must contain a space or the right curly bracket, the value can be specified within two quotation marks (" (@L (@H "“") (kbd "\"") (@H "”")) ", U+0022)." " " "Within the quotation marks, the backslash character functions as an escape character to specify the quotation mark (and the backslash character too).") (p "Some examples:") (ul (li (code "{key=value}") " sets the attribute " (em "key") " to value " (em "value") ".") (li (code "{key=\"value with space\"}") " sets the attribute to the given value.") (li (code "{key=\"value with quote \\\" (and backslash \\\\)\"}")) (li (code "{name}") " sets the attribute " (em "name") "." " " "It has no corresponding value." " " "It is equivalent to " (code "{name=}") ".") (li (code "{=key}") " sets the " (em "generic attribute") " to the given value." " " "It is mostly used for modifying behavior according to a programming language.") (li (code "{.key}") " sets the " (em "class attribute") " to the given value." " " "It is equivalent to " (code "{class=key}") ".")) (p "In these examples, " (code "key") " must conform the the syntax of attribute keys, even if it is used as a value.") (p "If a key is given more than once in an attribute, the values are concatenated (and separated by a space).") (ul (li (code "{key=value1 key=value2}") " is the same as " (code "{key\"value1 value2\"}") ".") (li (code "{key key}") " is the same as " (code "{key}") ".") (li (code "{.class1 .class2}") " is equivalent to " (code "{class=\"class1 class2\"}") ".")) (p "This is not true for the generic attribute." " " "In " (code "{=key1 =key2}") ", the first key is ignored." " " "Therefore it is equivalent to " (code "{=key2}") ".") (p "The key " (@L (@H "“") (kbd "-") (@H "”")) " (just hyphen-minus) is special." " " "It is called " (em "default attribute") " and has a markup specific meaning." " " "For example, when used for plain text, it replaces the non-visible space with a visible representation:") (ul (li (kbd "``Hello, world``{-}") " produces " (samp "Hello,␣world") ".") (li (kbd "``Hello, world``") " produces " (samp "Hello, world") ".")) (p "Attributes may be continued on the next line when a space or line ending character is possible." " " "In case of a quoted attribute value, the line ending character will be part of the attribute value." " " "For example:") (pre (code "{key=\"quoted\nvalue\"}")) (p "will produce a value " (kbd "quoted\\nvalue") " (where \\n denotes a line ending character).") (pre (code "::GREEN::{class=example\nbackground=grey}")) (p "is allowed, but not") (pre (code "::GREEN::{background=color:\ngreen}")) (p "However,") (pre (code "::GREEN::{background=color:\"\ngreen\"}")) (p "is allowed, because line endings are allowed within quotes.") (p "For " (a (@ (href . "00001007030000")) "block-structured elements") ", there is a syntax variant if you only want to specify a generic attribute." " " "For all line-range blocks you can specify the generic attributes directly in the first line, after the three (or more) characters starting the block.") (pre (code ":::attr\n...\n:::")) (p "is equivalent to") (pre (code ":::{=attr}\n...\n:::")) (p "For block-structured elements, spaces are allowed between the blocks characters and the attributes.") (pre (code "=== Heading {example}")) (p "is allowed and equivalent to") (pre (code "=== Heading{example}")) (p "For " (a (@ (href . "00001007040000")) "inline-structured elements") ", the attributes must immediately follow the inline markup.") (p (code "::GREEN::{example}") " is allowed, but not " (code "::GREEN:: {example}") ".") (h2 (@ (id . "reference-material")) "Reference material") (ul (li (a (@ (href . "00001007050100")) "Supported attribute values for natural languages")) (li (a (@ (href . "00001007050200")) "Supported attribute values for programming languages"))))