subcommands lack one-line description

[jonassmedegaard]

Running rdfsx --help provides a list of subcommands, but they are not self-explanatory.

Ideally, next to each subcommand would be a one-line description introducing it, and when running rdfsx SUBCOMMAND --help at least that same introduction, but preferrably an additional elaboration in few paragraphs, would be at the top of the output, before listing arguments.

I have tried, with the help of the wiki pages, to construct the one-line descriptions (which also hints at where to expand with additional paragraphs):

Description: add initial descriptive sentence for each subcommand
Author: Jonas Smedegaard <dr@jones.dk>
Forwarded: not-needed
Last-Update: 2024-07-14
---
This patch header follows DEP-3: http://dep.debian.net/deps/dep3/
--- a/rdfsx_cli/src/cli.rs
+++ b/rdfsx_cli/src/cli.rs
@@ -24,6 +24,7 @@

 #[derive(Subcommand, Debug)]
 pub enum Command {
+    /// Process a ShapeMap
     Shapemap {
         #[arg(short = 'm', long = "shapemap", value_name = "ShapeMap file name")]
         shapemap: PathBuf,
@@ -50,6 +51,7 @@
         output: Option<PathBuf>,
     },

+    /// Show info about a ShEx schema
     Schema {
         #[arg(short = 's', long = "schema", value_name = "Schema file name")]
         schema: PathBuf,
@@ -84,6 +86,7 @@
         output: Option<PathBuf>,
     },

+    /// Validate a specific node with a shape in ShEx
     Validate {
         #[arg(short = 's', long = "schema", value_name = "Schema file name")]
         schema: PathBuf,
@@ -146,6 +149,7 @@
         output: Option<PathBuf>,
     },

+    /// Process RDF data
     Data {
         #[arg(short = 'd', long = "data", value_name = "RDF data path")]
         data: PathBuf,
@@ -166,6 +170,7 @@
         output: Option<PathBuf>,
     },

+    /// Show information about a node in an RDF file or a SPARQL endpoint
     Node {
         #[arg(short = 'n', long = "node")]
         node: String,
@@ -206,6 +211,7 @@
         output: Option<PathBuf>,
     },

+    /// Show information about a SHACL shapes graph
     Shacl {
         #[arg(short = 's', long = "shapes", value_name = "Shapes file name")]
         shapes: PathBuf,
@@ -234,6 +240,7 @@
         output: Option<PathBuf>,
     },

+    /// Convert from DCTap to JSON
     #[command(name = "dctap")]
     DCTap {
         #[arg(short = 'd', long = "DCTap file", value_name = "DCTap file name")]
@@ -263,6 +270,7 @@
         output: Option<PathBuf>,
     },

+    /// Convert from DCTap or ShEx to SPARQL, ShEx, UML or HTML
     #[command(name = "convert")]
     Convert {
         #[arg(short = 'm', long = "input-mode", value_name = "Input mode")]

Please note the places saying "Processing" which is purely made up, and probably needs rewording.

[jonassmedegaard]

Also, please note that the initial line is not a full sentence, so should not contain a trailing full stop (ideally it should also not have initial letter capitalized, but apparently that's how clap styles such one-liners itself, judging from the automatic "Print this message or the help of the given subcommand(s)").

[labra]

Thank...I really appreciate those suggestions to improve usebility of the tool.

I added those description lines and published a latest version yesterday (0.1.2), could you check if they are what you expected so we could close this issue?

[jonassmedegaard]

I am glad that you took inspiration from my suggestions.

Still, instead of dropping my patch I felt the need to nudge it slightly.
What I do with those text strings is run the output of rdfsx --help through help2man" where I not only use the full output as the source for the full content of a manual page, but also reuse the initial line as the one-liner description for that same manual page (I think it is called a synopsis, but I might be wrong - at least in Perl PODs a synopsis is differently a multi-paragraph summary) which also appears when you run "apropos rdf".
When looking at other one-line descriptions, a common pattern is to me that they answer the question "what is this?", and then it feels wrong to me with the description "Information about ..." because the subcommands is not that information - instead of the tool holding information, it unpacks information from data.

Therefore, I suggest these changes to clarify that the subcommands provides rather than in itself already contains the described information (or something similar - you know best what exactly it is your tool does, of course):

Description: add initial descriptive sentence for each subcommand
Author: Jonas Smedegaard <dr@jones.dk>
Forwarded: not-needed
Last-Update: 2024-07-14
---
This patch header follows DEP-3: http://dep.debian.net/deps/dep3/
--- a/rdfsx_cli/src/cli.rs
+++ b/rdfsx_cli/src/cli.rs
@@ -24,7 +24,7 @@
 
 #[derive(Subcommand, Debug)]
 pub enum Command {
-    /// Information about ShEx shapemaps
+    /// Show information about ShEx shapemaps
     Shapemap {
         #[arg(short = 'm', long = "shapemap", value_name = "ShapeMap file name")]
         shapemap: PathBuf,
@@ -53,7 +53,7 @@
         output: Option<PathBuf>,
     },
 
-    /// Information about ShEx schemas
+    /// Show information about ShEx schemas
     ShEx {
         #[arg(short = 's', long = "schema", value_name = "Schema file name")]
         schema: PathBuf,
@@ -88,7 +88,7 @@
         output: Option<PathBuf>,
     },
 
-    /// RDF Validation using ShEx schemas
+    /// Validate RDF using ShEx schemas
     Validate {
         #[arg(short = 's', long = "schema", value_name = "Schema file name")]
         schema: PathBuf,
@@ -151,7 +151,7 @@
         output: Option<PathBuf>,
     },
 
-    /// Information about RDF data
+    /// Show information about RDF data
     Data {
         #[arg(short = 'd', long = "data", value_name = "RDF data path")]
         data: PathBuf,
@@ -172,7 +172,7 @@
         output: Option<PathBuf>,
     },
 
-    /// Information about RDF nodes which are part of RDF Graphs
+    /// Show information about RDF nodes which are part of RDF Graphs
     Node {
         #[arg(short = 'n', long = "node")]
         node: String,
@@ -213,7 +213,7 @@
         output: Option<PathBuf>,
     },
 
-    /// Information about SHACL shapes
+    /// Show information about SHACL shapes
     Shacl {
         #[arg(short = 's', long = "shapes", value_name = "Shapes file name")]
         shapes: PathBuf,
@@ -242,7 +242,7 @@
         output: Option<PathBuf>,
     },
 
-    /// Information and processing of DCTAP files
+    /// Show information about and process DCTAP files
     #[command(name = "dctap")]
     DCTap {
         #[arg(short = 'd', long = "data", value_name = "DCTap file name")]
@@ -272,7 +272,7 @@
         output: Option<PathBuf>,
     },
 
-    /// Conversion between different Data modeling technologies
+    /// Convert between different Data modeling technologies
     #[command(name = "convert")]
     Convert {
         #[arg(short = 'm', long = "input-mode", value_name = "Input mode")]

What do you think about that?

[jonassmedegaard]

The proposed changes are maintained (and just now synced with v0.1.10) as a patch here.

I do not push code to Github as a political principle, but perhaps I can persuade you to try out the decentralized git tool Radicle - it integrates seemlessly with git (at least on my Debian system) and should only involve you (or anyone permitted, after the initial push) to change your daily routine from git push to git push && git push rad, and I am then more than happy to share my change proposals there, wheren you can accept them by doing git pull rad && git push

[labra]

Tnanks a lot for the suggestion on the description of the commands, it makes a lot of sense for me. I applied your patch and already pushed it to master.

About using radicle, I was looking at it and it seems nice. I started this discussion in case more people want to express their opinion. As I understand, it would require me to run:

rad init

in the root of the project and after that, try to keep the remote rad up-to-date, right?

I think you are only suggesting to keep rad as another remote, not to replace github by rad, is that also right? At this moment, I would prefer that option, I mean, to keep github and to add support for radicle so other contributors who don't want to use github, can also contribute...

[jonassmedegaard]

Looks good to me. Thanks!