improve formatting+readability of `jpm -h` output

[uvtc]

Add definition list formatting for subcommand entries.

Stuck to regular 4-space formatting (nicely vertically aligned).

Wrapped at 80 columns.

Added some whitespace to improve readability.

[sogaiu]

@uvtc The locations of many of the leading colons looks weird to me, e.g. https://github.com/janet-lang/jpm/pull/49/commits/71eac35ee41950eac6ce35b1a2e23d55bef0c702#diff-778c43f97c9ae2b6c5f66a4dc6f05f293f7aef963eefef5a97e32df6fceac297R33

I would have expected the colon to have been on the previous line (or perhaps dispense with the colon altogether?).

Just me perhaps?

[uvtc]

I made it pretty much markdown --- in particular, the pandoc-markdown flavor, which contains a conservative, stable, thoughtful, pretty well-accepted set of markdown syntax extensions. Pandoc markdown includes syntax for definition lists (using the colon you asked about). (jgm is the author of Pandoc, and also a principal behind the commonmark spec, upon which github-flavored markdown is based.)

Aside from good readability, having the jpm -h output be markdown-formatted allows for easy conversion to html if (at some point later on) it's desired to put it up online rendered with the rest of the docs.

@bakpakin , please advise if you'd prefer to go with non-markdown manpage-style, which uses indentation only. My goal was to make it easier for humans to parse, and markdown or manpage-style both work if only reading it in the terminal.

---

More about the syntax: that location of the semicolon is the markdown syntax for definition lists that pandoc eventually settled upon (this was years ago, I think, after lots of debate and consideration (but I can't find the old issue -- may have been pre-github!)). The semicolon is placed in an analogous location as a list marker (two spaces, the marker, and then another space before the content begins).

I think it looks good, and it also works nicely when you've got multiple paragraphs in one definition, e.g.:

vanilla
  : A flavor from the
    vanilla bean.

    Also, tastes good
    with some fruits.

chocolate
  : A flavor from
    the cocoa bean

I've never seen a better, more markdown-ish syntax for definition lists.

---

Incidentally, in the long run, I think it would be useful if the Janet docstring formatter recognized definition lists with this syntax. For example, in docstrings that contain lists of terms and their descriptions, we currently have something like:

Supported options:

  * `:this` -- Lorem ipsum dolor sit amet, consectetur
    adipiscing elit, sed do eiusmod tempor incididunt
    ut labore et dolore magna aliqua.

  * `:that` -- Lorem ipsum dolor sit amet, consectetur
    adipiscing elit, sed do eiusmod tempor incididunt
    ut labore et dolore magna aliqua.

  * `:other` -- Lorem ipsum dolor sit amet, consectetur
    adipiscing elit, sed do eiusmod tempor incididunt
    ut labore et dolore magna aliqua.

  * `:else` -- Lorem ipsum dolor sit amet, consectetur
    adipiscing elit, sed do eiusmod tempor incididunt
    ut labore et dolore magna aliqua.

I think those options would be easier to pick out and skim if instead formatted with the definition list syntax:

Supported options:

`:this`
  : Lorem ipsum dolor sit amet, consectetur adipiscing
    elit, sed do eiusmod tempor incididunt ut labore et
    dolore magna aliqua.

`:that`
  : Lorem ipsum dolor sit amet, consectetur adipiscing
    elit, sed do eiusmod tempor incididunt ut labore et
    dolore magna aliqua.

`:other`
  : Lorem ipsum dolor sit amet, consectetur adipiscing
    elit, sed do eiusmod tempor incididunt ut labore et
    dolore magna aliqua.

`:else`
  : Lorem ipsum dolor sit amet, consectetur adipiscing
    elit, sed do eiusmod tempor incididunt ut labore et
    dolore magna aliqua.

[sogaiu]

@uvtc Thanks for the explanation.

I'd also like to hear bakpakin's thoughts about the proposed changes.

[bakpakin]

Yeah, Im not a fan of markdown in usage text. Normal plain text is fine, we are not generating html.