fix(chore): Update help documentation (#5002)

* tweaks to help system

* update help text

* update changelog

* fix order of printing deps

* Apply suggestions from code review

Co-authored-by: Hsiao-nan Cheung <niheaven@gmail.com>

* Update scoop-help.ps1

* Update scoop.ps1

Co-authored-by: Hsiao-nan Cheung <niheaven@gmail.com>

CHANGELOG.md

@@ -2,6 +2,7 @@
 
 ### Bug Fixes
 
+- **chore:** Update help documentation ([#5002](https://github.com/ScoopInstaller/Scoop/issues/5002))
 - **shortcuts:** Fix network drive shortcut creation ([#4410](https://github.com/ScoopInstaller/Scoop/issues/4410))
 
 ### Code Refactoring

bin/scoop.ps1

@@ -47,7 +47,7 @@ switch ($subCommand) {
         }
     }
     default {
-        "scoop: '$subCommand' isn't a scoop command. See 'scoop help'."
+        warn "scoop: '$subCommand' isn't a scoop command. See 'scoop help'."
         exit 1
     }
 }

libexec/scoop-alias.ps1

@@ -52,10 +52,10 @@ function add_alias($name, $command) {
     # generate script
     $shimdir = shimdir $false
     $script =
-    @"
-# Summary: $description
-$command
-"@
+    @(
+        "# Summary: $description",
+        "$command"
+    ) -join "`r`n"
     $script | Out-UTF8File "$shimdir\$alias_file.ps1"
 
     # add alias to config

libexec/scoop-depends.ps1

@@ -1,5 +1,5 @@
 # Usage: scoop depends <app>
-# Summary: List dependencies for an app
+# Summary: List dependencies for an app, in the order they'll be installed
 
 . "$PSScriptRoot\..\lib\getopt.ps1"
 . "$PSScriptRoot\..\lib\depends.ps1" # 'Get-Dependency'
@@ -17,9 +17,12 @@ try {
     abort "ERROR: $_"
 }
 
-$deps = @(Get-Dependency $app $architecture) -ne $app
-if($deps) {
-    $deps[($deps.length - 1)..0]
+$deps = @()
+Get-Dependency $app $architecture | ForEach-Object {
+    $dep = [ordered]@{}
+    $dep.Source, $dep.Name = $_ -split '/'
+    $deps += [PSCustomObject]$dep
 }
+$deps
 
 exit 0

libexec/scoop-download.ps1

@@ -3,6 +3,10 @@
 # Help: e.g. The usual way to download an app, without installing it (uses your local 'buckets'):
 #      scoop download git
 #
+# To download a different version of the app
+# (note that this will auto-generate the manifest using current version):
+#      scoop download gh@2.7.0
+#
 # To download an app from a manifest at a URL:
 #      scoop download https://raw.githubusercontent.com/ScoopInstaller/Main/master/bucket/runat.json
 #

libexec/scoop-help.ps1

@@ -3,41 +3,42 @@
 param($cmd)
 
 function print_help($cmd) {
-    $file = Get-Content (command_path $cmd) -raw
+    $file = Get-Content (command_path $cmd) -Raw
 
     $usage = usage $file
-    $summary = summary $file
     $help = scoop_help $file
 
-    if($usage) { "$usage`n" }
-    if($help) { $help }
+    if ($usage) { "$usage`n" }
+    if ($help) { $help }
 }
 
 function print_summaries {
-    $commands = @{}
+    $commands = @()
 
     command_files | ForEach-Object {
-        $command = command_name $_
-        $summary = summary (Get-Content (command_path $command) -raw)
-        if(!($summary)) { $summary = '' }
-        $commands.add("$command ", $summary) # add padding
+        $command = [ordered]@{}
+        $command.Command = command_name $_
+        $command.Summary = summary (Get-Content (command_path $command.Command))
+        $commands += [PSCustomObject]$command
     }
 
-    $commands.getenumerator() | Sort-Object name | Format-Table -hidetablehead -autosize -wrap
+    $commands
 }
 
 $commands = commands
 
 if(!($cmd)) {
-    "Usage: scoop <command> [<args>]
+    Write-Host "Usage: scoop <command> [<args>]
 
-Some useful commands are:"
+Available commands are listed below.
+
+Type 'scoop help <command>' to get more help for a specific command."
     print_summaries
-    "Type 'scoop help <command>' to get help for a specific command."
 } elseif($commands -contains $cmd) {
     print_help $cmd
 } else {
-    "scoop help: no such command '$cmd'"; exit 1
+    warn "scoop help: no such command '$cmd'"
+    exit 1
 }
 
 exit 0

libexec/scoop-install.ps1

@@ -3,6 +3,10 @@
 # Help: e.g. The usual way to install an app (uses your local 'buckets'):
 #      scoop install git
 #
+# To install a different version of the app
+# (note that this will auto-generate the manifest using current version):
+#      scoop install gh@2.7.0
+#
 # To install an app from a manifest at a URL:
 #      scoop install https://raw.githubusercontent.com/ScoopInstaller/Main/master/bucket/runat.json
 #