Merge branch 'main' of https://github.com/GISBlox/gisblox-services-cli …

…into main

documentation/authentication/auth.md

@@ -1,48 +1,70 @@
 # Authentication 
-Login, logout, and get information about your authentication state
+Login, logout, and get information about your authentication state.
 
 Available commands:
 - [login](#gbs-login)
 - [logout](#gbs-logout)
 - [status](#gbs-status)
 
 ## gbs login
-Authenticate with a GISBlox Services host.
+Authenticate with a GISBlox Services host. 
+
+You must have a personal service key to access GISBlox Services. To generate a service key, create an account in the [GISBlox Account Center](https://account.gisblox.com/) and add a free subscription to the GISBlox Location Services. Once subscribed, click the Location Services tile and copy the service key from the information panel. [More information](http://library.gisblox.com/content/nl-nl/gb1810090).
+
 
-### Usage
 ```
 gbs login [options]
 ```
 
+### Example
+
+```
+# authenticate against gisblox.com with a service key.
+
+$ gbs login --with-token MY_SERVICE_KEY
+```
+
 ### Options
 ```
 --help                            Show help information.
 -t|--with-token <service-key>     Authenticate with a GISBlox Services service key.
 ```
 
 ## gbs logout
-Log out of a GISBlox Services host.
+Log out of a GISBlox Services host. This command removes the authentication configuration.
 
-### Usage
 ```
 gbs logout [options]
 ```
 
+### Example
+
+```
+$ gbs logout
+```
+
 ### Options
 ```
---help                            Show help information.
+--help   Show help information.
 ```
 
 ## gbs status 
 Verifies and displays information about your authentication state.
 
-### Usage
+This command will test your authentication state and reports current subscription details.
+
 ```
 gbs status [options]
 ```
 
+### Example
+
+```
+$ gbs status
+```
+
 ### Options
 ```
---help                            Show help information.
+--help   Show help information.
 ```
 

documentation/conversion/convert.md

@@ -7,14 +7,19 @@ Available commands:
 ## gbs convert
 Converts WKT geometries into GeoJson.
 
-### Usage
 ```
 gbs convert [options]
 ```
 
+### Example
+
+```
+$ gbs convert --wkt "MULTILINESTRING ((10 10, 20 20, 10 40),(40 40, 30 30, 40 20, 30 10))"
+```
+
 ### Options
+
 ```
 --help          Show help information.
 -w|--wkt <wkt>  The WKT geometry to convert.
-
 ```

documentation/projection/project.md

@@ -7,14 +7,36 @@ Available commands:
 - [to-wgs84](#gbs-project-to-wgs84)
 
 ## gbs project to-rds
-Converts WGS84 coordinates to Rijksdriehoeksstelsel (RDNew) locations. Projects a single coordinate, or batch-processes a file with coordinates.
+Converts WGS84 coordinates to Rijksdriehoeksstelsel (RDNew) locations. Projects a single coordinate, or batch-processes a file with coordinates. Supported file formats are flat files (`.txt` or `.csv`) and Excel files (version 2007 and higher).
 
-### Usage
 ```
 gbs project to-rds [options]
 ```
 
+### Examples
+
+```
+# Project a WGS84 coordinate to an RDNew location
+
+$ gbs project to-rds -c "4.15, 53.3" -s ","
+
+# Project a WGS84 coordinate in lat-lon format and include the original coordinate in the result
+
+$ gbs project to-rds -c "53.3, 4.15" -s "," -l true -is
+
+# Project coordinates in lat-lon order from a flat file to RDNew location into an output file
+# Skip the first (header) line and specify a semi-colon is used as separator
+
+$ gbs project to-rds -i "C:\input.csv" -o "C:\output.csv" -l true -h true -s ";"
+
+# Project coordinates in lat-lon order from an Excel file to RDNew location into an output file
+# Specify the input range as columns A:B and include the original coordinates in the result
+
+$ gbs project to-rds -i "C:\input.xlsx" -o "C:\output.csv" -l true -r "A:B" -is
+```
+
 ### Options
+
 ```
 --help                            Show help information.
 -c|--coordinate <coordinate>      The coordinate to project to a RDNew location (ignored when an input file is used).
@@ -25,18 +47,42 @@ gbs project to-rds [options]
 -o|--output <output file>         The output file to which to write the result.
 -h|--headers <true/false>         True to specify the input file contains headers (ignored when the input file is an Excel file).
 -l|--lat-lon-format <true/false>  True to indicate the coordinates are specified in lat-lon format, False if they are specified in lon-lat format.
-
 ```
 
 ## gbs project to-wgs84
-Converts Rijksdriehoekstelsel (RDNew) locations to WGS84 coordinates. Projects a single location, or batch-processes a file with locations.
+Converts Rijksdriehoekstelsel (RDNew) locations to WGS84 coordinates. Projects a single location, or batch-processes a file with locations. Supported file formats are flat files (`.txt` or `.csv`) and Excel files (version 2007 and higher).
 
-### Usage
 ```
 gbs project to-wgs84 [options]
 ```
 
+### Examples
+
+```
+# Project an RDNew location in X-Y format into a WGS84 coordinate
+
+$ gbs project to-wgs84 -l "102395, 579549" -s "," -x true
+
+# Project an RDNew location in X-Y format into a coordinate and include the original coordinate in the result
+# Round the coordinate to 3 decimals
+
+$ gbs project to-wgs84 -l "102395, 579549" -s "," -x true -is -d 3
+
+# Project locations in X-Y order from a flat file to WGS84 coordinates into an output file
+# Skip the first (header) line and specify a semi-colon is used as separator
+# Include the original locations in the result and round the coordinates to 2 decimals
+
+$ gbs project to-wgs84 -i "C:\input.txt" -o "C:\output.csv" -x true -h false -s ";" -is -d 2
+
+# Project locations in X-Y order from an Excel file to WGS84 coordinates into an output file
+# Specify the input range as columns A:B and include the original coordinates in the result
+# Round the coordinates to 6 decimals
+
+$ gbs project to-wgs84 -i "C:\input.xlsx" -o "C:\output.csv" -x true -d 6 -r "A:B" -is
+```
+
 ### Options
+
 ```
 --help                       Show help information.
 -l|--location <location>     The RDNew location to project to a WGS84 coordinate (ignored when an input file is used).
@@ -47,5 +93,5 @@ gbs project to-wgs84 [options]
 -r|--range <Excel range>     The Excel range that contains the coordinates to project (only if the input file is an Excel file).
 -o|--output <output file>    The output file to which to write the result.
 -h|--headers <true/false>    True to specify the input file contains headers (ignored when the input file is an Excel file).
-
+-x|--XY-format <true/false>  True to indicate the coordinates are specified in X-Y format, False if they are specified in Y-X format.
 ```