Bug 12409

Created attachment 4203 [details]
Unformatted wic help text

This is what the wic help looks like right now.  It needs reformatted.

I don't know where the paste went of the suggested formatting.... Here it is..

---------------

The Wic help returned to the user is unreadable.  Formatting is non-existent and the amount of information is unnecessary.  

Here are the commands that return help:

  $ wic help
  $ wic --help
  $ wic -h

Wic has 6 commands and 3 topics on which it can return help using the following form:

  $ wic help [COMMAND or TOPIC]

The only command you cannot get help on is the help command.  Thus, the following command returns an error:

  $ wic help help

All other help returned for any COMMAND or TOPIC is formatted very well, is readable, and is informative.  So commands like the following are all good:

  $ wic help create
  $ wic help ls
  $ wic help list

When a user enters general help (wic help), they get a huge listing of unformatted help that spans every facet of the wic command.  All the user really needs is help and usage on the wic command itself.  It is redundant to provide help on individual COMMANDs or TOPICs.  

I propose the following help output for general help:

$ wic help

wic version 0.2.0
       Creates a customized OpenEmbedded image.

       Usage: wic [--version]
              wic help [COMMAND or TOPIC]
              wic COMMAND [ARGS]

          usage 1: Returns the current version of Wic
          usage 2: Returns detailed help for a COMMAND or TOPIC
          usage 3: Executes COMMAND


       COMMAND:

          list   -   List available canned images and source plugins
          ls     -   List contents of partitioned image or partition
          rm     -   Remove files or directories from the vfat or ext*
                     partitions
          help   -   Show help for a wic COMMAND or TOPIC
          write  -   Write an image to a device
          cp     -   Copy files and directories to the vfat or ext*
                     partitions
          create -   Create a new OpenEmbedded image


        TOPIC:

          overview  - Presents an overall overview of Wic
          plugins   - Presents an overview and API for Wic plugins
          kickstart - Presents a Wic kicstart file reference


        Examples:

          $ wic --version

            Returns the current version of Wic


          $ wic help cp

            Returns the SYNOPSIS and DESCRIPTION for the Wic "cp" command.


          $ wic list images

            Returns the list of canned images (i.e. *.wks files located in
            the /scripts/lib/wic/canned-wks directory.


          $ wic create mkefidisk -e core-image-minimal

            Creates an EFI disk image from artifacts used in a previous
            core-image-minimal build in standard BitBake locations
            (e.g. Cooked Mode).

I will contact Scott to clear up documentation needs here.

We can make sure that Wic is documented properly in the YP manual set after the Wic help output is properly formatted as suggested below.  

Scott

Created attachment 4672 [details]
Screenshot of Wic --help from master branch of OpenEmbedded

Marking as resolved since the Wic documentation is much more comprehensive and the "wic --help" command is properly formatted (see https://bugzilla.yoctoproject.org/attachment.cgi?id=4672)