From 81de31771d38b458c5d6e1cbff33cf8568a823ff Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stanis=C5=82aw=20Ma=C5=82olepszy?= Date: Wed, 29 Nov 2023 14:05:44 +0100 Subject: [PATCH 1/4] Document the open questions around standalone markup --- exploration/open-close-expressions.md | 46 +++++++++++++++++++++++---- 1 file changed, 39 insertions(+), 7 deletions(-) diff --git a/exploration/open-close-expressions.md b/exploration/open-close-expressions.md index b90b15467c..2a06b8c4f0 100644 --- a/exploration/open-close-expressions.md +++ b/exploration/open-close-expressions.md @@ -49,7 +49,7 @@ _What context is helpful to understand this proposal?_ On runtime, I expect these markup elements to produce live UI elements. > ``` - > This is a giraffe: {#img src=giraffe.gif}. + > This is a giraffe: {#img src=giraffe.gif/}. > ``` - I want to be able to use minimal markup to inform XLIFF interchange. @@ -139,6 +139,8 @@ such as `Click here to continue`. As with function options, markup options should be defined in a registry so that they can be validated. +Provide a way to tell open and standalone elements apart. + ## Constraints Due to segmentation, @@ -148,6 +150,9 @@ Following previously established consensus, the resolution of the value of an _expression_ may only depend on its own contents, without access to the other parts of the selected pattern. +Any information stored in the registry is not available on runtime, +and may be unavailable in tooling. + ## Proposed Design This design relies on the recognition that the formatted output of MF2 @@ -178,7 +183,7 @@ This is {#strong}bold{/strong} and this is {#img alt=|an image|}. Markup names are _namespaced_ by their use of the pound sign `#` and the forward slash `/` sigils. They are distinct from `$variables`, `:functions`, and `|literals|`. -This allows for placeholders like `{#b}`, `{#img}`, and `{#a title=|Link tooltip|}`. +This allows for placeholders like `{#b}`, and `{#a title=|Link tooltip|}`. Unlike annotations, markup expressions may not have operands. Markup is not valid in _declarations_ or _selectors_. @@ -195,13 +200,40 @@ Markup is not valid in _declarations_ or _selectors_. * Introduces two new sigils, the pound sign `#` and the forward slash `/`. -* As in HTML, differentiating "open" and "standalone" elements relies on registry information, - or in translations matching the structure used in the source - A rather clunky `{#foo/}` syntax was considered for explicitly-standalone elements, - but this did not reach consensus support. - * In Mustache, the `{{#foo}}`...`{{/foo}}` syntax is used for *control flow* statements rather than printable data. +### Standalone Markup + +_Standalone_ markup remains an open question. +Three alternatives have been suggested: + +* Introduce additional syntax inspired by XML: `{#foo/}`. + + This approach encodes the _standalone_ aspect in the data model, and doesn't rely on external sources of truth, + at the expense of introducing new syntax, which is admittedly a bit clunky. + + It also creates a dichotomy between standalone _markup_ and regular _placeholders_, which can be argued to be _standalone_ as well. + +* Differentiate _open_ and _standalone_ elements based on the information stored in the registry, + or based on some other external source of truth + (e.g. the structure of the source to which the message is applied). + + This approach offers a cleaner syntax at the expense of relying on external sources of truth for telling open and standalone elements apart. + Without the access to these sources of truth (e.g. a custom registry), standalone markup will be interpreted as open elements. + +* Re-use regular placeholders with regular function calls: `{:img src=logo.png}`. + + This approach leverages the fact that regular placeholders can also be thought of as being _standalone_. + It also doesn't introduce any new syntax, instead relying on the function call syntax: `:img`. + + Namespacing is a concern: to ensure forward compatibility, implementations and users should avoid introducing new symbols to the default, anonymous namespace. + Thus, a custom function representing a standalone element should be namespaced: `:html:img` or `:moz:img`. + While a good practice in general, it results in more verbose syntax, + possibly also for the _open_ and _close_ markup, which would be namespaced for consistency: `{#html:link}...{/html:link}`. + + In this approach there's also no way to enforce the lack of operands to standalone markup at the syntax level. + Instead, access to a custom registry is required to know that `:img` does not accept any operands. + ### Runtime Behavior #### Formatting to a String From d9feb62d0e173026e5eb19716c197866e21489a1 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stanis=C5=82aw=20Ma=C5=82olepszy?= Date: Wed, 29 Nov 2023 15:53:20 +0100 Subject: [PATCH 2/4] Update exploration/open-close-expressions.md Co-authored-by: Eemeli Aro --- exploration/open-close-expressions.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/exploration/open-close-expressions.md b/exploration/open-close-expressions.md index 2a06b8c4f0..d6661a928f 100644 --- a/exploration/open-close-expressions.md +++ b/exploration/open-close-expressions.md @@ -150,7 +150,8 @@ Following previously established consensus, the resolution of the value of an _expression_ may only depend on its own contents, without access to the other parts of the selected pattern. -Any information stored in the registry is not available on runtime, +Any information stored in the registry is not available at runtime +unless reflected in the implementation's behaviour, and may be unavailable in tooling. ## Proposed Design From f8bf04d4a778033fd66ee46bda80041a60d69848 Mon Sep 17 00:00:00 2001 From: Addison Phillips Date: Tue, 5 Dec 2023 07:50:07 -0800 Subject: [PATCH 3/4] Address comment about Unicode character references ... but using Unicode code points and names instead of being super informal. This is strictly an editorial change. --- exploration/open-close-expressions.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/exploration/open-close-expressions.md b/exploration/open-close-expressions.md index d6661a928f..425fe07069 100644 --- a/exploration/open-close-expressions.md +++ b/exploration/open-close-expressions.md @@ -181,7 +181,7 @@ This is similar to [Mustache](http://mustache.github.io/mustache.5.html)'s contr This is {#strong}bold{/strong} and this is {#img alt=|an image|}. ``` -Markup names are _namespaced_ by their use of the pound sign `#` and the forward slash `/` sigils. +Markup names are _namespaced_ by their use of the U+0023 NUMBER SIGN `#` and the U+002F SOLIDUS `/` sigils. They are distinct from `$variables`, `:functions`, and `|literals|`. This allows for placeholders like `{#b}`, and `{#a title=|Link tooltip|}`. @@ -191,7 +191,7 @@ Markup is not valid in _declarations_ or _selectors_. #### Pros -* Leverages the familiarity of the forward slash `/` used for closing spans. +* Leverages the familiarity of the forward slash (U+002F SOLIDUS `/`) for closing spans. * Doesn't conflict with any other placeholder expressions. @@ -199,7 +199,7 @@ Markup is not valid in _declarations_ or _selectors_. #### Cons -* Introduces two new sigils, the pound sign `#` and the forward slash `/`. +* Introduces two new sigils, U+0023 NUMBER SIGN `#` and the U+002F SOLIDUS `/`. * In Mustache, the `{{#foo}}`...`{{/foo}}` syntax is used for *control flow* statements rather than printable data. @@ -455,10 +455,10 @@ This is [html:strong]bold[/html:strong] and this is [html:img alt=|an image|/]. * Concise and less noisy than the alternatives. -* Doesn't add new sigils except for the forward slash `/`, +* Doesn't add new sigils except for the forward slash (U+002F SOLIDUS `/`), which is universally known thanks to the wide-spread use of HTML. -* Leverages the familiarity of the forward slash `/` used for closing spans. +* Leverages the familiarity of the forward slash (U+002F SOLIDUS `/`) used for closing spans. * Makes it clear that `{42}` and `[foo]` are different concepts: one is a standalone placeholder and the other is an open-span element. From 0e8d167d45bbe51627f698f8466a4dde7ab4395e Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Stanis=C5=82aw=20Ma=C5=82olepszy?= Date: Wed, 13 Dec 2023 21:25:08 +0100 Subject: [PATCH 4/4] Apply suggestions from code review by @eemeli Co-authored-by: Eemeli Aro --- exploration/open-close-placeholders.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/exploration/open-close-placeholders.md b/exploration/open-close-placeholders.md index e6034d19dc..71a7c7f77b 100644 --- a/exploration/open-close-placeholders.md +++ b/exploration/open-close-placeholders.md @@ -185,7 +185,7 @@ This is {#strong}bold{/strong} and this is {#img alt=|an image|}. Markup names are _namespaced_ by their use of the U+0023 NUMBER SIGN `#` and the U+002F SOLIDUS `/` sigils. They are distinct from `$variables`, `:functions`, and `|literals|`. -This allows for placeholders like `{#b}`, and `{#a title=|Link tooltip|}`. +This allows for placeholders like `{#b}`, `{#img}`, and `{#a title=|Link tooltip|}`. Unlike annotations, markup _placeholders_ may not have operands. Markup is not valid in _declarations_ or _selectors_. @@ -202,6 +202,9 @@ Markup is not valid in _declarations_ or _selectors_. * Introduces two new sigils, U+0023 NUMBER SIGN `#` and the U+002F SOLIDUS `/`. +* As in HTML, differentiating "open" and "standalone" placeholders requires + additional information not encoded in the bare syntax. + * In Mustache, the `{{#foo}}`...`{{/foo}}` syntax is used for *control flow* statements rather than printable data. ### Standalone Markup