Nicer looking help, inspired by man pages.

2 files changed, 47 insertions, 32 deletions

diff --git a/src/luarocks/download.lua b/src/luarocks/download.lua
index 6ae5f7af..268dc113 100644
--- a/src/luarocks/download.lua
+++ b/src/luarocks/download.lua
@@ -9,11 +9,12 @@ local fetch = require("luarocks.fetch")
 local search = require("luarocks.search")
 
 help_summary = "Download a specific rock file from a rocks server."
-help_arguments = "[--all] [--source] [--arch=<arch>] [<name> [<version>]]"
+help_arguments = "[--all] [--arch=<arch> | --source | --rockspec] [<name> [<version>]]"
 
 help = [[
---all          Download multiple rock files if there is more than one match.
+--all          Download all files if there are multiple matches.
 --source       Download .src.rock if available.
+--rockspec     Download .rockspec if available.
 --arch=<arch>  Download rock for a specific architecture.
 ]]
 
diff --git a/src/luarocks/help.lua b/src/luarocks/help.lua
index 6272d213..3a366f44 100644
--- a/src/luarocks/help.lua
+++ b/src/luarocks/help.lua
@@ -9,13 +9,21 @@ module("luarocks.help", package.seeall)
 local util = require("luarocks.util")
 local cfg = require("luarocks.cfg")
 
-help_summary = "Help on commands."
+help_summary = "Help on commands. Type '"..program_name.." help <command>' for more."
 
 help_arguments = "[<command>]"
 help = [[
 <command> is the command to show help for.
 ]]
 
+local function print_banner()
+   util.printout("\nLuaRocks "..cfg.program_version..", a module deployment system for Lua")
+end
+
+local function print_section(section)
+   util.printout("\n"..section)
+end
+
 --- Driver function for the "help" command.
 -- @param command string or nil: command to show help for; if not
 -- given, help summaries for all commands are shown.
@@ -26,30 +34,28 @@ function run(...)
 
    if not command then
       local sys_file, sys_ok, home_file, home_ok = cfg.which_config()
+      print_banner()
+      print_section("NAME")
+      util.printout("\t"..program_name..[[ - ]]..program_description)
+      print_section("SYNOPSIS")
+      util.printout("\t"..program_name..[[ [--from=<server> | --only-from=<server>] [--to=<tree>] [VAR=VALUE]... <command> [<argument>] ]])
+      print_section("GENERAL OPTIONS")
       util.printout([[
-LuaRocks ]]..cfg.program_version..[[, a module deployment system for Lua
-
-Using system configuration file: ]]..sys_file .. " (" .. (sys_ok and "ok" or "failed") ..[[)
-and user configuration file: ]]..home_file .. " (" .. (home_ok and "ok" or "failed") ..[[)
-
-]]..program_name..[[ - ]]..program_description..[[
+        These apply to all commands, as appropriate:
 
-usage: ]]..program_name..[[ [--from=<server> | --only-from=<server>] [--to=<tree>] [VAR=VALUE]... <command> [<argument>]
-
-Variables from the "variables" table of the configuration file
-can be overriden with VAR=VALUE assignments.
-
---server=<server>      Fetch rocks/rockspecs from this server
-                       (takes priority over config file)
---only-server=<server> Fetch rocks/rockspecs from this server only
-                       (overrides any entries in the config file)
---only-sources=<url>   Restrict downloads to paths matching the
-                       given URL.
---tree=<tree>          Which tree to operate on.
---local                Use the tree in the user's home directory.
-
-Supported commands:
-]])
+        --server=<server>      Fetch rocks/rockspecs from this server
+                               (takes priority over config file)
+        --only-server=<server> Fetch rocks/rockspecs from this server only
+                               (overrides any entries in the config file)
+        --only-sources=<url>   Restrict downloads to paths matching the
+                               given URL.
+        --tree=<tree>          Which tree to operate on.
+        --local                Use the tree in the user's home directory.]])
+      print_section("VARIABLES")
+      util.printout([[
+        Variables from the "variables" table of the configuration file
+        can be overriden with VAR=VALUE assignments.]])
+      print_section("COMMANDS")
       local names = {}
       for name, command in pairs(commands) do
          table.insert(names, name)
@@ -57,18 +63,26 @@ Supported commands:
       table.sort(names)
       for _, name in ipairs(names) do
          local command = commands[name]
-         util.printout(name, command.help_summary)
+         util.printout("", name)
+         util.printout("\t", command.help_summary)
       end
+      print_section("CONFIGURATION")
+      util.printout([[
+        Using system configuration file: ]]..sys_file .. " (" .. (sys_ok and "ok" or "failed") ..[[)
+        and user configuration file: ]]..home_file .. " (" .. (home_ok and "ok" or "failed") ..")\n")
    else
       command = command:gsub("-", "_")
       if commands[command] then
          local arguments = commands[command].help_arguments or "<argument>"
-         util.printout()
-         util.printout(program_name.." "..command.." "..arguments)
-         util.printout()
-         util.printout(command.." - "..commands[command].help_summary)
-         util.printout()
-         util.printout(commands[command].help)
+         print_banner()
+         print_section("NAME")
+         util.printout("\t"..program_name.." "..command.." - "..commands[command].help_summary)
+         print_section("SYNOPSIS")
+         util.printout("\t"..program_name.." "..command.." "..arguments)
+         print_section("DESCRIPTION")
+         util.printout("",(commands[command].help:gsub("\n","\n\t"):gsub("\n\t$","")))
+         print_section("SEE ALSO")
+         util.printout("","'luarocks help' for general options and configuration.\n")
       else
          return nil, "Unknown command '"..command.."'"
       end