adobe · Jul 4, 2018 · Nov 12, 2018 · Nov 12, 2018 · Dec 13, 2018 · Dec 13, 2018
Showing with 287 additions and 73 deletions.

+52 −11 CHANGELOG.md

+74 −0 CODE_OF_CONDUCT.md

+47 −0 CONTRIBUTING.md

+4 −4 README.md

+110 −58 SPECIFICATION.md
diff --git a/CHANGELOG.md b/CHANGELOG.md
@@ -1,22 +1,63 @@
-HTML Template Language Specification [1.2](https://github.com/Adobe-Marketing-Cloud/htl-spec/tree/1.2) - March 30th, 2016
+HTML Template Language Specification [1.4.1](https://github.com/adobe/htl-spec/tree/1.4.1) - TBD
+====
+Version 1.4.1 is a micro release that clarifies some of the wording from version 1.4 or provides more guidance for implementations.
+
+For a full list of issues addressed by this release please check [8].
+
+[8] - https://github.com/adobe/htl-spec/milestone/4?closed=1
+
+HTML Template Language Specification [1.4](https://github.com/adobe/htl-spec/tree/1.4) - June 18th, 2018
+====
+Version 1.4 brings the following enhancements:
+* `data-sly-list` and `data-sly-repeat` iteration control (#55) [0][1]
+*  the introduction of the `in` relational operator (#56) [2]
+* support for negative Number literals (#44) [3]
+* attribute identifier for the `data-sly-unwrap` block statement (#52) [4]
+* an extended list of attributes for which the `uri` display context is applied automatically (#62) [5]
+* a new block statement - `data-sly-set` [6]
+
+For a full list of issues addressed by this release please check [7].
+
+[0] - https://github.com/adobe/htl-spec/blob/1.4/SPECIFICATION.md#226-list  
+[1] - https://github.com/adobe/htl-spec/blob/1.4/SPECIFICATION.md#227-repeat  
+[2] - https://github.com/adobe/htl-spec/blob/1.4/SPECIFICATION.md#1143-relational-operators  
+[3] - https://github.com/adobe/htl-spec/blob/1.4/SPECIFICATION.md#111-grammar  
+[4] - https://github.com/adobe/htl-spec/blob/1.4/SPECIFICATION.md#2211-unwrap  
+[5] - https://github.com/adobe/htl-spec/blob/1.4/SPECIFICATION.md#113-context-sensitive  
+[6] - https://github.com/adobe/htl-spec/blob/1.4/SPECIFICATION.md#2212-set  
+[7] - https://github.com/adobe/htl-spec/milestone/3?closed=1
+
+HTML Template Language Specification [1.3.1](https://github.com/adobe/htl-spec/tree/1.3.1) - August 1st, 2017
+====
+Enhancements:
+* corrected examples from the [URI manipulation](https://github.com/adobe/htl-spec/blob/1.3.1/SPECIFICATION.md#125-uri-manipulation) section
+* added paragraph about the style and the event attributes for the `data-sly-attribute` block element
+
+HTML Template Language Specification [1.3](https://github.com/adobe/htl-spec/tree/1.3) - March 16th, 2017
+====
+New features:
+- the [`format`](https://github.com/adobe/htl-spec/blob/1.3/SPECIFICATION.md#122-format) option has been extended to allow formatting `strings`, `dates` and `numbers`
+
+
+HTML Template Language Specification [1.2](https://github.com/adobe/htl-spec/tree/1.2) - March 30th, 2016
 ====
 
 New Features:
-* allow Java enums to be used in [comparisons](https://github.com/Adobe-Marketing-Cloud/htl-spec/blob/1.2/SPECIFICATION.md#1142-comparison-operators)
+* allow Java enums to be used in [comparisons](https://github.com/adobe/htl-spec/blob/1.2/SPECIFICATION.md#1142-comparison-operators)
 
 Enhancements:
-* documented the `data-sly-include` `file` option, which was present in the [TCK](https://github.com/Adobe-Marketing-Cloud/htl-tck/blob/io.sightly.tck-1.0.0/src/main/resources/testfiles/scripts/blockstatements/include/include.html#L27) + reference implementation since 1.0
+* documented the `data-sly-include` `file` option, which was present in the [TCK](https://github.com/adobe/htl-tck/blob/io.sightly.tck-1.0.0/src/main/resources/testfiles/scripts/blockstatements/include/include.html#L27) + reference implementation since 1.0
 
-HTML Template Language Specification [1.1](https://github.com/Adobe-Marketing-Cloud/htl-spec/tree/1.1) - February 16th, 2015
+HTML Template Language Specification [1.1](https://github.com/adobe/htl-spec/tree/1.1) - February 16th, 2015
 ====
 
 New Features:
-* [`styleComment`](https://github.com/Adobe-Marketing-Cloud/htl-spec/blob/1.1/SPECIFICATION.md#121-display-context) display context
-* [URI manipulation](https://github.com/Adobe-Marketing-Cloud/htl-spec/blob/1.1/SPECIFICATION.md#125-uri-manipulation) options
-* [`data-sly-repeat`](https://github.com/Adobe-Marketing-Cloud/htl-spec/blob/1.1/SPECIFICATION.md#227-repeat) block element
-* special HTML tags - [`<sly>`](https://github.com/Adobe-Marketing-Cloud/htl-spec/blob/1.1/SPECIFICATION.md#31-sly)
+* [`styleComment`](https://github.com/adobe/htl-spec/blob/1.1/SPECIFICATION.md#121-display-context) display context
+* [URI manipulation](https://github.com/adobe/htl-spec/blob/1.1/SPECIFICATION.md#125-uri-manipulation) options
+* [`data-sly-repeat`](https://github.com/adobe/htl-spec/blob/1.1/SPECIFICATION.md#227-repeat) block element
+* special HTML tags - [`<sly>`](https://github.com/adobe/htl-spec/blob/1.1/SPECIFICATION.md#31-sly)
 
 Enhancements:
-* the [`join`](https://github.com/Adobe-Marketing-Cloud/htl-spec/blob/1.1/SPECIFICATION.md#124-array-join) option can also be used with a simple string, outputting just the string in this case
-* for [`data-sly-list`](https://github.com/Adobe-Marketing-Cloud/htl-spec/blob/1.1/SPECIFICATION.md#226-list) (and also for [`data-sly-repeat`](https://github.com/Adobe-Marketing-Cloud/htl-spec/blob/1.1/SPECIFICATION.md#227-repeat)) the element will be shown only if the attribute's value provides a non-empty collection, a string or a number
-* no need to strictly define [reserved options](https://github.com/Adobe-Marketing-Cloud/htl-spec/blob/1.0/SPECIFICATION.md#13-reserved-options) like in 1.0
+* the [`join`](https://github.com/adobe/htl-spec/blob/1.1/SPECIFICATION.md#124-array-join) option can also be used with a simple string, outputting just the string in this case
+* for [`data-sly-list`](https://github.com/adobe/htl-spec/blob/1.1/SPECIFICATION.md#226-list) (and also for [`data-sly-repeat`](https://github.com/adobe/htl-spec/blob/1.1/SPECIFICATION.md#227-repeat)) the element will be shown only if the attribute's value provides a non-empty collection, a string or a number
+* no need to strictly define [reserved options](https://github.com/adobe/htl-spec/blob/1.0/SPECIFICATION.md#13-reserved-options) like in 1.0
diff --git a/CODE_OF_CONDUCT.md b/CODE_OF_CONDUCT.md
@@ -0,0 +1,74 @@
+# Adobe Code of Conduct
+
+## Our Pledge
+
+In the interest of fostering an open and welcoming environment, we as
+contributors and maintainers pledge to making participation in our project and
+our community a harassment-free experience for everyone, regardless of age, body
+size, disability, ethnicity, gender identity and expression, level of experience,
+nationality, personal appearance, race, religion, or sexual identity and
+orientation.
+
+## Our Standards
+
+Examples of behavior that contributes to creating a positive environment
+include:
+
+* Using welcoming and inclusive language
+* Being respectful of differing viewpoints and experiences
+* Gracefully accepting constructive criticism
+* Focusing on what is best for the community
+* Showing empathy towards other community members
+
+Examples of unacceptable behavior by participants include:
+
+* The use of sexualized language or imagery and unwelcome sexual attention or
+advances
+* Trolling, insulting/derogatory comments, and personal or political attacks
+* Public or private harassment
+* Publishing others' private information, such as a physical or electronic
+  address, without explicit permission
+* Other conduct which could reasonably be considered inappropriate in a
+  professional setting
+
+## Our Responsibilities
+
+Project maintainers are responsible for clarifying the standards of acceptable
+behavior and are expected to take appropriate and fair corrective action in
+response to any instances of unacceptable behavior.
+
+Project maintainers have the right and responsibility to remove, edit, or
+reject comments, commits, code, wiki edits, issues, and other contributions
+that are not aligned to this Code of Conduct, or to ban temporarily or
+permanently any contributor for other behaviors that they deem inappropriate,
+threatening, offensive, or harmful.
+
+## Scope
+
+This Code of Conduct applies both within project spaces and in public spaces
+when an individual is representing the project or its community. Examples of
+representing a project or community include using an official project e-mail
+address, posting via an official social media account, or acting as an appointed
+representative at an online or offline event. Representation of a project may be
+further defined and clarified by project maintainers.
+
+## Enforcement
+
+Instances of abusive, harassing, or otherwise unacceptable behavior may be
+reported by contacting the project team at Grp-opensourceoffice@adobe.com. All
+complaints will be reviewed and investigated and will result in a response that
+is deemed necessary and appropriate to the circumstances. The project team is
+obligated to maintain confidentiality with regard to the reporter of an incident.
+Further details of specific enforcement policies may be posted separately.
+
+Project maintainers who do not follow or enforce the Code of Conduct in good
+faith may face temporary or permanent repercussions as determined by other
+members of the project's leadership.
+
+## Attribution
+
+This Code of Conduct is adapted from the [Contributor Covenant][homepage], version 1.4,
+available at [http://contributor-covenant.org/version/1/4][version]
+
+[homepage]: http://contributor-covenant.org
+[version]: http://contributor-covenant.org/version/1/4/
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -0,0 +1,47 @@
+# Contributing
+
+Thanks for choosing to contribute!
+
+The following are a set of guidelines to follow when contributing to this project.
+
+## Code Of Conduct
+
+This project adheres to the Adobe [code of conduct](CODE_OF_CONDUCT.md). By participating,
+you are expected to uphold this code. Please report unacceptable behavior to
+[Grp-opensourceoffice@adobe.com](mailto:Grp-opensourceoffice@adobe.com).
+
+## Have A Question?
+
+Start by filing an issue. The existing committers on this project work to reach
+consensus around project direction and issue solutions within issue threads
+(when appropriate).
+
+## Contributor License Agreement
+
+All third-party contributions to this project must be accompanied by a signed contributor
+license agreement. This gives Adobe permission to redistribute your contributions
+as part of the project. [Sign our CLA](http://opensource.adobe.com/cla.html). You
+only need to submit an Adobe CLA one time, so if you have submitted one previously,
+you are good to go!
+
+## Code Reviews
+
+All submissions should come in the form of pull requests and need to be reviewed
+by project committers. Read [GitHub's pull request documentation](https://help.github.com/articles/about-pull-requests/)
+for more information on sending pull requests.
+
+Lastly, please follow the [pull request template](PULL_REQUEST_TEMPLATE.md) when
+submitting a pull request!
+
+## From Contributor To Committer
+
+We love contributions from our community! If you'd like to go a step beyond contributor
+and become a committer with full write access and a say in the project, you must
+be invited to the project. The existing committers employ an internal nomination
+process that must reach lazy consensus (silence is approval) before invitations
+are issued. If you feel you are qualified and want to get more deeply involved,
+feel free to reach out to existing committers to have a conversation about that.
+
+## Security Issues
+
+Security issues shouldn't be reported on this issue tracker. Instead, [file an issue to our security experts](https://helpx.adobe.com/security/alertus.html)
diff --git a/README.md b/README.md
@@ -1,11 +1,11 @@
 HTML Template Language Specification
 ====
-The [HTML Template Language](https://docs.adobe.com/docs/en/htl.html "Introduction to the HTML Template Language") (HTL), formerly known as Sightly, has been introduced with [Adobe Experience Manager](http://www.adobe.com/solutions/web-experience-management.html) 6.0 and takes the place of JSP (JavaServer Pages) as the preferred and recommended server-side template system for HTML.
+The [HTML Template Language](https://experienceleague.adobe.com/docs/experience-manager-htl/content/overview.html "HTL Guide") (HTL), formerly known as Sightly, has been introduced with [Adobe Experience Manager](http://www.adobe.com/solutions/web-experience-management.html) 6.0 and takes the place of JSP (JavaServer Pages) as the preferred and recommended server-side template system for HTML.
 
-This is the [HTL Specification](https://github.com/Adobe-Marketing-Cloud/htl-spec/blob/master/SPECIFICATION.md) that defines the syntax and the behavior of the language.
+This is the [HTL Specification](https://github.com/adobe/htl-spec/blob/master/SPECIFICATION.md) that defines the syntax and the behavior of the language.
 
 A Java-based reference implementation has been [donated to the Apache Sling project](https://issues.apache.org/jira/browse/SLING-3959) and can be checked out from https://github.com/apache/sling/tree/trunk/bundles/scripting/sightly.
 
-The [Technology Compatibility Kit](https://github.com/Adobe-Marketing-Cloud/htl-tck) can be run on implementations to check their compliance with the specification.
+The [Technology Compatibility Kit](https://github.com/adobe/htl-tck) can be run on implementations to check their compliance with the specification.
 
-An implementation of [version 1.3](https://github.com/Adobe-Marketing-Cloud/htl-spec/blob/1.3/SPECIFICATION.md) of the language specification is available in AEM 6.3.
+An implementation of [version 1.4](https://github.com/adobe/htl-spec/blob/1.4/SPECIFICATION.md) of the language specification is available in AEM 6.3 SP3 and AEM 6.4 SP1.
diff --git a/SPECIFICATION.md b/SPECIFICATION.md
@@ -85,9 +85,9 @@ The grammar of the HTL Expression Language is pretty simple and can be summarise
 
     andBinaryOp = inBinaryOp {, '&&', inBinaryOp};
 
-    inBinaryOp = comparisonOp {, 'in', comparisonOp};
+    inBinaryOp = comparisonOp [, 'in', comparisonOp];
 
-    comparisonOp = factor {, comparisonOperator, factor};
+    comparisonOp = factor [, comparisonOperator, factor];
 
     comparisonOperator = '<'
          | '<='
@@ -151,7 +151,7 @@ The grammar of the HTL Expression Language is pretty simple and can be summarise
 
     hexDigit = ('0'..'9'|'a'..'f'|'A'..'F') ;
 
-The above grammar is adapted from the source ANTLR files. It uses the following conventions:
+The above grammar is adapted from the [source ANTLR files](https://github.com/apache/sling-org-apache-sling-scripting-sightly-compiler/tree/master/src/main/antlr4/org/apache/sling/scripting/sightly/impl/parser/expr/generated). It uses the following conventions:
 
     foo   Alphabetic words and comma (',') are rule names.
     /**/  Slash-star and star-slash delimit comments.
@@ -245,7 +245,7 @@ ${varOne && !(varTwo || varThree)} <!--/* 1. Grouping parenthesis */-->
 ${!myVar}                          <!--/* 2. Logical NOT */-->
 ${varOne && varTwo}                <!--/* 3. Logical AND */-->
 ${varOne || varTwo}                <!--/* 4. Logical OR */-->
-${varChoice ? varOne : varTwo}     <!--/* 5. Conditional (ternary) (note that the ? and : separators must be surrounded by a space) */-->
+${varChoice ? varOne : varTwo}     <!--/* 5. Conditional (ternary) (note that the ':' separator must be surrounded by a space) */-->
 ```
 
 The numbers written in the comments above correspond to the precedence of the operators.
@@ -419,23 +419,27 @@ To protect against cross-site scripting (XSS) vulnerabilities, HTL automatically
 It is also possible to override the automatic display context handling with the `context` option.
 
 ```html
-${properties.jcr:title @ context='html'}          <!--/* Use this in case you want to output HTML - Removes markup that may contain XSS risks */-->
-${properties.jcr:title @ context='text'}          <!--/* Use this for simple HTML content - Encodes all HTML */-->
-${properties.jcr:title @ context='elementName'}   <!--/* Allows only element names that are white-listed, outputs 'div' otherwise */-->
-${properties.jcr:title @ context='attributeName'} <!--/* Outputs nothing if the value doesn't correspond to the HTML attribute name syntax - doesn't allow 'style' and 'on*' attributes */-->
-${properties.jcr:title @ context='attribute'}     <!--/* Applies HTML attribute escaping */-->
-${properties.jcr:title @ context='uri'}           <!--/* Outputs nothing if the value contains XSS risks */-->
-${properties.jcr:title @ context='scriptToken'}   <!--/* Outputs nothing if the value doesn't correspond to an Identifier, String literal or Numeric literal JavaScript token */-->
-${properties.jcr:title @ context='scriptString'}  <!--/* Applies JavaScript string escaping */-->
-${properties.jcr:title @ context='scriptComment'} <!--/* Context for Javascript block comments. Outputs nothing if value is trying to break out of the comment context */-->
-${properties.jcr:title @ context='scriptRegExp'}  <!--/* Applies JavaScript regular expression escaping */-->
-${properties.jcr:title @ context='styleToken'}    <!--/* Outputs nothing if the value doesn't correspond to the CSS token syntax */-->
-${properties.jcr:title @ context='styleString'}   <!--/* Applies CSS string escaping */-->
-${properties.jcr:title @ context='styleComment'}  <!--/* Context for CSS comments. Outputs nothing if value is trying to break out of the comment context */-->
-${properties.jcr:title @ context='comment'}       <!--/* Applies HTML comment escaping */-->
-${properties.jcr:title @ context='number'}        <!--/* Outputs zero if the value is not a number */-->
-${properties.jcr:title @ context='unsafe'}        <!--/* Use this at your own risk, this disables XSS protection completely */-->
-```
+${properties.jcr:title @ context='text'}
+```
+
+The following table lists the available contexts:
+
+|Context|When to use|What it does|
+|--- |--- |--- |
+|`attribute`|Default for attribute values|Encodes all HTML special characters.|
+|`attributeName`|Default for data-sly-attribute when setting attribute names|Validates the attribute name, outputs nothing if validation fails.|
+|`elementName`|Default for data-sly-element|Validates the element name, outputs nothing if validation fails.|
+|`html`|To safely output markup|Filters HTML in order to remove dangerous tags.|
+|`number`|To display numbers|Validates that the passed value is a number, outputs nothing if validation fails.|
+|`scriptComment`|Within JavaScript comments|Validates the JavaScript comment, outputs nothing if validation fails.|
+|`scriptString`|Within JavsScript strings|Encodes characters that would break out of the string.|
+|`scriptToken`|For JavaScript identifiers, literal numbers, or literal strings|Validates the JavaScript token, outputs nothing if validation fails.|
+|`styleComment`|Within CSS comments|Validates the CSS comment, outputs nothing if validation fails.|
+|`styleString`|Within CSS strings|Encodes characters that would break out of the string.|
+|`styleToken`|For CSS identifiers, numbers, dimensions, strings, hex colours or functions.|Validates the CSS token, outputs nothing if validation fails.|
+|`text`|Default for content inside HTML [Text Nodes](https://developer.mozilla.org/en-US/docs/Web/API/Text)|Encodes all HTML special characters.|
+|`unsafe`|When all the other contexts are too restrictive|_Disables escaping and XSS protection completely._|
+|`uri`|To display links and paths; default for the `action`, `cite`, `data`, `formaction`, `href`, `manifest`, `poster` and `src` attribute values|Validates the URI and outputs nothing if validation fails.|
 
 Note that `context='elementName'` allows only the following element names:
 
@@ -817,13 +821,18 @@ URI manipulation can be performed by adding any of the following options to an e
 ## 2. Block Statements
 
 ### 2.1. Syntax
-HTL block plugins are defined by `data-sly-*` attributes set on HTML elements. Elements can have a closing tag or be self-closing. Attributes can have values (which can be static strings or expressions), or simply be boolean attributes (without a value).
+HTL block plugins are defined by `data-sly-*` attributes set on HTML elements. Elements can have a closing tag or be self-closing. Attributes can have values (which can be static strings or expressions), or simply be boolean attributes (without a value). The attribute values can be single-quoted, double-quoted or unquoted.
 
 ```html
 <tag data-sly-BLOCK></tag>                                 <!--/* A block is simply consists in a data-sly attribute set on an element. */-->
 <tag data-sly-BLOCK/>                                      <!--/* Empty elements (without a closing tag) should have the trailing slash. */-->
 <tag data-sly-BLOCK="string value"/>                       <!--/* A block statement usually has a value passed, but not necessarily. */-->
-<tag data-sly-BLOCK="${expression}"/>                      <!--/* The passed value can be an expression as well. */-->
+
+<!--/* The passed value can be an expression as well. */-->
+<tag data-sly-BLOCK="${expression}"
+     data-sly-BLOCK='${expression}'
+     data-sly-BLOCK=${expression}/>
+
 <tag data-sly-BLOCK="${@ myArg='foo'}"/>                   <!--/* Or a parametric expression with arguments. */-->
 <tag data-sly-BLOCKONE="value" data-sly-BLOCKTWO="value"/> <!--/* Several block statements can be set on a same element. */-->
 ```
@@ -891,7 +900,7 @@ Parameters can be passed to the Use-API by using expression options:
 
 More informations about how the Use-API is working can be found in the [Use-API section](#4-use-api).
 
-The use statement can also be used to load external templates. See the [Template & Call section](#229-template--call) for this usage.
+The use statement can also be used to load external templates. See the [Template & Call section](#2210-template--call) for this usage.
 
 #### 2.2.2. Text
 **`data-sly-text`:**
@@ -1069,7 +1078,7 @@ The element name is automatically XSS-protected with the `elementName` context,
 * Keeps or removes the element depending on the attribute value.
 * **Element:** shown if test evaluates to `true`.
 * **Content of element:** shown if test evaluates to `true`.
-* **Attribute value:** optional; evaluated as `Boolean` (but not type-cased to `Boolean` when exposed in a variable); evaluates to `false` if the value is omitted.
+* **Attribute value:** optional; evaluated as `Boolean` (but not type-casted to `Boolean` when exposed in a variable); evaluates to `false` if the value is omitted.
 * **Attribute identifier:** optional; identifier name to access the result of the test.
 * **Scope:** The identifier set by the `data-sly-test` block element is global to the script and can be used anywhere after its declaration:
 
@@ -1104,7 +1113,7 @@ Note that the identifier contains the value of the condition as it was (not cast
 * **Content of element:** repeated as many times as there are items in the attribute value.
 * **Attribute value:** optional; the item to iterate over; if omitted the content will not be shown.
 * **Attribute identifier:** optional; customised identifier name to access the item within the list element; if an identifier is not provided, the block element will implicitly make available an `item` identifier to access the element of the current iteration.
-* **Scope:** The identifier set by the `data-sly-list` block element is available only in the element's scope. The identifier will override other identifiers with the same name available in the scope, however their values will be restored once outside of the element's scope.
+* **Scope:** The identifier set by the `data-sly-list` block element is available only in the element's content scope. The identifier will override other identifiers with the same name available in the scope, however their values will be restored once outside of the element's scope.
 
 Repeats the content of the element for each item of the provided object (which can be an array, or any iterable object).
 
@@ -1160,7 +1169,7 @@ value, allowing to control the iteration through the following options:
 * **Content of element:** repeated as many times as there are items in the attribute value.
 * **Attribute value:** optional; the item to iterate over; if omitted the containing element and its content will not be shown.
 * **Attribute identifier:** optional; customised identifier name to access the item within the repeat element; if an identifier is not provided, the block element will implicitly make available an `item` identifier to access the element of the current iteration.
-* **Scope:** The identifier set by the `data-sly-list` block element is available only in the element's scope. The identifier will override other identifiers with the same name available in the scope, however their values will be restored once outside of the element's scope.
+* **Scope:** The identifier set by the `data-sly-repeat` block element is available only in the element's scope. The identifier will override other identifiers with the same name available in the scope, however their values will be restored once outside of the element's scope.
 
 Repeats the content of the element for each item of the provided object (which can be an array, or any iterable object).
 
@@ -1205,7 +1214,9 @@ When iterating over `Map` objects, the item variable contains the key of each ma
 * **Attribute value:** required; the file to include.
 * **Attribute identifier:** none.
 
-Includes the output of a rendering script run with the current context, passing back control to the current HTL script.
+Includes the output of a rendering script run with the current request context, passing back control to the current HTL script.
+
+> Note: this is comparable to the JSP `<%@ include file="" %>`.
 
 ```html
 <div data-sly-include="template.html"></div>
@@ -1216,14 +1227,21 @@ Includes the output of a rendering script run with the current context, passing
 <div data-sly-include="${'template.html'}"></div>
 ```
 
-With an expression more options can be specified:
+With an expression more path manipulation options can be specified. Paths are resolved relative to the current rendering context:
 
-```html
-<!--/* Manipulating the path: */-->
-<div data-sly-include="${'template.html' @ appendPath='appended/path'}"></div>
-<div data-sly-include="${'template.html' @ prependPath='prepended/path'}"></div>
-<div data-sly-include="${@ file='template.html', prependPath='prepended/path', appendPath='appended/path'}"></div>
-```
+* `appendPath` - appends its content to the passed path
+* `prependPath` - prepends its content to the passed path
+
+    ```html
+    <div data-sly-include="${'partials' @ appendPath='template.html'}"></div>
+    <!--/* will include partials/template.html */-->
+
+    <div data-sly-include="${'template.html' @ prependPath='partials'}"></div>
+    <!--/* will include partials/template.html */-->
+
+    <div data-sly-include="${'components' @ prependPath='partials', appendPath='template.html'}"></div>
+    <!--/* will include partials/components/template.html */-->
+    ```
 
 The element on which a data-sly-include has been set is ignored and not displayed:
 
@@ -1243,35 +1261,50 @@ The scope of the `data-sly-include` statement isn't passed to the template of th
 * **Attribute value:** required; the path to include.
 * **Attribute identifier:** none.
 
-Includes a rendered resource from the same server, using an absolute or relative path.
+Includes a rendered resource from the same server, using an absolute or relative path. An implementation should create a new request context when retrieving the output.
+
+> Note: this is comparable to a `<jsp:include page="" />`.
 
 ```html
+<!--/* Following statements are equivalent: */-->
 <section data-sly-resource="./path"></section>
+<section data-sly-resource="${'./path'}"></section>
 ```
 
 With an expression more options can be specified:
 
-```html
-<!--/* Following statements are equivalent: */-->
-<section data-sly-resource="./path"></section>
-<section data-sly-resource="${'./path'}"></section>
-
-<!--/* Manipulating the path: */-->
-<section data-sly-resource="${'my/path' @ appendPath='appended/path'}"></section>
-<section data-sly-resource="${'my/path' @ prependPath='prepended/path'}"></section>
-
-<!--/* Manipulating selectors: */-->
-<section data-sly-resource="${'my/path' @ selectors='selector1.selector2'}"></section>
-<section data-sly-resource="${'my/path' @ selectors=['selector1', 'selector2']}"></section>
-<section data-sly-resource="${'my/path' @ addSelectors='selector1.selector2'}"></section>
-<section data-sly-resource="${'my/path' @ addSelectors=['selector1', 'selector2']}"></section>
-<section data-sly-resource="${'my/path' @ removeSelectors='selector1.selector2'}"></section>
-<section data-sly-resource="${'my/path' @ removeSelectors=['selector1', 'selector2']}"></section>
-<section data-sly-resource="${'my/path' @ removeSelectors}"></section>
+* `appendPath` - appends its content to the passed path
+* `prependPath` - prepends its content to the passed path
+    ```html
+    <section data-sly-resource="${'my/path' @ appendPath='appended/path'}"></section>
+    <!--/* Will include my/path/appended/path */-->
+    <section data-sly-resource="${'my/path' @ prependPath='prepended/path'}"></section>
+    <!--/* Will include prepended/path/my/path */-->
+    ```
+* `selectors` - replaces all selectors from the original request with the selectors passed in a selector string or a selector array before including the passed path:
+    ```html
+    <!--/* Manipulating selectors: */-->
+    <section data-sly-resource="${'my/path' @ selectors='selector1.selector2'}"></section>
+    <section data-sly-resource="${'my/path' @ selectors=['selector1', 'selector2']}"></section>
+    ```
 
-<!--/* Forcing the type of the rendered resource: */-->
-<section data-sly-resource="${'./path' @ resourceType='my/resource/type'}"></section>
-```
+* `addSelectors` - adds the selectors from the passed selector string or selector array to the original request before including the passed path:
+    ```html
+    <section data-sly-resource="${'my/path' @ addSelectors='selector1.selector2'}"></section>
+    <section data-sly-resource="${'my/path' @ addSelectors=['selector1', 'selector2']}"></section>
+    ```
+
+* `removeSelectors` - removes the selectors found in the passed selector string or selector array from the original request before including the passed path; when the option doesn't have a value, all the selectors will be removed from the original request:
+    ```html
+    <section data-sly-resource="${'my/path' @ removeSelectors='selector1.selector2'}"></section>
+    <section data-sly-resource="${'my/path' @ removeSelectors=['selector1', 'selector2']}"></section>
+    <section data-sly-resource="${'my/path' @ removeSelectors}"></section>
+    ```
+
+* `resourceType` - forces the rendering of the passed path with a script mapped to the overridden resource type:
+    ```html
+    <section data-sly-resource="${'./path' @ resourceType='my/resource/type'}"></section>
+    ```
 
 The scope of the `data-sly-resource` statement isn't passed to the template of the included resource.
 
@@ -1292,7 +1325,7 @@ Template blocks can be used like function calls: in their declaration they can g
 * Calls a declared HTML block, passing parameters to it.
 * **Element:** always shown.
 * **Content of element:** replaced with the content of the called `data-sly-template` element.
-* **Attribute value:** optional; an expression defining the template identifier and the parameters to pass.
+* **Attribute value:** required; an expression defining the template identifier and the parameters to pass.
 * **Attribute identifier:** none.
 
 ##### 2.2.10.3. Examples
@@ -1325,7 +1358,7 @@ When some parameters are missing in a template call, that parameter would be ini
 #### 2.2.11. Unwrap
 **`data-sly-unwrap`:**
 * Unwraps the element.
-* **Element:** never shown.
+* **Element:** shown if expression evaluates to `false`.
 * **Content of element:** always shown.
 * **Attribute value:** optional; an expression evaluated as `Boolean`; defaults to `true` if the value is omitted.
 * **Attribute identifier:** optional; identifier name to access the result of the test.
@@ -1410,6 +1443,11 @@ The Use-API POJOs can also expose a public method, called `init`, with the follo
 The `bindings` map can contain objects that provide context to the currently executed HTL script that the Use-API object can use for its processing.
 
 ### 4.2. JavaScript Use-API
+
+>The JavaScript Use API has been deprecated for use with AEM as a Cloud Service. Please use [the Java Use API instead.](https://experienceleague.adobe.com/en/docs/experience-manager-htl/content/java-use-api)
+>
+>[Please see the AEM as a Cloud Service release notes](https://experienceleague.adobe.com/en/docs/experience-manager-cloud-service/content/release-notes/deprecated-removed-features) for more information on deprecated and removed features.
+
 Use objects can also be defined with JavaScript, using the following conventions:
 
 ```javascript
@@ -1431,3 +1469,17 @@ use(['dep1.js', 'dep2.js'], function (Dep1, Dep2) {
     }
 });
 ```
+
+### 4.3. Object Resolution and their Properties or Methods
+HTL implementations have to provide the appropriate support for the Use-API depending on the platform on which they run. However, property or method resolution on a target object must obey the following rules:
+
+1. `expression.identifier` is equivalent to `expression["identifier"]` and to `expression['identifier']`
+2. the `identifier` resolution uses the following algorithm:
+
+    1. try to resolve the `identifier` as a publicly accessible field of the object returned by the `expression`; if found, return;
+    2. try to resolve the `identifier` as a publicly accessible method without formal parameters of the object returned by the `expression`:
+
+        1. try to find a method whose name is `identifier`; if found, call method and return;
+        2. try to find a getter called `getIdentifier` (notice the `camelCase`); if found, call method and return;
+        3. try to find an `isIdentifier` method (notice the `camelCase`); if found, call method and return;
+        4. return `null`