Re: [PATCH 2/4] docs: add man page for xenstore-list

[Andrew Cooper <andrew.cooper3@xxxxxxxxxx>]

On 12/03/2026 12:22 pm, Juergen Gross wrote:
> There is no man page for xenstore-list, add it.
>
> Signed-off-by: Juergen Gross <jgross@xxxxxxxx>
> ---
>  docs/man/xenstore-list.1.pod | 24 ++++++++++++++++++++++++
>  1 file changed, 24 insertions(+)
>  create mode 100644 docs/man/xenstore-list.1.pod
>
> diff --git a/docs/man/xenstore-list.1.pod b/docs/man/xenstore-list.1.pod
> new file mode 100644
> index 0000000000..4bc1ff9846
> --- /dev/null
> +++ b/docs/man/xenstore-list.1.pod
> @@ -0,0 +1,24 @@
> +=head1 NAME
> +
> +xenstore-list - list Xenstore key children
> +
> +=head1 SYNOPSIS
> +
> +B<xenstore-list> [I<OPTION>]... [I<PATH>]...
> +
> +=head1 DESCRIPTION
> +
> +List direct children of one or more Xenstore I<PATH>s, one child per line.
> +
> +=over
> +
> +=item B<-p>
> +
> +List the full Xenstore path of each listed path.
> +
> +=back
> +
> +=head1 BUGS
> +
> +Send bugs to xen-devel@xxxxxxxxxxxxxxxxxxxx, see
> +https://wiki.xenproject.org/wiki/Reporting_Bugs_against_Xen_Project on how 
> to send bug reports.

I had no idea we even had this...  Why on earth do we have both
xenstore-ls and xenstore-list, and for them to be different?

Even for the options; xenstore-ls uses -f for full path and -p for
permissions.


Having both is gross error on behalf of whomever accepted the code in
the first place.  It's a bad enough usability problem that I think we
should seriously consider deleting the binary rather than allowing
accepting it's existance.

But as I expect that to be controversial, at a minimum both of the
manpages need some kind of "do not confuse $THIS with $OTHER" warning.

~Andrew