Missing `name` in README example

[marcoscaceres]

Trying to run the example throws with:
NAME_MISSING: Invalid option definitions: the name property is required on each definition

[marcoscaceres]

Might be good to actually allow "header" to be a fallback for name? That way, name can be optional if header is present.

[75lb]

Everything is fine with the example code, you have something wrong locally.

[75lb]

sounds like you have command-line-usage v2 installed locally.. the docs on the README are for v3.

[marcoscaceres]

Right, let me double check!

[marcoscaceres]

(I'm actually in the process of updating the v3, which is what brought me here 😄)

[marcoscaceres]

No, definitely on the right version ("command-line-usage": "^3.0.1",)

[75lb]

you have v2 installed somewhere, else you would not be getting these errors..

[75lb]

actually, i see now.. you are running the example code with command-line-args, instead of usage.. if i replace the line at the top with this (notice it loads args), i get your errors:

const getUsage = require('command-line-args')

[marcoscaceres]

ah, d'oh

[marcoscaceres]

@75lb I'm still a bit confused tho, ideally, I would still like to use the same object for command-line-args and for command-line-usage.

[75lb]

the same object is still used.. say your option definitions are:

const optionDefinitions = [
  {
    name: 'port', alias: 'p', type: Number, defaultOption: true,
    description: 'Web server port.', group: 'server'
  }
]

that object is passed to your optionList section in the usage:

const usage = commandLineUsage([
  {
     header: 'Options',
     optionList: optionDefinitions
  }
])

[75lb]

i needed to change the usage API to be more flexible, to cater for other use cases and guys using different option parsers.. in v2, the usage template was limited, in v3 you have more control.

Also, it was necessary for me to completely de-couple args and usage.

[marcoscaceres]

yeah, I see that. It's cool. Just means a little re-adjustment.

Ok, so: "optionDefinitions" is for getUsage() and "optionsList" is for commandLineArgs().

[marcoscaceres]

Just for completeness, in case others run into this problem during migration... I ended up with:

const commandLineArgs = require("command-line-args");
const getUsage = require("command-line-usage");

// ℹ️ This is for commandLineArgs, so it can parse incoming arguments.
const optionList = [{
  alias: "h",
  defaultValue: false,
  description: "Display this usage guide.",
  name: "help",
  type: Boolean,
}, {
  alias: "s",
  defaultOption: true,
  description: "URL to ReSpec source file.",
  multiple: false,
  name: "src",
  type: String,
}];

// ℹ️ this is for getUsage(), so it can display helpful stuff. 
const usageSections = [{
  header: "respec2html",
  content: "Converts a ReSpec source file to HTML and prints to std out.",
  footer: "Project home: [underline]{https://github.com/w3c/respec}"
}, {
  header: "Options",
  optionList,
}];

let parsedArgs;
try {
  parsedArgs = commandLineArgs(optionList);
} catch (err) {
  console.error(err);
  console.log(getUsage(usageSections));
  return process.exit(2);
}
// other stuff... where it's all good :)

[marcoscaceres]

Wait... don't go all reacting all negative just yet! 😄 ... still cleaning it up!

[75lb]

the bottom half should be like this..

const usageSections = [{
  header: "respec2html",
  content: "Converts a ReSpec source file to HTML and prints to std out.",
}, {
  header: "Options",
  optionsList: optionDefinitions
}, {
  content: "Project home: [underline]{https://github.com/w3c/respec}"
}];

let parsedArgs;
try {
  parsedArgs = commandLineArgs(optionsList);
} catch (err) {
  console.error(err);
  console.log(getUsage(usageSections));
  return process.exit(2);
}

[marcoscaceres]

Ah, I was just about to ask you about "footer"!

[75lb]

if you want a content section not to be indented (as the v2 footer field was not indented), set the raw flag: https://github.com/75lb/command-line-usage#commandlineusagecontent.

maybe the v3 docs are not clear enough?

[marcoscaceres]

I just hadn't gotten to raw yet :)

This has been super helpful, @75lb! I'll give the docs another read now and see if I can help in some way.