v help: unify and clarify some 'help' documents (#9276)

cmd/v/help/bin2v.txt

@@ -1,11 +1,11 @@
 Usage:
-v bin2v [options] FILE [FILE]...
+  v bin2v [options] FILE[...]
 
-Converts a list of arbitrary files into a single v module file.
+  Converts a list of arbitrary files into a single v module file.
 
-You can use this tool to embed binary files, like pictures or fonts inside
+  You can use this tool to embed binary files, like pictures or fonts inside
-the executable of a v program, such that it would not need access to external
+  the executable of a v program, such that it would not need access to external
-resources during runtime, and it would be as self-contained as possible.
+  resources during runtime, and it would be as self-contained as possible.
 
 Options:
   -h, --help                Show this help screen.

cmd/v/help/default.txt

@@ -13,6 +13,7 @@ V supports the following commands:
 * New project scaffolding:
    new               Setup the file structure for a V project (in a sub folder).
    init              Setup the file structure for an already existing V project.
+
 * Ordinary development:
    run               Compile and run a V program.
    test              Run all test files in the provided directory.
@@ -21,11 +22,13 @@ V supports the following commands:
    doc               Generate the documentation for a V module.
    vlib-docs         Generate and open the documentation of all the vlib modules.
    repl              Run the REPL.
+
 * Installation/self updating:
    symlink           Create a symbolic link for V.
    up                Run the V self-updater.
    self [-prod]      Run the V self-compiler, use -prod to optimize compilation.
    version           Print the version text and exits.
+
 * Module/package management:
    install           Install a module from VPM.
    remove            Remove a module that was installed from VPM.
@@ -34,8 +37,9 @@ V supports the following commands:
    upgrade           Upgrade all the outdated modules.
    list              List all installed modules.
    outdated          Show installed modules that need updates.
+
 * Others:
-   doctor            Display some usefull info about your system to help reporting bugs.
+   doctor            Display some useful info about your system to help reporting bugs.
    translate         Translate C code to V (coming soon in 0.3).
    tracev            Produce a tracing version of the v compiler.
                      Use `tracev yourfile.v` when the compiler panics.

cmd/v/help/doc.txt

@@ -1,5 +1,5 @@
 Usage:
-  v doc [flags] [module_name / folder / V file] [symbol name]
+  v doc [options] [MODULE / DIRECTORY / FILE] [symbol name]
 
 Examples:
   v doc os
@@ -7,9 +7,9 @@ Examples:
   v doc -o math.html math
   v doc -m -f html vlib/
 
-Generates the documentation of a given directory, module, or V source file
+  Generates the documentation of a given MODULE, DIRECTORY, or FILE
-and prints or saves them to its desired format. It can generate HTML, JSON,
+  and prints or saves them to its desired format. It can generate HTML, JSON,
-or Markdown format.
+  or Markdown format.
 
 Options:
   -all            Includes private and public functions/methods/structs/consts/enums.

cmd/v/help/help.v

@@ -18,7 +18,9 @@ pub fn print_and_exit(topic string) {
 		eprintln(help.unknown_topic)
 		exit(1)
 	}
-	target_topic := os.join_path(vroot, 'cmd', 'v', 'help', '${topic}.txt')
+	// `init` has the same help topic as `new`
+	name := if topic == "init" { "new" } else { topic }
+	target_topic := os.join_path(vroot, 'cmd', 'v', 'help', '${name}.txt')
 	content := os.read_file(target_topic) or {
 		eprintln(help.unknown_topic)
 		exit(1)

cmd/v/help/install.txt

@@ -1,10 +1,8 @@
 Usage:
-  v install module [module] [module] [...]
+  v install [MODULE...]
-  ^^^^^^^^^^^^^ will install the modules you specified
+    Installs each MODULE.
 
-You can also do `v install` directly if you have dependencies stored
+    If no MODULEs, the modules listed in the `v.mod` file are installed instead.
-inside the `v.mod` file. This will automatically installs the modules
-specified inside of it.
 
 Options:
   -help         - Show usage info.

cmd/v/help/new.txt

@@ -1,5 +1,18 @@
 Usage:
-  v new [name] [description]
+  v new [NAME] [DESCRIPTION]
-  v init
+	Sets up a new V project with a 'v.mod' file, and a 'main.v' "Hello World"
+	file, and performs 'git init' (if git is installed on the system).
 
-Setup file structure for a V project.
+	If NAME is given, the project will be setup in a new directory with that
+	name, and that name will be added to the 'v.mod' file. If no name is given,
+	the user will be prompted for a name.
+
+	If DESCRIPTION is given, the 'v.mod' file is updated with said description.
+
+  v init
+	Sets up a V project within the current directory.
+
+	If no '.v' file exists, then will create a 'main.v' file.
+	If no 'v.mod' file exists, one will be created.
+	If the current directory is not already controlled with 'git', will perform
+	'git init' (if git is installed on the system).

cmd/v/help/other.txt

@@ -1,14 +1,14 @@
 These are utility commands that you can also launch through v,
 but which are used less frequently by users:
 
-   bin2v             Convert a binary file to a v source file,
+   bin2v              Convert a binary file to a v source file,
-                     that can be later embedded in a module or program.
+                      that can be later embedded in a module or program.
 
    build-examples     Test if all examples can be built.
    build-tools        Test if all tools can be built.
    build-vbinaries    Test if V can be built with different configuration.
 
-   check-md          Check that V examples in markdown files are formatted and can compile.
+   check-md           Check that V examples in markdown files are formatted and can compile.
 
    test-all           Run most checks, that the CI does locally.
                       It may take over 2 minutes, and it needs internet connectivity too,
@@ -16,7 +16,7 @@ but which are used less frequently by users:
 
    test-fmt           Test if all files in the current directory are formatted properly.
 
-   test-self Test if V is working properly by running all tests, including the compiler ones.
+   test-self          Test if V is working properly by running all tests, including the compiler ones.
                       NB: this can 1-2 minutes to run.
 
    test-parser        Test that the V parser works with the given files, as if

cmd/v/help/remove.txt

@@ -1,8 +1,8 @@
 Usage:
- a) v remove module [module] [module] [...]
+  v remove [MODULE...]
-    ^^^^^^^^^^^^ will remove the listed modules
+    Removes all listed MODULEs.
- b) v remove
+	If no MODULE is provided, removes ALL installed modules.
-    ^^^^^^^^^^^^ will remove ALL installed modules
+
 Options:
   -help        - Show usage info.
   -v           - Print more details about the performed operation.

cmd/v/help/search.txt

@@ -1,8 +1,10 @@
 Usage:
-  v search keyword1 [keyword2] [...]
+  v search KEYWORD[...]
-  ^^^^^^^^^^^^^^^^^ will search https://vpm.vlang.io/ for matching modules,
+    Searches https://vpm.vlang.io/ for matching KEYWORDs and displays the
-                    and will show details about them
+    details
+
 Options:
   -help         - Show usage info.
   -v            - Print more details about the performed operation.
-  -server-url   - When doing network operations, use this vpm server. Can be given multiple times.
+  -server-url   - When doing network operations, use this vpm server. Can be
+                  given multiple times.

cmd/v/help/test.txt

@@ -1,26 +1,18 @@
 Usage:
+  v [-stats] test FILE|DIRECTORY[...]
+    Runs test functions in the given FILEs and DIRECTORYs
 
-   A)
+    If '-stats' is given, more statistics about the tests are printed along
-      v test folder/ : run all v tests in the given folder.
+    with a report of passes/failures
-      v -stats test folder/ : the same, but print more stats.
-   B)
-      v test file_test.v : run test functions in a given test file.
-      v -stats test file_test.v : as above, but with more stats.
 
-NB: you can also give many and mixed folder/ file_test.v arguments after test.
+NB 1: very frequently, when you work on a module you can cd into its folder,
+and then you can perform:
+	  v test .
+... to run all the module's '_test.v' files.
 
-NB 2: very frequently, when you work on a module, you can cd into its folder,
+NB 2: V builtin testing requires you to name your files with a _test.v
-and then you can just run:
+suffix, and to name your test functions with test_ prefix. Each 'test_'
-      v test .
+function in a '_test.v' file will be called automatically by the test
-... which will run all the module _test.v files.
+framework. You can use `assert condition` inside each 'test_' function.
-
-
-NB 3: V builtin testing requires you to name your files with a _test.v
-suffix, and to name your test functions with test_ prefix. Each test_
-function in a _test.v file will be called automatically by the test
-framework. You can use `assert condition` inside each test_ function.
 If the asserted condition fails, then v will record that and produce a
 more detailed error message about where the failure was.
-
-After all test_ functions are called, if you passed -stats, v will
-produce a report about how many tests passed, and how many failed.

cmd/v/help/update.txt

@@ -1,8 +1,9 @@
 Usage:
- a) v update module [module] [module] [...]
+  v update [MODULE]...
-    ^^^^^^^^^^^^ will update the listed modules to their latest versions.
+	Updates each MODULE.
- b) v update
+
-    ^^^^^^^^^^^^ will update ALL installed modules to their latest versions.
+	With no MODULE, ALL installed modules are updated to their latest versions.
+
 Options:
   -help        - Show usage info.
   -v           - Print more details about the performed operation.

cmd/v/help/vpm.txt

@@ -1,7 +1,7 @@
 Usage:
-  a) v install module [module] [module] [...]
+  a) v install [MODULE...]
-  b) v update [module] [...]
+  b) v update [MODULE...]
-  c) v remove [module] [...]
+  c) v remove [MODULE...]
-  d) v search keyword1 [keyword2] [...]
+  d) v search KEYWORD[...]
 
   You can also pass -h or --help after each vpm command from the above, to see more details about it.