Changeset 94198 in vbox

Timestamp:

Mar 12, 2022 6:56:13 PM (3 years ago)

Author:

vboxsync

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

150454

Message:

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

Location:

trunk

Files:

• doc/manual/Config.kmk (modified) (1 diff)
• doc/manual/en_US/man_VBoxManage-createmedium.xml (modified) (1 diff)
• 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) (7 diffs)
• src/VBox/Frontends/VBoxManage/VBoxManageHelp.cpp (modified) (1 diff)

trunk/doc/manual/Config.kmk

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

trunk/doc/manual/en_US/man_VBoxManage-createmedium.xml

@@ -32 +32 @@
     <refname>VBoxManage-createmedium</refname>
     <refpurpose>create a new medium</refpurpose>
-    <refclass>Oracle VM VirtualBox</refclass>
+    <refclass>&product-name;</refclass>
   </refnamediv>
 

trunk/doc/manual/en_US/user_VBoxManage.xml

@@ -931 +931 @@
   <xi:include href="user_man_VBoxManage-showmediuminfo.xml" xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
 
-  <sect1 id="vboxmanage-createmedium">
-
-    <title>VBoxManage createmedium</title>
-
-    <para>
-      This command creates a new medium. The syntax is as follows:
-    </para>
-
-<screen>VBoxManage createmedium     [disk|dvd|floppy]    --filename &lt;filename&gt;
-                            [--size &lt;megabytes&gt;|--sizebyte &lt;bytes&gt;]
-                            [--diffparent &lt;uuid&gt;|&lt;filename&gt;
-                            [--format VDI|VMDK|VHD] (default: VDI)
-                            [--variant Standard,Fixed,Split2G,Stream,ESX,RawDisk]
-                            [[--property &lt;name&gt;=&lt;value&gt;]
-                             --property &lt;name&gt;=&lt;value&gt;]...
-                            [[--property-file &lt;name&gt;=&lt;/path/to/file/with/value&gt;]
-                             --property-file &lt;name&gt;=&lt;/path/to/file/with/value&gt;]...</screen>
-
-    <para>
-      The parameters are as follows:
-    </para>
-
-    <variablelist>
-
-      <varlistentry>
-        <term>
-          <computeroutput>--filename &lt;filename&gt;</computeroutput>
-        </term>
-
-        <listitem>
-          <para>
-            Specifies a file name &lt;filename&gt; as an absolute path
-            on the host file system. Mandatory.
-          </para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>
-          <computeroutput>--size &lt;megabytes&gt;</computeroutput>
-        </term>
-
-        <listitem>
-          <para>
-            Specifies the image capacity, in 1 MB units. Optional.
-          </para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>
-          <computeroutput>--diffparent
-          &lt;uuid&gt;|&lt;filename&gt;</computeroutput>
-        </term>
-
-        <listitem>
-          <para>
-            Specifies the differencing image parent, either as a UUID or
-            by the absolute pathname of the file on the host file
-            system. Useful for sharing a base box disk image among
-            several VMs.
-          </para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>
-          <computeroutput>--format VDI|VMDK|VHD</computeroutput>
-        </term>
-
-        <listitem>
-          <para>
-            Specifies the file format for the output file. Available
-            options are VDI, VMDK, VHD. The default format is VDI.
-            Optional.
-          </para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>
-          <computeroutput>--variant</computeroutput>
-        </term>
-
-        <listitem>
-          <para>
-            Specifies any required file format variants for the output
-            file. This is a comma-separated list of variant flags.
-            Options are Standard,Fixed,Split2G,Stream,ESX,RawDisk. Not all
-            combinations are supported, and specifying mutually
-            incompatible flags results in an error message. Optional.
-          </para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>
-          <computeroutput>--property &lt;name&gt;=&lt;value&gt;</computeroutput>
-        </term>
-
-        <listitem>
-          <para>
-            Specifies any required file format dependent parameters in
-            <literal>key=value</literal> form. Optional.
-          </para>
-        </listitem>
-      </varlistentry>
-
-      <varlistentry>
-        <term>
-          <computeroutput>--property-file &lt;name&gt;=&lt;/path/to/file/with/value&gt;</computeroutput>
-        </term>
-
-        <listitem>
-          <para>
-            Specifies any required file format dependent parameters in
-            <literal>key=file/with/value</literal> form. The value is
-            taken from the file. Optional.
-          </para>
-        </listitem>
-      </varlistentry>
-
-    </variablelist>
-
-    <note>
-      <para>
-        For compatibility with earlier versions of &product-name;, the
-        <command>createvdi</command> and <command>createhd</command>
-        commands are also supported and mapped internally to the
-        <command>createmedium</command> command.
-      </para>
-    </note>
-
-  </sect1>
+  <xi:include href="user_man_VBoxManage-createmedium.xml"   xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
 
   <sect1 id="vboxmanage-modifymedium">

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

@@ -200 +200 @@
     { "mediumproperty",     USAGE_MEDIUMPROPERTY,   VBMG_CMD_TODO, handleMediumProperty,       0 },
     { "hdproperty",         USAGE_MEDIUMPROPERTY,   VBMG_CMD_TODO, handleMediumProperty,       0 }, /* backward compatibility */
-    { "createmedium",       USAGE_CREATEMEDIUM,     VBMG_CMD_TODO, handleCreateMedium,         0 },
-    { "createhd",           USAGE_CREATEMEDIUM,     VBMG_CMD_TODO, handleCreateMedium,         0 }, /* backward compatibility */
-    { "createvdi",          USAGE_CREATEMEDIUM,     VBMG_CMD_TODO, handleCreateMedium,         0 }, /* backward compatibility */
+    { "createmedium",       USAGE_S_NEWCMD, HELP_CMD_CREATEMEDIUM, handleCreateMedium,         0 },
+    { "createhd",           USAGE_S_NEWCMD, HELP_CMD_CREATEMEDIUM, handleCreateMedium,         0 }, /* backward compatibility */
+    { "createvdi",          USAGE_S_NEWCMD, HELP_CMD_CREATEMEDIUM, handleCreateMedium,         0 }, /* backward compatibility */
     { "modifymedium",       USAGE_MODIFYMEDIUM,     VBMG_CMD_TODO, handleModifyMedium,         0 },
     { "modifyhd",           USAGE_MODIFYMEDIUM,     VBMG_CMD_TODO, handleModifyMedium,         0 }, /* backward compatibility */

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

@@ -98 +98 @@
 {
     USAGE_INVALID = 0,
-    USAGE_CREATEMEDIUM,
     USAGE_MODIFYMEDIUM,
     USAGE_CLONEMEDIUM,

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

@@ -328 +328 @@
             case 'H':   // disk
                 if (cmd != CMD_NONE)
-                    return errorSyntax(USAGE_CREATEMEDIUM, 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;
@@ -334 +334 @@
             case 'D':   // DVD
                 if (cmd != CMD_NONE)
-                    return errorSyntax(USAGE_CREATEMEDIUM, 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;
@@ -340 +340 @@
             case 'L':   // floppy
                 if (cmd != CMD_NONE)
-                    return errorSyntax(USAGE_CREATEMEDIUM, 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;
@@ -437 +437 @@
 
             case VINF_GETOPT_NOT_OPTION:
-                return errorSyntax(USAGE_CREATEMEDIUM, Disk::tr("Invalid parameter '%s'"), ValueUnion.psz);
+                return errorSyntax(Disk::tr("Invalid parameter '%s'"), ValueUnion.psz);
 
             default:
@@ -443 +443 @@
                 {
                     if (RT_C_IS_PRINT(c))
-                        return errorSyntax(USAGE_CREATEMEDIUM, Disk::tr("Invalid option -%c"), c);
+                        return errorSyntax(Disk::tr("Invalid option -%c"), c);
                     else
-                        return errorSyntax(USAGE_CREATEMEDIUM, Disk::tr("Invalid option case %i"), c);
+                        return errorSyntax(Disk::tr("Invalid option case %i"), c);
                 }
                 else if (c == VERR_GETOPT_UNKNOWN_OPTION)
-                    return errorSyntax(USAGE_CREATEMEDIUM, Disk::tr("unknown option: %s\n"), ValueUnion.psz);
+                    return errorSyntax(Disk::tr("unknown option: %s\n"), ValueUnion.psz);
                 else if (ValueUnion.pDef)
-                    return errorSyntax(USAGE_CREATEMEDIUM, "%s: %Rrs", ValueUnion.pDef->pszLong, c);
+                    return errorSyntax("%s: %Rrs", ValueUnion.pDef->pszLong, c);
                 else
-                    return errorSyntax(USAGE_CREATEMEDIUM, Disk::tr("error: %Rrs"), c);
+                    return errorSyntax(Disk::tr("error: %Rrs"), c);
         }
     }
@@ -463 +463 @@
     {
         if (!filename || !*filename)
-            return errorSyntax(USAGE_CREATEMEDIUM, Disk::tr("Parameters --filename is required"));
+            return errorSyntax(Disk::tr("Parameters --filename is required"));
         if ((enmMediumVariant & MediumVariant_VmdkRawDisk) == 0 && size == 0)
-            return errorSyntax(USAGE_CREATEMEDIUM, Disk::tr("Parameters --size is required"));
+            return errorSyntax(Disk::tr("Parameters --size is required"));
         if (!format || !*format)
         {
@@ -483 +483 @@
         if (   !filename
             || !*filename)
-            return errorSyntax(USAGE_CREATEMEDIUM, Disk::tr("Parameters --filename is required"));
+            return errorSyntax(Disk::tr("Parameters --filename is required"));
         size = 0;
         if (cmd != CMD_DISK)
-            return errorSyntax(USAGE_CREATEMEDIUM, Disk::tr("Creating a differencing medium is only supported for hard disks"));
+            return errorSyntax(Disk::tr("Creating a differencing medium is only supported for hard disks"));
         enmMediumVariant = MediumVariant_Diff;
         if (!format || !*format)

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

@@ -625 +625 @@
                      "\n", SEP);
 
-    if (enmCommand == USAGE_CREATEMEDIUM || enmCommand == USAGE_S_ALL)
-        RTStrmPrintf(pStrm,
-                           "%s createmedium %s    [disk|dvd|floppy] --filename <filename>\n"
-                     "                            [--size <megabytes>|--sizebyte <bytes>]\n"
-                     "                            [--diffparent <uuid>|<filename>]\n"
-                     "                            [--format VDI|VMDK|VHD] (default: VDI)]\n"
-                     "                            [--variant Standard,Fixed,Split2G,Stream,ESX,\n"
-                     "                                       Formatted,RawDisk]\n"
-                     "                            [[--property <name>=<value>] --property <name>=<value>\n"
-                     "                              --property-file <name>=</path/to/file/with/value>]...\n"
-                     "\n", SEP);
-
     if (enmCommand == USAGE_MODIFYMEDIUM || enmCommand == USAGE_S_ALL)
         RTStrmPrintf(pStrm,