Merge pull request #174 from marklogic/feature/command-inline-docs

Documentation fixes for "copy" command

docs/copy.md

@@ -15,7 +15,7 @@ Flux supports copying documents and their associated metadata from one database
 ## Usage
 
 Similar to the commands for [exporting documents](export/export-documents.md), the `copy` command requires that you 
-specify the documents you wish to copy, along with connection information for the MarkLogic database to wish to read
+specify the documents you wish to copy, along with connection information for the MarkLogic database you wish to read
 from.
 
 The following options control which documents are read from MarkLogic:
@@ -31,10 +31,13 @@ The following options control which documents are read from MarkLogic:
 You must specify at least one of `--string-query`, `--query`, `--collections`, or `--directory`. You may specify any
 combination of those options as well.
 
-The `copy` command then requires that you specify connection information via for the target database that the documents
-will be copied into. Each of the [connection options](common-options.md) can be used for this target database, but with
+For examples of what the `--query` option support, please see 
+[the MarkLogic search documentation](https://docs.marklogic.com/guide/rest-dev/search#id_49329).
+
+The `copy` command then requires that you specify connection information for the output database that the documents
+will be copied into. Each of the [connection options](common-options.md) can be used for this output database, but with
 `output` as a prefix so that they are distinguished from the connections used for the source database. For example, 
-`--output-connection-string` is used to specify a connection string for the target database. If you are copying the documents
+`--output-connection-string` is used to specify a connection string for the output database. If you are copying the documents
 to the same database that they were read from, you can omit output connection options.
 
 The following shows an example of copying documents from a collection to a different database in the same MarkLogic 
@@ -51,7 +54,7 @@ cluster:
 ## Controlling what metadata is read
 
 The `--categories` option controls what metadata is read from the source database. The option defaults to a value of 
-`content,metadata`, resulting in the document content and all of its metadata being read for each matching URI. 
+`content,metadata`, resulting in the document content and all metadata being read for each matching URI. 
 In addition to `content` and `metadata`, valid choices include `collections`, `permissions`, `quality`, `properties`, 
 and `metadatavalues`. Choices should be concatenated together into a comma-delimited string. For example, the 
 following will only read documents and their collections and permissions:
@@ -61,6 +64,6 @@ following will only read documents and their collections and permissions:
 ## Controlling how documents are written
 
 The `copy` command supports many of the same options as the [import commands](import/common-import-features.md) for 
-writing documents. But similar to the output connection options, each option for controlling how documents are written
+writing documents. Similar to the output connection options, each option for controlling how documents are written
 is prefixed with `output`. For example, to specify collections for the documents, `--output-collections` is used instead
 of `--collections`.

flux-cli/src/main/java/com/marklogic/flux/impl/AbstractCommand.java

@@ -20,11 +20,12 @@ public abstract class AbstractCommand<T extends Executor> implements Command, Ex
     protected static final String MARKLOGIC_CONNECTOR = "marklogic";
     protected static final Logger logger = LoggerFactory.getLogger("com.marklogic.flux");
 
-    // This is declared before CommonParams so that it appears first in the picocli usage.
-    @CommandLine.ArgGroup(exclusive = false, heading = "%nConnection Options%n")
+    // The order values of 1 and 3 allow for CopyCommand to include Output Connection Options in between them. Feel free
+    // to tweak these in the future as needed.
+    @CommandLine.ArgGroup(exclusive = false, heading = "%nConnection Options%n", order = 1)
     private ConnectionParams connectionParams = new ConnectionParams();
 
-    @CommandLine.ArgGroup(exclusive = false, heading = "%nCommon Options%n")
+    @CommandLine.ArgGroup(exclusive = false, heading = "%nCommon Options%n", order = 3)
     private CommonParams commonParams = new CommonParams();
 
     private SparkSession sparkSession;

flux-cli/src/main/java/com/marklogic/flux/impl/copy/CopyCommand.java

@@ -55,7 +55,7 @@ public static class CopyWriteDocumentsParams implements WriteDocumentsOptions<Co
 
         @CommandLine.Option(
             names = "--output-abort-on-write-failure",
-            description = "Include this option to cause the command to fail when a batch of documents cannot be written to MarkLogic."
+            description = "Causes the command to fail when a batch of documents cannot be written to MarkLogic."
         )
         private Boolean abortOnWriteFailure;
 
@@ -73,7 +73,8 @@ public static class CopyWriteDocumentsParams implements WriteDocumentsOptions<Co
 
         @CommandLine.Option(
             names = "--output-failed-documents-path",
-            description = "File path for writing an archive file containing failed documents and their metadata."
+            description = "File path for writing an archive file containing failed documents and their metadata. " +
+                "The documents in the archive file can then be retried via the 'import-archive-files' command."
         )
         private String failedDocumentsPath;
 
@@ -115,7 +116,7 @@ public static class CopyWriteDocumentsParams implements WriteDocumentsOptions<Co
 
         @CommandLine.Option(
             names = "--output-transform-params-delimiter",
-            description = "Delimiter to use instead of a comma for the '--transform-params' parameter."
+            description = "Delimiter to use instead of a comma for the '--output-transform-params' parameter."
         )
         private String transformParamsDelimiter;
 
@@ -127,8 +128,9 @@ public static class CopyWriteDocumentsParams implements WriteDocumentsOptions<Co
 
         @CommandLine.Option(
             names = "--output-uri-replace",
-            description = "Modify the URI for a document via a comma-delimited list of regular expression " +
-                "and replacement string pairs - e.g. regex,'value',regex,'value'. Each replacement string must be enclosed by single quotes."
+            description = "Comma-delimited sequence of regular expressions and replacement strings for modifying " +
+                "the URI of each document - e.g. regex,'value',regex,'value'. " +
+                "Each replacement string must be enclosed by single quotes."
         )
         private String uriReplace;
 
@@ -140,7 +142,7 @@ public static class CopyWriteDocumentsParams implements WriteDocumentsOptions<Co
 
         @CommandLine.Option(
             names = "--output-uri-template",
-            description = "String defining a template for constructing each document URI. " +
+            description = "Defines a template for constructing each document URI. " +
                 "See the Flux user guide on controlling document URIs for more information."
         )
         private String uriTemplate;
@@ -268,7 +270,7 @@ public CopyWriteDocumentsParams uriTemplate(String uriTemplate) {
     @CommandLine.Mixin
     protected final CopyWriteDocumentsParams writeParams = new CopyWriteDocumentsParams();
 
-    @CommandLine.ArgGroup(exclusive = false, heading = "\nOutput Connection Options\n")
+    @CommandLine.ArgGroup(exclusive = false, heading = "\nOutput Connection Options\n", order = 2)
     private OutputConnectionParams outputConnectionParams = new OutputConnectionParams();
 
     @Override

flux-cli/src/main/java/com/marklogic/flux/impl/copy/OutputConnectionParams.java

@@ -154,7 +154,7 @@ public ConnectionOptions certificateFile(String certificateFile) {
     @Override
     @CommandLine.Option(
         names = "--output-certificate-password",
-        description = "Password for the keystore referenced by '--certificate-file'.",
+        description = "Password for the keystore referenced by '--output-certificate-file'.",
         interactive = true,
         arity = "0..1"
     )
@@ -227,7 +227,7 @@ public ConnectionOptions keyStorePath(String keyStorePath) {
     @Override
     @CommandLine.Option(
         names = "--output-keystore-password",
-        description = "Password for the keystore identified by '--keystore-path'.",
+        description = "Password for the keystore identified by '--output-keystore-path'.",
         interactive = true,
         arity = "0..1"
     )
@@ -239,7 +239,7 @@ public ConnectionOptions keyStorePassword(String keyStorePassword) {
     @Override
     @CommandLine.Option(
         names = "--output-keystore-type",
-        description = "Type of the keystore identified by '--keystore-path'; defaults to 'JKS'."
+        description = "Type of the keystore identified by '--output-keystore-path'; defaults to 'JKS'."
     )
     public ConnectionOptions keyStoreType(String keyStoreType) {
         this.keyStoreType = keyStoreType;
@@ -249,7 +249,7 @@ public ConnectionOptions keyStoreType(String keyStoreType) {
     @Override
     @CommandLine.Option(
         names = "--output-keystore-algorithm",
-        description = "Algorithm of the keystore identified by '--keystore-path'; defaults to 'SunX509'."
+        description = "Algorithm of the keystore identified by '--output-keystore-path'; defaults to 'SunX509'."
     )
     public ConnectionOptions keyStoreAlgorithm(String keyStoreAlgorithm) {
         this.keyStoreAlgorithm = keyStoreAlgorithm;
@@ -269,7 +269,7 @@ public ConnectionOptions trustStorePath(String trustStorePath) {
     @Override
     @CommandLine.Option(
         names = "--output-truststore-password",
-        description = "Password for the truststore identified by '--truststore-path'.",
+        description = "Password for the truststore identified by '--output-truststore-path'.",
         interactive = true,
         arity = "0..1"
     )
@@ -281,7 +281,7 @@ public ConnectionOptions trustStorePassword(String trustStorePassword) {
     @Override
     @CommandLine.Option(
         names = "--output-truststore-type",
-        description = "Type of the truststore identified by '--truststore-path'; defaults to 'JKS'."
+        description = "Type of the truststore identified by '--output-truststore-path'; defaults to 'JKS'."
     )
     public ConnectionOptions trustStoreType(String trustStoreType) {
         this.trustStoreType = trustStoreType;
@@ -291,7 +291,7 @@ public ConnectionOptions trustStoreType(String trustStoreType) {
     @Override
     @CommandLine.Option(
         names = "--output-truststore-algorithm",
-        description = "Algorithm of the truststore identified by '--truststore-path'; defaults to 'SunX509'."
+        description = "Algorithm of the truststore identified by '--output-truststore-path'; defaults to 'SunX509'."
     )
     public ConnectionOptions trustStoreAlgorithm(String trustStoreAlgorithm) {
         this.trustStoreAlgorithm = trustStoreAlgorithm;

flux-cli/src/main/java/com/marklogic/flux/impl/export/ExportRdfFilesCommand.java

@@ -72,7 +72,7 @@ public static class ReadTriplesParams implements Supplier<Map<String, String>>,
         private String uris;
 
         @CommandLine.Option(names = "--string-query", description = "A query utilizing the MarkLogic search grammar; " +
-            "see https://docs.marklogic.com/guide/search-dev/string-query for more information.")
+            "see %nhttps://docs.marklogic.com/guide/search-dev/string-query for more information.")
         private String stringQuery;
 
         @CommandLine.Option(names = "--query", description = "A JSON or XML representation of a structured query, serialized CTS query, or combined query. " +

flux-cli/src/main/java/com/marklogic/flux/impl/export/ReadDocumentParams.java

@@ -24,7 +24,7 @@ public class ReadDocumentParams<T extends ReadDocumentsOptions> implements ReadD
     };
 
     @CommandLine.Option(names = "--string-query", description = "A query utilizing the MarkLogic search grammar; " +
-        "see https://docs.marklogic.com/guide/search-dev/string-query for more information.")
+        "see %nhttps://docs.marklogic.com/guide/search-dev/string-query for more information.")
     private String stringQuery;
 
     @CommandLine.Option(names = "--uris", description = "Newline-delimited sequence of document URIs to retrieve. Can be combined " +

flux-cli/src/main/java/com/marklogic/flux/impl/importdata/WriteDocumentParams.java

@@ -21,7 +21,7 @@ public class WriteDocumentParams<T extends WriteDocumentsOptions> implements Wri
 
     @CommandLine.Option(
         names = "--abort-on-write-failure",
-        description = "Include this option to cause the command to fail when a batch of documents cannot be written to MarkLogic."
+        description = "Causes the command to fail when a batch of documents cannot be written to MarkLogic."
     )
     private Boolean abortOnWriteFailure;
 

flux-cli/src/main/java/com/marklogic/flux/impl/reprocess/ReprocessCommand.java

@@ -346,7 +346,7 @@ public static class WriteParams implements Supplier<Map<String, String>>, WriteO
 
         @CommandLine.Option(
             names = "--abort-on-write-failure",
-            description = "Include this option to cause the command to fail when a batch of documents cannot be written to MarkLogic."
+            description = "Causes the command to fail when a batch of documents cannot be written to MarkLogic."
         )
         private Boolean abortOnWriteFailure;