Changeset 94199 in vbox for trunk

Timestamp:

Mar 12, 2022 7:18:11 PM (3 years ago)

Author:

vboxsync

svn:sync-xref-src-repo-rev:

150455

Message:

doc/manual,FE/VBoxManage: Convert clonemedium command to refentry documentation, ​bugref:9186

Location:

trunk

Files:

• doc/manual/Config.kmk (modified) (1 diff)
• doc/manual/en_US/man_VBoxManage-clonemedium.xml (modified) (2 diffs)
• doc/manual/en_US/user_VBoxManage.xml (modified) (1 diff)
• src/VBox/Frontends/VBoxManage/VBoxManage.cpp (modified) (1 diff)
• src/VBox/Frontends/VBoxManage/VBoxManage.h (modified) (1 diff)
• src/VBox/Frontends/VBoxManage/VBoxManageDisk.cpp (modified) (6 diffs)
• src/VBox/Frontends/VBoxManage/VBoxManageHelp.cpp (modified) (1 diff)

trunk/doc/manual/Config.kmk ¶

@@ -68 +68 @@
         man_VBoxManage-bandwidthctl.xml \
         man_VBoxManage-showmediuminfo.xml \
-        man_VBoxManage-createmedium.xml
+        man_VBoxManage-createmedium.xml \
+        man_VBoxManage-clonemedium.xml
 
 ## List of user manual XML files.

trunk/doc/manual/en_US/man_VBoxManage-clonemedium.xml ¶

@@ -20 +20 @@
 <refentry id="vboxmanage-clonemedium" lang="en">
   <refentryinfo>
-    <pubdate>August 2019</pubdate>
+    <pubdate>$Date$</pubdate>
     <title>VBoxManage clonemedium</title>
   </refentryinfo>
@@ -32 +32 @@
     <refname>VBoxManage-clonemedium</refname>
     <refpurpose>create a clone of a medium</refpurpose>
-    <refclass>Oracle VM VirtualBox</refclass>
+    <refclass>&product-name;</refclass>
   </refnamediv>
 

trunk/doc/manual/en_US/user_VBoxManage.xml ¶

@@ -1089 +1089 @@
   </sect1>
 
-  <sect1 id="vboxmanage-clonemedium">
-
-    <title>VBoxManage clonemedium</title>
-
-    <para>
-      This command duplicates a virtual disk, DVD, or floppy medium to a
-      new medium, usually an image file, with a new unique identifier
-      (UUID). The new image can be transferred to another host system or
-      reimported into &product-name; using the Virtual Media Manager.
-      See <xref linkend="vdis" /> and <xref linkend="cloningvdis" />.
-      The syntax is as follows:
-    </para>
-
-<screen>VBoxManage clonemedium      [disk|dvd|floppy] &lt;uuid|inputfile&gt; &lt;uuid|outputfile&gt;
-
-                            [--format VDI|VMDK|VHD|RAW|&lt;other&gt;]
-                            [--variant Standard,Fixed,Split2G,Stream,ESX]
-                            [--existing]</screen>
-
-    <para>
-      The medium to clone as well as the target image must be described
-      either by its UUIDs, if the mediums are registered, or by its
-      filename. Registered images can be listed by <command>VBoxManage
-      list hdds</command>. See <xref linkend="vboxmanage-list" />. A
-      filename must be specified as valid path, either as an absolute
-      path or as a relative path starting from the current directory.
-    </para>
-
-    <para>
-      The following options are available:
-    </para>
-
-    <variablelist>
-
-      <varlistentry>
-        <term>
-          <computeroutput>--format</computeroutput>
-        </term>
-
-        <listitem>
-          <para>
-            Set a file format for the output file different from the
-            file format of the input file.
-          </para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>
-          <computeroutput>--variant</computeroutput>
-        </term>
-
-        <listitem>
-          <para>
-            Set a file format variant for the output file. This is a
-            comma-separated list of variant flags. Not all combinations
-            are supported, and specifying inconsistent flags will result
-            in an error message.
-          </para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>
-          <computeroutput>--existing</computeroutput>
-        </term>
-
-        <listitem>
-          <para>
-            Perform the clone operation to an already existing
-            destination medium. Only the portion of the source medium
-            which fits into the destination medium is copied. This means
-            if the destination medium is smaller than the source only a
-            part of it is copied, and if the destination medium is
-            larger than the source the remaining part of the destination
-            medium is unchanged.
-          </para>
-        </listitem>
-      </varlistentry>
-
-    </variablelist>
-
-    <note>
-      <para>
-        For compatibility with earlier versions of &product-name;, the
-        <command>clonevdi</command> and <command>clonehd</command>
-        commands are still supported and mapped internally to the
-        <command>clonemedium</command> command.
-      </para>
-    </note>
-
-  </sect1>
+  <xi:include href="user_man_VBoxManage-clonemedium.xml"   xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
 
   <sect1 id="vboxmanage-mediumproperty">

trunk/src/VBox/Frontends/VBoxManage/VBoxManage.cpp ¶

@@ -206 +206 @@
     { "modifyhd",           USAGE_MODIFYMEDIUM,     VBMG_CMD_TODO, handleModifyMedium,         0 }, /* backward compatibility */
     { "modifyvdi",          USAGE_MODIFYMEDIUM,     VBMG_CMD_TODO, handleModifyMedium,         0 }, /* backward compatibility */
-    { "clonemedium",        USAGE_CLONEMEDIUM,      VBMG_CMD_TODO, handleCloneMedium,          0 },
-    { "clonehd",            USAGE_CLONEMEDIUM,      VBMG_CMD_TODO, handleCloneMedium,          0 }, /* backward compatibility */
-    { "clonevdi",           USAGE_CLONEMEDIUM,      VBMG_CMD_TODO, handleCloneMedium,          0 }, /* backward compatibility */
+    { "clonemedium",        USAGE_S_NEWCMD,  HELP_CMD_CLONEMEDIUM, handleCloneMedium,          0 },
+    { "clonehd",            USAGE_S_NEWCMD,  HELP_CMD_CLONEMEDIUM, handleCloneMedium,          0 }, /* backward compatibility */
+    { "clonevdi",           USAGE_S_NEWCMD,  HELP_CMD_CLONEMEDIUM, handleCloneMedium,          0 }, /* backward compatibility */
     { "encryptmedium",      USAGE_ENCRYPTMEDIUM,    VBMG_CMD_TODO, handleEncryptMedium,        0 },
     { "checkmediumpwd",     USAGE_MEDIUMENCCHKPWD,  VBMG_CMD_TODO, handleCheckMediumPassword,  0 },

trunk/src/VBox/Frontends/VBoxManage/VBoxManage.h ¶

@@ -99 +99 @@
     USAGE_INVALID = 0,
     USAGE_MODIFYMEDIUM,
-    USAGE_CLONEMEDIUM,
     USAGE_CREATEHOSTIF,
     USAGE_REMOVEHOSTIF,

trunk/src/VBox/Frontends/VBoxManage/VBoxManageDisk.cpp ¶

@@ -1025 +1025 @@
             case 'd':   // disk
                 if (cmd != CMD_NONE)
-                    return errorSyntax(USAGE_CLONEMEDIUM, Disk::tr("Only one command can be specified: '%s'"), ValueUnion.psz);
+                    return errorSyntax(Disk::tr("Only one command can be specified: '%s'"), ValueUnion.psz);
                 cmd = CMD_DISK;
                 break;
@@ -1031 +1031 @@
             case 'D':   // DVD
                 if (cmd != CMD_NONE)
-                    return errorSyntax(USAGE_CLONEMEDIUM, Disk::tr("Only one command can be specified: '%s'"), ValueUnion.psz);
+                    return errorSyntax(Disk::tr("Only one command can be specified: '%s'"), ValueUnion.psz);
                 cmd = CMD_DVD;
                 break;
@@ -1037 +1037 @@
             case 'f':   // floppy
                 if (cmd != CMD_NONE)
-                    return errorSyntax(USAGE_CLONEMEDIUM, Disk::tr("Only one command can be specified: '%s'"), ValueUnion.psz);
+                    return errorSyntax(Disk::tr("Only one command can be specified: '%s'"), ValueUnion.psz);
                 cmd = CMD_FLOPPY;
                 break;
@@ -1069 +1069 @@
                     pszDst = ValueUnion.psz;
                 else
-                    return errorSyntax(USAGE_CLONEMEDIUM, Disk::tr("Invalid parameter '%s'"), ValueUnion.psz);
+                    return errorSyntax(Disk::tr("Invalid parameter '%s'"), ValueUnion.psz);
                 break;
 
@@ -1076 +1076 @@
                 {
                     if (RT_C_IS_GRAPH(c))
-                        return errorSyntax(USAGE_CLONEMEDIUM, Disk::tr("unhandled option: -%c"), c);
+                        return errorSyntax(Disk::tr("unhandled option: -%c"), c);
                     else
-                        return errorSyntax(USAGE_CLONEMEDIUM, Disk::tr("unhandled option: %i"), c);
+                        return errorSyntax(Disk::tr("unhandled option: %i"), c);
                 }
                 else if (c == VERR_GETOPT_UNKNOWN_OPTION)
-                    return errorSyntax(USAGE_CLONEMEDIUM, Disk::tr("unknown option: %s"), ValueUnion.psz);
+                    return errorSyntax(Disk::tr("unknown option: %s"), ValueUnion.psz);
                 else if (ValueUnion.pDef)
-                    return errorSyntax(USAGE_CLONEMEDIUM, "%s: %Rrs", ValueUnion.pDef->pszLong, c);
+                    return errorSyntax("%s: %Rrs", ValueUnion.pDef->pszLong, c);
                 else
-                    return errorSyntax(USAGE_CLONEMEDIUM, Disk::tr("error: %Rrs"), c);
+                    return errorSyntax(Disk::tr("error: %Rrs"), c);
         }
     }
@@ -1092 +1092 @@
         cmd = CMD_DISK;
     if (!pszSrc)
-        return errorSyntax(USAGE_CLONEMEDIUM, Disk::tr("Mandatory UUID or input file parameter missing"));
+        return errorSyntax(Disk::tr("Mandatory UUID or input file parameter missing"));
     if (!pszDst)
-        return errorSyntax(USAGE_CLONEMEDIUM, Disk::tr("Mandatory output file parameter missing"));
+        return errorSyntax(Disk::tr("Mandatory output file parameter missing"));
     if (fExisting && (!format.isEmpty() || enmMediumVariant != MediumVariant_Standard))
-        return errorSyntax(USAGE_CLONEMEDIUM, Disk::tr("Specified options which cannot be used with --existing"));
+        return errorSyntax(Disk::tr("Specified options which cannot be used with --existing"));
 
     ComPtr<IMedium> pSrcMedium;

trunk/src/VBox/Frontends/VBoxManage/VBoxManageHelp.cpp ¶

@@ -639 +639 @@
                      "\n", SEP);
 
-    if (enmCommand == USAGE_CLONEMEDIUM || enmCommand == USAGE_S_ALL)
-        RTStrmPrintf(pStrm,
-                           "%s clonemedium %s     [disk|dvd|floppy] <uuid|inputfile> <uuid|outputfile>\n"
-                     "                            [--format VDI|VMDK|VHD|RAW|<other>]\n"
-                     "                            [--variant Standard,Fixed,Split2G,Stream,ESX]\n"
-                     "                            [--existing]\n"
-                     "\n", SEP);
-
     if (enmCommand == USAGE_MEDIUMPROPERTY || enmCommand == USAGE_S_ALL)
         RTStrmPrintf(pStrm,