Merge pull request #1714 from reebhub/RDoc-2393_loadToSyntax

RDoc-2393_loadToSyntax

Documentation/4.0/Raven.Documentation.Pages/server/ongoing-tasks/etl/basics.markdown

@@ -98,7 +98,7 @@ In addition to ECMAScript 5.1 API, RavenDB introduces the following functions an
 Specific ETL functions:  
 
 | ------ |:------:| ------ |
-| `loadTo<Target>(obj)` | function | Load an object to a specified `<Target>`.<br/>The target must be either a collection name (RavenDB ETL) or a table name (SQL ETL).<br/>**An object will be sent to the destination only if** the `loadTo` method was called.|
+| `loadTo` | function | Load an object to a specified target. <br> There are several possible flavors to the syntax of this command, <br> find the general details [below](../../../server/ongoing-tasks/etl/basics#load) and more in the documentation for each ETL type. <br> **Note:** An object will be sent to the destination **only** if the `loadTo` method was called. |
 | `loadAttachment(name)` | function | Load an attachment (SQL ETL only) |
 
 {INFO: Batch processing}
@@ -118,7 +118,31 @@ The number of documents processed depends on the following configuration limits:
 
  Loading the results to the target destination is the last stage.
 
- Updates are implemented by executing consecutive DELETEs and INSERTs.
+{NOTE: Syntax}
+An object can generally be loaded to a specified target using one of the below templates:  
+
+* The target is specified as a part of the `loadTo` command: `loadToTarget(obj)`  
+  E.g., `loadToOrders(obj)`  
+* The target is specified as an argument of the `loadTo` command: `loadTo('Target', obj)`  
+  E.g., `loadTo('Orders', obj)`
+  {INFO: }
+
+   * The target name in this syntax is **not** a variable and **cannot** be used as one: 
+     it is simply a string literal of the target's name.  
+   * Separating the target name from the `loadTo` command makes it possible to include symbols like 
+     `-` and `.` in target names. This is not possible when the standard `loadToOrders` syntax is 
+     used because special characters are invalid in the name of a JS function.  
+   * Note that the general syntax specified above, `loadTo('Target', obj)`, changes for some 
+     ETL types. Find the accurate syntax for each ETL type in the type's specific documentation.  
+  {INFO/}
+
+The target must be:  
+
+* _RavenDB_ ETL: a _collection_ name  
+* _SQL_ ETL: a _table_ name  
+{NOTE/}
+
+Updates are implemented by executing consecutive DELETEs and INSERTs.
  When a document is modified, the delete command is sent before the new data is inserted, and both are processed under the same transaction on the destination side.
  This applies to both ETL types.  
 

Documentation/4.0/Raven.Documentation.Pages/server/ongoing-tasks/etl/raven.markdown

@@ -62,6 +62,31 @@ loadToEmployees(this);
 {CODE-BLOCK/}
 {NOTE/}
 
+---
+
+{NOTE: }
+### Alternative Syntax
+
+The target collection name can be passed to the `loadTo` command separately, as a string argument, 
+using this syntax: `loadTo('Target', obj)`  
+
+* **Example**:  
+  The following two calls to `loadTo` are equivalent.  
+  `loadToEmployees(this);`  
+  `loadTo('Employees', this);`  
+
+{INFO: }
+
+ * The target name `'Employees'` in this syntax is **not** a variable and **cannot** be used as one: 
+   it is simply a string literal of the target's name.  
+ * Separating the target name from the `loadTo` command makes it possible to include symbols like 
+   `-` and `.` in target names. This is not possible when the standard `loadToEmployees` syntax is 
+   used because including special characters in the name of a JS function turns it invalid.  
+{INFO/}
+{NOTE/}
+
+---
+
 {NOTE: Documents Identifiers}
 
 * The documents generated in the destination database are given an id according to the collection name specified in the `loadTo` method.  

Documentation/4.0/Raven.Documentation.Pages/server/ongoing-tasks/etl/sql.markdown

@@ -59,6 +59,32 @@ loadToOrderLines({
 });
 {CODE-BLOCK/}
 
+
+---
+
+{NOTE: }
+### Alternative Syntax
+
+The target table name can be passed to the `loadTo` command separately, as a string argument, 
+using this syntax: `loadTo('Target', obj)`  
+
+* **Example**:  
+  The following two calls to `loadTo` are equivalent.  
+  `loadToEmployees(this);`  
+  `loadTo('Employees', this);`  
+
+{INFO: }
+
+ * The target name `'Employees'` in this syntax is **not** a variable and **cannot** be used as one: 
+   it is simply a string literal of the target's name.  
+ * Separating the target name from the `loadTo` command makes it possible to include symbols like 
+   `-` and `.` in target names. This is not possible when the standard `loadToEmployees` syntax is 
+   used because including special characters in the name of a JS function turns it invalid.  
+{INFO/}
+{NOTE/}
+
+---
+
 ### Filtering
 
 If you want to filter some documents out from the ETL you simply omit `loadTo` call:

Documentation/4.1/Raven.Documentation.Pages/server/ongoing-tasks/etl/basics.markdown

@@ -98,7 +98,7 @@ In addition to the ECMAScript 5.1 API, RavenDB introduces the following function
 Specific ETL functions:  
 
 | ------ |:------:| ------ |
-| `loadTo<Target>(obj)` | function | Load an object to a specified `<Target>`.<br/>The target must be either a collection name (RavenDB ETL) or a table name (SQL ETL).<br/>**An object will be sent to the destination only if the `loadTo` method was called**.|
+| `loadTo` | function | Load an object to a specified target. <br> There are several possible flavors to the syntax of this command, <br> find the general details [below](../../../server/ongoing-tasks/etl/basics#load) and more in the documentation for each ETL type. <br> **Note:** An object will be sent to the destination **only** if the `loadTo` method was called. |
 | Attachments: |||
 | `loadAttachment(name)` | function | Load an attachment of the current document |
 | `hasAttachment(name)` | function | Check if an attachment with a given name exists for the current document |
@@ -125,7 +125,31 @@ The number of documents processed depends on the following configuration limits:
 
  Loading the results to the target destination is the last stage.
 
- Updates are implemented by executing consecutive DELETEs and INSERTs.
+{NOTE: Syntax}
+An object can generally be loaded to a specified target using one of the below templates:  
+
+* The target is specified as a part of the `loadTo` command: `loadToTarget(obj)`  
+  E.g., `loadToOrders(obj)`  
+* The target is specified as an argument of the `loadTo` command: `loadTo('Target', obj)`  
+  E.g., `loadTo('Orders', obj)`
+  {INFO: }
+
+   * The target name in this syntax is **not** a variable and **cannot** be used as one: 
+     it is simply a string literal of the target's name.  
+   * Separating the target name from the `loadTo` command makes it possible to include symbols like 
+     `-` and `.` in target names. This is not possible when the standard `loadToOrders` syntax is 
+     used because special characters are invalid in the name of a JS function.  
+   * Note that the general syntax specified above, `loadTo('Target', obj)`, changes for some 
+     ETL types. Find the accurate syntax for each ETL type in the type's specific documentation.  
+  {INFO/}
+
+The target must be:  
+
+* _RavenDB_ ETL: a _collection_ name  
+* _SQL_ ETL: a _table_ name  
+{NOTE/}
+
+Updates are implemented by executing consecutive DELETEs and INSERTs.
  When a document is modified, the delete command is sent before the new data is inserted and both are processed under the same transaction on the destination side.
  This applies to both ETL types.  
 

Documentation/4.1/Raven.Documentation.Pages/server/ongoing-tasks/etl/raven.markdown

@@ -36,6 +36,7 @@
 {PANEL: Transformation Script Options}
 
 * [Loading Documents](../../../server/ongoing-tasks/etl/raven#loading-documents)
+* [Alternative Syntax](../../../server/ongoing-tasks/etl/raven#alternative-syntax)
 * [Documents Identifiers](../../../server/ongoing-tasks/etl/raven#documents-identifiers)
 * [Filtering](../../../server/ongoing-tasks/etl/raven#filtering)
 * [Loading Data from Other Documents](../../../server/ongoing-tasks/etl/raven#loading-data-from-other-documents)
@@ -103,6 +104,29 @@ The following is an example of a RavenDB ETL script processing documents from th
 
 ---
 
+{NOTE: }
+### Alternative Syntax
+
+The target collection name can be passed to the `loadTo` command separately, as a string argument, 
+using this syntax: `loadTo('Target', obj)`  
+
+* **Example**:  
+  The following two calls to `loadTo` are equivalent.  
+  `loadToEmployees(this);`  
+  `loadTo('Employees', this);`  
+
+{INFO: }
+
+ * The target name `'Employees'` in this syntax is **not** a variable and **cannot** be used as one: 
+   it is simply a string literal of the target's name.  
+ * Separating the target name from the `loadTo` command makes it possible to include symbols like 
+   `-` and `.` in target names. This is not possible when the standard `loadToEmployees` syntax is 
+   used because including special characters in the name of a JS function turns it invalid.  
+{INFO/}
+{NOTE/}
+
+---
+
 ### Documents Identifiers
 
 The documents generated in the destination database are given an ID according to the collection name specified in the `loadTo` method.  

Documentation/4.1/Raven.Documentation.Pages/server/ongoing-tasks/etl/sql.markdown

@@ -1,11 +1,39 @@
-#Ongoing Tasks: SQL ETL
-
-**SQL ETL** is a task that creates [ETL](../../../server/ongoing-tasks/etl/basics) process for a given database where a destination is a relational database.
-
-It can be defined using the Studio by creating `SQL ETL` task in `Settings -> Manage Ongoing Tasks`.
+# Ongoing Tasks: SQL ETL  
+---
+
+{NOTE: }
+
+**SQL ETL** is a task that creates an [ETL](../../../server/ongoing-tasks/etl/basics) process 
+for a given database where the destination is a relational database.
+
+* In this page:  
+  * [Creating a Task](../../../server/ongoing-tasks/etl/sql#creating-a-task)  
+  * [Supported Databases](../../../server/ongoing-tasks/etl/sql#supported-databases)  
+  * [Relational Database Setup](../../../server/ongoing-tasks/etl/sql#relational-database-setup)  
+  * [SQL Tables](../../../server/ongoing-tasks/etl/sql#sql-tables)  
+  * [Transformation Scripts](../../../server/ongoing-tasks/etl/sql#transformation-scripts)  
+     * [`loadTo` Method](../../../server/ongoing-tasks/etl/sql#method)  
+     * [Alternative Syntax](../../../server/ongoing-tasks/etl/sql#alternative-syntax)  
+     * [Filtering](../../../server/ongoing-tasks/etl/sql#filtering)  
+     * [Loading Other Documents](../../../server/ongoing-tasks/etl/sql#loading-other-documents)  
+     * [Accessing Metadata](../../../server/ongoing-tasks/etl/sql#accessing-metadata)  
+     * [Loading to Multiple Tables](../../../server/ongoing-tasks/etl/sql#loading-to-multiple-tables)  
+     * [Loading Attachments](../../../server/ongoing-tasks/etl/sql#loading-attachments)  
+     * [Counters](../../../server/ongoing-tasks/etl/sql#counters)  
+     * [Transforming to VARCHAR and NVARCHAR](../../../server/ongoing-tasks/etl/sql#transforming-to-varchar-and-nvarchar)  
+  * [Transaction Processing](../../../server/ongoing-tasks/etl/sql#advanced-options)  
+
+{NOTE/}
+
+---
+
+{PANEL: Creating a Task}
+To create an SQL ETL task using Studio open `Settings -> Manage Ongoing Tasks`.
 
 ![Figure 1. Configure SQL ETL task](images/sql-etl-setup.png)
 
+{PANEL/}
+
 {PANEL:Supported Databases}
 
 RavenDB can ETL to the following relational databases:
@@ -72,6 +100,30 @@ loadToOrderLines({
 });
 {CODE-BLOCK/}
 
+---
+
+{NOTE: }
+### Alternative Syntax
+
+The target table name can be passed to the `loadTo` command separately, as a string argument, 
+using this syntax: `loadTo('Target', obj)`  
+
+* **Example**:  
+  The following two calls to `loadTo` are equivalent.  
+  `loadToEmployees(this);`  
+  `loadTo('Employees', this);`  
+
+{INFO: }
+
+ * The target name `'Employees'` in this syntax is **not** a variable and **cannot** be used as one: 
+   it is simply a string literal of the target's name.  
+ * Separating the target name from the `loadTo` command makes it possible to include symbols like 
+   `-` and `.` in target names. This is not possible when the standard `loadToEmployees` syntax is 
+   used because including special characters in the name of a JS function turns it invalid.  
+{INFO/}
+{NOTE/}
+
+---
 ### Filtering
 
 If you want to filter some documents out from the ETL you simply omit `loadTo` call:
@@ -181,8 +233,6 @@ loadToUsers(
 });
 {CODE-BLOCK/}
 
-
-
 {PANEL/}
 
 {PANEL:Transaction Processing}

Documentation/4.2/Raven.Documentation.Pages/server/ongoing-tasks/etl/basics.markdown

@@ -98,7 +98,7 @@ In addition to the ECMAScript 5.1 API, RavenDB introduces the following function
 Specific ETL functions:  
 
 | ------ |:------:| ------ |
-| `loadTo<Target>(obj)` | function | Load an object to a specified `<Target>`.<br/>The target must be either a collection name (RavenDB ETL) or a table name (SQL ETL).<br/>**An object will be sent to the destination only if the `loadTo` method was called**.|
+| `loadTo` | function | Load an object to a specified target. <br> There are several possible flavors to the syntax of this command, <br> find the general details [below](../../../server/ongoing-tasks/etl/basics#load) and more in the documentation for each ETL type. <br> **Note:** An object will be sent to the destination **only** if the `loadTo` method was called. |
 | Attachments: |||
 | `loadAttachment(name)` | function | Load an attachment of the current document |
 | `hasAttachment(name)` | function | Check if an attachment with a given name exists for the current document |
@@ -128,6 +128,30 @@ The number of documents processed depends on the following configuration limits:
 
  Loading the results to the target destination is the last stage.
 
+{NOTE: Syntax}
+An object can generally be loaded to a specified target using one of the below templates:  
+
+* The target is specified as a part of the `loadTo` command: `loadToTarget(obj)`  
+  E.g., `loadToOrders(obj)`  
+* The target is specified as an argument of the `loadTo` command: `loadTo('Target', obj)`  
+  E.g., `loadTo('Orders', obj)`
+  {INFO: }
+
+   * The target name in this syntax is **not** a variable and **cannot** be used as one: 
+     it is simply a string literal of the target's name.  
+   * Separating the target name from the `loadTo` command makes it possible to include symbols like 
+     `-` and `.` in target names. This is not possible when the standard `loadToOrders` syntax is 
+     used because special characters are invalid in the name of a JS function.  
+   * Note that the general syntax specified above, `loadTo('Target', obj)`, changes for some 
+     ETL types. Find the accurate syntax for each ETL type in the type's specific documentation.  
+  {INFO/}
+
+The target must be:  
+
+* _RavenDB_ ETL: a _collection_ name  
+* _SQL_ ETL: a _table_ name  
+{NOTE/}
+
  Updates are implemented by executing consecutive DELETEs and INSERTs.
  When a document is modified, the delete command is sent before the new data is inserted and both are processed under the same transaction on the destination side.
  This applies to both ETL types.  

Documentation/5.1/Raven.Documentation.Pages/server/ongoing-tasks/etl/raven.markdown

@@ -37,6 +37,7 @@
 {PANEL: Transformation Script Options}
 
 * [Loading Documents](../../../server/ongoing-tasks/etl/raven#loading-documents)
+* [Alternative Syntax](../../../server/ongoing-tasks/etl/raven#alternative-syntax)
 * [Documents Identifiers](../../../server/ongoing-tasks/etl/raven#documents-identifiers)
 * [Filtering](../../../server/ongoing-tasks/etl/raven#filtering)
 * [Loading Data from Other Documents](../../../server/ongoing-tasks/etl/raven#loading-data-from-other-documents)
@@ -103,6 +104,29 @@ The following is an example of a RavenDB ETL script processing documents from th
 
 ---
 
+{NOTE: }
+### Alternative Syntax
+
+The target collection name can be passed to the `loadTo` command separately, as a string argument, 
+using this syntax: `loadTo('Target', obj)`  
+
+* **Example**:  
+  The following two calls to `loadTo` are equivalent.  
+  `loadToEmployees(this);`  
+  `loadTo('Employees', this);`  
+
+{INFO: }
+
+ * The target name `'Employees'` in this syntax is **not** a variable and **cannot** be used as one: 
+   it is simply a string literal of the target's name.  
+ * Separating the target name from the `loadTo` command makes it possible to include symbols like 
+   `-` and `.` in target names. This is not possible when the standard `loadToEmployees` syntax is 
+   used because including special characters in the name of a JS function turns it invalid.  
+{INFO/}
+{NOTE/}
+
+---
+
 ### Documents Identifiers
 
 The documents generated in the destination database are given an ID according to the collection name specified in the `loadTo` method.  

Documentation/5.2/Raven.Documentation.Pages/server/ongoing-tasks/etl/basics.markdown

@@ -99,7 +99,7 @@ In addition to the ECMAScript 5.1 API, RavenDB introduces the following function
 Specific ETL functions:  
 
 | ------ |:------:| ------ |
-| `loadTo<Target>(obj)` | function | Load an object to a specified `<Target>`.<br/>The target must be either a collection name (RavenDB ETL) or a table name (SQL ETL).<br/>**An object will be sent to the destination only if the `loadTo` method was called**.|
+| `loadTo` | function | Load an object to a specified target. <br> There are several possible flavors to the syntax of this command, <br> find the general details [below](../../../server/ongoing-tasks/etl/basics#load) and more in the documentation for each ETL type. <br> **Note:** An object will be sent to the destination **only** if the `loadTo` method was called. |
 | Attachments: |||
 | `loadAttachment(name)` | function | Load an attachment of the current document |
 | `hasAttachment(name)` | function | Check if an attachment with a given name exists for the current document |
@@ -129,6 +129,30 @@ The number of documents processed depends on the following configuration limits:
 
  Loading the results to the target destination is the last stage.
 
+{NOTE: Syntax}
+An object can generally be loaded to a specified target using one of the below templates:  
+
+* The target is specified as a part of the `loadTo` command: `loadToTarget(obj)`  
+  E.g., `loadToOrders(obj)`  
+* The target is specified as an argument of the `loadTo` command: `loadTo('Target', obj)`  
+  E.g., `loadTo('Orders', obj)`
+  {INFO: }
+
+   * The target name in this syntax is **not** a variable and **cannot** be used as one: 
+     it is simply a string literal of the target's name.  
+   * Separating the target name from the `loadTo` command makes it possible to use symbols like 
+     `-` and `.` in target names. This is not possible when the standard `loadToOrders` syntax is 
+     used because special characters are invalid in the name of a JS function.  
+   * Note that the general syntax specified above, `loadTo('Target', obj)`, changes for some 
+     ETL types. Find the accurate syntax for each ETL type in the type's specific documentation.  
+  {INFO/}
+
+The target must be:  
+
+* _RavenDB_ ETL: a _collection_ name  
+* _SQL_ ETL: a _table_ name  
+{NOTE/}
+
  Updates are implemented by executing consecutive DELETEs and INSERTs.
  When a document is modified, the delete command is sent before the new data is inserted and both are processed under the same transaction on the destination side.
  This applies to both ETL types.