command help text formats

[jbenet]

Use the new formats from https://etherpad.mozilla.org/6aUpYEUPHK

Each command will have a HelpText object:

type HelpText struct {
  Tagline          string // used in <cmd usage>
  ShortDescription string // used in DESCRIPTION 

  // whole section overrides
  Usage           string // overrides USAGE section
  LongDescription string // overrides DESCRIPTION section
  Options         string // 
  Arguments       string // 
  Subcommands     string //
}

type Command struct {
  ...
  Help HelpText
}

NOTE: when overriding a section, user MUST still supply text for overridden parts, as they may be used elsewhere.

Examples:

  Help: HelpText{
    Tagline: "Add objects to ipfs.",
    ShortDescription: `Adds contents of <path> to ipfs. Use -r to add directories.
Note that directories are added recursively, to form the ipfs
MerkleDAG. A smarter partial add with a staging area (like git)
remains to be implemented.`,
},

...

  Help: HelpText{
    Tagline: "Add objects to ipfs.",
    Usage: "ipfs add <path>... - Add objects to ipfs."
    ShortDescription: `Adds contents of <path> to ipfs. Use -r to add directories.
Note that directories are added recursively, to form the ipfs MerkleDAG.`,
    LongDescription: `Adds contents of <path> to ipfs. Use -r to add directories.
Note that directories are added recursively, to form the ipfs MerkleDAG.

Add is the staple command of all ipfs activity. It is the first bridge
between the local filesystem and ipfs. Blah blah blahdsjf fdsaofdsafdsa 
asf dfakdas fkds lfroe-rer ew gew=g espogjrpozgjpdsog fdsgf odgfkds pa
fdasfkd safdosafk dosafdposjf pajrpoafk dsapofkeaop fkdspoakfpoffaa

A smarter partial add with a staging area (like git) remains to be implemented.`,
},

The help output will be one of two different "pages":

• ShortHelp - meant to be shown on errors, or with -h
• LongHelp - meant to be shown with --help or ipfs help <cmd>

These are rendered using the following tokens:

<cmd path>        := name of command e.g. "ipfs add", "ipfs name publish"
<cmd tagline>     := 1 line, concise description
<cmd usage>       := "<cmd path> common args - <cmd tagline>"
<cmd submcds>     := list
<cmd description> := from one sentence to one paragraph description

And the following formats.

Note:

• ? means the entire section can be omitted if empty
• @ means the section heading is silent (not shown)

LongHelp:

@USAGE

    <cmd usage>

?ARGUMENTS

    <arguments>

?OPTIONS

    <arguments>

?SUBCOMMANDS

    <cmd usage>
    <cmd usage>
    <cmd usage>
    .....

    Use `<cmd path> \<subcmd\> --help` for more information about each command.

DESCRIPTION

    <cmd longdescription>

ShortHelp:

USAGE:
    <cmd usage>

    <cmd shortdescription>

Use `<cmd path> --help` for more information about this command.

[btc]

thank you for concretizing this

[jbenet]

@mappum here's the HelpText struct. It's not going to compile if I just commit it in.

// HelpText is a set of strings used to generate command help text. The help
// text follows formats similar to man pages, but not exactly the same.
type HelpText struct {
    // required
    Tagline          string // used in <cmd usage>
    ShortDescription string // used in DESCRIPTION

    // optional - whole section overrides
    Usage           string // overrides USAGE section
    LongDescription string // overrides DESCRIPTION section
    Options         string // overrides OPTIONS section
    Arguments       string // overrides ARGUMENTS section
    Subcommands     string // overrides SUBCOMMANDS section
}

// Command is a runnable command, with input arguments and options (flags).
// It can also have Subcommands, to group units of work into sets.
type Command struct {
    Options     []Option
    Arguments   []Argument
    Run         Function
    Marshallers map[EncodingType]Marshaller
    Type        interface{}
    Subcommands map[string]*Command
    Help        HelpText
}

[whyrusleeping]

What is the format of data in Type?

[jbenet]

I think Type is the output type of the Run function. Maybe should be renamed OutputType (and it all probably needs comments)

[btc]

Described in precise terms 0915ab1

    // Type describes the type of the output of the Command's Run Function.
    // Precisely, the value of Type is an instance of the return type of the
    // Run Function.
    //
    // ie. If command Run returns &Block{}, then Command.Type == &Block{}

[whyrusleeping]

maybe it should be a reflect.Type then?

[jbenet]

@whyrusleeping i think it's not a basic type, I think it can be more complicated? see core/commands2/add.go

[mappum]

As of e501180, most of this is done. Remaining work is moving the different text fields into the HelpText struct (for each command, so this requires a lot of manual labor).

[mappum]

Finished as of 163a8a3

[btc]

thanks!

[jbenet]

👏