feat: introduce HELP command

Add support for a "HELP" verb in the HackMyResume CLI, allowing separate help
pages for each HackMyResume command per #205. The following command invocations
are recognized.

    hackmyresume help
    hackmyresume help build
    hackmyresume help new
    hackmyresume help convert
    hackmyresume help analyze
    hackmyresume help validate
    hackmyresume help peek
    hackmyresume help help

dist/cli/help/analyze.txt

@@ -0,0 +1,23 @@
+**analyze** | Analyze a FRESH resume document for statistics
+
+Usage:
+
+   hackmyresume ANALYZE <resume> [<options>]
+   hackmyresume ANALYZE <resumes...> [<options>]
+
+Parameters:
+
+   **<resume/resumes>**
+
+      Absolute or relative path(s) to one or more FRESH or
+      JSON Resume documents to be analyzed. Multiple resumes
+      can be specified, separated by spaces:
+
+         hackmyresume ANALYZE r1.json r2.json r3.json
+
+Options:
+
+   **None.**
+
+The ANALYZE command performs simple analysis on a FRESH or
+JSON Resume document.

dist/cli/help/build.txt

@@ -0,0 +1,69 @@
+**build** | Generate resumes in supported output formats
+
+Usage:
+
+   hackmyresume BUILD <sources...> TO <targets...> [<options>]
+
+Parameters:
+
+   **<sources...>**
+
+      Absolute or relative path(s) to one or more resumes in
+      FRESH or JSON format, separated by spaces. If multiple
+      resumes are specified, they will be merged into a
+      single resume prior to transformation.
+
+         hackmyresume BUILD resume.json output.all
+         hackmyresume BUILD base.json developer.json gamedev.json TO out/resume.all
+
+   **<targets...>**
+
+      Absolute or relative path(s) to one or more outbound
+      resume(s), separated by spaces. If multiple output
+      resumes are specified, all of them will be generated.
+      The desired format of each resume will be determined
+      from the file extension:
+
+         .all        Generate all supported formats
+         .html       HTML 5
+         .doc        MS Word
+         .pdf        Adobe Acrobat PDF
+         .txt        plain text
+         .md         Markdown
+         .png        PNG Image
+         .latex      LaTeX
+
+       Note: not all formats are supported by all themes.
+       Check the theme's documentation for details.
+
+Options:
+
+   **--theme -t <theme-name-or-path>**
+
+      Relative or absolute path to a FRESH or JSON Resume
+      theme, or the name of a built-in theme.
+
+      As of 1.9.0, the following built-in themes are
+      provided: basis, modern, positive, compact, awesome.
+
+   **--pdf -p <engine>**
+
+      Specify the PDF engine to use. Legal values are:
+
+         - none: Don't generate a PDF.
+         - wkhtmltopdf: Use the wkhtmltopdf PDF engine.
+         - phantom: use the PhantomJS PDF engine.
+         - weazyprint: use the WeazyPrint PDF engine.
+
+   **--no-escape**
+
+      Disable escaping / encoding of resume data during
+      resume generation. Handlebars themes only.
+
+   **--private**
+
+      Include resume fields marked as private.
+
+The BUILD command generates themed resumes and CVs in
+multiple formats from a single source of truth in the form
+of a FRESH or JSON Resume document.

dist/cli/help/convert.txt

@@ -0,0 +1,34 @@
+**convert** | Convert resumes between FRESH and JRS formats
+
+Usage:
+
+   hackmyresume CONVERT <sources...> TO <targets...> [<options>]
+
+Parameters:
+
+   **<sources...>**
+
+      Absolute or relative path(s) to one or more FRESH or
+      JSON Resume documents (*.json), separated by spaces.
+
+   **<targets...>**
+
+      The desired absolute or relative path(s) of the newly
+      converted resume(s). HackMyResume will create the
+      converted resume(s) here.
+
+Options:
+
+   **--format -f <fmt>**
+
+      The desired format for the new resume(s). Valid values
+      are 'FRESH', 'JRS', or, to target the latest edge
+      version of the JSON Resume Schema, 'JRS@1'.
+
+      If this parameter is omitted, the destination format
+      will be inferred from the source resume's format. If
+      the source format is FRESH, the destination format
+      will be JSON Resume, and vice-versa.
+
+The CONVERT command converts one or more resume documents
+between FRESH and JSON Resume formats.

dist/cli/help/help.txt

@@ -0,0 +1,23 @@
+**help** | View help on a specific HackMyResume command
+
+Usage:
+
+   hackmyresume HELP <command>
+
+Parameters:
+
+   **<command>**
+
+      The HackMyResume command to view help information for.
+      Must be BUILD, NEW, CONVERT, ANALYZE, VALIDATE, PEEK,
+      or HELP.
+
+         hackmyresume help convert
+         hackmyresume help help
+
+Options:
+
+   **None.**
+
+The HELP command displays help information for a specific
+HackMyResume command, including the HELP command itself.

dist/cli/help/new.txt

@@ -0,0 +1,27 @@
+**new** | Create a new FRESH or JRS resume document
+
+Usage:
+
+   hackmyresume NEW <resumes...> [<options>]
+
+Parameters:
+
+   **<resumes...>**
+
+      Absolute or relative path(s) to one or more FRESH or
+      JSON Resume documents (*.json), separated by spaces:
+
+         hackmyresume NEW r1.json r2.json r3.json
+
+Options:
+
+   **--format -f <fmt>**
+
+      The desired format for the new resume(s). Valid values
+      are 'FRESH', 'JRS', or, to target the latest edge
+      version of the JSON Resume Schema, 'JRS@1'.
+
+The NEW command generates one or more new resumes in FRESH
+or JSON Resume format. This document can serve as a source
+of truth for resume and career data and an input to tools
+like HackMyResume or resume-cli.

dist/cli/help/peek.txt

@@ -0,0 +1,30 @@
+**peek** | View portions of a resume from the command line
+
+Usage:
+
+   hackmyresume PEEK <resumes> <path> [<options>]
+
+Parameters:
+
+   **<resumes>**
+
+      Absolute or relative path(s) to one or more FRESH or
+      JSON Resume documents to be validated. Multiple resumes
+      can be specified, separated by spaces:
+
+         hackmyresume PEEK r1.json r2.json r3.json
+
+   **<path>**
+
+      The part of the resume to peek at.
+
+Options:
+
+   **--assert -a**
+
+      Tell HackMyResume to return a non-zero process exit
+      code if a resume fails to validate.
+
+The PEEK command displays a specific piece or part of the
+resume without requiring the resume to be opened in an
+editor.

dist/cli/help/validate.txt

@@ -0,0 +1,27 @@
+**validate** - Validate a resume for correctness
+
+Usage:
+
+   hackmyresume VALIDATE <resume> [<options>]
+   hackmyresume VALIDATE <resumes...> [<options>]
+
+Parameters:
+
+   **<resume(s)>**
+
+      Absolute or relative path(s) to one or more FRESH or
+      JSON Resume documents to be validated. Multiple resumes
+      can be specified, separated by spaces:
+
+         hackmyresume ANALYZE r1.json r2.json r3.json
+
+Options:
+
+   **--assert -a**
+
+      Tell HackMyResume to return a non-zero process exit
+      code if a resume fails to validate.
+
+The VALIDATE command validates a FRESH or JSON Resume
+document against its governing schema, verifying that the
+resume is correctly structured.

dist/cli/main.js

@@ -92,6 +92,16 @@ Definition of the `main` function.
       x = splitSrcDest.call(this);
       execute.call(this, x.src, x.dst, this.opts(), logMsg);
     });
+    program.command('help')["arguments"]('[command]').description('Get help on a HackMyResume command').action(function(command) {
+      var cmd, manPage;
+      cmd = command && command.trim();
+      if (cmd) {
+        manPage = FS.readFileSync(PATH.join(__dirname, 'help/' + cmd + '.txt'), 'utf8');
+      } else {
+        manPage = FS.readFileSync(PATH.join(__dirname, 'use.txt'), 'utf8');
+      }
+      console.log(M2C(manPage, 'white', 'yellow.bold'));
+    });
     program.parse(args);
     if (!program.args.length) {
       throw {
@@ -135,7 +145,7 @@ Definition of the `main` function.
       _out.log('');
     }
     _err.init(o.debug, o.assert, o.silent);
-    if (o.verb && !HMR.verbs[o.verb] && !HMR.alias[o.verb]) {
+    if (o.verb && !HMR.verbs[o.verb] && !HMR.alias[o.verb] && o.verb !== 'help') {
       _err.err({
         fluenterror: HMSTATUS.invalidCommand,
         quit: true,
@@ -143,14 +153,16 @@ Definition of the `main` function.
       }, true);
     }
     Command.prototype.missingArgument = function(name) {
+      if (this.name() !== 'help') {
         _err.err({
           fluenterror: this.name() !== 'new' ? HMSTATUS.resumeNotFound : HMSTATUS.createNameMissing
         }, true);
+      }
     };
     Command.prototype.helpInformation = function() {
       var manPage;
       manPage = FS.readFileSync(PATH.join(__dirname, 'use.txt'), 'utf8');
-      return chalk.green.bold(manPage);
+      return M2C(manPage, 'white', 'yellow');
     };
     return {
       args: o.args,

dist/cli/use.txt

@@ -1,32 +1,28 @@
+**HackMyResume** | A Swiss Army knife for resumes and CVs.
+
 Usage:
 
-  hackmyresume <command> <sources> [TO <targets>] [<options>]
+  hackmyresume <command> <params> [<options>]
 
-Available commands:
+Available commands (type "hackmyresume help COMMAND" for details):
 
-  BUILD         Build your resume to the destination format(s).
+  **BUILD**         Build your resume to the destination format(s).
-  ANALYZE       Analyze your resume for keywords, gaps, and metrics.
+  **ANALYZE**       Analyze your resume for keywords, gaps, and metrics.
-  VALIDATE      Validate your resume for errors and typos.
+  **VALIDATE**      Validate your resume for errors and typos.
-  CONVERT       Convert your resume between FRESH and JSON Resume.
+  **NEW**           Create a new resume in FRESH or JSON Resume format.
-  NEW           Create a new resume in FRESH or JSON Resume format.
+  **CONVERT**       Convert your resume between FRESH and JSON Resume.
-  PEEK          View a specific field or element on your resume.
+  **PEEK**          View a specific field or element on your resume.
+  **HELP**          View help on a specific HackMyResume command.
 
 Available options:
 
-  --theme -t    Path to a FRESH or JSON Resume theme.
+  **--options -o**  Load options from an external JSON file.
-  --pdf -p      Specify the PDF engine to use (wkhtmltopdf or phantom).
+  **--debug -d**    Emit extended debugging info.
-  --options -o  Load options from an external JSON file.
+  **--assert -a**   Treat resume validation warnings as errors.
-  --format -f   The format (FRESH or JSON Resume) to use.
+  **--no-colors**   Disable terminal colors.
-  --debug -d    Emit extended debugging info.
+  **--tips**        Display theme messages and tips.
-  --assert -a   Treat resume validation warnings as errors.
+  **--help -h**     Display help documentation.
-  --private     Include resume fields marked as private
+  **--version -v**  Display the current version.
-  --no-colors   Disable terminal colors.
-  --tips        Display theme messages and tips.
-  --help -h     Display help documentation.
-  --version -v  Display the current version.
-
-Not all options are supported for all commands. For example, the
---theme option is only supported for the BUILD command.
 
 Examples:
 
@@ -47,6 +43,6 @@ Tips:
     theme, or the path to a local FRESH or JSON Resume theme.
   - Visit https://www.npmjs.com/search?q=jsonresume-theme for a full
     listing of all available JSON Resume themes.
-  - Visit https://github.com/fluentdesk/fresh-themes for a complete
+  - Visit https://github.com/fresh-standard/fresh-themes for a complete
     listing of all available FRESH themes.
   - Report bugs to https://githut.com/hacksalot/HackMyResume/issues.

src/cli/help/analyze.txt

@@ -0,0 +1,23 @@
+**analyze** | Analyze a FRESH resume document for statistics
+
+Usage:
+
+   hackmyresume ANALYZE <resume> [<options>]
+   hackmyresume ANALYZE <resumes...> [<options>]
+
+Parameters:
+
+   **<resume/resumes>**
+
+      Absolute or relative path(s) to one or more FRESH or
+      JSON Resume documents to be analyzed. Multiple resumes
+      can be specified, separated by spaces:
+
+         hackmyresume ANALYZE r1.json r2.json r3.json
+
+Options:
+
+   **None.**
+
+The ANALYZE command performs simple analysis on a FRESH or
+JSON Resume document.

src/cli/help/build.txt

@@ -0,0 +1,69 @@
+**build** | Generate resumes in supported output formats
+
+Usage:
+
+   hackmyresume BUILD <sources...> TO <targets...> [<options>]
+
+Parameters:
+
+   **<sources...>**
+
+      Absolute or relative path(s) to one or more resumes in
+      FRESH or JSON format, separated by spaces. If multiple
+      resumes are specified, they will be merged into a
+      single resume prior to transformation.
+
+         hackmyresume BUILD resume.json output.all
+         hackmyresume BUILD base.json developer.json gamedev.json TO out/resume.all
+
+   **<targets...>**
+
+      Absolute or relative path(s) to one or more outbound
+      resume(s), separated by spaces. If multiple output
+      resumes are specified, all of them will be generated.
+      The desired format of each resume will be determined
+      from the file extension:
+
+         .all        Generate all supported formats
+         .html       HTML 5
+         .doc        MS Word
+         .pdf        Adobe Acrobat PDF
+         .txt        plain text
+         .md         Markdown
+         .png        PNG Image
+         .latex      LaTeX
+
+       Note: not all formats are supported by all themes.
+       Check the theme's documentation for details.
+
+Options:
+
+   **--theme -t <theme-name-or-path>**
+
+      Relative or absolute path to a FRESH or JSON Resume
+      theme, or the name of a built-in theme.
+
+      As of 1.9.0, the following built-in themes are
+      provided: basis, modern, positive, compact, awesome.
+
+   **--pdf -p <engine>**
+
+      Specify the PDF engine to use. Legal values are:
+
+         - none: Don't generate a PDF.
+         - wkhtmltopdf: Use the wkhtmltopdf PDF engine.
+         - phantom: use the PhantomJS PDF engine.
+         - weazyprint: use the WeazyPrint PDF engine.
+
+   **--no-escape**
+
+      Disable escaping / encoding of resume data during
+      resume generation. Handlebars themes only.
+
+   **--private**
+
+      Include resume fields marked as private.
+
+The BUILD command generates themed resumes and CVs in
+multiple formats from a single source of truth in the form
+of a FRESH or JSON Resume document.

src/cli/help/convert.txt

@@ -0,0 +1,34 @@
+**convert** | Convert resumes between FRESH and JRS formats
+
+Usage:
+
+   hackmyresume CONVERT <sources...> TO <targets...> [<options>]
+
+Parameters:
+
+   **<sources...>**
+
+      Absolute or relative path(s) to one or more FRESH or
+      JSON Resume documents (*.json), separated by spaces.
+
+   **<targets...>**
+
+      The desired absolute or relative path(s) of the newly
+      converted resume(s). HackMyResume will create the
+      converted resume(s) here.
+
+Options:
+
+   **--format -f <fmt>**
+
+      The desired format for the new resume(s). Valid values
+      are 'FRESH', 'JRS', or, to target the latest edge
+      version of the JSON Resume Schema, 'JRS@1'.
+
+      If this parameter is omitted, the destination format
+      will be inferred from the source resume's format. If
+      the source format is FRESH, the destination format
+      will be JSON Resume, and vice-versa.
+
+The CONVERT command converts one or more resume documents
+between FRESH and JSON Resume formats.

src/cli/help/help.txt

@@ -0,0 +1,23 @@
+**help** | View help on a specific HackMyResume command
+
+Usage:
+
+   hackmyresume HELP <command>
+
+Parameters:
+
+   **<command>**
+
+      The HackMyResume command to view help information for.
+      Must be BUILD, NEW, CONVERT, ANALYZE, VALIDATE, PEEK,
+      or HELP.
+
+         hackmyresume help convert
+         hackmyresume help help
+
+Options:
+
+   **None.**
+
+The HELP command displays help information for a specific
+HackMyResume command, including the HELP command itself.

src/cli/help/new.txt

@@ -0,0 +1,27 @@
+**new** | Create a new FRESH or JRS resume document
+
+Usage:
+
+   hackmyresume NEW <resumes...> [<options>]
+
+Parameters:
+
+   **<resumes...>**
+
+      Absolute or relative path(s) to one or more FRESH or
+      JSON Resume documents (*.json), separated by spaces:
+
+         hackmyresume NEW r1.json r2.json r3.json
+
+Options:
+
+   **--format -f <fmt>**
+
+      The desired format for the new resume(s). Valid values
+      are 'FRESH', 'JRS', or, to target the latest edge
+      version of the JSON Resume Schema, 'JRS@1'.
+
+The NEW command generates one or more new resumes in FRESH
+or JSON Resume format. This document can serve as a source
+of truth for resume and career data and an input to tools
+like HackMyResume or resume-cli.

src/cli/help/peek.txt

@@ -0,0 +1,30 @@
+**peek** | View portions of a resume from the command line
+
+Usage:
+
+   hackmyresume PEEK <resumes> <path> [<options>]
+
+Parameters:
+
+   **<resumes>**
+
+      Absolute or relative path(s) to one or more FRESH or
+      JSON Resume documents to be validated. Multiple resumes
+      can be specified, separated by spaces:
+
+         hackmyresume PEEK r1.json r2.json r3.json
+
+   **<path>**
+
+      The part of the resume to peek at.
+
+Options:
+
+   **--assert -a**
+
+      Tell HackMyResume to return a non-zero process exit
+      code if a resume fails to validate.
+
+The PEEK command displays a specific piece or part of the
+resume without requiring the resume to be opened in an
+editor.

src/cli/help/validate.txt

@@ -0,0 +1,27 @@
+**validate** - Validate a resume for correctness
+
+Usage:
+
+   hackmyresume VALIDATE <resume> [<options>]
+   hackmyresume VALIDATE <resumes...> [<options>]
+
+Parameters:
+
+   **<resume(s)>**
+
+      Absolute or relative path(s) to one or more FRESH or
+      JSON Resume documents to be validated. Multiple resumes
+      can be specified, separated by spaces:
+
+         hackmyresume ANALYZE r1.json r2.json r3.json
+
+Options:
+
+   **--assert -a**
+
+      Tell HackMyResume to return a non-zero process exit
+      code if a resume fails to validate.
+
+The VALIDATE command validates a FRESH or JSON Resume
+document against its governing schema, verifying that the
+resume is correctly structured.

src/cli/main.coffee

@@ -132,6 +132,22 @@ main = module.exports = ( rawArgs, exitCallback ) ->
       return
     )
 
+  # Create the HELP command
+  program
+    .command('help')
+    .arguments('[command]')
+    .description('Get help on a HackMyResume command')
+    .action ( command ) ->
+      cmd = command && command.trim()
+      if cmd
+        manPage = FS.readFileSync(
+          PATH.join(__dirname, 'help/' + cmd + '.txt'), 'utf8' )
+      else
+        manPage = FS.readFileSync(
+          PATH.join(__dirname, 'use.txt'), 'utf8' )
+      console.log M2C(manPage, 'white', 'yellow.bold')
+      return
+
   program.parse( args )
 
   if !program.args.length
@@ -171,11 +187,12 @@ initialize = ( ar, exitCallback ) ->
   _err.init o.debug, o.assert, o.silent
 
   # Handle invalid verbs here (a bit easier here than in commander.js)...
-  if o.verb && !HMR.verbs[ o.verb ] && !HMR.alias[ o.verb ]
+  if o.verb && !HMR.verbs[ o.verb ] && !HMR.alias[ o.verb ] && o.verb != 'help'
     _err.err fluenterror: HMSTATUS.invalidCommand, quit: true, attempted: o.orgVerb, true
 
   # Override the .missingArgument behavior
   Command.prototype.missingArgument = (name) ->
+    if this.name() != 'help'
       _err.err
         fluenterror:
           if this.name() != 'new'
@@ -188,7 +205,7 @@ initialize = ( ar, exitCallback ) ->
   Command.prototype.helpInformation = ->
     manPage = FS.readFileSync(
       PATH.join(__dirname, 'use.txt'), 'utf8' )
-    return chalk.green.bold(manPage)
+    return M2C(manPage, 'white', 'yellow')
 
   return {
     args: o.args,

src/cli/use.txt

@@ -1,32 +1,28 @@
+**HackMyResume** | A Swiss Army knife for resumes and CVs.
+
 Usage:
 
-  hackmyresume <command> <sources> [TO <targets>] [<options>]
+  hackmyresume <command> <params> [<options>]
 
-Available commands:
+Available commands (type "hackmyresume help COMMAND" for details):
 
-  BUILD         Build your resume to the destination format(s).
+  **BUILD**         Build your resume to the destination format(s).
-  ANALYZE       Analyze your resume for keywords, gaps, and metrics.
+  **ANALYZE**       Analyze your resume for keywords, gaps, and metrics.
-  VALIDATE      Validate your resume for errors and typos.
+  **VALIDATE**      Validate your resume for errors and typos.
-  CONVERT       Convert your resume between FRESH and JSON Resume.
+  **NEW**           Create a new resume in FRESH or JSON Resume format.
-  NEW           Create a new resume in FRESH or JSON Resume format.
+  **CONVERT**       Convert your resume between FRESH and JSON Resume.
-  PEEK          View a specific field or element on your resume.
+  **PEEK**          View a specific field or element on your resume.
+  **HELP**          View help on a specific HackMyResume command.
 
 Available options:
 
-  --theme -t    Path to a FRESH or JSON Resume theme.
+  **--options -o**  Load options from an external JSON file.
-  --pdf -p      Specify the PDF engine to use (wkhtmltopdf or phantom).
+  **--debug -d**    Emit extended debugging info.
-  --options -o  Load options from an external JSON file.
+  **--assert -a**   Treat resume validation warnings as errors.
-  --format -f   The format (FRESH or JSON Resume) to use.
+  **--no-colors**   Disable terminal colors.
-  --debug -d    Emit extended debugging info.
+  **--tips**        Display theme messages and tips.
-  --assert -a   Treat resume validation warnings as errors.
+  **--help -h**     Display help documentation.
-  --private     Include resume fields marked as private
+  **--version -v**  Display the current version.
-  --no-colors   Disable terminal colors.
-  --tips        Display theme messages and tips.
-  --help -h     Display help documentation.
-  --version -v  Display the current version.
-
-Not all options are supported for all commands. For example, the
---theme option is only supported for the BUILD command.
 
 Examples:
 
@@ -47,6 +43,6 @@ Tips:
     theme, or the path to a local FRESH or JSON Resume theme.
   - Visit https://www.npmjs.com/search?q=jsonresume-theme for a full
     listing of all available JSON Resume themes.
-  - Visit https://github.com/fluentdesk/fresh-themes for a complete
+  - Visit https://github.com/fresh-standard/fresh-themes for a complete
     listing of all available FRESH themes.
   - Report bugs to https://githut.com/hacksalot/HackMyResume/issues.