From: Richard W.M. Jones Date: Sun, 1 May 2011 21:41:20 +0000 (-0400) Subject: doc: Use I<-...> for cross-references to command line options. X-Git-Tag: 1.11.4~6 X-Git-Url: http://git.annexia.org/?p=libguestfs.git;a=commitdiff_plain;h=c49fc3831d12788c27b90d12f06a1cd69a88e3be doc: Use I<-...> for cross-references to command line options. This is now used consistently across all the documentation. --- diff --git a/cat/virt-ls.pod b/cat/virt-ls.pod index 53e72b6..1ba7417 100755 --- a/cat/virt-ls.pod +++ b/cat/virt-ls.pod @@ -40,7 +40,7 @@ recursive. A simple listing is like the ordinary L command: boot [etc.] -With the C<-l> (C<--long>) option, C shows more detail: +With the I<-l> (I<--long>) option, C shows more detail: $ virt-ls -l -d myguest / total 204 @@ -48,7 +48,7 @@ With the C<-l> (C<--long>) option, C shows more detail: dr-xr-xr-x. 5 root root 3072 2009-08-25 19:06 boot [etc.] -With the C<-R> (C<--recursive>) option, C lists the +With the I<-R> (I<--recursive>) option, C lists the names of files and directories recursively: $ virt-ls -R -d myguest /tmp diff --git a/fish/guestfish.pod b/fish/guestfish.pod index 172729a..94deb9c 100644 --- a/fish/guestfish.pod +++ b/fish/guestfish.pod @@ -1139,9 +1139,9 @@ to make guestfish case sensitive. =item test2.img (etc) -When using the C<-N> or C<--new> option, the prepared disk or +When using the I<-N> or I<--new> option, the prepared disk or filesystem will be created in the file C in the current -directory. The second use of C<-N> will use C and so on. +directory. The second use of I<-N> will use C and so on. Any existing file with the same name will be overwritten. =back diff --git a/generator/generator_actions.ml b/generator/generator_actions.ml index 58c5f84..abf3475 100644 --- a/generator/generator_actions.ml +++ b/generator/generator_actions.ml @@ -155,7 +155,7 @@ and specifying the format."); "\ This function adds a virtual CD-ROM disk image to the guest. -This is equivalent to the qemu parameter C<-cdrom filename>. +This is equivalent to the qemu parameter I<-cdrom filename>. Notes: @@ -190,7 +190,7 @@ automatically."); "add qemu parameters", "\ This can be used to add arbitrary qemu command line parameters -of the form C<-param value>. Actually it's not quite arbitrary - we +of the form I<-param value>. Actually it's not quite arbitrary - we prevent you from setting some parameters which would interfere with parameters that we use. @@ -2261,7 +2261,7 @@ of compressed file. The exact command which runs is C. Note in particular that the filename is not prepended to the output -(the C<-b> option). +(the I<-b> option). This command can also be used on C devices (and partitions, LV names). You can for example use this @@ -3380,8 +3380,8 @@ See also C."); "check an ext2/ext3 filesystem", "\ This runs C, ie. runs the ext2/ext3 -filesystem checker on C, noninteractively (C<-p>), -even if the filesystem appears to be clean (C<-f>). +filesystem checker on C, noninteractively (I<-p>), +even if the filesystem appears to be clean (I<-f>). This command is only needed because of C (q.v.). Normally you should use C."); @@ -4157,7 +4157,7 @@ This command creates a hard link using the C command."); "create a hard link", "\ This command creates a hard link using the C command. -The C<-f> option removes the link (C) if it exists already."); +The I<-f> option removes the link (C) if it exists already."); ("ln_s", (RErr, [String "target"; Pathname "linkname"], []), 166, [], [InitScratchFS, Always, TestOutputStruct ( @@ -4178,7 +4178,7 @@ This command creates a symbolic link using the C command."); "create a symbolic link", "\ This command creates a symbolic link using the C command, -The C<-f> option removes the link (C) if it exists already."); +The I<-f> option removes the link (C) if it exists already."); ("readlink", (RString "link", [Pathname "path"], []), 168, [], [] (* XXX tested above *), @@ -5861,7 +5861,7 @@ For UFS block sizes, please see L. =item C -This passes the C<-O> parameter to the external mkfs program. +This passes the I<-O> parameter to the external mkfs program. For certain filesystem types, this allows extra filesystem features to be selected. See L and L @@ -5917,7 +5917,7 @@ See also: C, C, L."); "resize an ext2, ext3 or ext4 filesystem to the minimum size", "\ This command is the same as C, but the filesystem -is resized to its minimum size. This works like the C<-M> option +is resized to its minimum size. This works like the I<-M> option to the C command. To get the resulting size of the filesystem you should call diff --git a/resize/virt-resize.pod b/resize/virt-resize.pod index 1a32f25..c84e40f 100644 --- a/resize/virt-resize.pod +++ b/resize/virt-resize.pod @@ -183,7 +183,7 @@ has been shrunk properly. After shrinking PVs and filesystems, shut down the guest, and proceed with steps 3 and 4 above to allocate a new disk image. -Then run virt-resize with any of the C<--shrink> and/or C<--resize> +Then run virt-resize with any of the I<--shrink> and/or I<--resize> options. =head2 IGNORING OR DELETING PARTITIONS @@ -205,7 +205,7 @@ create qcow2 output, use: qemu-img create [-c] -f qcow2 outdisk [size] -instead of the truncate command (use C<-c> for a compressed disk). +instead of the truncate command (use I<-c> for a compressed disk). Similarly, to get non-sparse raw output use: @@ -254,25 +254,25 @@ For example: --resize /dev/sda1=-10% You can increase the size of any partition. Virt-resize will expand -the direct content of the partition if it knows how (see C<--expand> +the direct content of the partition if it knows how (see I<--expand> below). You can only I the size of partitions that contain filesystems or PVs which have already been shrunk. Virt-resize will check this has been done before proceeding, or else will print an -error (see also C<--resize-force>). +error (see also I<--resize-force>). You can give this option multiple times. =item B<--resize-force part=size> -This is the same as C<--resize> except that it will let you decrease +This is the same as I<--resize> except that it will let you decrease the size of any partition. Generally this means you will lose any data which was at the end of the partition you shrink, but you may not care about that (eg. if shrinking an unused partition, or if you can easily recreate it such as a swap partition). -See also the C<--ignore> option. +See also the I<--ignore> option. =item B<--expand part> @@ -306,12 +306,12 @@ Windows will check the disk. =item * LVM PVs (physical volumes). virt-resize does not usually resize -anything inside the PV, but see the C<--LV-expand> option. The user +anything inside the PV, but see the I<--LV-expand> option. The user could also resize LVs as desired after boot. =back -Note that you cannot use C<--expand> and C<--shrink> together. +Note that you cannot use I<--expand> and I<--shrink> together. =item B<--shrink part> @@ -329,7 +329,7 @@ In this case, virt-resize would give an error unless the user specified a partition to shrink and that partition had more than a gigabyte of free space. -Note that you cannot use C<--expand> and C<--shrink> together. +Note that you cannot use I<--expand> and I<--shrink> together. =item B<--ignore part> @@ -368,7 +368,7 @@ root device to fill the extra space in the PV. The contents of the LV are also resized if virt-resize knows how to do that. You can stop virt-resize from trying to expand the content by -using the option C<--no-expand-content>. +using the option I<--no-expand-content>. Use L to list the filesystems in the guest. @@ -400,9 +400,9 @@ partition will be created. =item B<--no-expand-content> By default, virt-resize will try to expand the direct contents -of partitions, if it knows how (see C<--expand> option above). +of partitions, if it knows how (see I<--expand> option above). -If you give the C<--no-expand-content> option then virt-resize +If you give the I<--no-expand-content> option then virt-resize will not attempt this. =item B<-d> @@ -504,7 +504,7 @@ L can do everything that virt-resize can do and a lot more, but at a much lower level. You will probably end up hand-calculating sector offsets, which is something that virt-resize was designed to avoid. If you want to see the guestfish-equivalent -commands that virt-resize runs, use the C<--debug> flag. +commands that virt-resize runs, use the I<--debug> flag. =head1 SHELL QUOTING diff --git a/tools/virt-edit b/tools/virt-edit index c1556eb..a004291 100755 --- a/tools/virt-edit +++ b/tools/virt-edit @@ -292,7 +292,7 @@ The first method is to temporarily set C<$EDITOR> to any script or program you want to run. The script is invoked as C<$EDITOR tmpfile> and it should update C in place however it likes. -The second method is to use the C<-e> parameter of C to run +The second method is to use the I<-e> parameter of C to run a short Perl snippet in the style of L. For example to replace all instances of C with C in a file: diff --git a/tools/virt-make-fs b/tools/virt-make-fs index 833c8a5..1a19b98 100755 --- a/tools/virt-make-fs +++ b/tools/virt-make-fs @@ -71,14 +71,14 @@ fit" the files that it contains, but might have extra space. Depending on how you are going to use the output, you might think this extra space is wasted and want to minimize it, or you might want to leave space so that more files can be added later. Virt-make-fs -defaults to minimizing the extra space, but you can use the C<--size> +defaults to minimizing the extra space, but you can use the I<--size> flag to leave space in the filesystem if you want it. An alternative way to leave extra space but not make the output image any bigger is to use an alternative disk image format (instead of the -default "raw" format). Using C<--format=qcow2> will use the native +default "raw" format). Using I<--format=qcow2> will use the native QEmu/KVM qcow2 image format (check your hypervisor supports this -before using it). This allows you to choose a large C<--size> but the +before using it). This allows you to choose a large I<--size> but the extra space won't actually be allocated in the image until you try to store something in it. @@ -190,7 +190,7 @@ my $size; =item B<-s +ENE> -Use the C<--size> (or C<-s>) option to choose the size of the output +Use the I<--size> (or I<-s>) option to choose the size of the output image. If this option is I given, then the output image will be just @@ -203,7 +203,7 @@ enough to contain all the input files, else you will get an error. To leave extra space, specify C<+> (plus sign) and a number followed by b/K/M/G/T/P/E to mean bytes, Kilobytes, Megabytes, Gigabytes, -Terabytes, Petabytes or Exabytes. For example: C<--size=+200M> means +Terabytes, Petabytes or Exabytes. For example: I<--size=+200M> means enough space for the input files, and (approximately) an extra 200 MB free space. @@ -253,17 +253,17 @@ my $partition; If specified, this flag adds an MBR partition table to the output disk image. -You can change the partition table type, eg. C<--partition=gpt> for +You can change the partition table type, eg. I<--partition=gpt> for large disks. -Note that if you just use a lonesome C<--partition>, the Perl option +Note that if you just use a lonesome I<--partition>, the Perl option parser might consider the next parameter to be the partition type. For example: virt-make-fs --partition input.tar ... would cause virt-make-fs to think you wanted to use a partition type -of C which is completely wrong. To avoid this, use C<--> +of C which is completely wrong. To avoid this, use I<--> (a double dash) between options and the input file argument: virt-make-fs --partition -- input.tar ... diff --git a/tools/virt-tar b/tools/virt-tar index b2c2e88..bce2986 100755 --- a/tools/virt-tar +++ b/tools/virt-tar @@ -63,12 +63,12 @@ Upload a local tarball and unpack it inside C in the VM: =head1 WARNING -You must I use C with the C<-u> option (upload) on live +You must I use C with the I<-u> option (upload) on live virtual machines. If you do this, you risk disk corruption in the VM. C tries to stop you from doing this, but doesn't catch all cases. -You can use C<-x> (extract) on live virtual machines, but you might +You can use I<-x> (extract) on live virtual machines, but you might get inconsistent results or errors if there is filesystem activity inside the VM. If the live VM is synched and quiescent, then C will usually work, but the only way to guarantee @@ -85,14 +85,14 @@ If you want to just view a single file, use L. If you just want to edit a single file, use L. For more complex cases you should look at the L tool. -There are two modes of operation: C<-x> (eXtract) downloads a +There are two modes of operation: I<-x> (eXtract) downloads a directory and its contents (recursively) from the virtual machine into -a local tarball. C<-u> uploads from a local tarball, unpacking it +a local tarball. I<-u> uploads from a local tarball, unpacking it into a directory inside the virtual machine. You cannot use these two options together. -In addition, you may need to use the C<-z> (gZip) option to enable -compression. When uploading, you have to specify C<-z> if the upload +In addition, you may need to use the I<-z> (gZip) option to enable +compression. When uploading, you have to specify I<-z> if the upload file is compressed because virt-tar won't detect this on its own. C can only handle tar (optionally gzipped) format tarballs. @@ -157,10 +157,10 @@ my $mode; =item B<-u> | B<--upload> -Use C<-x> to extract (download) a directory from a virtual machine +Use I<-x> to extract (download) a directory from a virtual machine to a local tarball. -Use C<-u> to upload and unpack from a local tarball into a virtual +Use I<-u> to upload and unpack from a local tarball into a virtual machine. Please read the L section above before using this option. diff --git a/tools/virt-win-reg b/tools/virt-win-reg index 2db2671..695e619 100755 --- a/tools/virt-win-reg +++ b/tools/virt-win-reg @@ -50,14 +50,14 @@ virt-win-reg - Export and merge Windows Registry entries from a Windows guest =head1 WARNING -You must I use C with the C<--merge> option on live +You must I use C with the I<--merge> option on live virtual machines. If you do this, you I get irreversible disk corruption in the VM. C tries to stop you from doing this, but doesn't catch all cases. Modifying the Windows Registry is an inherently risky operation. The format is deliberately obscure and undocumented, and Registry changes -can leave the system unbootable. Therefore when using the C<--merge> +can leave the system unbootable. Therefore when using the I<--merge> option, make sure you have a reliable backup first. =head1 DESCRIPTION @@ -68,7 +68,7 @@ Windows guest. The first parameter is the libvirt guest name or the raw disk image of a Windows guest. -If C<--merge> is I specified, then the chosen registry +If I<--merge> is I specified, then the chosen registry key is displayed/exported (recursively). For example: $ virt-win-reg Windows7 'HKEY_LOCAL_MACHINE\SOFTWARE\Microsoft' @@ -80,7 +80,7 @@ for example: $ virt-win-reg Windows7 $cvkey ProductName Windows 7 Enterprise -With C<--merge>, you can merge a textual regedit file into +With I<--merge>, you can merge a textual regedit file into the Windows Registry: $ virt-win-reg --merge Windows7 changes.reg @@ -160,7 +160,7 @@ In merge mode, this merges a textual regedit file into the Windows Registry of the virtual machine. If this flag is I given then virt-win-reg displays or exports Registry entries instead. -Note that C<--merge> is I to use on live virtual machines, and +Note that I<--merge> is I to use on live virtual machines, and will result in disk corruption. However exporting (without this flag) is always safe. @@ -423,7 +423,7 @@ UTF-16LE with Windows-style line endings, you may need to reencode the whole file before or after processing. To reencode a file from Windows format to Linux (before processing it -with the C<--merge> option), you would do something like this: +with the I<--merge> option), you would do something like this: iconv -f utf-16le -t utf-8 < win.reg | dos2unix > linux.reg @@ -442,7 +442,7 @@ file with Windows-style (CRLF) line endings, like this: software.reg: Little-endian UTF-16 Unicode text, with very long lines, with CRLF line terminators -This file would need conversion before you could C<--merge> it. +This file would need conversion before you could I<--merge> it. =head1 CurrentControlSet etc.