Add new terms to glossary #584
Conversation
|
|
| - **API** - any function call(s) invoked by the user to perform message formatting. | ||
| - **API argument format** - syntax of values passed to input of message formatting API. May also refer to structure of values represented by the syntax. May be similar or same as _authoring format_. See _message syntax_. | ||
| - **application locale** - the locale for formatting (or formatting resources) requested by an application. | ||
| - **attribute** - A value in a message or a function call that provides additional information that may be needed to properly resolve. Attributes are key/value pairs expressed in the form "@key=value". |
There was a problem hiding this comment.
I'm actually unsure now if attributes can be outside of a function call. I should learn to read the ABNF I guess.
docs/glossary-and-resources.md
Outdated
| - **data model** - a syntax-independent description of the structure of values passed to the message formatting API. | ||
| - **implementation** - code written to make the API achieve the intended behavior of output for a given input. | ||
| - **format to parts** - context-aware functionality that can take a formatted string (such as a monetary amount, or a date), and return the seperated constituent parts. |
There was a problem hiding this comment.
Maybe this doesn't belong here because it is rarely discussed, but i also went with a generic description that may not be 100% accurate in the MF2 context.
There was a problem hiding this comment.
This description is actually wrong, as "format to parts" functions generally don't start with the formatted string. They start with an object (whatever the input is) and return the object as a sequence of formatted parts. See, for example, Intl.NumberFormat
| - **locale fallback** - offering a reasonable substitute locale when the requested locale's resources are not available. Results may vary depending on context (ex: audio vs. text vs. video). | ||
| - **locale matching** - computing the locale fallback. | ||
| - **markup** - characters present in the MessageFormat source strings that are intended to provide structure, functionality, or formatting to the output string, as opposed to display text. | ||
| - **match** - a mechanism in MessageFormat that allows the message author to specify a variety of outcomes based on the combined values of one or more inputs. | ||
| - **metadata** - Addition information about an MF2 message that aids in translation, or other pre-runtime processes, but has no impact on how the message will be rendered. This may be context notes, screenshots of the string in situ, etc. Metadata should never be relied upon at runtime. |
There was a problem hiding this comment.
As we've left expression attributes out of the LDML 45 release and we've previously ruled out message-level metadata from the MF2 spec, we've avoided needing to explicitly agree whether or not metadata may have a runtime impact.
| - **metadata** - Addition information about an MF2 message that aids in translation, or other pre-runtime processes, but has no impact on how the message will be rendered. This may be context notes, screenshots of the string in situ, etc. Metadata should never be relied upon at runtime. | ||
| - **open/close** - syntax within the source test that changes the execution context of the parser from output mode to code mode, and back again. | ||
| - **operand** - A character in a message that denotes an action taken during runtime execution, such as value assignment or comparison. | ||
| - **options** - values passed in, along with an MF2 message, that will be used to determine the output. Examples may be item count in a search results string. |
There was a problem hiding this comment.
Using "options" for this is misleading; that's used often for the named arguments of expressions and markup.
For this meaning, I think we usually say "arguments" or "parameters".
There was a problem hiding this comment.
ok, thanks. I was inferring from how I'd heard it used in conversation, but I don't think we are all using is consistently yet.
| - **resource** - files bundled with an application that are loaded in by the executable code. UI strings, etc. and their locale-specific translations are typically stored as resources. | ||
| - **roundtrip** - the process of transforming a message into another format or representation, then transforming it back into the original format. | ||
| - **translation merging** - in l10n TMSes, the document-level interpolation of translated content. In other words, the replacing of translatable units in the source document with their equivalent translated units. See _interpolate_. | ||
| - **selector** - see _placeholder type_. | ||
| - **specification** - the rules we decide that describe what is passed to the API for message formatting (structure of data, syntax, etc.). | ||
| - **serialization** - how to convert in-memory representations of data to/from a file/stream. | ||
| - **sigil** - A character in a string that is used to denote a change in context. |
There was a problem hiding this comment.
This isn't quite right; they used to be the leading prefix character, but now with standalone markup we also use one in a trailing position.
There was a problem hiding this comment.
Thanks @SimonClark for suggesting these additions.
Since this is an informative document, I might make two suggestions:
- We should leave this work to post-45
- The spec has many definitions carefully formatted into it. You might look for the
<dfn>tags in syntax.md, formatting.md, etc. and see if the definitions there are mirrored here. Where the definitions in the spec are insufficient (require more than just some formatting changes to appear in this document), that might be cause for work on the source document.
docs/glossary-and-resources.md
Outdated
| @@ -23,23 +23,44 @@ | |||
|
|
|||
| ### Terms for message formatting | |||
|
|
|||
|
|
|||
| - **[ABNF](https://en.wikipedia.org/wiki/Augmented_Backus%E2%80%93Naur_form)** - (Augmented Backus-Naur Form). ABNF is a method of specifying valid syntax for a specification. The MessageFormat ABNF spec defines what is and is not required for a string to be valid MessageFormat. ABNF is specified by RFC 5234 and RFC 7405; x | |||
There was a problem hiding this comment.
Use line breaks.
I don't think this term is needed?
Link the RFCs.
Unwanted x at the end?
There was a problem hiding this comment.
Perhaps. I approached this as an audience of me, trying to become a useful participant/contributor as well as consumer of MF2. I can see that it makes sense to narrow the audience to just the latter.
docs/glossary-and-resources.md
Outdated
| - **data model** - a syntax-independent description of the structure of values passed to the message formatting API. | ||
| - **implementation** - code written to make the API achieve the intended behavior of output for a given input. | ||
| - **format to parts** - context-aware functionality that can take a formatted string (such as a monetary amount, or a date), and return the seperated constituent parts. |
There was a problem hiding this comment.
This description is actually wrong, as "format to parts" functions generally don't start with the formatted string. They start with an object (whatever the input is) and return the object as a sequence of formatted parts. See, for example, Intl.NumberFormat
| - **markup** - characters present in the MessageFormat source strings that are intended to provide structure, functionality, or formatting to the output string, as opposed to display text. | ||
| - **match** - a mechanism in MessageFormat that allows the message author to specify a variety of outcomes based on the combined values of one or more inputs. | ||
| - **metadata** - Addition information about an MF2 message that aids in translation, or other pre-runtime processes, but has no impact on how the message will be rendered. This may be context notes, screenshots of the string in situ, etc. Metadata should never be relied upon at runtime. | ||
| - **open/close** - syntax within the source test that changes the execution context of the parser from output mode to code mode, and back again. |
There was a problem hiding this comment.
This is confusing for the reasons @eemeli states.
Co-authored-by: Eemeli Aro <eemeli@gmail.com>
Co-authored-by: Eemeli Aro <eemeli@gmail.com>
Co-authored-by: Eemeli Aro <eemeli@gmail.com>
Co-authored-by: Eemeli Aro <eemeli@gmail.com>
Co-authored-by: Eemeli Aro <eemeli@gmail.com>
Co-authored-by: Eemeli Aro <eemeli@gmail.com>
Co-authored-by: Eemeli Aro <eemeli@gmail.com>
aphillips
added
documentation
Adding some new terms from discussions in the group. These are my understandings of how we are using the words, so feel free to suggest better definitions.