Minor tweaks to command documentation pages

Refinements to command documentation as discovered during the generation of 0cec87a as part of #2815. Here the changes to the command documentation has been separated from the changes relating to the disabling of clang-format for CLI-relevant code.

cmd/5tt2gmwmi.cpp

@@ -36,7 +36,7 @@ void usage() {
 
   REFERENCES
   +"Smith, R. E.; Tournier, J.-D.; Calamante, F. & Connelly, A. " // Internal
-   "Anatomically-constrained tractography:"
+   "Anatomically-constrained tractography: "
    "Improved diffusion MRI streamlines tractography through effective use of anatomical information. "
    "NeuroImage, 2012, 62, 1924-1938";
 

cmd/connectome2tck.cpp

@@ -141,7 +141,7 @@ void usage() {
       + Example("Generate a single track file containing edge exemplar trajectories",
                 "connectome2tck tracks.tck assignments.txt exemplars.tck -files single -exemplars nodes.mif",
                 "This produces the track file that is required as input when attempting to display "
-                "connectome edges using the streamlines or streamtubes geometries within the meview "
+                "connectome edges using the streamlines or streamtubes geometries within the mrview "
                 "connectome tool.");
 
   ARGUMENTS

cmd/connectomestats.cpp

@@ -102,7 +102,6 @@ void usage() {
   REFERENCES +
       "* If using the NBS algorithm: \n"
       "Zalesky, A.; Fornito, A. & Bullmore, E. T. Network-based statistic: Identifying differences in brain networks. "
-      "\n"
       "NeuroImage, 2010, 53, 1197-1207"
 
       + "* If using the TFNBS algorithm: \n"
@@ -113,7 +112,7 @@ void usage() {
 
       + "* If using the -nonstationary option: \n"
         "Salimi-Khorshidi, G.; Smith, S.M. & Nichols, T.E. Adjusting the effect of nonstationarity in cluster-based "
-        "and TFCE inference. \n"
+        "and TFCE inference. "
         "Neuroimage, 2011, 54(3), 2006-19";
 }
 

cmd/dcmedit.cpp

@@ -35,21 +35,22 @@ void usage() {
    "will be truncated if it is too long to fit inside the existing tag."
 
       + "WARNING: this command will modify existing data! It is recommended to run "
-        "this command on a copy of the original data set to avoid loss of data.";
+        "this command on a copy of the original data set to avoid loss of data."
+
+      +"Command-line option -anonymise attempts to remove identifiable information "
+       "by replacing the following tags: \n"
+       "- any tag with Value Representation PN will be replaced with 'anonymous'; \n"
+       "- tag (0010,0030) PatientBirthDate will be replaced with an empty string. \n"
+       "WARNING: there is no guarantee that this command will remove all identiable information, "
+       "since such information may be contained in any number of private vendor-specific tags. "
+       "You will need to double-check the results independently if you need to ensure anonymity.";
 
   ARGUMENTS
   +Argument("file", "the DICOM file to be edited.").type_file_in();
 
   OPTIONS
   +Option("anonymise",
-          "remove any identifiable information, by replacing the following tags:\n"
-          "- any tag with Value Representation PN will be replaced with 'anonymous'\n"
-          "- tag (0010,0030) PatientBirthDate will be replaced with an empty string\n"
-          "WARNING: there is no guarantee that this command will remove all identiable "
-          "information, since such information may be contained in any number "
-          "of private vendor-specific tags. You will need to double-check the "
-          "results independently if you "
-          "need to ensure anonymity.")
+          "remove any identifiable information (see Description).")
 
       + Option("id",
                "replace all ID tags with string supplied. This consists of tags "

cmd/dwi2tensor.cpp

@@ -70,7 +70,7 @@ void usage() {
         "or parameters that correspond to non-monotonic decay of the predicted signal. "
         "By supplying the -constrain option, constrained optimization is performed instead "
         "and such physically implausible parameters can be avoided. Depending on the presence "
-        " of the -dkt option, the -constrain option will enforce the following constraints:"
+        "of the -dkt option, the -constrain option will enforce the following constraints:"
 
       + "* Non-negative apparent diffusivity (always)."
 

cmd/dwidenoise.cpp

@@ -45,8 +45,8 @@ void usage() {
         "magnitude-reconstructed MRI images. If available, including the MRI phase data can "
         "reduce such non-Gaussian biases, and the command now supports complex input data.";
 
-  AUTHOR = "Daan Christiaens ([email protected]) & "
-           "Jelle Veraart ([email protected]) & "
+  AUTHOR = "Daan Christiaens ([email protected]) and "
+           "Jelle Veraart ([email protected]) and "
            "J-Donald Tournier ([email protected])";
 
   REFERENCES

cmd/fixel2sh.cpp

@@ -33,7 +33,8 @@ using Fixel::index_type;
 
 void usage() {
 
-  AUTHOR = "Robert E. Smith ([email protected]) & David Raffelt ([email protected])";
+  AUTHOR = "Robert E. Smith ([email protected]) and "
+           "David Raffelt ([email protected])";
 
   SYNOPSIS = "Convert a fixel-based sparse-data image into an spherical harmonic image";
 

cmd/fixel2tsf.cpp

@@ -49,7 +49,7 @@ void usage() {
 
   ARGUMENTS
   +Argument("fixel_in", "the input fixel data file (within the fixel directory)").type_image_in() +
-      Argument("tracks", "the input track file ").type_tracks_in() +
+      Argument("tracks", "the input track file").type_tracks_in() +
       Argument("tsf", "the output track scalar file").type_file_out();
 
   OPTIONS

cmd/fixel2voxel.cpp

@@ -53,7 +53,8 @@ const char *operations[] = {"mean",
                             nullptr};
 
 void usage() {
-  AUTHOR = "Robert E. Smith ([email protected]) & David Raffelt ([email protected])";
+  AUTHOR = "Robert E. Smith ([email protected]) and "
+           "David Raffelt ([email protected])";
 
   SYNOPSIS = "Convert a fixel-based sparse-data image into some form of scalar image";
 

cmd/fixelconvert.cpp

@@ -57,7 +57,7 @@ void usage() {
                 "for_each *.msf : fixelconvert IN NAME_new/ -template template_fixels/",
                 "In this example, the for_each script is used to execute the fixelconvert "
                 "command once for each of a series of input files in the old fixel format, "
-                "generating a new output fixel directory for each."
+                "generating a new output fixel directory for each. "
                 "Importantly here though, the -template option is used to ensure that the "
                 "ordering of fixels within these output directories is identical, such that "
                 "fixel data files can be exchanged between them (e.g. accumulating fixel "

cmd/fixelcrop.cpp

@@ -29,7 +29,8 @@ using namespace App;
 using Fixel::index_type;
 
 void usage() {
-  AUTHOR = "David Raffelt ([email protected]) & Rami Tabarra ([email protected])";
+  AUTHOR = "David Raffelt ([email protected]) and "
+           "Rami Tabarra ([email protected])";
 
   SYNOPSIS = "Crop/remove fixels from sparse fixel image using a binary fixel mask";
 
@@ -40,7 +41,7 @@ void usage() {
 
   ARGUMENTS
   +Argument("input_fixel_directory",
-            "input fixel directory, all data files and directions "
+            "input fixel directory; all data files and directions "
             "file will be cropped and saved in the output fixel directory")
           .type_directory_in() +
       Argument("input_fixel_mask",

cmd/fixelreorient.cpp

@@ -44,9 +44,7 @@ void usage() {
   ARGUMENTS
   +Argument("fixel_in", "the input fixel directory").type_directory_in() +
       Argument("warp",
-               "a 4D deformation field used to perform reorientation. "
-               "Reorientation is performed by applying the Jacobian affine transform in each voxel in the warp, "
-               "then re-normalising the vector representing the fixel direction")
+               "a 4D deformation field used to perform reorientation.")
           .type_image_in() +
       Argument("fixel_out",
                "the output fixel directory. If the the input and output directories are the same, the existing "

cmd/fod2dec.cpp

@@ -80,13 +80,13 @@ void usage() {
                    " (*not* correcting is the theoretical equivalent of Cr,Cg,Cb = 1,1,1 and gamma = 2).")
 
       + Option("lum_coefs",
-               "The coefficients Cr,Cg,Cb to correct for luminance/perception. \nNote: this implicitly switches on "
+               "The coefficients Cr,Cg,Cb to correct for luminance/perception. Note: this implicitly switches on "
                "luminance/perception correction, using a default gamma = " +
                    str(DEFAULT_LUM_GAMMA, 2) + " unless specified otherwise.") +
       Argument("values").type_sequence_float()
 
       + Option("lum_gamma",
-               "The gamma value to correct for luminance/perception. \nNote: this implicitly switches on "
+               "The gamma value to correct for luminance/perception. Note: this implicitly switches on "
                "luminance/perception correction, using a default Cr,Cg,Cb = " +
                    str(DEFAULT_LUM_CR, 2) + "," + str(DEFAULT_LUM_CG, 2) + "," + str(DEFAULT_LUM_CB, 2) +
                    " unless specified otherwise.") +

cmd/maskfilter.cpp

@@ -49,7 +49,7 @@ const OptionGroup ConnectOption =
 
     + Option("largest", "only retain the largest connected component")
 
-    + Option("connectivity", "use 26-voxel-neighbourhood connectivity (Default: 6)")
+    + Option("connectivity", "use 26-voxel-neighbourhood connectivity (Default is 6-voxel-neighbourhood)")
 
     + Option("minsize", "impose minimum size of segmented components (Default: select all components)") +
     Argument("value").type_integer(1, 1e6);
@@ -67,7 +67,7 @@ const OptionGroup FillOption =
              "the first 3 axes are included. The axes should be provided as a comma-separated list of values.") +
     Argument("axes").type_sequence_int()
 
-    + Option("connectivity", "use 26-voxel-neighbourhood connectivity (Default: 6)");
+    + Option("connectivity", "use 26-voxel-neighbourhood connectivity (Default is 6-voxel-neighbourhood)");
 
 const OptionGroup MedianOption =
     OptionGroup("Options for median filter")
@@ -79,8 +79,10 @@ const OptionGroup MedianOption =
     Argument("voxels").type_sequence_int();
 
 void usage() {
-  AUTHOR = "Robert E. Smith ([email protected]), David Raffelt ([email protected]), Thijs "
-           "Dhollander ([email protected]) and J-Donald Tournier ([email protected])";
+  AUTHOR = "Robert E. Smith ([email protected]) and "
+           "David Raffelt ([email protected]) and "
+           "Thijs Dhollander ([email protected]) and "
+           "J-Donald Tournier ([email protected])";
 
   SYNOPSIS = "Perform filtering operations on 3D / 4D mask images";
 

cmd/meshfilter.cpp

@@ -49,10 +49,10 @@ void usage() {
   DESCRIPTION
   +"While this command has only one filter operation currently available, it "
    "nevertheless presents with a comparable interface to the MRtrix3 commands "
-   "maskfilter and mrfilter commands.";
+   "maskfilter and mrfilter.";
 
   EXAMPLES
-  +Example("Apply a mesh smoothing filter (currently the only filter available",
+  +Example("Apply a mesh smoothing filter (currently the only filter available)",
            "meshfilter input.vtk smooth output.vtk",
            "The usage of this command may cause confusion due to the generic interface "
            "despite only one filtering operation being currently available. This simple "
@@ -61,8 +61,8 @@ void usage() {
   ARGUMENTS
   +Argument("input", "the input mesh file").type_file_in() +
       Argument("filter",
-               "the filter to apply."
-               "Options are: smooth")
+               "the filter to apply; "
+               "options are: smooth")
           .type_choice(filters) +
       Argument("output", "the output mesh file").type_file_out();
 

cmd/mraverageheader.cpp

@@ -44,11 +44,13 @@ void usage() {
   +Option("padding", " boundary box padding in voxels. Default: " + str(PADDING_DEFAULT)) +
       Argument("value").type_float(0.0, std::numeric_limits<default_type>::infinity()) +
       Option("resolution",
-             " subsampling of template compared to smallest voxel size in any input image. "
-             "Valid options are 'mean': unbiased but loss of resolution for individual images possible, "
-             "and 'max': smallest voxel size of any input image defines the resolution. Default: mean") +
+             "subsampling of template compared to smallest voxel size in any input image. "
+             "Valid options are: "
+             "- 'mean': unbiased but loss of resolution for individual images possible; "
+             "- 'max': smallest voxel size of any input image defines the resolution. "
+             "Default: mean") +
       Argument("type").type_choice(resolution_choices) +
-      Option("fill", " set the intensity in the first volume of the average space to 1") + DataType::options();
+      Option("fill", "set the intensity in the first volume of the average space to 1") + DataType::options();
 }
 
 void run() {

cmd/mrcalc.cpp

@@ -361,12 +361,18 @@ void usage() {
         "single-voxel 4D image of size [ 1 1 1 N ], multiplied by a 3D image of "
         "size [ X Y Z ], which would allow the creation of a 4D image where each "
         "volume consists of the 3D image scaled by the corresponding value for "
-        "that volume in the single-voxel image.";
+        "that volume in the single-voxel image."
+
+      + "The following special keywords are permitted as operands on the stack: "
+        "'rand' (random number between 0 and 1); "
+        "'randn' (random number from unit std.dev. normal distribution); "
+        "'e' (Euler's number); "
+        "'pi' (ratio of circumference of circle to diameter)";
 
   EXAMPLES
   +Example("Double the value stored in every voxel",
            "mrcalc a.mif 2 -mult r.mif",
-           "This performs the operation: r = 2*a  for every voxel a,r in "
+           "This performs the operation:  r = 2*a  for every voxel a,r in "
            "images a.mif and r.mif respectively.")
 
       + Example("A more complex example",

cmd/mrcat.cpp

@@ -48,9 +48,9 @@ void usage() {
   +Option("axis",
           "specify axis along which concatenation should be performed. By default, "
           "the program will use the last non-singleton, non-spatial axis of any of "
-          "the input images - in other words axis 3 or whichever axis (greater than 3) "
+          "the input images; in other words, axis 3, or whichever axis (greater than 3) "
           "of the input images has size greater than one.") +
-      Argument("axis").type_integer(0)
+      Argument("index").type_integer(0)
 
       + DataType::options();
 }

cmd/mrconvert.cpp

@@ -144,7 +144,7 @@ void usage() {
                 "header that provide a linear mapping from raw intensity values stored "
                 "in the image data to some other scale. Where the raw data stored in a "
                 "particular voxel is I, the value within that voxel is interpreted as: "
-                "value = offset + (scale x I).  To adjust this scaling, the relevant "
+                "value = offset + (scale x I). To adjust this scaling, the relevant "
                 "parameters must be provided as a comma-separated 2-vector of "
                 "floating-point values, in the format \"offset,scale\" (no quotation "
                 "marks). This particular example sets the offset to zero and the scale "

cmd/mrdegibbs.cpp

@@ -26,15 +26,18 @@ using namespace App;
 const char *modes[] = {"2d", "3d", nullptr};
 
 void usage() {
-  AUTHOR = "Ben Jeurissen ([email protected]) & J-Donald Tournier ([email protected])";
+  AUTHOR = "Ben Jeurissen ([email protected]) and "
+           "J-Donald Tournier ([email protected])";
 
   SYNOPSIS = "Remove Gibbs Ringing Artifacts";
 
   DESCRIPTION
   +"This application attempts to remove Gibbs ringing artefacts from MRI images using the method "
-   "of local subvoxel-shifts proposed by Kellner et al. (see reference below for details). By default, "
-   "the original 2D slice-wise version is used. If the -mode 3d option is provided, the program will run "
-   "the 3D version as proposed by Bautista et al. (also in the reference list below)."
+   "of local subvoxel-shifts proposed by Kellner et al. (see reference below for details)."
+
+      + "By default, the original 2D slice-wise version is used. If the -mode 3d option is provided, "
+        "the program will run the 3D version as proposed by Bautista et al. "
+        "(also in the reference list below)."
 
       + "This command is designed to run on data directly after it has been reconstructed by the scanner, "
         "before any interpolation of any kind has taken place. You should not run this command after any "
@@ -53,7 +56,7 @@ void usage() {
   OPTIONS
   +Option("mode",
           "specify the mode of operation. Valid choices are: 2d, 3d (default: "
-          "2d). The 2d mode corresponds to the original slice-wise approach as "
+          "2d). The 2d mode corresponds to the original stack-of-slices approach as "
           "propoosed by Kellner et al., appropriate for images acquired using "
           "2D muli-slice approaches. The 3d mode corresponds to the 3D "
           "volume-wise extension proposed by Bautista et al., which is "
@@ -78,9 +81,9 @@ void usage() {
   REFERENCES
   +"Kellner, E; Dhital, B; Kiselev, V.G & Reisert, M. "
    "Gibbs-ringing artifact removal based on local subvoxel-shifts. "
-   "Magnetic Resonance in Medicine, 2016, 76, 1574–1581."
+   "Magnetic Resonance in Medicine, 2016, 76, 1574-1581."
 
-      + "Bautista, T; O’Muircheartaigh, J; Hajnal, JV; & Tournier, J-D. "
+      + "Bautista, T; O'Muircheartaigh, J; Hajnal, JV; & Tournier, J-D. "
         "Removal of Gibbs ringing artefacts for 3D acquisitions using subvoxel shifts. "
         "Proc. ISMRM, 2021, 29, 3535.";
 }