[PATCH] docs: add xenstore-ls man page

[PATCH] docs: add xenstore-ls man page

[David Vrabel]

From: David Vrabel <david.vrabel@citrix.com>

Signed-off-by: David Vrabel <david.vrabel@citrix.com>
---
 docs/man/xenstore-ls.pod.1 |   60 ++++++++++++++++++++++++++++++++++++++++++++
 1 files changed, 60 insertions(+), 0 deletions(-)
 create mode 100644 docs/man/xenstore-ls.pod.1

diff --git a/docs/man/xenstore-ls.pod.1 b/docs/man/xenstore-ls.pod.1
new file mode 100644
index 0000000..3990b9a
--- /dev/null
+++ b/docs/man/xenstore-ls.pod.1
@@ -0,0 +1,60 @@
+=head1 NAME
+
+xenstore-ls - list Xenstore keys and values
+
+=head1 SYNOPSIS
+
+B<xenstore-ls> [I<OPTION>]... [I<PATH>]...
+
+=head1 DESCRIPTION
+
+List keys, values and permissions of one or more Xenstore I<PATH>s,
+using a nested, tree-like view.
+
+=over
+
+=item B<-f>
+
+Show the full path for all keys.
+
+=item B<-p>
+
+Show permissions of all the listed keys as comma separated list.  The
+format of each permission is I<LD>, where I<L> is a letter for the
+type of permission and I<D> is the corresponding domain ID.
+
+The types of permission are:
+
+=over
+
+=item B<r>
+
+read
+
+=item B<w>
+
+write
+
+=item B<b>
+
+read and write (both)
+
+=item B<n>
+
+no access
+
+=back
+
+The first permission entry is the key owner.  The key owner always has
+full access (read, write, and set permissions).
+
+=item B<-s>
+
+Connect to the Xenstore daemon using a local socket only.
+
+=back
+
+=head1 BUGS
+
+Send bugs to xen-devel@lists.xen.org, see
+http://wiki.xen.org/xenwiki/ReportingBugs on how to send bug reports.
-- 
1.7.2.5

Re: [PATCH] docs: add xenstore-ls man page

[Ian Campbell]

On Tue, 2013-07-02 at 11:21 +0100, David Vrabel wrote:
> From: David Vrabel <david.vrabel@citrix.com>
> 
> Signed-off-by: David Vrabel <david.vrabel@citrix.com>

Cool, thanks.

Any reason not to do the others? (I'll assume lack of time...)

xenstore-ls is actually a pointer to the multifunction xenstore client
utility (i.e. you can run "xenstore ls ..." too).

Is the normal Unix idiom in this case to have a single manpage which
documents all the various sub-functions.

BTW I'm not suggesting you write them all but perhaps a single
xenstore.pod.1 with placeholders for the others would be a better start?

Ack on the actual text here.

> ---
>  docs/man/xenstore-ls.pod.1 |   60 ++++++++++++++++++++++++++++++++++++++++++++
>  1 files changed, 60 insertions(+), 0 deletions(-)
>  create mode 100644 docs/man/xenstore-ls.pod.1
> 
> diff --git a/docs/man/xenstore-ls.pod.1 b/docs/man/xenstore-ls.pod.1
> new file mode 100644
> index 0000000..3990b9a
> --- /dev/null
> +++ b/docs/man/xenstore-ls.pod.1
> @@ -0,0 +1,60 @@
> +=head1 NAME
> +
> +xenstore-ls - list Xenstore keys and values
> +
> +=head1 SYNOPSIS
> +
> +B<xenstore-ls> [I<OPTION>]... [I<PATH>]...
> +
> +=head1 DESCRIPTION
> +
> +List keys, values and permissions of one or more Xenstore I<PATH>s,
> +using a nested, tree-like view.
> +
> +=over
> +
> +=item B<-f>
> +
> +Show the full path for all keys.
> +
> +=item B<-p>
> +
> +Show permissions of all the listed keys as comma separated list.  The
> +format of each permission is I<LD>, where I<L> is a letter for the
> +type of permission and I<D> is the corresponding domain ID.
> +
> +The types of permission are:
> +
> +=over
> +
> +=item B<r>
> +
> +read
> +
> +=item B<w>
> +
> +write
> +
> +=item B<b>
> +
> +read and write (both)
> +
> +=item B<n>
> +
> +no access
> +
> +=back
> +
> +The first permission entry is the key owner.  The key owner always has
> +full access (read, write, and set permissions).
> +
> +=item B<-s>
> +
> +Connect to the Xenstore daemon using a local socket only.
> +
> +=back
> +
> +=head1 BUGS
> +
> +Send bugs to xen-devel@lists.xen.org, see
> +http://wiki.xen.org/xenwiki/ReportingBugs on how to send bug reports.

Re: [PATCH] docs: add xenstore-ls man page

[David Vrabel]

On 02/07/13 11:27, Ian Campbell wrote:
> On Tue, 2013-07-02 at 11:21 +0100, David Vrabel wrote:
>> From: David Vrabel <david.vrabel@citrix.com>
>>
>> Signed-off-by: David Vrabel <david.vrabel@citrix.com>
> 
> Cool, thanks.
> 
> Any reason not to do the others? (I'll assume lack of time...)

xenstore-ls -p output was confusing me and it probably confuses lots of
people.

I've not got around to the other pages yet.

> xenstore-ls is actually a pointer to the multifunction xenstore client
> utility (i.e. you can run "xenstore ls ..." too).
>
> Is the normal Unix idiom in this case to have a single manpage which
> documents all the various sub-functions.

man does the right thing.  Both "man xenstore-ls" and "man xenstore ls"
will get this man page.

I think its best to have separate pages for each (sub)utility -- keeps
each page short and free of clutter.  This is how the git man pages are
done.

> BTW I'm not suggesting you write them all but perhaps a single
> xenstore.pod.1 with placeholders for the others would be a better start?

An additional xenstore(1) man page summarizing the sub-commands would be
useful.  Again, ala git.

I'll work on this and the pages for the other xenstore utilities later,
when I have more time.

David

Re: [PATCH] docs: add xenstore-ls man page

[Ian Campbell]

On Tue, 2013-07-02 at 11:38 +0100, David Vrabel wrote:
> On 02/07/13 11:27, Ian Campbell wrote:
> > On Tue, 2013-07-02 at 11:21 +0100, David Vrabel wrote:
> >> From: David Vrabel <david.vrabel@citrix.com>
> >>
> >> Signed-off-by: David Vrabel <david.vrabel@citrix.com>
> > 
> > Cool, thanks.
> > 
> > Any reason not to do the others? (I'll assume lack of time...)
> 
> xenstore-ls -p output was confusing me and it probably confuses lots of
> people.
> 
> I've not got around to the other pages yet.
> 
> > xenstore-ls is actually a pointer to the multifunction xenstore client
> > utility (i.e. you can run "xenstore ls ..." too).
> >
> > Is the normal Unix idiom in this case to have a single manpage which
> > documents all the various sub-functions.
> 
> man does the right thing.  Both "man xenstore-ls" and "man xenstore ls"
> will get this man page.
> 
> I think its best to have separate pages for each (sub)utility -- keeps
> each page short and free of clutter.  This is how the git man pages are
> done.
> 
> > BTW I'm not suggesting you write them all but perhaps a single
> > xenstore.pod.1 with placeholders for the others would be a better start?
> 
> An additional xenstore(1) man page summarizing the sub-commands would be
> useful.  Again, ala git.
> 
> I'll work on this and the pages for the other xenstore utilities later,
> when I have more time.

OK, thanks.

In any case the original patch is:
Acked-by: Ian Campbell <ian.campbell@citrix.com>

Ian.

Re: [PATCH] docs: add xenstore-ls man page

[Matthew Daley]

On Tue, Jul 2, 2013 at 10:21 PM, David Vrabel <david.vrabel@citrix.com> wrote:
> +The first permission entry is the key owner.  The key owner always has
> +full access (read, write, and set permissions).

You might want to clarify that the key owner is the first permission
entry's domain ID, and also that the first permission entry's type
indicates the access granted to domains not explicitly listed in the
rest of the permission list. I find this an "interesting" part of the
permissions system.

Re: [PATCH] docs: add xenstore-ls man page

[David Vrabel]

On 03/07/13 08:38, Matthew Daley wrote:
> On Tue, Jul 2, 2013 at 10:21 PM, David Vrabel <david.vrabel@citrix.com> wrote:
>> +The first permission entry is the key owner.  The key owner always has
>> +full access (read, write, and set permissions).
> 
> You might want to clarify that the key owner is the first permission
> entry's domain ID, and also that the first permission entry's type
> indicates the access granted to domains not explicitly listed in the
> rest of the permission list. I find this an "interesting" part of the
> permissions system.

Good point, I didn't pick this up as the wiki page is wrong/confusing.
I'll also fix the wiki page as soon as I have edit permissions.

David

Re: [PATCH] docs: add xenstore-ls man page

[Ian Campbell]

On Wed, 2013-07-03 at 10:29 +0100, David Vrabel wrote:
> On 03/07/13 08:38, Matthew Daley wrote:
> > On Tue, Jul 2, 2013 at 10:21 PM, David Vrabel <david.vrabel@citrix.com> wrote:
> >> +The first permission entry is the key owner.  The key owner always has
> >> +full access (read, write, and set permissions).
> > 
> > You might want to clarify that the key owner is the first permission
> > entry's domain ID, and also that the first permission entry's type
> > indicates the access granted to domains not explicitly listed in the
> > rest of the permission list. I find this an "interesting" part of the
> > permissions system.
> 
> Good point, I didn't pick this up as the wiki page is wrong/confusing.
> I'll also fix the wiki page as soon as I have edit permissions.

What is yyour username? I'll do it now