From 395bb61cf3b54c396c25a6cd100ef25428e9ad85 Mon Sep 17 00:00:00 2001 From: Alexey Date: Sat, 14 Mar 2020 16:20:44 +0300 Subject: [PATCH] help: keep consistent style of help messages Use imperative mood everywhere. End sentences with dots. Capitalize sentences. --- cmd/v/internal/help/build-c.txt | 24 ++++++++++---------- cmd/v/internal/help/build.txt | 24 ++++++++++---------- cmd/v/internal/help/default.txt | 40 ++++++++++++++++----------------- cmd/v/internal/help/fmt.txt | 10 ++++----- cmd/v/internal/help/install.txt | 4 ++-- cmd/v/internal/help/other.txt | 20 ++++++++--------- cmd/v/internal/help/remove.txt | 6 ++--- cmd/v/internal/help/run.txt | 2 +- cmd/v/internal/help/search.txt | 4 ++-- cmd/v/internal/help/update.txt | 10 ++++----- 10 files changed, 72 insertions(+), 72 deletions(-) diff --git a/cmd/v/internal/help/build-c.txt b/cmd/v/internal/help/build-c.txt index 5b61ef3059..ea7ea71559 100644 --- a/cmd/v/internal/help/build-c.txt +++ b/cmd/v/internal/help/build-c.txt @@ -8,54 +8,54 @@ For help regarding building an executable, see `v help build`. These build flags are enabled on `build` and `run` as long as the backend is set to `c`: -arch - Changes the architecture that V will tell the C compiler to build. + Change the architecture that V will tell the C compiler to build. List of supported architectures: `x86` and `x64` (default). -cc , -compiler - Changes the C compiler V invokes to the specified compiler. + Change the C compiler V invokes to the specified compiler. The C compiler is required to support C99. Officially supported/tested C compilers include: `clang`, `gcc`, `tcc`, `mingw-w64` and `msvc`. -cf , -cflags - Passes the provided flag as is to the C compiler. + Pass the provided flag as is to the C compiler. Can be specified multiple times to provide multiple flags. Use quotes to wrap the flag argument if it contains spaces. -cg, -cdebug - Enables debug mode while preserving C line numbers in the compiled executable. + Enable debug mode while preserving C line numbers in the compiled executable. This allows issues regarding C compilation to be located more easily. -compress - Strips the compiled executable to compress it. + Strip the compiled executable to compress it. -csource - Specifies how V deals with the intermediate C source code. + Specify how V deals with the intermediate C source code. * `prettify` - The C source code will be kept. `clang-format` is used to prettify the C source code before compiling it. * `keep` - The C source code will be kept as generated by V. * `drop` (default) - The C source code will be deleted after compiling the executable. -freestanding - Builds the executable without dependency on libc. + Build the executable without dependency on libc. Supported only on `linux` targets currently. -live - Builds the executable with live capabilities (`[live]`). + Build the executable with live capabilities (`[live]`). -manual-free - Enables manually freeing on all V code. This will cause memory leaks in vlib. + Enable manually freeing on all V code. This will cause memory leaks in vlib. Currently enabled until a stable auto-free system is in place. -os , -target-os - Changes the target OS that V tries to compile for. + Change the target OS that V tries to compile for. By default, the target OS is the host system. When OS is `cross`, V will attempt to output cross-platform C code. List of OS supported by V: `linux`, `windows`, `mac`, `freebsd`, `openbsd`, `netbsd`, `dragonfly`, `solaris`, `android` and `haiku`. -sanitize - Passes flags related to sanitization to the C compiler. + Pass flags related to sanitization to the C compiler. -shared - Tells V to compile a shared object instead of an executable. + Tell V to compile a shared object instead of an executable. The resulting file extension will be `.dll` on Windows and `.so` on Unix systems diff --git a/cmd/v/internal/help/build.txt b/cmd/v/internal/help/build.txt index c836659a12..541519d479 100644 --- a/cmd/v/internal/help/build.txt +++ b/cmd/v/internal/help/build.txt @@ -33,7 +33,7 @@ The build flags are shared by the build and run commands: current backends when finished -d [=], -define [=] - Defines the provided flag. + Define the provided flag. If value is not provided, it is assumed to be set to `true`. `value` should be `1` or `0` to indicate `true` and `false` respectively otherwise. @@ -42,24 +42,24 @@ The build flags are shared by the build and run commands: Currently, the only experiment available is: `prealloc` -full-rebuild - Forces a full rebuild of all dependencies. + Force a full rebuild of all dependencies. Enabled by default currently until caching works reliably. -g - Compiles the executable in debug mode, allowing code to be debugged more easily. + Compile the executable in debug mode, allowing code to be debugged more easily. -o , -output - Forces V to output the executable in a specific location. - (relative to the current working directory if not absolute) + Force V to output the executable in a specific location + (relative to the current working directory if not absolute). -obf, -obfuscate - Turns on obfuscation for the code being built. Currently only renames symbols. + Turn on obfuscation for the code being built. Currently only renames symbols. -path - Specifies the order of path V looks up in while searching for imported dependencies, + Specify the order of path V looks up in while searching for imported dependencies, separated by pipes (`|`). In addition to absolute paths, you can also use these special strings too: - @vmodules - replaced with the location of the global ~/.vmodules/ folder + @vmodules - replaced with the location of the global ~/.vmodules/ folder (modules installed with `v install` are there). @vlib - replaced with the location of the v's vlib folder. Using these, you can arrange for very flexible search orders for you project, for example: @@ -67,21 +67,21 @@ The build flags are shared by the build and run commands: By default, -path is just "@vlib|@vmodules" . -prod - Compiles the executable in production mode where most optimizations are enabled. + Compile the executable in production mode where most optimizations are enabled. -prof, -profile - Compiles the executable with all functions profiled. + Compile the executable with all functions profiled. -stats Enable more detailed statistics reporting, while compiling test files. You can use that with `v test` too, for example: v -stats test vlib/ ... will run test_ functions inside all _test.v files inside vlib/ , - and will report detailed statistics about how much time each test_ function took, how many + and will report detailed statistics about how much time each test_ function took, how many assertions were made, how many tests passed/failed and so on. -translated - Enables features that are discouraged in regular V code but required for translated V code. + Enable features that are discouraged in regular V code but required for translated V code. -v, -vv, -vvv Enable varying verbosity in the V compiler while compiling diff --git a/cmd/v/internal/help/default.txt b/cmd/v/internal/help/default.txt index 04ead5323c..465447d767 100644 --- a/cmd/v/internal/help/default.txt +++ b/cmd/v/internal/help/default.txt @@ -4,31 +4,31 @@ Usage: v [options] [command] [arguments] Examples: - v hello.v compile the file `hello.v` and output it as `hello` or `hello.exe` - v run hello.v same as above but also run the produced executable immediately after compilation - v -o h.c hello.v translate `hello.v` to `h.c` . Do not compile further. + v hello.v Compile the file `hello.v` and output it as `hello` or `hello.exe`. + v run hello.v Same as above but also run the produced executable immediately after compilation. + v -o h.c hello.v Translate `hello.v` to `h.c` . Do not compile further. The commands are: - build build V code in the provided path (default) - create setup the file structure for a V project - doc generates the documentation for a V module (coming soon in 0.3) - fmt format the V code provided - repl run the REPL - run compile and run a V program - symlink create a symbolic link for V - test run all test files in the provided directory - translate translate C code to V (coming soon in 0.3) - up run the V self-updater - self run the V self-compiler - version prints the version text and exits + build Build V code in the provided path (default). + create Setup the file structure for a V project. + doc Generates the documentation for a V module (coming soon in 0.3). + fmt Format the V code provided. + repl Run the REPL. + run Compile and run a V program. + symlink Create a symbolic link for V. + test Run all test files in the provided directory. + translate Translate C code to V (coming soon in 0.3). + up Run the V self-updater. + self Run the V self-compiler. + version Print the version text and exits. - install installs a module from VPM - remove removes a module that was installed from VPM - search searches for a module from VPM - update updates an installed module from VPM + install Install a module from VPM. + remove Remove a module that was installed from VPM. + search Search for a module from VPM. + update Update an installed module from VPM. Use "v help " for more information about a command, example: `v help build` Use "v help other" to see less frequently used commands. -Note: Help is required to write more help topics. +Note: Help is required to write more help topics. Only build, fmt, run, test, search, install, remove, update, bin2v are properly documented currently. diff --git a/cmd/v/internal/help/fmt.txt b/cmd/v/internal/help/fmt.txt index 46d73e3b88..6a0b72b02d 100644 --- a/cmd/v/internal/help/fmt.txt +++ b/cmd/v/internal/help/fmt.txt @@ -1,14 +1,14 @@ -Usage: +Usage: v [flags] fmt path_to_source.v [path_to_other_source.v] Formats the given V source files, then prints their formatted source to stdout. Options: - -c check if file is already formatted. + -c Check if file is already formatted. If it is not, print filepath, and exit with code 2. - -diff display only diffs between the formatted source and the original source. - -l list files whose formatting differs from vfmt. - -w write result to (source) file(s) instead of to stdout. + -diff Display only diffs between the formatted source and the original source. + -l List files whose formatting differs from vfmt. + -w Write result to (source) file(s) instead of to stdout. -2 Use the new V parser/vfmt. NB: this is EXPERIMENTAL for now. The new vfmt is much faster and more forgiving. It also may EAT some of your code for now. diff --git a/cmd/v/internal/help/install.txt b/cmd/v/internal/help/install.txt index 229f70fbf7..be6e4a9a1a 100644 --- a/cmd/v/internal/help/install.txt +++ b/cmd/v/internal/help/install.txt @@ -2,6 +2,6 @@ Usage: v install module [module] [module] [...] ^^^^^^^^^^^^^ will install the modules you specified Options: - -help - Show usage info - -verbose - Print more details about the performed operation + -help - Show usage info. + -verbose - Print more details about the performed operation. -server-url - When doing network operations, use this vpm server. Can be given multiple times. diff --git a/cmd/v/internal/help/other.txt b/cmd/v/internal/help/other.txt index bcfa13930f..9d5703a36f 100644 --- a/cmd/v/internal/help/other.txt +++ b/cmd/v/internal/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, - 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 - test-fmt test if all files in the current directory is formatted properly - test-compiler test if V is working properly by running all tests, including the compiler ones + + bin2v Convert a binary file to a v source file, + 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. + test-fmt Test if all files in the current directory is formatted properly. + test-compiler Test if V is working properly by running all tests, including the compiler ones. NB: this can take a minute or two to run - setup-freetype setup thirdparty freetype on Windows + setup-freetype Setup thirdparty freetype on Windows. diff --git a/cmd/v/internal/help/remove.txt b/cmd/v/internal/help/remove.txt index 17527258a3..bfddbe88a9 100644 --- a/cmd/v/internal/help/remove.txt +++ b/cmd/v/internal/help/remove.txt @@ -1,9 +1,9 @@ -Usage: +Usage: a) v remove module [module] [module] [...] ^^^^^^^^^^^^ will remove the listed modules b) v remove ^^^^^^^^^^^^ will remove ALL installed modules Options: - -help - Show usage info - -verbose - Print more details about the performed operation + -help - Show usage info. + -verbose - Print more details about the performed operation. -server-url - When doing network operations, use this vpm server. Can be given multiple times. diff --git a/cmd/v/internal/help/run.txt b/cmd/v/internal/help/run.txt index cfd672d20e..53a147c06f 100644 --- a/cmd/v/internal/help/run.txt +++ b/cmd/v/internal/help/run.txt @@ -3,7 +3,7 @@ Usage: v [build flags] run [arguments...] This command is equivalent to running `v build` and running the compiled executable. The executable is passed the arguments as provided in [arguments...]. -The exit status of Run will be: +The exit status of run will be: * `1` if the compilation failed. * The exit code of the compiled executable otherwise. diff --git a/cmd/v/internal/help/search.txt b/cmd/v/internal/help/search.txt index 0b9a9aa86c..9a84850ca5 100644 --- a/cmd/v/internal/help/search.txt +++ b/cmd/v/internal/help/search.txt @@ -3,6 +3,6 @@ Usage: ^^^^^^^^^^^^^^^^^ will search https://vpm.vlang.io/ for matching modules, and will show details about them Options: - -help - Show usage info - -verbose - Print more details about the performed operation + -help - Show usage info. + -verbose - Print more details about the performed operation. -server-url - When doing network operations, use this vpm server. Can be given multiple times. diff --git a/cmd/v/internal/help/update.txt b/cmd/v/internal/help/update.txt index 4600f43d92..6bc37bc417 100644 --- a/cmd/v/internal/help/update.txt +++ b/cmd/v/internal/help/update.txt @@ -1,9 +1,9 @@ -Usage: +Usage: a) v update module [module] [module] [...] - ^^^^^^^^^^^^ will update the listed modules to their latest versions + ^^^^^^^^^^^^ will update the listed modules to their latest versions. b) v update - ^^^^^^^^^^^^ will update ALL installed modules to their latest versions + ^^^^^^^^^^^^ will update ALL installed modules to their latest versions. Options: - -help - Show usage info - -verbose - Print more details about the performed operation + -help - Show usage info. + -verbose - Print more details about the performed operation. -server-url - When doing network operations, use this vpm server. Can be given multiple times.