Re: [Qemu-devel] [PATCH v4] Add manpage for QEMU Backup Tool

[John Snow]

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 <address@hidden>
> ---
>  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
> address@hidden qemu-backup
> +
> address@hidden en
> address@hidden UTF-8
> +
> address@hidden 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?

> address@hidden
> +
> +Copyright @copyright{} 2017 The QEMU Project developers
> address@hidden copying
> address@hidden
> address@hidden
> +* QEMU: (QEMU-backup).    Man page for QEMU Backup Tool.
> address@hidden direntry
> address@hidden ifinfo
> address@hidden
> address@hidden
> address@hidden 7
> address@hidden @titlefont{QEMU Backup Tool}
> address@hidden 1
> address@hidden 3
> address@hidden titlepage
> address@hidden iftex
> address@hidden
> address@hidden Top
> address@hidden Short Sample
> +
> address@hidden
> +* Name::
> +* Synopsis::
> +* list of Commands::
> +* Command Parameters::
> +* Command Descriptions::
> +* License::
> address@hidden menu
> +
> address@hidden ifnottex
> +
> address@hidden Name
> address@hidden Name
> +
> +QEMU disk backup tool.
> +
> address@hidden Synopsis
> address@hidden Synopsis
> +
> +qemu-backup command [ command options].
> +
> address@hidden  List of Commands
> address@hidden  List of Commands
> address@hidden
> address@hidden qemu-backup guest add --guest guestname --qmp socketpath
> address@hidden qemu-backup guest list
> address@hidden qemu-backup drive add --id driveid --guest guestname --target 
> target
> address@hidden qemu-backup drive add --all --guest guestname --target target
> address@hidden qemu-backup drive list --guest guestname
> address@hidden qemu-backup backup [--inc] --guest guestname
> address@hidden qemu-backup restore --guest guestname
> address@hidden qemu-backup drive remove --guest guestname --id driveid
> address@hidden qemu-backup guest remove --guest guestname
> address@hidden itemize
> address@hidden  Command Parameters
> address@hidden  Command Parameters
> address@hidden
> address@hidden --guest: Name of the guest.
> address@hidden --id: id of guest or drive.
> address@hidden --target: Destination path on which you want your backup to be 
> made.
> address@hidden --all: Add all the drives present in a guest which are 
> suitable for backup.
> address@hidden --inc: For incremental backup.
> address@hidden --qmp: Path of qmp socket.
> address@hidden itemize
> +
> address@hidden  Command Descriptions
> address@hidden  Command Descriptions
> address@hidden
> address@hidden 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
> +
> address@hidden qemu-backup guest list
> +This commands lists the names of guests which are added to configuration 
> file.
> +
> address@hidden 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
> +
> address@hidden 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/
> +
> address@hidden 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
> +
> address@hidden 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
> +
> address@hidden 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
> +
> address@hidden 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
> +
> address@hidden qemu-backup guest remove --guest guestname
> +This command removes the guest from the configuration file.
> +
> +example: qemu-backup guest remove --guest=fedora
> +
> address@hidden itemize
> +
> address@hidden License
> address@hidden License
> +QEMU is a trademark of Fabrice Bellard.
> +QEMU is released under the
> address@hidden://www.gnu.org/licenses/gpl-2.0.txt,GNU General Public License},
> +version 2. Parts of QEMU have specific licenses, see file
> address@hidden://git.qemu.org/?p=qemu.git;a=blob_plain;f=LICENSE,LICENSE}.
> address@hidden
>