[v4] Add manpage for QEMU Backup Tool

qemu-backup will be a command-line tool for performing full and incremental disk backups on running VMs.  It is intended as a reference implementation for management stack and backup developers to see QEMU's backup features in action. The following commit is an initial implementation of manpage listing the commands which the backup tool will support.

Signed-off-by: Ishani Chugh <chugh.ishani@research.iiit.ac.in>
---
 Makefile                        |   2 +-
 contrib/backup/qemu-backup.texi | 132 ++++++++++++++++++++++++++++++++++++++++
 2 files changed, 133 insertions(+), 1 deletion(-)
 create mode 100644 contrib/backup/qemu-backup.texi

On Thu, Jun 22, 2017 at 11:43:02PM +0530, Ishani Chugh wrote:

I'm happy with the overall command-line interface.  A few minor comments
below.

> qemu-backup will be a command-line tool for performing full and incremental disk backups on running VMs.  It is intended as a reference implementation for management stack and backup developers to see QEMU's backup features in action. The following commit is an initial implementation of manpage listing the commands which the backup tool will support.
> 
> Signed-off-by: Ishani Chugh <chugh.ishani@research.iiit.ac.in>
> ---
>  Makefile                        |   2 +-
>  contrib/backup/qemu-backup.texi | 132 ++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 133 insertions(+), 1 deletion(-)
>  create mode 100644 contrib/backup/qemu-backup.texi
> 
> diff --git a/Makefile b/Makefile
> index c830d7a..094f291 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -504,7 +504,7 @@ clean:
>  VERSION ?= $(shell cat VERSION)
>  
>  dist: qemu-$(VERSION).tar.bz2
> -
> +qemu-backup.8: contrib/backup/qemu-backup.texi

This generates a man page.  Documentation should also be generated in
other output formats (.info, .html, .pdf, .txt).

Please add the other documentation output file formats (see Makefile for
examples).

>  qemu-%.tar.bz2:
>  	$(SRC_PATH)/scripts/make-release "$(SRC_PATH)" "$(patsubst qemu-%.tar.bz2,%,$@)"
>  
> diff --git a/contrib/backup/qemu-backup.texi b/contrib/backup/qemu-backup.texi
> new file mode 100644
> index 0000000..cdfad82
> --- /dev/null
> +++ b/contrib/backup/qemu-backup.texi
> @@ -0,0 +1,132 @@
> +\input texinfo
> +@setfilename qemu-backup
> +
> +@documentlanguage en
> +@documentencoding UTF-8
> +
> +@settitle QEMU Backup Tool
> +@copying
> +
> +Copyright @copyright{} 2017 The QEMU Project developers
> +@end copying
> +@ifinfo
> +@direntry
> +* QEMU: (QEMU-backup).    Man page for QEMU Backup Tool.
> +@end direntry
> +@end ifinfo
> +@iftex
> +@titlepage
> +@sp 7
> +@center @titlefont{QEMU Backup Tool}
> +@sp 1
> +@sp 3
> +@end titlepage
> +@end iftex
> +@ifnottex
> +@node Top
> +@top Short Sample
> +
> +@menu
> +* Name::
> +* Synopsis::
> +* list of Commands::

s/list/List/

> +* Command Parameters::
> +* Command Descriptions::
> +* License::
> +@end menu
> +
> +@end ifnottex
> +
> +@node Name
> +@chapter Name
> +
> +QEMU disk backup tool.
> +
> +@node Synopsis
> +@chapter Synopsis
> +
> +qemu-backup command [ command options].

s/[ command options]/[command options]/

> +
> +@node  List of Commands
> +@chapter  List of Commands
> +@itemize
> +@item qemu-backup guest add --guest guestname --qmp socketpath
> +@item qemu-backup guest list
> +@item qemu-backup drive add --id driveid --guest guestname --target target
> +@item qemu-backup drive add --all --guest guestname --target target
> +@item qemu-backup drive list --guest guestname
> +@item qemu-backup backup [--inc] --guest guestname
> +@item qemu-backup restore --guest guestname
> +@item qemu-backup drive remove --guest guestname --id driveid
> +@item qemu-backup guest remove --guest guestname
> +@end itemize
> +@node  Command Parameters
> +@chapter  Command Parameters
> +@itemize
> +@item --guest: Name of the guest.
> +@item --id: id of guest or drive.
> +@item --target: Destination path on which you want your backup to be made.
> +@item --all: Add all the drives present in a guest which are suitable for backup.
> +@item --inc: For incremental backup.
> +@item --qmp: Path of qmp socket.

Does this support both UNIX domain sockets (/path/to/qmp.sock) and TCP
(localhost:1234)?  Please document this.

> +@end itemize
> +
> +@node  Command Descriptions
> +@chapter  Command Descriptions
> +@itemize
> +@item qemu-backup guest add --guest guestname --qmp socketpath
> +This command adds a guest to the configuration file given its path to qmp socket.
> +
> +example:
> +qemu-backup guest add --id=fedora –qmp=/var/run/qemu/fedora.sock

Careful, there is a En Dash (U+2013) character here instead of a
Hypen-Minus (U+002D):

s/–/--/

Please use the ASCII character so the example can be copy-pasted and
executes correctly.

> +
> +@item qemu-backup guest list
> +This commands lists the names of guests which are added to configuration file.
> +
> +@item qemu-backup drive add --guest guestname --id driveid --target target
> +This command adds different drives for backup in a particular guest by giving the name of drive to be backed up and target imagefile in which we want to store the drive backup.
> +
> +example:qemu-backup drive add --guest=fedora --id=root
> +--target=/backup/root.img

The line is wrapped.  An example should not be formatted since it cannot
be copy-pasted into a shell with newlines in the middle:

example:
qemu-backup drive add --guest=fedora --id=root --target=/backup/root.img

> +
> +@item qemu-backup drive add --all --guest guestname --destination destination
> +This command adds all the drives of the guest for backup other than CDROM drive. Here all the backup drives will have the same names as original drives and target will be the destination folder.

Read-only drives shouldn't be included either.  Please say "all drives
except read-only".

On 06/22/2017 02:13 PM, Ishani Chugh wrote:
> qemu-backup will be a command-line tool for performing full and incremental disk backups on running VMs.  It is intended as a reference implementation for management stack and backup developers to see QEMU's backup features in action. The following commit is an initial implementation of manpage listing the commands which the backup tool will support.
> 

Try wrapping your commit messages to about 72-73 columns or so.

> Signed-off-by: Ishani Chugh <chugh.ishani@research.iiit.ac.in>
> ---
>  Makefile                        |   2 +-
>  contrib/backup/qemu-backup.texi | 132 ++++++++++++++++++++++++++++++++++++++++
>  2 files changed, 133 insertions(+), 1 deletion(-)
>  create mode 100644 contrib/backup/qemu-backup.texi
> 
> diff --git a/Makefile b/Makefile
> index c830d7a..094f291 100644
> --- a/Makefile
> +++ b/Makefile
> @@ -504,7 +504,7 @@ clean:
>  VERSION ?= $(shell cat VERSION)
>  
>  dist: qemu-$(VERSION).tar.bz2
> -

It's OK to leave the newline in here.

> +qemu-backup.8: contrib/backup/qemu-backup.texi

What command do I need to invoke to actually build this? I guess it
doesn't get build unless I type "make qemu-backup.8" explicitly. Maybe
this should build with other manpage documents? (Unless Stefan told you
not to?)

>  qemu-%.tar.bz2:
>  	$(SRC_PATH)/scripts/make-release "$(SRC_PATH)" "$(patsubst qemu-%.tar.bz2,%,$@)"
>  
> diff --git a/contrib/backup/qemu-backup.texi b/contrib/backup/qemu-backup.texi
> new file mode 100644
> index 0000000..cdfad82
> --- /dev/null
> +++ b/contrib/backup/qemu-backup.texi
> @@ -0,0 +1,132 @@
> +\input texinfo
> +@setfilename qemu-backup
> +
> +@documentlanguage en
> +@documentencoding UTF-8
> +
> +@settitle QEMU Backup Tool

The file I am seeing generated includes this line and nothing else
afterwards.

I am doing this:

cd ~/src/qemu
mkdir -p bin/git
cd bin/git
../../configure --enable-docs --target-list=x86_64-softmmu
make qemu-backup.8

Then I am attempting to view the manual:
man ./qemu-backup.8

but it appears mostly blank, so I think we probably have the wrong
syntax below. You can look at the intermediate file "qemu-backup.8.pod"
and see that it is mostly empty.

Am I doing this wrong?


As an aside, a question for the list:

Why are we using a perl script to convert texi->pod->man instead of just
using something like pandoc directly?

> +@copying
> +
> +Copyright @copyright{} 2017 The QEMU Project developers
> +@end copying
> +@ifinfo
> +@direntry
> +* QEMU: (QEMU-backup).    Man page for QEMU Backup Tool.
> +@end direntry
> +@end ifinfo
> +@iftex
> +@titlepage
> +@sp 7
> +@center @titlefont{QEMU Backup Tool}
> +@sp 1
> +@sp 3
> +@end titlepage
> +@end iftex
> +@ifnottex
> +@node Top
> +@top Short Sample
> +
> +@menu
> +* Name::
> +* Synopsis::
> +* list of Commands::
> +* Command Parameters::
> +* Command Descriptions::
> +* License::
> +@end menu
> +
> +@end ifnottex
> +
> +@node Name
> +@chapter Name
> +
> +QEMU disk backup tool.
> +
> +@node Synopsis
> +@chapter Synopsis
> +
> +qemu-backup command [ command options].
> +
> +@node  List of Commands
> +@chapter  List of Commands
> +@itemize
> +@item qemu-backup guest add --guest guestname --qmp socketpath
> +@item qemu-backup guest list
> +@item qemu-backup drive add --id driveid --guest guestname --target target
> +@item qemu-backup drive add --all --guest guestname --target target
> +@item qemu-backup drive list --guest guestname
> +@item qemu-backup backup [--inc] --guest guestname
> +@item qemu-backup restore --guest guestname
> +@item qemu-backup drive remove --guest guestname --id driveid
> +@item qemu-backup guest remove --guest guestname
> +@end itemize
> +@node  Command Parameters
> +@chapter  Command Parameters
> +@itemize
> +@item --guest: Name of the guest.
> +@item --id: id of guest or drive.
> +@item --target: Destination path on which you want your backup to be made.
> +@item --all: Add all the drives present in a guest which are suitable for backup.
> +@item --inc: For incremental backup.
> +@item --qmp: Path of qmp socket.
> +@end itemize
> +
> +@node  Command Descriptions
> +@chapter  Command Descriptions
> +@itemize
> +@item qemu-backup guest add --guest guestname --qmp socketpath
> +This command adds a guest to the configuration file given its path to qmp socket.
> +
> +example:
> +qemu-backup guest add --id=fedora –qmp=/var/run/qemu/fedora.sock
> +
> +@item qemu-backup guest list
> +This commands lists the names of guests which are added to configuration file.
> +
> +@item qemu-backup drive add --guest guestname --id driveid --target target
> +This command adds different drives for backup in a particular guest by giving the name of drive to be backed up and target imagefile in which we want to store the drive backup.
> +
> +example:qemu-backup drive add --guest=fedora --id=root
> +--target=/backup/root.img
> +
> +@item qemu-backup drive add --all --guest guestname --destination destination
> +This command adds all the drives of the guest for backup other than CDROM drive. Here all the backup drives will have the same names as original drives and target will be the destination folder.
> +
> +example: qemu-backup drive add --all --guest fedora --destination =/backup/fedora/
> +
> +@item qemu-backup drive list --guest guestname
> +This commands gives the names of the drive present in a guest which are added for backup.
> +
> +example: qemu-backup drive list --guest=fedora
> +
> +@item qemu-backup backup --guest guestname
> +
> +This command makes the backup of the drives, in their respective given destinations. The ids of drive and their destinations are taken from the configuration file.
> +
> +example: qemu-backup backup --guest=fedora
> +
> +@item qemu-backup restore --guest guestname
> +This command is needed if we want to restore the backup. It will list the commands to be run for performing the same but will not perform any action.
> +
> +example: qemu-backup restore --guest=fedora
> +
> +@item qemu-backup drive remove --guest guestname --id driveid
> +This command helps remove a drive which is set for backup in configuration of given host.
> +
> +example: drive remove --guest=fedora --id=root
> +
> +@item qemu-backup guest remove --guest guestname
> +This command removes the guest from the configuration file.
> +
> +example: qemu-backup guest remove --guest=fedora
> +
> +@end itemize
> +
> +@node License
> +@appendix License
> +QEMU is a trademark of Fabrice Bellard.
> +QEMU is released under the
> +@url{https://www.gnu.org/licenses/gpl-2.0.txt,GNU General Public License},
> +version 2. Parts of QEMU have specific licenses, see file
> +@url{http://git.qemu.org/?p=qemu.git;a=blob_plain;f=LICENSE,LICENSE}.
> +@bye
>