Merge branch 'soh-cah-toa/interactive'

TODO

@@ -1,4 +1,4 @@
-### Looking for something to work on?  See TASKS.
+### Looking for something to work on? See TASKS.
 ###
 ### This file is more of a "don't forget to do this" list.
 
@@ -141,7 +141,7 @@ Plumage:
     * Generate .pc files if module install type does not automatically do so
     * Hmmm, seems to be some fail here WRT standardizing lib names ...
 * Documentation
-  * Hacking docs (WIP)
+  * Add a tutorial/examples document
   * FAQ
     * Relationship between plumage and distutils/make/etc.
 * Test Suite
@@ -152,7 +152,6 @@ Plumage:
   * Improve harness output
 * Misc suggestions
   * Merge Plumage .pbc's all together into executable using pbc_merge
-  * Make Plumage itself installable
   * Avoid asking questions (after first setup?) if at all possible
   * Recommendations ("optional dependencies") should not abort top-level
     install if they fail to install
@@ -168,6 +167,26 @@ Plumage:
     * From #perl6:
       * mberends does not like adding directories to PATH
         mberends does 'sudo ln -s <parrot_install>/bin/perl6 /usr/local/bin' instead
+* Rename --ignore-fail=<stage>=0 to --no-ignore-fail=<stage> as this is a more common
+  convention and is much cleaner
+
+
+CLI:
+----
+* Support temporary and permanent modification of config file
+* Fully document usage in docs/interactive.pod
+* Set version to 1.0 after soh-cah-toa/interactive is merged into master
+  * Display Plumage version in welcome message (update example in docs/interactive.pod)
+
+
+Misc:
+-----
+* Move all perldoc to top of file so code is easier to read
+* Improve output messages so that they don't try to sound like a real person talking
+  because this is really childish.
+* Reword all comments that say Plumage is the "module ecosystem" because that's not
+  true: it's a package manager for the module ecosystem
+* Cleanup code for probe tests
 
 
 Parrot:

docs/interactive.pod

@@ -0,0 +1,149 @@
+=begin pod
+
+=head1 Using the Plumage Interactive Command-Line Interface
+
+In addition to the basic single command interface from the shell, Plumage
+also provides an interactive command-line interface (CLI). If you need to
+run several commands, you will probably feel more comfortable with the CLI
+rather than continually invoking Plumage for each command.
+
+The CLI is invoked by default when no commands have been specified.
+Additionally, you can start an interactive session by explicitly specifying the
+C<cli> command. However, this is a bit redundant so it's easier to just not
+specify a command.
+
+=head2 Recognized Commands
+
+Any command that can be used from the shell interface can be invoked from the
+CLI as well. The CLI also allows you to change the config file either just
+temporarily or permanently.
+
+=head2 Examples
+
+After you've started Plumage, you will be greeted by the welcome message.
+
+=begin code
+
+    Plumage: Package Manager for Parrot
+    Copyright (C) 2009-2011, Parrot Foundation.
+
+    Enter 'help' for help or see docs/interactive.pod for further information.
+
+    plumage>
+
+=end code
+
+As the above message suggests, if you aren't sure of something, use the C<help>
+command.
+
+=begin code
+
+    plumage> help
+    List of commands:
+
+    Query metadata and project info:
+      projects                Lists all known projects.
+      status      [<project>] Shows status of <project> (defaults to all).
+      info         <project>  Displays detailed description of <project>.
+      metadata     <project>  Displays JSON metadata for <project>.
+      show-deps    <project>  Shows dependencies for <project>.
+      project-dir  <project>  Displays top directory for <project>.
+
+    Perform actions on a project:
+      fetch        <project>  Downloads source code for <project>.
+      update       <project>  Updates source code for <project> (falls back to fetch).
+      configure    <project>  Configures source code for <project> (runs 'update' first).
+      build        <project>  Builds <project> in current directory (runs 'configure' first).
+      test         <project>  Runs test suite for <project> (runs 'build' first).
+      smoke        <project>  Sends test results to Parrot's Smolder server (runs 'build' first).
+      install      <project>  Installs <project> (runs 'test' first).
+      uninstall    <project>  Uninstalls <project> from system (not always available).
+      clean        <project>  Performs basic cleanup of source tree for <project>.
+      realclean    <project>  Removes all generated files during the build process for <project>.
+
+    Get information about Plumage:
+      version                 Displays Plumage version and copyright statement.
+      help        [<command>] Displays a help message on <command> usage (defaults to all).
+
+=end code
+
+Suppose you want to try a new programming language but aren't sure which. Let's
+see what's available.
+
+=begin code
+
+    plumage> projects
+    Known projects:
+      Close                  Systems programming language (C-like) for the Parrot VM
+      bf                     Brainfuck
+      blizkost               Embed Perl 5 in Parrot, exposed as a standard HLL
+      cardinal               Cardinal - Ruby compiler for Parrot
+      chitchat               ChitChat
+      dbm-dynpmcs            dynpmc interface to dbm-like databases.
+      decnum-dynpmcs         Set of decimal arithmetic PMCs for the Parrot VM
+      digest-dynpmcs         Set of message-digest dynpmcs for the Parrot VM.
+      ecmascript             aka JavaScript
+      forth                  Forth on Parrot
+      fun                    An even happier Joy
+      gil                    Generic Imperative Language
+      hq9plus                HQ9plus is a non turing-complete joke language
+      kakapo                 Run-time library for NQP programs on the Parrot VM
+      kea                    Factor on Parrot
+      lolcode                Lolcode
+      lua                    Lua on Parrot
+      lua-batteries          Libraries for Lua on Parrot
+
+    # Output truncated for brevity
+
+=end code
+
+As you can see, the C<projects> command lists all the projects in the
+ecosystem. Maybe you're feeling a little silly and want to write some
+LOLCODE. Let's find out a little bit more about LOLCODE.
+
+=begin code
+
+    plumage> info lolcode
+    Name        : lolcode
+    Version     : HEAD
+    Summary     : Lolcode
+    Author      : Parrot Foundation
+    URL         : 
+    License     : Artistic License 2.0
+    Description : Lolcode
+
+=end code
+
+Looks like someone was lazy and didn't fully fill out the LOLCODE metadata
+file. That's alright, it'll be a surprise!
+
+=begin code
+
+    plumage> install lolcode
+    /usr/bin/git clone git://github.com/parrot/lolcode.git /home/foo/.parrot/plumage/build/lolcode
+    Cloning into /home/foo/.parrot/plumage/build/lolcode...
+    /usr/bin/git submodule update --init
+    Successful.
+
+    Configuration not required for lolcode.
+    Successful.
+
+    # Output truncated for brevity
+
+=end code
+
+This builds, tests, and installs a particular project/module; in this case,
+C<lolcode>. It could be that you're not really in a lolcatz mood right now.
+Uninstalling a project is done with the aptly named C<uninstall> command.
+
+=begin code
+
+    plumage> uninstall lolcode
+
+    Uninstalling lolcode ...
+    /home/foo/bin/bin/parrot setup.pir uninstall
+    Successful.
+
+=end code
+
+=end pod

man/man1/plumage.1

@@ -13,78 +13,78 @@ ecosystem.
 .SH OPTIONS
 .TP
 \fB-h\fR, \fB--help\fR
-Print a helpful usage message.
+Displays a help message on command usage.
 .TP
 \fB\-c\fR, \fB\-\-config\-file\fR=\fIPATH\fR
-Read additional config file.
+Reads additional config file in \fIPATH\fR.
 .TP
 \fB-i\fR, \fB\-\-ignore\-fail\fR
-Ignore any failing build stages.
+Ignores any failed build stages.
 .TP
 \fB-i\fR, \fB\-\-ignore\-fail\fR=\fISTAGE\fR
-Ignore failures only in a particular stage. May be repeated to select more than
-one stage.
+Ignores failures only for \fISTAGE\fR (may be repeated to select more than one
+stage).
 .TP
 \fB-i\fR, \fB\-\-ignore\-fail\fR=\fISTAGE\fR=\fI0\fR
-Don't ignore failues in this stage.
+Doesn't ignore failures in \fISTAGE\fR.
 .SH COMMANDS
-.SS Query metadata/project info:
+.SS Query metadata and project info:
 .TP
 \fBprojects\fR
-List all known projects.
+Lists all known projects.
 .TP
 \fBstatus\fR [\fIPROJECT\fR]
-Show status of projects. Defaults to all.
+Shows status of \fIPROJECT\fR (defaults to all).
 .TP
 \fBinfo\fR \fIPROJECT\fR
-Print summary about a particular project.
+Displays detailed description of \fIPROJECT\fR.
 .TP
 \fBmetadata\fR \fIPROJECT\fR
-Print JSON metadata about a particular project.
+Displays JSON metadata for \fIPROJECT\fR.
 .TP
-\fBshowdeps\fR \fIPROJECT\fR
-Show dependency resolution for a project.
+\fBshow-deps\fR \fIPROJECT\fR
+Shows dependencies for \fIPROJECT\fR.
 .TP
 \fBproject-dir\fR \fIPROJECT\fR
-Print project's top directory.
+Displays top directory for \fIPROJECT\fR.
 .SS Perform actions on a project:
 .TP
 \fBfetch\fR \fIPROJECT\fR
-Download source.
+Downloads source code for \fIPROJECT\fR.
 .TP
 \fBupdate\fR \fIPROJECT\fR
-Update source. Falls back to fetch.
+Updates source code for \fIPROJECT\fR (falls back to fetch).
 .TP
 \fBconfigure\fR \fIPROJECT\fR
-Configure source. Updates first.
+Configures source code for \fIPROJECT\fR (runs 'update' first).
 .TP
 \fBbuild\fR \fIPROJECT\fR
-Build project from source. Configures first.
+Builds \fIPROJECT\fR in current directory (runs 'configure' first).
 .TP
 \fBtest\fR \fIPROJECT\fR
-Test build project. Builds first.
+Runs test suite for \fIPROJECT\fR (runs 'build' first).
 .TP
 \fBsmoke\fR \fIPROJECT\fR
-Smoke test project. Builds first.
+Sends test results to Parrot's Smolder server (runs 'build' first).
 .TP
 \fBinstall\fR \fIPROJECT\fR
-Install built files. Tests first.
+Installs \fIPROJECT\fR (runs 'test' first).
 .TP
 \fBuninstall\fR \fIPROJECT\fR
-Uninstall installed files. Not always available.
+Uninstalls \fIPROJECT\fR from system (not always available).
 .TP
 \fBclean\fR \fIPROJECT\fR
-Clean source tree.
+Performs basic cleanup of source tree for \fIPROJECT\fR.
 .TP
 \fBrealclean\fR \fIPROJECT\fR
-Clobber/realclean source tree.
+Removes all generated files during the build process for \fIPROJECT\fR.
 .SS Get info about Plumage itself:
 .TP
 \fBversion\fR
-Print program version and copyright.
+Displays Plumage version and copyright statement.
 .TP
 \fBhelp\fR [\fICOMMAND\fR]
-Print a helpful usage message.
+Displays a help message on \fICOMMAND\fR usage (defaults to all).
 .SH AUTHORS
 Written by Geoffrey Broadwell.
 .PP
@@ -103,5 +103,4 @@ For further information, please see LICENSE or visit
 .UE .
 .SH SEE ALSO
 .PP
-http://parrot.github.com/plumage
-
+http://parrot.github.com/plumage, https://github.com/parrot/plumage