[sheepdog] [PATCH v2] man: autogenerate sheepdog manuals

Fri May 31 20:06:16 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.
> 

Applied, thanks.

Yuan