Index: /trunk/doc/manual/Makefile.kmk =================================================================== --- /trunk/doc/manual/Makefile.kmk (revision 56532) +++ /trunk/doc/manual/Makefile.kmk (revision 56533) @@ -101,9 +101,11 @@ # xsltproc with the catalog trick if applicable. ifdef VBOX_XML_CATALOG - VBOX_XSLTPROC_WITH_CAT = $(REDIRECT) -E "XML_CATALOG_FILES=$(VBOX_XML_CATALOG)" -- $(VBOX_XSLTPROC) - VBOX_XMLLINT_WITH_CAT = $(REDIRECT) -E "XML_CATALOG_FILES=$(VBOX_XML_CATALOG)" -- $(VBOX_XMLLINT) + VBOX_XSLTPROC_WITH_CAT = $(REDIRECT) -E "XML_CATALOG_FILES=$(VBOX_XML_CATALOG)" -- \ + $(VBOX_XSLTPROC) --nonet --xinclude $(VBOX_XSLTPROC_OPTS) + VBOX_XMLLINT_WITH_CAT = $(REDIRECT) -E "XML_CATALOG_FILES=$(VBOX_XML_CATALOG)" -- \ + $(VBOX_XMLLINT) --nonet --xinclude --noout $(VBOX_XMLLINT_OPTS) else - VBOX_XSLTPROC_WITH_CAT = $(VBOX_XSLTPROC) - VBOX_XMLLINT_WITH_CAT = $(VBOX_XMLLINT) + VBOX_XSLTPROC_WITH_CAT = $(VBOX_XSLTPROC) --nonet --xinclude $(VBOX_XSLTPROC_OPTS) + VBOX_XMLLINT_WITH_CAT = $(VBOX_XMLLINT) --nonet --xinclude --noout $(VBOX_XMLLINT_OPTS) endif @@ -165,6 +167,6 @@ ## List of refentry files (manpages). VBOX_MANUAL_XML_REFENTRY_FILES = \ - man_VBoxManage_debugvm.xml \ - man_VBoxManage_extpack.xml + man_VBoxManage-debugvm.xml \ + man_VBoxManage-extpack.xml @@ -283,4 +285,6 @@ $(VBOX_MANUAL_XML_FILES_INCL_CHANGELOG) \ $(VBOX_MANUAL_XML_REFENTRY_FILES) \ + $(addprefix user_,$(VBOX_MANUAL_XML_REFENTRY_FILES)) \ + $(patsubst man_%,%.1,$(basename $(VBOX_MANUAL_XML_REFENTRY_FILES))) \ $(VBOX_MANUAL_LATEX_FILES_TARGET) \ $(VBOX_MANUAL_PNG_FILES_$(lang)) \ @@ -466,5 +470,5 @@ $(foreach lang,$(VBOX_MANUAL_LANGUAGES), \ $(eval $$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/user_VBoxManage.xml: $(VBOX_PATH_MANUAL_SRC)/$(lang)/user_VBoxManage.xml \ - $$(addprefix $$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/,$$(filter man_VBoxManage%,$$(VBOX_MANUAL_XML_REFENTRY_FILES))) \ + $$(addprefix $$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/user_,$$(filter man_VBoxManage%,$$(VBOX_MANUAL_XML_REFENTRY_FILES))) \ $$(addprefix $$(VBOX_PATH_MANUAL_OUTBASE)/overview_,$$(filter man_VBoxManage%,$$(VBOX_MANUAL_XML_REFENTRY_FILES))) \ $(VBOX_PATH_MANUAL_OUTBASE)/user_VBoxManage_CommandsOverview.xml )) @@ -474,5 +478,5 @@ $(VBOX_PATH_MANUAL_OUTBASE)/% : \ $(VBOX_PATH_MANUAL_SRC)/% \ - $$(addprefix $$(@D)/,$$(filter man_VBoxManage%,$$(VBOX_MANUAL_XML_REFENTRY_FILES))) \ + $$(addprefix $$(@D)/user_,$$(filter man_VBoxManage%,$$(VBOX_MANUAL_XML_REFENTRY_FILES))) \ $$(addprefix $$(@D)/overview_,$$(filter man_VBoxManage%,$$(VBOX_MANUAL_XML_REFENTRY_FILES))) \ $(VBOX_PATH_MANUAL_OUTBASE)/user_VBoxManage_CommandsOverview.xml \ @@ -510,15 +514,21 @@ $(QUIET)$(RM) -f $@.dumpopts $@.screen - +## # Morph man pages into manual sections. -$(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/,$(VBOX_MANUAL_XML_REFENTRY_FILES))): \ - $(VBOX_PATH_MANUAL_OUTBASE)/% : $(VBOX_PATH_MANUAL_SRC)/% \ - $(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manual-sect1.xsl \ - $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) \ - $(VBOX_VERSION_STAMP) | $$(dir $$@) - $(call MSG_GENERATE,,$@,$<) - $(QUIET)$(RM) -f $@ - $(QUIET)$(VBOX_XSLTPROC_WITH_CAT) --xinclude --nonet --output $@ \ - $(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manual-sect1.xsl $< +# $(evalcall2 def_vbox_refentry_to_user_sect1) +# @param 1 The XSLT source file (relative to Makefile dir). +# @param 2 Optional output subdirectory. +define def_vbox_refentry_to_user_sect1 +$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/user_$(2): \ + $$(VBOX_PATH_MANUAL_SRC)/$(1)/$(2) \ + $$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manual-sect1.xsl \ + $$(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) \ + $$(VBOX_VERSION_STAMP) | $$(dir $$@) + $$(call MSG_GENERATE,,$$@,$$<) + $$(QUIET)$$(RM) -f "$$@" + $$(QUIET)$$(VBOX_XSLTPROC_WITH_CAT) --output $$@ $$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manual-sect1.xsl $$< +endef +$(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(foreach file,$(VBOX_MANUAL_XML_REFENTRY_FILES) \ +, $(evalcall2 def_vbox_refentry_to_user_sect1,$(lang),$(file)))) @@ -537,5 +547,5 @@ | $$(dir $$@) $(call MSG_GENERATE,,$@,$(filter %.xml,$^)) - $(QUIET)$(VBOX_XSLTPROC_WITH_CAT) --xinclude --nonet --output "$@" $< $(filter %.xml,$^) + $(QUIET)$(VBOX_XSLTPROC_WITH_CAT) --output "$@" $< $(filter %.xml,$^) $(VBOX_PATH_MANUAL_OUTBASE)/user_VBoxManage_CommandsOverview.xml: $(MAKEFILE_CURRENT) | $$(dir $$@) @@ -653,5 +663,5 @@ # pass current language to xsltproc in TARGETLANG variable (extract it from the # current directory, should become "de_DE" or the like) - $(QUIET)$(VBOX_XSLTPROC_WITH_CAT) $(XSLTPROC_VERBOSE) --xinclude --nonet --stringparam TARGETLANG $(notdir $(@D)) \ + $(QUIET)$(VBOX_XSLTPROC_WITH_CAT) --stringparam TARGETLANG $(notdir $(@D)) \ -o $@.tmp $(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl $< # for pretty quotes, replace " with `` or '' depending on whether it's at the start of a word; @@ -682,6 +692,5 @@ $$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK) $$(MAKEFILE_CURRENT) | $$$$(dir $$$$@) $$(call MSG_L1,Validating $$<) - $$(QUIET)$$(VBOX_XMLLINT_WITH_CAT) $$(VBOX_XMLLINT_OPTS) --dtdvalid $$(VBOX_PATH_DOCBOOK_DTD)/docbookx.dtd \ - --xinclude --noout $$< + $$(QUIET)$$(VBOX_XMLLINT_WITH_CAT) --dtdvalid $$(VBOX_PATH_DOCBOOK_DTD)/docbookx.dtd $$< $$(QUIET)$$(APPEND) -t "$$@" "done" endef @@ -718,5 +727,5 @@ $(QUIET)$(RM) -f $(addprefix $(@D/),$(VBOX_SDKREF_LATEX_FILES_TARGET)) # generate TeX source from processed docbook and store it in SDKRef.tex.tmp - $(QUIET)$(VBOX_XSLTPROC_WITH_CAT) $(XSLTPROC_VERBOSE) --xinclude --nonet --stringparam TARGETLANG en_US \ + $(QUIET)$(VBOX_XSLTPROC_WITH_CAT) --stringparam TARGETLANG en_US \ -o $@.tmp $(VBOX_PATH_MANUAL_SRC)/docbook2latex.xsl $< # for pretty quotes, replace " with `` or '' depending on whether it's at the start of a word; @@ -734,6 +743,5 @@ $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(MAKEFILE_CURRENT) $(call MSG_L1,Validating $(filter %.xml,$^)) - $(QUIET)$(VBOX_XMLLINT_WITH_CAT) $(VBOX_XMLLINT_OPTS) --dtdvalid $(VBOX_PATH_DOCBOOK_DTD)/docbookx.dtd \ - --xinclude --noout $(filter %.xml,$^) + $(QUIET)$(VBOX_XMLLINT_WITH_CAT) --dtdvalid $(VBOX_PATH_DOCBOOK_DTD)/docbookx.dtd $(filter %.xml,$^) @@ -799,5 +807,5 @@ $(QUIET)$(RM) -f $@ $(QUIET)$(MKDIR) -p $(@D) - $(QUIET)$(VBOX_XSLTPROC_WITH_CAT) --xinclude --nonet --output $(@D)/ \ + $(QUIET)$(VBOX_XSLTPROC_WITH_CAT) --output $(@D)/ \ --stringparam htmlhelp.chm \ $(subst /,\\,$(@D)/../VirtualBox.chm) \ @@ -865,5 +873,5 @@ | $$(dir $$@) $(call MSG_L1,xsltproc $<) - $(QUIET)$(VBOX_XSLTPROC_WITH_CAT) --xinclude --nonet $(XSLTPROC_VERBOSE) \ + $(QUIET)$(VBOX_XSLTPROC_WITH_CAT) \ --output $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-single/UserManual.html \ $(VBOX_PATH_MANUAL_OUTBASE)/en_US/docbook-html-one-page-formatcfg.xsl \ @@ -878,5 +886,5 @@ | $$(dir $$@) $(call MSG_L1,xsltproc $<) - $(QUIET)$(VBOX_XSLTPROC_WITH_CAT) --xinclude --nonet $(XSLTPROC_VERBOSE) \ + $(QUIET)$(VBOX_XSLTPROC_WITH_CAT) \ --output $(VBOX_PATH_MANUAL_OUTBASE)/en_US/html-chunks/index.html \ --stringparam chunk.section.depth 0 \ @@ -935,25 +943,45 @@ # -# VBoxManage man pages. -# -$(evalcall2 def_vbox_replace_paths_in_xslt,docbook-refentry-to-man.xsl,) - -man-experiment: \ - $(VBOX_PATH_MANUAL_SRC)/en_US/man_VBoxManage_extpack.xml \ - $(VBOX_PATH_MANUAL_OUTBASE)/docbook-refentry-to-man.xsl \ - $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) - $(VBOX_XSLTPROC_WITH_CAT) --xinclude --nonet --output z:/tmp/vboxmanage-extpack.1 \ - $(VBOX_PATH_MANUAL_OUTBASE)/docbook-refentry-to-man.xsl \ - $(VBOX_PATH_MANUAL_SRC)/en_US/man_VBoxManage_extpack.xml - -$(evalcall2 def_vbox_replace_paths_in_xslt,docbook-refentry-to-C-help.xsl,) -$(evalcall2 def_vbox_replace_paths_in_xslt,docbook-refentry-to-H-help.xsl,) - -# validate man page XML source -validateman: $(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_MANUAL_XML_REFENTRY_FILES)) \ - $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(MAKEFILE_CURRENT) - $(call MSG_L1,Validating $(filter %.xml,$^)) - $(QUIET)$(VBOX_XMLLINT_WITH_CAT) $(VBOX_XMLLINT_OPTS) --dtdvalid $(VBOX_PATH_DOCBOOK_DTD)/docbookx.dtd \ - --noout $(filter %.xml,$^) +# VBoxManage man pages (parts also required by VBoxManage build-in help). +# +$(evalcall2 def_vbox_replace_paths_in_xslt,docbook-refentry-to-manpage.xsl,) + +## +# Emits rules for preprocessing refentry sources (applying remarks element), +# and for producing the actual man pages. +# $(evalcall2 def_vbox_refentry_to_manpage) +# @param 1 The language +# @param 2 The file name (no path). +define def_vbox_refentry_to_manpage +$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/$(2): \ + $$(VBOX_PATH_MANUAL_SRC)/$(1)/$(2) \ + $$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manpage-preprocessing.xsl \ + $$(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) \ + $$(VBOX_VERSION_STAMP) | $$$$(dir $$$$@) + $$(call MSG_GENERATE,,$$@,$$<) + $$(QUIET)$$(RM) -f "$$@" + $$(QUIET)$$(VBOX_XSLTPROC_WITH_CAT) --output $$@ \ + $$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manpage-preprocessing.xsl $$< + ifdef VBOX_WITH_XMLLINT + $$(QUIET)$$(VBOX_XMLLINT_WITH_CAT) --dtdvalid $$(VBOX_PATH_DOCBOOK_DTD)/docbookx.dtd $$@ + endif + +$$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/$(patsubst man_%,%.1,$(basename $(2))): \ + $$(VBOX_PATH_MANUAL_OUTBASE)/$(1)/$(2) \ + $$(VBOX_PATH_MANUAL_OUTBASE)/docbook-refentry-to-manpage.xsl \ + $$(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) \ + $$(VBOX_VERSION_STAMP) | $$$$(dir $$$$@) + $$(call MSG_GENERATE,,$$@,$$<) + $$(QUIET)$$(RM) -f "$$@" + $$(QUIET)$$(VBOX_XSLTPROC_WITH_CAT) --output $$@ $$(VBOX_PATH_MANUAL_OUTBASE)/docbook-refentry-to-manpage.xsl $$< +endef +$(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(foreach file,$(VBOX_MANUAL_XML_REFENTRY_FILES) \ +, $(evalcall2 def_vbox_refentry_to_manpage,$(lang),$(file)))) + + +# Handy aliases. +validate-manpages:: $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(VBOX_MANUAL_XML_REFENTRY_FILES)) +man-experiment:: $(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(foreach file,$(VBOX_MANUAL_XML_REFENTRY_FILES) \ + ,$$(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/$(patsubst man_%,%.1,$(basename $(file))))) @@ -974,8 +1002,11 @@ $(VBOX_PATH_MANUAL_OUTBASE)/VBoxManageBuiltInHelp.h +$(evalcall2 def_vbox_replace_paths_in_xslt,docbook-refentry-to-C-help.xsl,) +$(evalcall2 def_vbox_replace_paths_in_xslt,docbook-refentry-to-H-help.xsl,) + $(VBOX_PATH_MANUAL_OUTBASE)/VBoxManageBuiltInHelp.cpp: \ $(VBOX_PATH_MANUAL_OUTBASE)/docbook-refentry-to-C-help.xsl \ - $(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(filter man_VBoxManage_%,$(VBOX_MANUAL_XML_REFENTRY_FILES))) \ - $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(MAKEFILE) + $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(filter man_VBoxManage-%,$(VBOX_MANUAL_XML_REFENTRY_FILES))) \ + $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(MAKEFILE) | $$(dir $$@) $(call MSG_GENERATE,,$@,$<) $(QUIET)$(APPEND) -tn "$@" \ @@ -986,10 +1017,11 @@ '' $(foreach refentry,$(filter %.xml,$^) \ - ,$(NLTAB)$(QUIET)$(REDIRECT) -a+to "$@" -- $(VBOX_XSLTPROC_WITH_CAT) --xinclude --nonet $< $(refentry)) + ,$(NLTAB)$(QUIET)$(REDIRECT) -a+to "$@" -- $(VBOX_XSLTPROC_WITH_CAT) $< $(refentry)) $(QUIET)$(APPEND) -n "$@" \ '' \ 'PCREFENTRY g_apHelpEntries[] = ' \ '{' \ - $(foreach refentry,$(filter %.xml,$^), ' &g_$(tolower $(patsubst man_%,%,$(notdir $(basename $(refentry))))), ') \ + $(foreach refentry,$(filter %.xml,$^) \ + , ' &g_$(subst -,_,$(tolower $(patsubst man_%,%,$(notdir $(basename $(refentry)))))), ') \ '};' \ 'const uint32_t g_cHelpEntries = RT_ELEMENTS(g_apHelpEntries);' \ @@ -998,6 +1030,6 @@ $(VBOX_PATH_MANUAL_OUTBASE)/VBoxManageBuiltInHelp.h: \ $(VBOX_PATH_MANUAL_OUTBASE)/docbook-refentry-to-H-help.xsl \ - $(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(filter man_VBoxManage_%,$(VBOX_MANUAL_XML_REFENTRY_FILES))) \ - $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(MAKEFILE) + $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/en_US/,$(filter man_VBoxManage-%,$(VBOX_MANUAL_XML_REFENTRY_FILES))) \ + $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(MAKEFILE) | $$(dir $$@) $(call MSG_GENERATE,,$@,$<) $(QUIET)$(APPEND) -tn "$@" \ @@ -1015,5 +1047,5 @@ ' HELP_CMD_VBOXMANAGE_INVALID = 0,' $(foreach refentry,$(filter %.xml,$^) \ - ,$(NLTAB)$(QUIET)$(REDIRECT) -a+to "$@" -- $(VBOX_XSLTPROC_WITH_CAT) --xinclude --nonet \ + ,$(NLTAB)$(QUIET)$(REDIRECT) -a+to "$@" -- $(VBOX_XSLTPROC_WITH_CAT) \ --stringparam 'g_sMode' 'cmd' $< $(refentry)) $(QUIET)$(APPEND) -n "$@" \ @@ -1021,5 +1053,5 @@ '} HELP_CMD_VBOXMANAGE;' $(foreach refentry,$(filter %.xml,$^) \ - ,$(NLTAB)$(QUIET)$(REDIRECT) -a+to "$@" -- $(VBOX_XSLTPROC_WITH_CAT) --xinclude --nonet \ + ,$(NLTAB)$(QUIET)$(REDIRECT) -a+to "$@" -- $(VBOX_XSLTPROC_WITH_CAT) \ --stringparam 'g_sMode' 'subcmd' $< $(refentry)) $(QUIET)$(APPEND) -n "$@" \ Index: /trunk/doc/manual/docbook-refentry-to-C-help.xsl =================================================================== --- /trunk/doc/manual/docbook-refentry-to-C-help.xsl (revision 56532) +++ /trunk/doc/manual/docbook-refentry-to-C-help.xsl (revision 56533) @@ -165,5 +165,5 @@ cmdsynopsis with text is not supported. - { , + { | REFENTRYSTR_FLAGS_SYNOPSIS, "" }, @@ -171,6 +171,17 @@ " }, - { REFENTRYSTR_SCOPE_SAME, - " + { REFENTRYSTR_SCOPE_SAME | REFENTRYSTR_FLAGS_SYNOPSIS, + " + + + + " }, + { REFENTRYSTR_SCOPE_SAME | REFENTRYSTR_FLAGS_SYNOPSIS, + " + + + + + @@ -234,16 +245,5 @@ - - - - - Could not find any cmdsynopsis with id= in refsynopsisdiv. - - - - - - - + @@ -447,14 +447,8 @@ - - - - Misplaced remark/@role=help-copy-synopsis element. -Only supported on: refsect2 - - + remark/@role=help-copy-synopsis is not supported by this stylesheet. Must preprocess input! Index: unk/doc/manual/docbook-refentry-to-man.xsl =================================================================== --- /trunk/doc/manual/docbook-refentry-to-man.xsl (revision 56532) +++ (revision ) @@ -1,31 +1,0 @@ - - - - - - - - - - - - - Index: /trunk/doc/manual/docbook-refentry-to-manpage.xsl =================================================================== --- /trunk/doc/manual/docbook-refentry-to-manpage.xsl (revision 56533) +++ /trunk/doc/manual/docbook-refentry-to-manpage.xsl (revision 56533) @@ -0,0 +1,31 @@ + + + + + + + + + + + + + Index: /trunk/doc/manual/en_US/man_VBoxManage-debugvm.xml =================================================================== --- /trunk/doc/manual/en_US/man_VBoxManage-debugvm.xml (revision 56533) +++ /trunk/doc/manual/en_US/man_VBoxManage-debugvm.xml (revision 56533) @@ -0,0 +1,358 @@ + + + + + + + $Date$ + VBoxManage debugvm + + + + VBoxManage-debugvm + 1 + + + + VBoxManage-debugvm + introspection and guest debugging + Oracle VM VirtualBox + + + + + VBoxManage debugvm + uuid|vmname + dumpvmcore + --filename name + + + VBoxManage debugvm + uuid|vmname + info + item + args + + + VBoxManage debugvm + uuid|vmname + injectnmi + + + VBoxManage debugvm + uuid|vmname + log + --release--debug + group-settings + + + VBoxManage debugvm + uuid|vmname + logdest + --release--debug + destinations + + + VBoxManage debugvm + uuid|vmname + logflags + --release--debug + flags + + + VBoxManage debugvm + uuid|vmname + osdetect + + + VBoxManage debugvm + uuid|vmname + osinfo + + + VBoxManage debugvm + uuid|vmname + osdmesg + --lines lines + + + VBoxManage debugvm + uuid|vmname + getregisters + --cpu id + reg-set.reg-name + + + VBoxManage debugvm + uuid|vmname + setregisters + --cpu id + reg-set.reg-name=value + + + VBoxManage debugvm + uuid|vmname + show + --human-readable--sh-export--sh-eval--cmd-set + settings-item + + + VBoxManage debugvm + uuid|vmname + statistics + --reset + --descriptions + --pattern pattern + + + + Description + + The "debugvm" commands are for experts who want to tinker with the + exact details of virtual machine execution. Like the VM debugger + described in , these commands are only useful if you are + very familiar with the details of the PC architecture and how to debug + software. + + + Common options + + The subcommands of debugvm all operate on a running virtual + machine: + + + uuid|vmname + Either the UUID or the name (case sensitive) of a VM. + + + + + + debugvm dumpvmcore + + + Creates a system dump file of the specified VM. This file will have + the standard ELF core format (with custom sections); see + . + + + This corresponds to the writecore command in the debugger. + + + + + The name of the output file. + + + + + + debugvm info + + + Displays info items relating to the VMM, device emulations and + associated drivers. + + + This corresponds to the info command in the debugger. + + + + info + + Name of the info item to display. The special name + will list all the available info items and + hints about optional arguments. + + + + args + + Optional argument string for the info item handler. Most info items + does not take any extra arguments. Arguments not recognized are generally + ignored. + + + + + + + debugvm injectnmi + + + Causes a non-maskable interrupt (NMI) to be injected into the guest. This + might be useful for certain debugging scenarios. What happens exactly is + dependent on the guest operating system, but an NMI can crash the whole + guest operating system. Do not use unless you know what you're doing. + + + + + debugvm log + + + TODO + + + + + debugvm logdest + + + TODO + + + + + debugvm logflags + + + TODO + + + + + debugvm osdetect + + + Make the VMM's debugger facility (re)-detect the guest operating system (OS). + This will first load all debugger plug-ins. + + + This corresponds to the detect command in the debugger. + + + + + debugvm osinfo + + + Displays information about the guest operating system (OS) previously + detected by the VMM's debugger facility. + + + + + debugvm osdmesg + + + Displays the guest OS kernel log, if detected and supported. + + + + + Number of lines of the log to display, counting from + the end. The default is infinite. + + + + + + debugvm getregisters + + + Retrieves register values for guest CPUs and emulated devices. + + + + reg-set.reg-name + One of more registers, each having one of the following forms: + + register-set.register-name.sub-field + register-set.register-name + cpu-register-name.sub-field + cpu-register-name + all + + The all form will cause all registers + to be shown (no sub-fields). The registers names are case-insensitive. + + + + + Selects the CPU register set when specifying just a + CPU register (3rd and 4th form). The default is 0. + + + + + + + debugvm setregisters + + + Changes register values for guest CPUs and emulated devices. + + + + reg-set.reg-name=value + One of more register assignment, each having one of the following forms: + + register-set.register-name.sub-field=value + register-set.register-name=value + cpu-register-name.sub-field=value + cpu-register-name=value + + The value format should be in the same style as what getregisters + displays, with the exception that both octal and decimal can be used instead of + hexadecimal. + + + + + Selects the CPU register set when specifying just a + CPU register (3rd and 4th form). The default is 0. + + + + + + + debugvm show + + + TODO + + + + + debugvm statistics + + + Displays or resets VMM statistics. + + + Retrieves register values for guest CPUs and emulated devices. + + + + + DOS/NT-style wildcards patterns for selecting statistics. Multiple + patterns can be specified by using the '|' (pipe) character as separator. + + + + + Select reset instead of display mode. + + + + + + + + + + Index: /trunk/doc/manual/en_US/man_VBoxManage-extpack.xml =================================================================== --- /trunk/doc/manual/en_US/man_VBoxManage-extpack.xml (revision 56533) +++ /trunk/doc/manual/en_US/man_VBoxManage-extpack.xml (revision 56533) @@ -0,0 +1,134 @@ + + + + + + + $Date$ + VBoxManage extpack + + + + VBoxManage-extpack + 1 + + + + VBoxManage-extpack + extension package management + Oracle VM VirtualBox + + + + + VBoxManage extpack install + --replace + tarball + + + VBoxManage extpack uninstall + --force + name + + + VBoxManage extpack cleanup + + + + + Description + + + extpack install + + + Installs a new extension pack on the system. This command will fail if an older + version of the same extension pack is already installed. The + option can be used to uninstall any + old package before the new one is installed. + + + + Uninstall existing extension pack version. + + + tarball + + The file containing the extension pack to be installed. + + + + + + + extpack uninstall + + + Uninstalls an extension pack from the system. The subcommand will also succeed + in the case where the specified extension pack is not present on the system. + You can use VBoxManage list extpacks to show + the names of the extension packs which are currently installed. + + + + + + Overrides most refusals to uninstall an extension pack + + + + name + + The name of the extension pack to be uninstalled. + + + + + + + extpack cleanup + + + Used to remove temporary files and directories that may have been left behind + if a previous install or uninstall command failed. + + + + + + + Examples + + + How to list extension packs: +$ VBoxManage list extpacks +Extension Packs: 1 +Pack no. 0: Oracle VM VirtualBox Extension Pack +Version: 4.1.12 +Revision: 77218 +Edition: +Description: USB 2.0 Host Controller, VirtualBox RDP, PXE ROM with E1000 support. +VRDE Module: VBoxVRDP +Usable: true +Why unusable: + + How to remove an extension pack: +$ VBoxManage extpack uninstall "Oracle VM VirtualBox Extension Pack" +0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100% +Successfully uninstalled "Oracle VM VirtualBox Extension Pack". + + + + Index: unk/doc/manual/en_US/man_VBoxManage_debugvm.xml =================================================================== --- /trunk/doc/manual/en_US/man_VBoxManage_debugvm.xml (revision 56532) +++ (revision ) @@ -1,358 +1,0 @@ - - - - - - - $Date$ - VBoxManage debugvm - - - - VBoxManage-debugvm - 1 - - - - VBoxManage-debugvm - introspection and guest debugging - Oracle VM VirtualBox - - - - - VBoxManage debugvm - uuid|vmname - dumpvmcore - --filename name - - - VBoxManage debugvm - uuid|vmname - info - item - args - - - VBoxManage debugvm - uuid|vmname - injectnmi - - - VBoxManage debugvm - uuid|vmname - log - --release--debug - group-settings - - - VBoxManage debugvm - uuid|vmname - logdest - --release--debug - destinations - - - VBoxManage debugvm - uuid|vmname - logflags - --release--debug - flags - - - VBoxManage debugvm - uuid|vmname - osdetect - - - VBoxManage debugvm - uuid|vmname - osinfo - - - VBoxManage debugvm - uuid|vmname - osdmesg - --lines lines - - - VBoxManage debugvm - uuid|vmname - getregisters - --cpu id - reg-set.reg-name - - - VBoxManage debugvm - uuid|vmname - setregisters - --cpu id - reg-set.reg-name=value - - - VBoxManage debugvm - uuid|vmname - show - --human-readable--sh-export--sh-eval--cmd-set - settings-item - - - VBoxManage debugvm - uuid|vmname - statistics - --reset - --descriptions - --pattern pattern - - - - Description - - The "debugvm" commands are for experts who want to tinker with the - exact details of virtual machine execution. Like the VM debugger - described in , these commands are only useful if you are - very familiar with the details of the PC architecture and how to debug - software. - - - Common options - - The subcommands of debugvm all operate on a running virtual - machine: - - - uuid|vmname - Either the UUID or the name (case sensitive) of a VM. - - - - - - debugvm dumpvmcore - - - Creates a system dump file of the specified VM. This file will have - the standard ELF core format (with custom sections); see - . - - - This corresponds to the writecore command in the debugger. - - - - - The name of the output file. - - - - - - debugvm info - - - Displays info items relating to the VMM, device emulations and - associated drivers. - - - This corresponds to the info command in the debugger. - - - - info - - Name of the info item to display. The special name - will list all the available info items and - hints about optional arguments. - - - - args - - Optional argument string for the info item handler. Most info items - does not take any extra arguments. Arguments not recognized are generally - ignored. - - - - - - - debugvm injectnmi - - - Causes a non-maskable interrupt (NMI) to be injected into the guest. This - might be useful for certain debugging scenarios. What happens exactly is - dependent on the guest operating system, but an NMI can crash the whole - guest operating system. Do not use unless you know what you're doing. - - - - - debugvm log - - - TODO - - - - - debugvm logdest - - - TODO - - - - - debugvm logflags - - - TODO - - - - - debugvm osdetect - - - Make the VMM's debugger facility (re)-detect the guest operating system (OS). - This will first load all debugger plug-ins. - - - This corresponds to the detect command in the debugger. - - - - - debugvm osinfo - - - Displays information about the guest operating system (OS) previously - detected by the VMM's debugger facility. - - - - - debugvm osdmesg - - - Displays the guest OS kernel log, if detected and supported. - - - - - Number of lines of the log to display, counting from - the end. The default is infinite. - - - - - - debugvm getregisters - - - Retrieves register values for guest CPUs and emulated devices. - - - - reg-set.reg-name - One of more registers, each having one of the following forms: - - register-set.register-name.sub-field - register-set.register-name - cpu-register-name.sub-field - cpu-register-name - all - - The all form will cause all registers - to be shown (no sub-fields). The registers names are case-insensitive. - - - - - Selects the CPU register set when specifying just a - CPU register (3rd and 4th form). The default is 0. - - - - - - - debugvm setregisters - - - Changes register values for guest CPUs and emulated devices. - - - - reg-set.reg-name=value - One of more register assignment, each having one of the following forms: - - register-set.register-name.sub-field=value - register-set.register-name=value - cpu-register-name.sub-field=value - cpu-register-name=value - - The value format should be in the same style as what getregisters - displays, with the exception that both octal and decimal can be used instead of - hexadecimal. - - - - - Selects the CPU register set when specifying just a - CPU register (3rd and 4th form). The default is 0. - - - - - - - debugvm show - - - TODO - - - - - debugvm statistics - - - Displays or resets VMM statistics. - - - Retrieves register values for guest CPUs and emulated devices. - - - - - DOS/NT-style wildcards patterns for selecting statistics. Multiple - patterns can be specified by using the '|' (pipe) character as separator. - - - - - Select reset instead of display mode. - - - - - - - - - - Index: unk/doc/manual/en_US/man_VBoxManage_extpack.xml =================================================================== --- /trunk/doc/manual/en_US/man_VBoxManage_extpack.xml (revision 56532) +++ (revision ) @@ -1,134 +1,0 @@ - - - - - - - $Date$ - VBoxManage extpack - - - - VBoxManage-extpack - 1 - - - - VBoxManage-extpack - extension package management - Oracle VM VirtualBox - - - - - VBoxManage extpack install - --replace - tarball - - - VBoxManage extpack uninstall - --force - name - - - VBoxManage extpack cleanup - - - - - Description - - - extpack install - - - Installs a new extension pack on the system. This command will fail if an older - version of the same extension pack is already installed. The - option can be used to uninstall any - old package before the new one is installed. - - - - Uninstall existing extension pack version. - - - tarball - - The file containing the extension pack to be installed. - - - - - - - extpack uninstall - - - Uninstalls an extension pack from the system. The subcommand will also succeed - in the case where the specified extension pack is not present on the system. - You can use VBoxManage list extpacks to show - the names of the extension packs which are currently installed. - - - - - - Overrides most refusals to uninstall an extension pack - - - - name - - The name of the extension pack to be uninstalled. - - - - - - - extpack cleanup - - - Used to remove temporary files and directories that may have been left behind - if a previous install or uninstall command failed. - - - - - - - Examples - - - How to list extension packs: -$ VBoxManage list extpacks -Extension Packs: 1 -Pack no. 0: Oracle VM VirtualBox Extension Pack -Version: 4.1.12 -Revision: 77218 -Edition: -Description: USB 2.0 Host Controller, VirtualBox RDP, PXE ROM with E1000 support. -VRDE Module: VBoxVRDP -Usable: true -Why unusable: - - How to remove an extension pack: -$ VBoxManage extpack uninstall "Oracle VM VirtualBox Extension Pack" -0%...10%...20%...30%...40%...50%...60%...70%...80%...90%...100% -Successfully uninstalled "Oracle VM VirtualBox Extension Pack". - - - - Index: /trunk/doc/manual/en_US/user_VBoxManage.xml =================================================================== --- /trunk/doc/manual/en_US/user_VBoxManage.xml (revision 56532) +++ /trunk/doc/manual/en_US/user_VBoxManage.xml (revision 56533) @@ -4522,8 +4522,8 @@ - - Index: /trunk/include/VBox/refentry.h =================================================================== --- /trunk/include/VBox/refentry.h (revision 56532) +++ /trunk/include/VBox/refentry.h (revision 56533) @@ -43,10 +43,17 @@ #define REFENTRY_NBSP '\b' -/** @name REFENTRYSTR_SCOPE_XXX - Common string scoping. +/** @name REFENTRYSTR_SCOPE_XXX - Common string scoping and flags. * @{ */ -/** Same scope as previous string table entry. */ +/** Same scope as previous string table entry, flags are reset and can be + * ORed in. */ #define REFENTRYSTR_SCOPE_SAME UINT64_C(0) /** Global scope. */ -#define REFENTRYSTR_SCOPE_GLOBAL UINT64_MAX +#define REFENTRYSTR_SCOPE_GLOBAL UINT64_C(0x00ffffffffffffff) +/** Scope mask. */ +#define REFENTRYSTR_SCOPE_MASK UINT64_C(0x00ffffffffffffff) +/** Flags mask. */ +#define REFENTRYSTR_FLAGS_MASK UINT64_C(0xff00000000000000) +/** Command synopsis, special hanging indent rules applies. */ +#define REFENTRYSTR_FLAGS_SYNOPSIS RT_BIT_64(63) /** @} */ Index: /trunk/src/VBox/Frontends/VBoxManage/VBoxManageHelp.cpp =================================================================== --- /trunk/src/VBox/Frontends/VBoxManage/VBoxManageHelp.cpp (revision 56532) +++ /trunk/src/VBox/Frontends/VBoxManage/VBoxManageHelp.cpp (revision 56533) @@ -44,6 +44,7 @@ enum HELP_CMD_VBOXMANAGE g_enmCurCommand = HELP_CMD_VBOXMANAGE_INVALID; /** The scope maskt for the current subcommand. */ -uint64_t g_fCurSubcommandScope = UINT64_MAX; - +uint64_t g_fCurSubcommandScope = REFENTRYSTR_SCOPE_GLOBAL; +/** String of spaces that can be used for indentation. */ +static const char g_szSpaces[] = " "; /** @@ -58,5 +59,5 @@ Assert(g_enmCurCommand == HELP_CMD_VBOXMANAGE_INVALID); g_enmCurCommand = enmCommand; - g_fCurSubcommandScope = UINT64_MAX; + g_fCurSubcommandScope = REFENTRYSTR_SCOPE_GLOBAL; } @@ -104,6 +105,7 @@ * @param psz The string table string to print. * @param cchMaxWidth The maximum output width. - */ -static uint32_t printString(PRTSTREAM pStrm, const char *psz, uint32_t cchMaxWidth) + * @param fFlags String flags that may affect formatting. + */ +static uint32_t printString(PRTSTREAM pStrm, const char *psz, uint32_t cchMaxWidth, uint64_t fFlags) { uint32_t cLinesWritten; @@ -142,14 +144,17 @@ while (*psz == ' ') cchIndent++, psz++; + Assert(cchIndent + 4 + 1 <= RT_ELEMENTS(g_szSpaces)); + if (cchIndent + 8 >= cchMaxWidth) cchMaxWidth += cchIndent + 8; /* Work our way thru the string, line by line. */ + uint32_t cchHangingIndent = 0; cLinesWritten = 0; do { - RTStrmWrite(pStrm, pszIndent, cchIndent); - size_t offLine = cchIndent; - bool fPendingSpace = false; + RTStrmWrite(pStrm, g_szSpaces, cchIndent + cchHangingIndent); + size_t offLine = cchIndent + cchHangingIndent; + bool fPendingSpace = false; do { @@ -183,4 +188,8 @@ RTStrmPutCh(pStrm, '\n'); cLinesWritten++; + + /* Set up hanging indent if relevant. */ + if (fFlags & REFENTRYSTR_FLAGS_SYNOPSIS) + cchHangingIndent = 4; } while (*psz != '\0'); } @@ -223,7 +232,10 @@ { uint64_t fCurScope = pStrTab->paStrings[i].fScope; - if (fCurScope == REFENTRYSTR_SCOPE_SAME) - fCurScope = fPrevScope; - if (fCurScope & fScope) + if ((fCurScope & REFENTRYSTR_SCOPE_MASK) == REFENTRYSTR_SCOPE_SAME) + { + fCurScope &= ~REFENTRYSTR_SCOPE_MASK; + fCurScope |= (fPrevScope & REFENTRYSTR_SCOPE_MASK); + } + if (fCurScope & REFENTRYSTR_SCOPE_MASK & fScope) { const char *psz = pStrTab->paStrings[i].psz; @@ -236,5 +248,5 @@ cLinesWritten++; } - cLinesWritten += printString(pStrm, psz, cchWidth); + cLinesWritten += printString(pStrm, psz, cchWidth, fCurScope & REFENTRYSTR_FLAGS_MASK); } else @@ -255,5 +267,6 @@ * @returns Number of lines written. * @param enmCommand The command. - * @param fSubcommandScope The subcommand scope, UINT64_MAX for all. + * @param fSubcommandScope The subcommand scope, REFENTRYSTR_SCOPE_GLOBAL + * for all. * @param pStrm The output stream. */ @@ -301,5 +314,6 @@ * * @param enmCommand The command. - * @param fSubcommandScope The subcommand scope, UINT64_MAX for all. + * @param fSubcommandScope The subcommand scope, REFENTRYSTR_SCOPE_GLOBAL + * for all. * @param pStrm The output stream. */ @@ -343,5 +357,5 @@ { Assert(g_enmCurCommand != HELP_CMD_VBOXMANAGE_INVALID); - Assert(g_fCurSubcommandScope == UINT64_MAX); + Assert(g_fCurSubcommandScope == REFENTRYSTR_SCOPE_GLOBAL); return errorSyntax("No subcommand specified"); @@ -360,5 +374,5 @@ { Assert(g_enmCurCommand != HELP_CMD_VBOXMANAGE_INVALID); - Assert(g_fCurSubcommandScope == UINT64_MAX); + Assert(g_fCurSubcommandScope == REFENTRYSTR_SCOPE_GLOBAL); /* check if help was requested. */ @@ -387,5 +401,5 @@ { Assert(g_enmCurCommand != HELP_CMD_VBOXMANAGE_INVALID); - Assert(g_fCurSubcommandScope != UINT64_MAX); + Assert(g_fCurSubcommandScope != REFENTRYSTR_SCOPE_GLOBAL); /* check if help was requested. */