VirtualBox

Changeset 94290 in vbox


Ignore:
Timestamp:
Mar 17, 2022 12:47:49 PM (3 years ago)
Author:
vboxsync
Message:

doc/manual,FE/VBoxManage: Make use of the general options from the refentry XML files when printing the help text and some more cleanups getting rid of all the legacy help code, bugref:9186

Location:
trunk
Files:
7 edited
2 moved

Legend:

Unmodified
Added
Removed

  • trunk/doc/manual/Config.kmk

    r94218 r94290  
    3636## List of refentry files (manpages).
    3737VBOX_MANUAL_XML_REFENTRY_FILES := \
    38         man_VBoxManage.xml \
     38        man_VBoxManage-common.xml \
    3939        man_VBoxManage-list.xml \
    4040        man_VBoxManage-showvminfo.xml \

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

    r94268 r94290  
    233233    </para>
    234234
    235     <xi:include href="overview_man_VBoxManage.xml"                xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
     235    <xi:include href="overview_man_VBoxManage-common.xml"         xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
    236236
    237237    <xi:include href="overview_man_VBoxManage-list.xml"           xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
    … …  
    400400
    401401  <!-- TODO: Check the overview/common man page -->
    402   <xi:include href="user_man_VBoxManage.xml"                xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
     402  <xi:include href="user_man_VBoxManage-common.xml"         xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />
    403403
    404404  <xi:include href="user_man_VBoxManage-list.xml"           xpointer="element(/1)" xmlns:xi="http://www.w3.org/2001/XInclude" />

  • trunk/src/VBox/Frontends/VBoxManage/Makefile.kmk

    r94234 r94290  
    193193$(call KB_FN_DO_PASS0_ON_TARGET,VBoxManage)
    194194
    195 ## @todo r=klaus the VBoxManage manpage handling currently cannot deal with
    196 # man_VBoxManage.xml and that's not just removing the - in the patterns. The
    197 # common options (and the included overview of the command) need to be handled
    198 # specially to be useful in VBoxManage.
    199 
    200195VBoxManage_CLEAN += \
    201196        $(VBOX_XML_CATALOG) \

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

    r94240 r94290  
    134134
    135135
     136/** @name Syntax diagram category, i.e. the command.
     137 * @{ */
     138typedef enum
     139{
     140    USAGE_INVALID = 0,
     141    USAGE_I_LOADSYMS,
     142    USAGE_I_LOADMAP,
     143    USAGE_I_SETHDUUID,
     144    USAGE_I_LISTPARTITIONS,
     145    USAGE_I_CREATERAWVMDK,
     146    USAGE_I_MODINSTALL,
     147    USAGE_I_MODUNINSTALL,
     148    USAGE_I_RENAMEVMDK,
     149    USAGE_I_CONVERTTORAW,
     150    USAGE_I_CONVERTHD,
     151    USAGE_I_DUMPHDINFO,
     152    USAGE_I_DEBUGLOG,
     153    USAGE_I_SETHDPARENTUUID,
     154    USAGE_I_PASSWORDHASH,
     155    USAGE_I_GUESTSTATS,
     156    USAGE_I_REPAIRHD,
     157    USAGE_I_ALL
     158} USAGECATEGORY;
     159/** @} */
     160
     161
    136162/**
    137163 * Print the usage info.
    … …  
    140166{
    141167    Assert(enmCommand != USAGE_INVALID);
    142     Assert(enmCommand != USAGE_S_NEWCMD);
    143     Assert(enmCommand != USAGE_S_DUMPOPTS);
    144168    RTStrmPrintf(pStrm,
    145169        Internal::tr(
    … …  
    153177         "         incompatible ways without warning.\n"),
    154178
    155         (enmCommand == USAGE_I_LOADMAP || enmCommand == USAGE_S_ALL)
     179        (enmCommand == USAGE_I_LOADMAP || enmCommand == USAGE_I_ALL)
    156180        ? Internal::tr(
    157181           "  loadmap <vmname|uuid> <symfile> <address> [module] [subtrahend] [segment]\n"
    … …  
    160184           "\n")
    161185        : "",
    162         (enmCommand == USAGE_I_LOADSYMS || enmCommand == USAGE_S_ALL)
     186        (enmCommand == USAGE_I_LOADSYMS || enmCommand == USAGE_I_ALL)
    163187        ? Internal::tr(
    164188           "  loadsyms <vmname|uuid> <symfile> [delta] [module] [module address]\n"
    … …  
    167191           "\n")
    168192        : "",
    169         (enmCommand == USAGE_I_SETHDUUID || enmCommand == USAGE_S_ALL)
     193        (enmCommand == USAGE_I_SETHDUUID || enmCommand == USAGE_I_ALL)
    170194        ? Internal::tr(
    171195           "  sethduuid <filepath> [<uuid>]\n"
    … …  
    174198           "\n")
    175199        : "",
    176         (enmCommand == USAGE_I_SETHDPARENTUUID || enmCommand == USAGE_S_ALL)
     200        (enmCommand == USAGE_I_SETHDPARENTUUID || enmCommand == USAGE_I_ALL)
    177201        ? Internal::tr(
    178202           "  sethdparentuuid <filepath> <uuid>\n"
    … …  
    180204           "\n")
    181205        : "",
    182         (enmCommand == USAGE_I_DUMPHDINFO || enmCommand == USAGE_S_ALL)
     206        (enmCommand == USAGE_I_DUMPHDINFO || enmCommand == USAGE_I_ALL)
    183207        ? Internal::tr(
    184208           "  dumphdinfo <filepath>\n"
    … …  
    186210           "\n")
    187211        : "",
    188         (enmCommand == USAGE_I_LISTPARTITIONS || enmCommand == USAGE_S_ALL)
     212        (enmCommand == USAGE_I_LISTPARTITIONS || enmCommand == USAGE_I_ALL)
    189213        ? Internal::tr(
    190214           "  listpartitions -rawdisk <diskname>\n"
    … …  
    192216           "\n")
    193217        : "",
    194         (enmCommand == USAGE_I_CREATERAWVMDK || enmCommand == USAGE_S_ALL)
     218        (enmCommand == USAGE_I_CREATERAWVMDK || enmCommand == USAGE_I_ALL)
    195219        ? Internal::tr(
    196220           "  createrawvmdk -filename <filename> -rawdisk <diskname>\n"
    … …  
    211235           "\n")
    212236        : "",
    213         (enmCommand == USAGE_I_RENAMEVMDK || enmCommand == USAGE_S_ALL)
     237        (enmCommand == USAGE_I_RENAMEVMDK || enmCommand == USAGE_I_ALL)
    214238        ? Internal::tr(
    215239           "  renamevmdk -from <filename> -to <filename>\n"
    … …  
    217241           "\n")
    218242        : "",
    219         (enmCommand == USAGE_I_CONVERTTORAW || enmCommand == USAGE_S_ALL)
     243        (enmCommand == USAGE_I_CONVERTTORAW || enmCommand == USAGE_I_ALL)
    220244#ifdef ENABLE_CONVERT_RAW_TO_STDOUT
    221245        ? Internal::tr(
    … …  
    232256#endif
    233257        : "",
    234         (enmCommand == USAGE_I_CONVERTHD || enmCommand == USAGE_S_ALL)
     258        (enmCommand == USAGE_I_CONVERTHD || enmCommand == USAGE_I_ALL)
    235259        ? Internal::tr(
    236260           "  converthd [-srcformat VDI|VMDK|VHD|RAW]\n"
    … …  
    240264           "\n")
    241265        : "",
    242         (enmCommand == USAGE_I_REPAIRHD || enmCommand == USAGE_S_ALL)
     266        (enmCommand == USAGE_I_REPAIRHD || enmCommand == USAGE_I_ALL)
    243267        ? Internal::tr(
    244268           "  repairhd [-dry-run]\n"
    … …  
    249273        : "",
    250274#ifdef RT_OS_WINDOWS
    251         (enmCommand == USAGE_I_MODINSTALL || enmCommand == USAGE_S_ALL)
     275        (enmCommand == USAGE_I_MODINSTALL || enmCommand == USAGE_I_ALL)
    252276        ? Internal::tr(
    253277           "  modinstall\n"
    … …  
    255279           "\n")
    256280        : "",
    257         (enmCommand == USAGE_I_MODUNINSTALL || enmCommand == USAGE_S_ALL)
     281        (enmCommand == USAGE_I_MODUNINSTALL || enmCommand == USAGE_I_ALL)
    258282        ? Internal::tr(
    259283           "  moduninstall\n"
    … …  
    265289        "",
    266290#endif
    267         (enmCommand == USAGE_I_DEBUGLOG || enmCommand == USAGE_S_ALL)
     291        (enmCommand == USAGE_I_DEBUGLOG || enmCommand == USAGE_I_ALL)
    268292        ? Internal::tr(
    269293           "  debuglog <vmname|uuid> [--enable|--disable] [--flags todo]\n"
    … …  
    272296           "\n")
    273297        : "",
    274         (enmCommand == USAGE_I_PASSWORDHASH || enmCommand == USAGE_S_ALL)
     298        (enmCommand == USAGE_I_PASSWORDHASH || enmCommand == USAGE_I_ALL)
    275299        ? Internal::tr(
    276300           "  passwordhash <password>\n"
    … …  
    278302           "\n")
    279303        : "",
    280         (enmCommand == USAGE_I_GUESTSTATS || enmCommand == USAGE_S_ALL)
     304        (enmCommand == USAGE_I_GUESTSTATS || enmCommand == USAGE_I_ALL)
    281305        ? Internal::tr(
    282306           "  gueststats <vmname|uuid> [--interval <seconds>]\n"
    … …  
    356380        return RTMsgErrorExit(RTEXITCODE_SYNTAX, "%s: %Rrs", pValueUnion->pDef->pszLong, rc);
    357381    return RTMsgErrorExit(RTEXITCODE_SYNTAX, "%Rrs", rc);
     382}
     383
     384
     385/**
     386 * Externally visible wrapper around printUsageInternal() to dump the
     387 * complete usage text.
     388 *
     389 * @returns nothing.
     390 * @param   pStrm           The stream to dump the usage text to.
     391 */
     392DECLHIDDEN(void) printUsageInternalCmds(PRTSTREAM pStrm)
     393{
     394    printUsageInternal(USAGE_I_ALL, pStrm);
    358395}
    359396
    … …  
    26552692    /* at least a command is required */
    26562693    if (a->argc < 1)
    2657         return errorSyntaxInternal(USAGE_S_ALL, Internal::tr("Command missing"));
     2694        return errorSyntaxInternal(USAGE_I_ALL, Internal::tr("Command missing"));
    26582695
    26592696    /*
    … …  
    26952732
    26962733    /* default: */
    2697     return errorSyntaxInternal(USAGE_S_ALL, Internal::tr("Invalid command '%s'"), a->argv[0]);
    2698 }
     2734    return errorSyntaxInternal(USAGE_I_ALL, Internal::tr("Invalid command '%s'"), a->argv[0]);
     2735}

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

    r94240 r94290  
    615615            {
    616616                showLogo(g_pStdOut);
    617                 printUsage(USAGE_S_ALL, RTMSGREFENTRYSTR_SCOPE_GLOBAL, g_pStdOut);
     617                printUsage(g_pStdOut);
    618618                return 0;
    619619            }
    … …  
    646646            /* Special option to dump really all commands,
    647647             * even the ones not understood on this platform. */
    648             printUsage(USAGE_S_DUMPOPTS, RTMSGREFENTRYSTR_SCOPE_GLOBAL, g_pStdOut);
     648            printUsage(g_pStdOut);
    649649            return 0;
    650650        }
    … …  
    740740    {
    741741        if (pCmd->enmCmdHelp == VBMG_CMD_INTERNAL)
    742             printUsage(USAGE_INVALID, RTMSGREFENTRYSTR_SCOPE_GLOBAL, g_pStdOut);
     742            printUsageInternalCmds(g_pStdOut);
    743743        else if (fShowHelp)
    744744            printHelp(g_pStdOut);

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

    r94240 r94290  
    8989
    9090
    91 /** @name Syntax diagram category, i.e. the command.
    92  * @{ */
    93 typedef enum
    94 {
    95     USAGE_INVALID = 0,
    96     USAGE_I_LOADSYMS,
    97     USAGE_I_LOADMAP,
    98     USAGE_I_SETHDUUID,
    99     USAGE_I_LISTPARTITIONS,
    100     USAGE_I_CREATERAWVMDK,
    101     USAGE_I_MODINSTALL,
    102     USAGE_I_MODUNINSTALL,
    103     USAGE_I_RENAMEVMDK,
    104     USAGE_I_CONVERTTORAW,
    105     USAGE_I_CONVERTHD,
    106     USAGE_I_DUMPHDINFO,
    107     USAGE_I_DEBUGLOG,
    108     USAGE_I_SETHDPARENTUUID,
    109     USAGE_I_PASSWORDHASH,
    110     USAGE_I_GUESTSTATS,
    111     USAGE_I_REPAIRHD,
    112     /* Insert new entries before this line, but only if it is not an option
    113      * to go for the new style command and help handling (see e.g. extpack,
    114      * unattend or mediumio. */
    115     USAGE_S_NEWCMD = 10000, /**< new style command with no old help support */
    116     USAGE_S_ALL,
    117     USAGE_S_DUMPOPTS
    118 } USAGECATEGORY;
    119 /** @} */
    120 
    121 
    12291/** command handler argument */
    12392struct HandlerArg
    … …  
    158127
    159128/* VBoxManageHelp.cpp */
    160 /* Legacy help infrastructure, to be replaced by new one using generated help. */
    161 void printUsage(USAGECATEGORY enmCommand, uint64_t fSubcommandScope, PRTSTREAM pStrm);
    162 
    163129void        setCurrentCommand(enum HELP_CMD_VBOXMANAGE enmCommand);
    164130void        setCurrentSubcommand(uint64_t fCurSubcommandScope);
    … …  
    186152void showLogo(PRTSTREAM pStrm);
    187153
     154/* VBoxInternalManage.cpp */
     155DECLHIDDEN(void) printUsageInternalCmds(PRTSTREAM pStrm);
    188156RTEXITCODE handleInternalCommands(HandlerArg *a);
    189157

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

    r94240 r94290  
    4949DECLARE_TRANSLATION_CONTEXT(Help);
    5050
    51 static enum HELP_CMD_VBOXMANAGE    g_enmCurCommand = HELP_CMD_VBOXMANAGE_INVALID;
     51static enum HELP_CMD_VBOXMANAGE    g_enmCurCommand = HELP_CMD_COMMON;
    5252/** The scope mask for the current subcommand. */
    5353static uint64_t                    g_fCurSubcommandScope = RTMSGREFENTRYSTR_SCOPE_GLOBAL;
    … …  
    6262void setCurrentCommand(enum HELP_CMD_VBOXMANAGE enmCommand)
    6363{
    64     Assert(g_enmCurCommand == HELP_CMD_VBOXMANAGE_INVALID);
     64    Assert(g_enmCurCommand == HELP_CMD_COMMON);
    6565    g_enmCurCommand       = enmCommand;
    6666    g_fCurSubcommandScope = RTMSGREFENTRYSTR_SCOPE_GLOBAL;
    … …  
    128128        {
    129129            PCRTMSGREFENTRY pHelp = apHelpLangEntries[k]->papHelpEntries[i];
    130             if (pHelp->idInternal == (int64_t)enmCommand)
     130            if (   pHelp->idInternal == (int64_t)enmCommand
     131                || enmCommand == HELP_CMD_COMMON)
    131132            {
    132133                cFound++;
    … …  
    194195
    195196            if (   pHelp->idInternal == (int64_t)enmCommand
    196                 || enmCommand == HELP_CMD_VBOXMANAGE_INVALID)
     197                || enmCommand == HELP_CMD_COMMON)
    197198            {
    198199                cFound++;
    … …  
    503504    }
    504505}
    505 
    506 
    507 
    508 
    509 void printUsage(USAGECATEGORY enmCommand, uint64_t fSubcommandScope, PRTSTREAM pStrm)
    510 {
    511     RT_NOREF(fSubcommandScope);
    512 
    513     Assert(enmCommand != USAGE_INVALID);
    514     Assert(enmCommand != USAGE_S_NEWCMD);
    515 
    516     if (enmCommand == USAGE_S_DUMPOPTS)
    517         enmCommand = USAGE_S_ALL;
    518 
    519     RTStrmPrintf(pStrm,
    520                  Help::tr("Usage:\n"
    521                           "\n"));
    522 
    523     if (enmCommand == USAGE_S_ALL)
    524         RTStrmPrintf(pStrm,
    525                      "  VBoxManage [<general option>] <command>\n"
    526                      "\n"
    527                      "\n"
    528                      "General Options:\n"
    529                      "\n"
    530                      "  [-V|--version]            print version number and exit\n"
    531                      "  [--dump-build-type]       print build type and exit\n"
    532                      "  [-q|--nologo]             suppress the logo\n"
    533                      "  [--settingspw <pw>]       provide the settings password\n"
    534                      "  [--settingspwfile <file>] provide a file containing the settings password\n"
    535                      "  [@<response-file>]        load arguments from the given response file (bourne style)\n"
    536                      "\n"
    537                      "\n"
    538                      "Commands:\n"
    539                      "\n");
    540 
    541     if (enmCommand == USAGE_S_ALL)
    542     {
    543         uint32_t            cPendingBlankLines = 0;
    544         PCHELP_LANG_ENTRY_T pHelpLangEntry     = ASMAtomicUoReadPtrT(&g_pHelpLangEntry, PCHELP_LANG_ENTRY_T);
    545         uint32_t const      cHelpEntries       = *pHelpLangEntry->pcHelpEntries;
    546         for (uint32_t i = 0; i < cHelpEntries; i++)
    547         {
    548             PCRTMSGREFENTRY pHelp = pHelpLangEntry->papHelpEntries[i];
    549 
    550             while (cPendingBlankLines-- > 0)
    551                 RTStrmPutCh(pStrm, '\n');
    552 
    553             char szFirstChar[8];
    554             RTStrmPrintf(pStrm, " %s%s:\n", szFirstChar, captialize(pHelp->pszBrief, szFirstChar));
    555 
    556             cPendingBlankLines = 0;
    557             RTMsgRefEntryPrintStringTable(pStrm, &pHelp->Synopsis, RTMSGREFENTRYSTR_SCOPE_GLOBAL,
    558                                           &cPendingBlankLines, NULL /*pcLinesWritten*/);
    559             cPendingBlankLines = RT_MAX(cPendingBlankLines, 1);
    560         }
    561     }
    562 }
Note: See TracChangeset for help on using the changeset viewer.

© 2024 Oracle Support Privacy / Do Not Sell My Info Terms of Use Trademark Policy Automated Access Etiquette