[sheepdog] [PATCH v2] man: autogenerate sheepdog manuals
Liu Yuan
namei.unix at gmail.com
Fri May 31 12:43:49 CEST 2013
On 05/31/2013 05:32 PM, MORITA Kazutaka wrote:
> From: MORITA Kazutaka <morita.kazutaka at lab.ntt.co.jp>
>
> Signed-off-by: MORITA Kazutaka <morita.kazutaka at lab.ntt.co.jp>
> ---
>
> v2:
> - rename QEMU/KVM to QEMU
> - add sheepfs(8) to the see also section in sheep.8 and collie.8
> - autogenerate sheepfs.8
> - make man after executables because we use them to generate manuals
>
> Makefile.am | 4 +-
> man/Makefile.am | 33 ++++++++++
> man/{collie.8 => collie.8.in} | 138 ++-------------------------------------
> man/{sheep.8 => sheep.8.in} | 54 ++-------------
> man/{sheepfs.8 => sheepfs.8.in} | 29 ++------
> 5 files changed, 51 insertions(+), 207 deletions(-)
> rename man/{collie.8 => collie.8.in} (15%)
> rename man/{sheep.8 => sheep.8.in} (43%)
> rename man/{sheepfs.8 => sheepfs.8.in} (73%)
>
> diff --git a/Makefile.am b/Makefile.am
> index c0f31ac..16eb532 100644
> --- a/Makefile.am
> +++ b/Makefile.am
> @@ -17,12 +17,14 @@ sheepdogsysconfdir = ${SHEEPDOGCONFDIR}
>
> sheepdogsysconf_DATA =
>
> -SUBDIRS = lib collie sheep include script man shepherd
> +SUBDIRS = lib collie sheep include script shepherd
>
> if BUILD_SHEEPFS
> SUBDIRS += sheepfs
> endif
>
> +SUBDIRS += man
> +
> install-exec-local:
> $(INSTALL) -d $(DESTDIR)/${localstatedir}/lib/sheepdog
>
> diff --git a/man/Makefile.am b/man/Makefile.am
> index 0343610..8c1f46a 100644
> --- a/man/Makefile.am
> +++ b/man/Makefile.am
> @@ -5,3 +5,36 @@ dist_man_MANS = sheep.8 collie.8
> if BUILD_SHEEPFS
> dist_man_MANS += sheepfs.8
> endif
> +
> +sheep.8.options = $(shell ../sheep/sheep -h | \
> + perl -ne 'print ".TP\n.BI $$1 \"\\fR, \\fP\" $$2\n$$3\n" if /^ ([^,]+), (\S+)\s+(.+)/' | \
> + sed 's/\\/\\\\\\/g' | \
> + sed 's/"/\\"/g' | \
> + perl -pe 's/\n/\\n/g')
> +
> +collie.8.options = $(shell ../collie/collie -h | \
> + perl -ne 'if (/^ (.+?) \s+(.+)/) {system "../collie/collie $$1 -h"; print "Description:\n $$2\n"}'| \
> + sed 's/Usage: collie \(.*\)/.TP\n.BI "\1"/g' | \
> + sed 's/\(^[a-zA-Z]*:\)/\n\1/g' | \
> + sed 's/\\/\\\\\\/g' | \
> + sed 's/"/\\"/g' | \
> + perl -pe 's/\n/\\n/g')
> +
> +sheepfs.8.options = $(shell ../sheepfs/sheepfs -h | \
> + perl -ne 'print ".TP\n.BI $$1 \"\\fR, \\fP\" $$2\n$$3\n" if /^ ([^,]+), (\S+)\s+(.+)/' | \
> + sed 's/\\/\\\\\\/g' | \
> + sed 's/"/\\"/g' | \
> + perl -pe 's/\n/\\n/g')
> +
> +%: %.in Makefile
> + rm -f $@-t $@
> + @sed \
> + -e "s#@DATE@#`date '+%Y-%m-%d'`#g" \
> + -e "s#@OPTIONS@#${$@.options}#g" \
> + $< > $@-t
> + mv $@-t $@
> +
> +all-local: $(dist_man_MANS)
> +
> +clean-local:
> + rm -rf $(dist_man_MANS)
> diff --git a/man/collie.8 b/man/collie.8.in
> similarity index 15%
> rename from man/collie.8
> rename to man/collie.8.in
> index 3ca2372..7fdee4a 100644
> --- a/man/collie.8
> +++ b/man/collie.8.in
> @@ -1,152 +1,23 @@
> -.TH SHEEPDOG 8 2012-08-05
> +.TH SHEEPDOG 8 @DATE@
> .SH NAME
> collie \- Command line utility for the sheep daemon
> .SH SYNOPSIS
> .B "collie <command> <subcommand> [options]"
> .SH DESCRIPTION
> .B collie
> -- Sheepdog is a distributed storage system for KVM/QEMU. It provides
> +- Sheepdog is a distributed storage system for QEMU. It provides
> highly available block level storage volumes to virtual machines.
> Sheepdog supports advanced volume management features such as snapshot,
> cloning, and thin provisioning. The architecture of Sheepdog is fully
> symmetric; there is no central node such as a meta-data server.
>
> The server daemon is called sheep(8). A command line utility is available
> -via collie(8). KVM/QEMU virtual machines use the sheep daemon via a block
> +via collie(8). QEMU virtual machines use the sheep daemon via a block
> driver available in qemu(1).
>
> For more information, run 'collie <command> <subcommand> --help'.
> -.SH OPTIONS
> -.TP
> -.BI \-a "\fR, \fP" \--address
> -This option specifies the daemon address (default: localhost).
> -.TP
> -.BI \-p "\fR, \fP" \--port
> -This option specifies the daemon port.
> -.TP
> -.BI \-i "\fR, \fP" \--index
> -This option specifies the index of data objects.
> -.TP
> -.BI \-s "\fR, \fP" \--snapshot
> -This option specifies a snapshot id or tag name.
> -.TP
> -.BI \-P "\fR, \fP" \--prealloc
> -This option preallocates all the data objects.
> -.TP
> -.BI \-r "\fR, \fP" \--raw
> -This option set raw output mode: omit headers, separate fields with single spaces and print all sizes in decimal bytes.
> -.TP
> -.BI \-d "\fR, \fP" \--delete
> -This option deletes a key.
> -.TP
> -.BI \-x "\fR, \fP" \--exclusive
> -This option enables exclusive write mode.
> -.TP
> -.BI \-b "\fR, \fP" \--store
> -This option specifies the backend store.
> -.TP
> -.BI \-c "\fR, \fP" \--copies
> -This option specifies the level of data redundancy (i.e. number of copies to maintain of each object).
> -.TP
> -.BI \-m "\fR, \fP" \--mode\ [safe|quorum|unsafe]
> -This option controls the behavior when there are too few nodes for the configured redundancy. Mode 'safe' will halt cluster IO when (nr_nodes < nr_copies). Mode 'quorum' will halt cluster IO when (nr_nodes < nr_copies/2 + 1). Mode 'unsafe' will never halt the cluster and therefore data loss may result.
> -.TP
> -.BI \-f "\fR, \fP" \--force
> -Do not prompt for confirmation.
> -.TP
> -.BI \-R "\fR, \fP" \--restore
> -This option restores the cluster.
> -.TP
> -.BI \-h "\fR, \fP" \--help
> -Display help and exit.
> .SH COMMAND & SUBCOMMAND
> -.TP
> -.BI "vdi create [-P|--prealloc] [-a|--address address] [-p|--port port] [-h|--help] <vdiname> <size>"
> -This command creates an image.
> -.TP
> -.BI "vdi snapshot [-s snapshot] [-a address] [-p port] [-h] <vdiname>"
> -This command creates a snapshot.
> -.TP
> -.BI "vdi check [-s snapshot] [-a address] [-p port] [-h] <vdiname>"
> -This command checks and repairs an image's consistency.
> -.TP
> -.BI "vdi clone [-s snapshot] [-P] [-a address] [-p port] [-h] <src vdi> <dst vdi>"
> -This command clones an image.
> -.TP
> -.BI "vdi delete [-s snapshot] [-a address] [-p port] [-h] <vdiname>"
> -This command deletes an image.
> -.TP
> -.BI "vdi rollback [-s snapshot] [-a address] [-p port] [-h] <vdiname>"
> -This command rollbacks the current vdi to the requested snapshot.
> -.TP
> -.BI "vdi list [-a address] [-p port] [-r] [-h] [vdiname]"
> -This command lists images.
> -.TP
> -.BI "vdi track [-i index] [-s snapshot] [-a address] [-p port] [-h] <vdiname>"
> -This command shows the object epoch trace in the image.
> -.TP
> -.BI "vdi tree [-a address] [-p port] [-h]"
> -This command shows images in tree view format.
> -.TP
> -.BI "vdi graph [-a address] [-p port] [-h]"
> -This command shows images in Graphviz dot format.
> -.TP
> -.BI "vdi object [-i index] [-s snapshot] [-a address] [-p port] [-h] <vdiname>"
> -This command shows object information in the image.
> -.TP
> -.BI "vdi setattr [-d] [-x] [-a address] [-p port] [-h] <vdiname> <key> [value]"
> -This command sets a VDI attribute.
> -.TP
> -.BI "vdi getattr [-a address] [-p port] [-h] <vdiname> <key>"
> -This command gets a VDI attribute.
> -.TP
> -.BI "vdi resize [-a address] [-p port] [-h] <vdiname> <new size>"
> -This command resizes an image.
> -.TP
> -.BI "vdi read [-s snapshot] [-a address] [-p port] [-h] <vdiname> [<offset> [<len>]]"
> -This command reads data from an image.
> -.TP
> -.BI "vdi write [-a address] [-p port] [-h] <vdiname> [<offset> [<len>]]"
> -This command writes data to an image.
> -.TP
> -.BI "vdi backup [-s snapshot] [-F from] [-a address] [-p port] [-h] <vdiname>"
> -This command creates an incremental backup between two snapshots.
> -.TP
> -.BI "vdi restore [-s snapshot] [-a address] [-p port] [-h] <vdiname>"
> -This command restores snapshot images from a backup.
> -.TP
> -.BI "node kill [-a address] [-p port] [-r] [-h] <node id>"
> -This command kills the specified node.
> -.TP
> -.BI "node list [-a address] [-p port] [-r] [-h]"
> -This command lists nodes.
> -.TP
> -.BI "node info [-a address] [-p port] [-r] [-h]"
> -This command shows information about each node.
> -.TP
> -.BI "node recovery [-a address] [-p port] [-r] [-h]"
> -This command shows nodes currently in recovery.
> -.TP
> -.BI "cluster info [-a address] [-p port] [-r] [-h]"
> -This command shows cluster information.
> -.TP
> -.BI "cluster format [-b store] [-c copies] [-m mode] [-a address] [-p port] [-h]"
> -This command creates a Sheepdog store.
> -.TP
> -.BI "cluster shutdown [-a address] [-p port] [-h]"
> -This command stops Sheepdog.
> -.TP
> -.BI "cluster recover info [-a address] [-f] [-p port] [-h]"
> -Show the status of recovery to user.
> -.TP
> -.BI "cluster recover force [-a address] [-f] [-p port] [-h]"
> -Force recover cluster immediately.
> -.TP
> -.BI "cluster recover enable [-a address] [-f] [-p port] [-h]"
> -Enable automatic recovery and run once recover if necessary.
> -.TP
> -.BI "cluster recover disable [-a address] [-f] [-p port] [-h]"
> -Disable automatic recovery.
> + at OPTIONS@
>
> .SH DEPENDENCIES
> \fBSheepdog\fP requires QEMU 0.13.z or later and Corosync 1.y.z or 2.y.z.
> @@ -157,6 +28,7 @@ none
> .SH SEE ALSO
> .BR sheep(8),
> .BR qemu(1),
> +.BR sheepfs(8),
> .BR corosync_overview(8)
>
> .SH AUTHORS
> diff --git a/man/sheep.8 b/man/sheep.8.in
> similarity index 43%
> rename from man/sheep.8
> rename to man/sheep.8.in
> index f996431..93295a8 100644
> --- a/man/sheep.8
> +++ b/man/sheep.8.in
> @@ -1,64 +1,21 @@
> -.TH SHEEPDOG 8 2012-08-05
> +.TH SHEEPDOG 8 @DATE@
> .SH NAME
> -sheep \- Distributed Block Storage System for KVM
> +sheep \- Distributed Block Storage System for QEMU
> .SH SYNOPSIS
> .B "sheep [options] [PATH]"
> .SH DESCRIPTION
> .B sheep
> -- Sheepdog is a distributed storage system for KVM/QEMU. It provides
> +- Sheepdog is a distributed storage system for QEMU. It provides
> highly available block level storage volumes to virtual machines.
> Sheepdog supports advanced volume management features such as snapshot,
> cloning, and thin provisioning. The architecture of Sheepdog is fully
> symmetric; there is no central node such as a meta-data server.
>
> The server daemon is called sheep(8). A command line utility is available
> -via collie(8). KVM/QEMU virtual machines use the sheep daemon via a block
> +via collie(8). QEMU virtual machines use the sheep daemon via a block
> driver available in qemu(1).
> .SH OPTIONS
> -.TP
> -.BI \-P "\fR, \fP" \--pidfile " pidfile"
> -This option creates a pid file.
> -.TP
> -.BI \-p "\fR, \fP" \--port " port"
> -This option specifies the IP port over which \fBsheep\fP looks for other
> -sheepdog cluster nodes.
> -.TP
> -.BI \-f "\fR, \fP" \--foreground
> -This option forces the sheepdog daemon to run in the foreground.
> -.TP
> -.BI \-d "\fR, \fP" \--debug
> -This option displays debug messages.
> -.TP
> -.BI \-D "\fR, \fP" \--directio
> -This option enables direct IO when accessing the object cache.
> -.TP
> -.BI \-z "\fR, \fP" \--zone
> -This option specifies the availability zone id.
> -.TP
> -.BI \-c "\fR, \fP" \--cluster
> -This option specifies the cluster driver.
> -.TP
> -.BI \-g "\fR, \fP" \--gateway
> -Makes the sheep instance run in gateway mode.
> -.TP
> -.BI \-l "\fR, \fP" \--loglevel
> -Specify the level of logging detail.
> -.TP
> -.BI \-o "\fR, \fP" \--stdout
> -Log to stdout instead of shared logger.
> -.TP
> -.BI \-s "\fR, \fP" \--disk-space
> -Specify the free disk space in megabytes.
> -.TP
> -.BI \-w "\fR, \fP" \--enable-cache " size[,mode]"
> -Enable object cache and specify the max cache size in megabytes and mode.
> -Mode can be writethrough (default) or writeback. (EXPERIMENTAL)
> -.TP
> -.BI \-y "\fR, \fP" \--myaddr
> -Specify the address advertised to other sheep.
> -.TP
> -.BI \-h "\fR, \fP" \--help
> -Display help and exit.
> + at OPTIONS@
>
> .SH PATH
> Proper LSB systems will store sheepdog files in /var/lib/sheepdog. The init
> @@ -77,6 +34,7 @@ mount \-o remount,user_xattr /var/lib/sheepdog
> .SH SEE ALSO
> .BR collie(8),
> .BR qemu(1),
> +.BR sheepfs(8),
> .BR corosync_overview(8)
>
> .SH AUTHORS
> diff --git a/man/sheepfs.8 b/man/sheepfs.8.in
> similarity index 73%
> rename from man/sheepfs.8
> rename to man/sheepfs.8.in
> index 5e285e0..58d8624 100644
> --- a/man/sheepfs.8
> +++ b/man/sheepfs.8.in
> @@ -1,18 +1,18 @@
> -.TH SHEEPDOG 8 2012-06-27
> +.TH SHEEPDOG 8 @DATE@
> .SH NAME
> sheepfs \- A pseudo file system exports both Sheepdog's internal state as well as Sheepdog's storage
> .SH SYNOPSIS
> .B "sheepfs [OPTION]... MOUNTPOINT"
> .SH DESCRIPTION
> .B sheepfs
> -- Sheepdog is a distributed storage system for KVM/QEMU. It provides
> +- Sheepdog is a distributed storage system for QEMU. It provides
> highly available block level storage volumes to virtual machines.
> Sheepdog supports advanced volume management features such as snapshot,
> cloning, and thin provisioning. The architecture of Sheepdog is fully
> symmetric; there is no central node such as a meta-data server.
>
> The server daemon is called sheep(8). A command line utility is available
> -via collie(8). A pseudo file system is available via sheepfs(8). KVM/QEMU
> +via collie(8). A pseudo file system is available via sheepfs(8). QEMU
> virtual machines use the sheep daemon via a block driver available in qemu(1).
>
> Sheepfs is a FUSE-based pseudo file system in userland to access both
> @@ -37,28 +37,7 @@ can be used as
>
> This file abstraction integrates well into kernel's pagecache.
> .SH OPTIONS
> -.TP
> -.BI \-a "\fR, \fP" \--address
> -This option specify the daemon address (default: localhost).
> -.TP
> -.BI \-p "\fR, \fP" \--port
> -This option specify the daemon port (default: 7000).
> -.TP
> -.TP
> -.BI \-d "\fR, \fP" \--debug
> -This option enable debug output (implies -f).
> -.TP
> -.BI \-f "\fR, \fP" \--foreground
> -This option let sheepfs run in the foreground.
> -.TP
> -.BI \-k "\fR, \fP" \--pagecache
> -This option use local kernel's page cache to access volume.
> -.TP
> -.BI \-n "\fR, \fP" \--noobjectcache
> -This option disable object cache of the attached volumes.
> -.TP
> -.BI \-h "\fR, \fP" \--help
> -Display help and exit.
> + at OPTIONS@
>
> .SH DEPENDENCIES
> \fBSheepdog\fP requires QEMU 0.13.z or later and Corosync 1.y.z.
>
Seems that some entries are missing in the manual, for e.g,
yliu at K55VM-ubuntu:~/sheepdog$ sheepfs -h
Usage: sheepfs [OPTION]... MOUNTPOINT
Options:
-a --address specify the sheep address (default: localhost)
-d, --debug enable debug output (implies -f)
-f, --foreground sheepfs run in the foreground
-k, --pagecache use local kernel's page cache to access volume
-n --noobjectcache disable object cache of the attached volumes
-p --port specify the sheep port (default: 7000)
-h, --help display this help and exit
but the manual:
OPTIONS
-d, --debug
enable debug output (implies -f)
-f, --foreground
sheepfs run in the foreground
-k, --pagecache
use local kernel's page cache to access volume
-h, --help
display this help and exit
Thanks,
Yuan
More information about the sheepdog
mailing list