remove whitespace

packages/lobster-tool-codebeamer/README.md

@@ -15,46 +15,95 @@ requirements management tool
 
 ## Configuration
 This tool works with an optional config file.
-*   You can declare the  codebeamer fields which shall be used as 'refs' reference in the output file.
-
-    For the `refs` reference in config file you can write:
-
-    ```json
-    {
-      "refs" : "cb-fieldname"
-    }
-    ```
-    or
-    ```json
-    {
-      "refs" : ["cb-fieldname"]
-    }
-    ```
-    or
-    ```json
-    {
-      "refs" : ["cb-fieldname1", "cb-fieldname2"]
-    }
-    ```
-
-* Schema
-
-  You can also specify the type of schema for the resulting output file. The supported values for the schema field are:
-  1. Activity: Sets the schema to lobster-act-trace.
-  2. Implementation: Sets the schema to lobster-imp-trace.
-  3. Requirement: Sets the schema to lobster-req-trace.
-
-  If the schema is not specified, the tool will default to Requirement, and the schema lobster-req-trace will be used.
-
-  Here’s an example configuration:
-  ```json
-  {
-    "schema": "Activity",  // Specifies schema
-    "refs": ["cb-fieldname1", "cb-fieldname2"]  // Specifies references
-  }
-  ```
-
-  If an invalid schema is provided, the tool will raise an exception. Supported schema values are Activity, Implementation, and Requirement.
+It allows to configure the following features:
+
+### References
+Codebeamer items can reference other items through
+[Reference Fields](https://support.ptc.com/help/codebeamer/r2.1/en/index.html#page/codebeamer/user_guide/ug_reference_fields.html).
+This piece of information can be extracted by the tool, and serialized into the
+LOBSTER output file.
+It only needs to know which fields to take into account.
+Following the LOBSTER JSON schema, the item references will be added to the
+`refs` property of the LOBSTER item.
+Accordingly, the configuration parameter to specify the codebeamer field names
+is called `refs`, too. 
+It can contain a single field name, or a list of field names.
+Field IDs cannot be used, only the field names.
+
+Examples:
+```json
+{
+  "refs" : "cb-fieldname"
+}
+```
+or
+```json
+{
+  "refs" : ["cb-fieldname"]
+}
+```
+or
+```json
+{
+  "refs" : ["cb-fieldname1", "cb-fieldname2"]
+}
+```
+
+### Bearer Authentication Token
+It is also possible to define the Bearer authentication token in the
+configuration file:
+```json
+{
+  "token" : "your-codebeamer-Bearer-token"
+}
+```
+Note:
+- The Bearer authentication token can also be provided as a command line
+  argument (use `--cb-token=your-codebeamer-Bearer-token`).
+- If the token is provided in the configuration file and as command line
+  argument, then the configuration file takes precedence.
+- If `--cb-user` or `--cb-pass` is given together with a Bearer token (either
+  as a command line argument or through the configuration file), then the
+  Bearer authentication method is used, and the username and/or password are
+  ignored.
+- If neither a token nor a username or password are given, then the tool tries
+  to read the username and password from the `.netrc` file in the user's home
+  directory.
+
+### Example Configuration
+Here is an example configuration file:
+```json
+{
+  "refs" : ["derived from", "satisfied by"],
+  "token" : "SomeTokenStringABC123"
+}
+```
+
+Is it also possible to define the codebeamer token in this file:
+```
+{
+"refs" : "cb-fieldname",
+"token" : "your cb-token"
+}
+```
+
+### Schema
+You can also specify the type of schema for the resulting output file. The supported values for the schema field are:
+- Activity: Sets the schema to lobster-act-trace.
+- Implementation: Sets the schema to lobster-imp-trace.
+- Requirement: Sets the schema to lobster-req-trace.
+
+If the schema is not specified, the tool will default to Requirement, and the schema lobster-req-trace will be used.
+
+Here is an example configuration file:
+```json
+{
+  "schema": "Activity",  // Specifies schema
+  "refs": ["cb-fieldname1", "cb-fieldname2"]  // Specifies references
+}
+```
+
+If an invalid schema is provided, the tool will raise an exception. Supported schema values are Activity, Implementation, and Requirement.
 
 ## Command-Line Arguments and Configuration