Github user aledsage commented on a diff in the pull request:
https://github.com/apache/brooklyn-docs/pull/148#discussion_r103166453
--- Diff: guide/yaml/yaml-reference.md ---
@@ -213,6 +213,9 @@ concise DSL defined here:
`$brooklyn:root()`.
* `$brooklyn:formatString("pattern e.g. %s %s", "field 1", "field 2")`
returns a future which creates the formatted string
with the given parameters, where parameters may be strings *or* other
tasks such as `attributeWhenReady`
+* `$brooklyn:urlEncode("val")` returns a future which creates a string
with the characters escaped
--- End diff --
@drigodwin agreed - the wording I used here is consistent with the rest of
the descriptions. I'll leave it as-is for this PR. We should revisit to rewrite
the descriptions of the entire "DSL Commands" section. An introductory
paragraph that says about how the DSL is resolved is probably worth while (it's
important that users understand it's a future for any non-trivial use-case, so
they can understand when/if it will block (and also what happens if you compose
DSL).
---
We are also missing a better description and examples of how to compose the
DSL - e.g. are we recommending what to me feels like "idiomatic yaml" like:
```
$brooklyn:formatString:
- "http://%s";
- $brooklyn:attributeWhenReady("host.subnet.hostname")
```
versus `$brooklyn:formatString("http://%s";,
$brooklyn:attributeWhenReady("host.subnet.hostname"))`, which looks more like a
programming language and less like configuration. (I get that it is effectively
programming, but that doesn't mean the user needs to write it like that!).
---
If your project is set up for it, you can reply to this email and have your
reply appear on GitHub as well. If your project does not have this feature
enabled and wishes so, or if the feature is enabled but not working, please
contact infrastructure at [email protected] or file a JIRA ticket
with INFRA.
---
