Standardize help text #710
Conversation
|
Hi, thanks for the PR. While we generally are not against the use of AI generated code, please review your code changes before submitting your PR. If you are not sure at the time of creation create a draft. In your case specifically the PR makes the output look more consistent in some places, but makes it worse in others. Please fix this. Also, I am not particularly a fan of describing examples like this: instead of the previous The |
|
@ipatix : Hi! Thank you for your comment!
Not sure if above pertains to this particular PR or is a general comment. Disclaimer: No GenAI tool was used for the preparation/creation of this PR.
Could you please highlight the points that need changes?
Sure, I get your point and it's totally fine. # Description
$ command
output line # 1
output line # 2
...This format is particularly useful for automated tools that generate documentation. `gh repo clone --help`gh repo clone --help
Clone a GitHub repository locally. Pass additional `git clone` flags by listing
them after `--`.
If the `OWNER/` portion of the `OWNER/REPO` repository argument is omitted, it
defaults to the name of the authenticating user.
When a protocol scheme is not provided in the repository argument, the `git_protocol` will be
chosen from your configuration, which can be checked via `gh config get git_protocol`. If the protocol
scheme is provided, the repository will be cloned using the specified protocol.
If the repository is a fork, its parent repository will be added as an additional
git remote called `upstream`. The remote name can be configured using `--upstream-remote-name`.
The `--upstream-remote-name` option supports an `@owner` value which will name
the remote after the owner of the parent repository.
If the repository is a fork, its parent repository will be set as the default remote repository.
USAGE
gh repo clone <repository> [<directory>] [-- <gitflags>...]
FLAGS
-u, --upstream-remote-name string Upstream remote name when cloning a fork (default "upstream")
INHERITED FLAGS
--help Show help for command
EXAMPLES
# Clone a repository from a specific org
$ gh repo clone cli/cli
# Clone a repository from your own account
$ gh repo clone myrepo
# Clone a repo, overriding git protocol configuration
$ gh repo clone https://github.com/cli/cli
$ gh repo clone [email protected]:cli/cli.git
# Clone a repository to a custom directory
$ gh repo clone cli/cli workspace/cli
# Clone a repository with additional git clone flags
$ gh repo clone cli/cli -- --depth=1
LEARN MORE
Use `gh <command> <subcommand> --help` for more information about a command.
Read the manual at https://cli.github.com/manual
Learn about exit codes using `gh help exit-codes`
Learn about accessibility experiences using `gh help accessibility`Here's its generated online documentation: https://cli.github.com/manual/gh_repo_clone Screenshot of the examples section: 
Apart from that, it looks like there needs to be another iteration to make the help text more suitable for the automated generation of manpages. |
|
Sorry for the delay (christmas/new year holiyday).
In terms of actual style to choose. I'd say go ahead with the In regards to help2man: I think a more preferrable solution would be something like what git does, which will simply show the man page pager. But I'll have to talk with @TomTheBear about that. This would also eliminate the duplication between man pages and help text. |
| print_stdout(" $ likwid-mpirun -nperdomain S:2 -g MEM ./a.out") | ||
| print_stdout(" # Run 2 processes on each socket and measure the MEM performance group.") | ||
| print_stdout(" # Only one process on a socket measures the Uncore/RAPL counters, the other one(s) only HWThread-local counters.") | ||
| print_stdout(" $ likwid-mpirun -nperdomain S:2 -g MEM ./a.out") |
There was a problem hiding this comment.
@ipatix: Are you referring to these examples with multiline description?
Maybe, due to multiline description, these look different i.e.
# Description (Line 1)
# Description (Line 2)
$ command
|
@ipatix: Updated likwid-pin -- Version 5.4.0 (commit: 441aa007bc9649fcb7b56d80433f9ea6494e9dc2)
A tool to pin a program including threads.
Options:
-h, --help Help message
-v, --version Version information
-V, --verbose <level> Verbose output, 0 (only errors), 1 (info), 2 (details), 3 (developer)
-i Set NUMA interleave policy with all involved NUMA nodes
-m Set NUMA membind policy with all involved NUMA nodes
-S, --sweep Sweep memory and LLC of involved NUMA nodes
-c/-C <list> Comma separated processor IDs or expression
Following syntax variants are available for expression:
1. -c E:<thread domain>:<number of threads>
2. -c E:<thread domain>:<number of threads>:<chunk size>:<stride>
For two hardware threads per core on a SMT4 machine use e.g. -c E:N:122:2:4
-s, --skip <hex> Bitmask with threads to skip
-p Print available domains with mapping on physical IDs
If used together with -c option outputs the list of physical processor IDs.
-d <string> Delimiter used for using -p to output physical processor list, default is comma.
-q, --quiet Silent without output
Notes:
You can pin with the following numberings:
1. Logical numbering inside node.
e.g. -c N:0,1,2,3 for the first 4 physical cores of the node
2. Logical numbering inside socket.
e.g. -c S0:0-1 for the first 2 physical cores of the first socket
3. Logical numbering inside last level cache group.
e.g. -c C0:0-3 for the first 4 physical cores of the first last level cache domain
4. Logical numbering inside NUMA domain.
e.g. -c M0:0-3 for the first 4 physical cores of the first NUMA domain
You can also mix domains separated by '@',
e.g. -c S0:0-3@S1:0-3 for the 4 first physical cores of the first two sockets.
likwid-pin sets OMP_NUM_THREADS with as many threads as specified
in your pin expression if OMP_NUM_THREADS is not present in your environment.
Examples:
# Pin to hardware threads 0,4,5 and 6 using physical numbering
$ likwid-pin -c 0,4-6 ./app
# Pin to hardware threads using logical thread numberings in physical cores first sorted list
$ likwid-pin -c N:0,4-6 ./app
# Expressions based thread list generation with compact processor numbering
# This will generate a compact list of thread to processor mapping for the node domain with 8 threads.
$ likwid-pin -c E:N:8 ./app
# Scatter policy among thread domain type
# This will generate a thread to processor mapping scattered among all memory domains
# with physical hardware threads first.
$ likwid-pin -c M:scatter ./app |
|
At least |
|
I am no fan of having paged help output despite some of the help text can be quite long. I thought about calling a pager for some output (like the event and counter list of 'likwid-perfctr -e') but not for help. Help2man seems nice but for me, a man page should always be more than the help output. It is possible with help2man but then you depend on another tool being available at build time and it is split (help text inside the application and h2m file) One thing on my wish list is to unify the man pages and the application pages for doxygen. Just my 2 cents while relaxing at the beach. |
Updated with 02b7b23. likwid-setFrequencies -- Version 5.4.0 (commit: 441aa007bc9649fcb7b56d80433f9ea6494e9dc2)
A tool to adjust frequencies and governors on x86 CPUs.
Options:
-h Help message
-v Version information
-V <0-3> Verbosity (0=only_error, 3=developer)
-c dom CPU selection or LIKWID thread domain
Default behavior is to apply the frequencies to all CPUs.
See likwid-pin -h for details
-g gov Set governor ()
-f/--freq freq Set minimal and maximal CPU frequency
-p Print current frequencies (CPUs + Uncore)
-l List available CPU frequencies
-m List available CPU governors
-t/--turbo <0|1> De/Activate turbo mode
-x/--min freq Set minimal CPU frequency
-y/--max freq Set maximal CPU frequency
--umin freq Set minimal Uncore frequency
--umax freq Set maximal Uncore frequency
-reset Set governor 'performance', set minimal and maximal frequency to
the CPU limits and deactivate turbo.
-ureset Set Uncore frequencies to its min and max limits
Notes:
For the options -f, -x and -y:
- acpi-cpufreq driver: set the userspace governor implicitly
- intel_pstate driver: keep current governor
In general the min/max Uncore frequency can be set freely, even to 0 or 1E20
but the hardware stays inside its limits. LIKWID reduces the range of possible
frequencies to the minimal core frequency (likwid-setFrequencies -l) and the
maximally achievable turbo frequency with a single core (C0 value at
likwid-powermeter -i output).
Sleeping is commonly not sufficient.
If you switch governors with the intel_pstate driver, it might be that the driver
changes the frequency settings, please check afterwards and re-set frequencies if
needed.
Examples:
# Check whether the set Uncore frequency is really set and fixed
$ likwid-perfctr -g UNCORE_CLOCK:UBOXFIX -C 0 <exec_doing_work>
|
|
Thanks, but can you please go over all tools in src/applications and make sure that the style is consistent? If the point of this PR is to standardize the help text, and you change the usage of |
Updated with 8bd6514. for TOOL in /usr/local/bin/likwid-*; do echo; echo "--- $TOOL ---"; $TOOL --help | grep '/'; echo; done |
|
Thanks for the corrections. Looks good to me. |
3 participants
# Description$ commandprintwithprint_stdoutfor consistency across all applicationsversionandusagefunctions aslocalSigned-off-by: Azeem Sajid [email protected]