VirtualBox

Changeset 77353 in vbox


Ignore:
Timestamp:
Feb 18, 2019 9:15:47 PM (6 years ago)
Author:
vboxsync
Message:

doc/manual: Replace xref in man and --help output with chapter/section numbers+names to avoid having to wrap these in hacky <remark role=help-manual> elements.

Location:
trunk
Files:
1 added
4 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc/manual/Config.kmk

    r76786 r77353  
    4040        man_VBoxManage-extpack.xml \
    4141        man_VBoxManage-unattended.xml
     42
     43## List of user manual XML files.
     44VBOX_MANUAL_XML_FILES = \
     45        UserManual.xml \
     46        user_Preface.xml \
     47        user_Introduction.xml \
     48        user_Installation.xml \
     49        user_BasicConcepts.xml \
     50        user_GuestAdditions.xml \
     51        user_Storage.xml \
     52        user_Networking.xml \
     53        user_Frontends.xml \
     54        user_VBoxManage.xml \
     55        user_AdvancedTopics.xml \
     56        user_Technical.xml \
     57        user_VirtualBoxAPI.xml \
     58        user_Troubleshooting.xml \
     59        user_Security.xml \
     60        user_KnownIssues.xml \
     61        user_ChangeLog.xml \
     62        user_ThirdParty.xml \
     63        user_PrivacyPolicy.xml \
     64        user_Glossary.xml \
     65        oracle-accessibility-en.xml \
     66        oracle-support-en.xml
     67
     68## List of user manual XML files common for all languages.
     69VBOX_MANUAL_XML_FILES_COMMON = \
     70        $(VBOX_PATH_MANUAL_SRC)/user_ChangeLogImpl.xml
    4271
    4372
     
    6291ifdef VBOX_XML_CATALOG
    6392 VBOX_XSLTPROC_WITH_CAT    = $(REDIRECT) -E "XML_CATALOG_FILES=$(VBOX_XML_CATALOG)" -E "XML_DEBUG_CATALOG=" $1 -- \
    64         $(VBOX_XSLTPROC) --nonet --xinclude $(VBOX_XSLTPROC_OPTS)
     93        $(VBOX_XSLTPROC) --nonet --xinclude $(VBOX_XSLTPROC_OPTS) --path "$(VBOX_PATH_MANUAL_OUTBASE)"
    6594 VBOX_XMLLINT_WITH_CAT     = $(REDIRECT) -E "XML_CATALOG_FILES=$(VBOX_XML_CATALOG)" -E "XML_DEBUG_CATALOG=" -- \
    66         $(VBOX_XMLLINT) --nonet --xinclude --noout $(VBOX_XMLLINT_OPTS)
     95        $(VBOX_XMLLINT) --nonet --xinclude --noout $(VBOX_XMLLINT_OPTS) --path "$(VBOX_PATH_MANUAL_OUTBASE)"
    6796else
    68  VBOX_XSLTPROC_WITH_CAT    = $(if $(1), $(REDIRECT) $1 --,) $(VBOX_XSLTPROC) --nonet --xinclude $(VBOX_XSLTPROC_OPTS)
    69  VBOX_XMLLINT_WITH_CAT     = $(VBOX_XMLLINT) --nonet --xinclude --noout $(VBOX_XMLLINT_OPTS)
    70 endif
    71 
     97 VBOX_XSLTPROC_WITH_CAT    = $(if $(1), $(REDIRECT) $1 --,) $(VBOX_XSLTPROC) --nonet --xinclude $(VBOX_XSLTPROC_OPTS) \
     98        --path "$(VBOX_PATH_MANUAL_OUTBASE)"
     99 VBOX_XMLLINT_WITH_CAT     = $(VBOX_XMLLINT) --nonet --xinclude --noout $(VBOX_XMLLINT_OPTS) --path "$(VBOX_PATH_MANUAL_OUTBASE)"
     100endif
     101
     102
     103# Location of the generate stylesheet for transformating xref elements into
     104# name user manual sections.
     105VBOX_XML_XREF_TO_TEXT      = $(VBOX_PATH_MANUAL_OUTBASE)/xref-to-text.xsl
    72106
    73107##
     
    79113# @param    2   The XML file name (no path).
    80114# @param    3   The XML file with full path.
     115# @param    4   Non-empty if xrefs to replace.
    81116define def_vbox_refentry_preprocess_for_manpage
    82117$(1)/$(2): \
    83118                $(3) \
    84119                $$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manpage-preprocessing.xsl \
     120                $(if $(4),$$(VBOX_XML_XREF_TO_TEXT),) \
    85121                $$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK) $$(VBOX_XML_CATALOG_MANUAL) \
    86122                $$(VBOX_VERSION_STAMP) | $$$$(dir $$$$@)
     
    88124        $$(QUIET)$$(RM) -f "$$@"
    89125        $$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --output $$@ \
    90                 $$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manpage-preprocessing.xsl $$<
     126                "$$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manpage-preprocessing.xsl" $$<
     127ifneq ($(4),)
     128        $$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --output [email protected] $$(VBOX_XML_XREF_TO_TEXT) $$@
     129        $$(QUIET)$$(MV) -f -- "[email protected]" "$$@"
     130endif
    91131if defined(VBOX_HAVE_XMLLINT) && "$(USER)" == "bird" # Effing stuff happends on build servers, probably kmk related...
    92132        $$(VBOX_XMLLINT_WITH_CAT) --dtdvalid $$(VBOX_PATH_DOCBOOK_DTD)/docbookx.dtd $$@
     
    238278        $(call MSG_L1,Creating entities $@)
    239279        $(QUIET)$(APPEND) -tn "$@" \
    240         '<!-- Entities for product names -->' \
     280                '<!-- Entities for product names -->' \
    241281                '<!ENTITY product-version "$(VBOX_VERSION_STRING)">' \
    242282                '<!ENTITY product-name "Oracle VM VirtualBox">' \
     
    259299
    260300
     301## Produce stylesheet for translating cross references (xref) to user manual
     302# chapters and sections in the man pages and --help output.
     303#
     304# Note! This requires processing UserManual.xml as a single document in order
     305#       to get the correct chapter and section numbering, so we use a catalog
     306#       file to replace the generated XML documents it includes with a dummy
     307#       one.  This reduces the dependencies and recipies we require to build
     308#       VBoxManage and the RTIsoMaker (w/ derivatives).
     309$(VBOX_XML_XREF_TO_TEXT) + $(VBOX_XML_XREF_TO_TEXT).cat: \
     310                $(VBOX_PATH_MANUAL_SRC)/docbook-refentry-link-replacement-xsl-gen.xsl \
     311                $(addprefix $(VBOX_PATH_MANUAL_SRC)/en_US/,$(VBOX_MANUAL_XML_FILES)) \
     312                $(VBOX_MANUAL_XML_FILES_COMMON) \
     313                $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK) $(VBOX_XML_CATALOG_MANUAL) $(VBOX_XML_ENTITIES) \
     314               | $$(dir $$@)
     315        $(call MSG_L1,Creating stylesheet $@)
     316        $(QUIET)$(APPEND) -nt "$(VBOX_XML_XREF_TO_TEXT).cat" \
     317                '<?xml version="1.0"?>' \
     318                '<!DOCTYPE catalog PUBLIC "-//OASIS//DTD Entity Resolution XML Catalog V1.0//EN" "http://www.oasis-open.org/committees/entity/release/1.0/catalog.dtd">' \
     319                '<catalog xmlns="urn:oasis:names:tc:entity:xmlns:xml:catalog">' \
     320                $(foreach x,user_VBoxManage_CommandsOverview.xml user_isomakercmd-man.xml $(addprefix user_,$(VBOX_MANUAL_XML_REFENTRY_FILES))\
     321                ,'  <system systemId="$(VBOX_PATH_MANUAL_SRC)/en_US/$(x)" uri="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_PATH_MANUAL_SRC)/dummy-sect1.xml"/>') \
     322                '  <nextCatalog catalog="file://$(VBOX_FILE_URL_MAYBE_SLASH)$(VBOX_XML_CATALOG)"/>' \
     323                '</catalog>'
     324        $(QUIET)$(call VBOX_XSLTPROC_WITH_CAT, -E "XML_CATALOG_FILES=$(VBOX_XML_XREF_TO_TEXT).cat") \
     325                --output "$@" "$<" $(filter %UserManual.xml,$^)
     326
    261327#
    262328# Generate rules for editing the refentry to C/H style sheets.
  • trunk/doc/manual/Makefile.kmk

    r77312 r77353  
    131131BLDDIRS += $(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/, $(VBOX_MANUAL_LANGUAGES))
    132132
    133 
    134133if defined(VBOX_WITH_DOCS) && (!defined(VBOX_ONLY_BUILD) || defined(VBOX_ONLY_DOCS) || defined(VBOX_ONLY_SDK))
    135134 if defined(VBOX_ONLY_SDK) || defined(VBOX_WITH_DOCS_SDKREF)
     
    183182 endif
    184183
    185  VBOX_MANUAL_XML_FILES = \
    186         UserManual.xml \
    187         user_Preface.xml \
    188         user_Introduction.xml \
    189         user_Installation.xml \
    190         user_BasicConcepts.xml \
    191         user_GuestAdditions.xml \
    192         user_Storage.xml \
    193         user_Networking.xml \
    194         user_Frontends.xml \
    195         user_VBoxManage.xml \
    196         user_AdvancedTopics.xml \
    197         user_Technical.xml \
    198         user_VirtualBoxAPI.xml \
    199         user_Troubleshooting.xml \
    200         user_Security.xml \
    201         user_KnownIssues.xml \
    202         user_ChangeLog.xml \
    203         user_ThirdParty.xml \
    204         user_PrivacyPolicy.xml \
    205         user_Glossary.xml \
    206         oracle-accessibility-en.xml \
    207         oracle-support-en.xml
    208 
    209  VBOX_MANUAL_XML_FILES_COMMON = \
    210         $(VBOX_PATH_MANUAL_SRC)/user_ChangeLogImpl.xml
    211 
    212184$(foreach lang,$(VBOX_MANUAL_LANGUAGES), \
    213185 $(eval VBOX_MANUAL_XML_FILES_GENERATED_$$(lang) := \
     
    256228        $(VBOX_XML_CATALOG_MANUAL) \
    257229        $(VBOX_XML_ENTITIES) \
     230        $(VBOX_XML_XREF_TO_TEXT) \
     231        $(VBOX_XML_XREF_TO_TEXT).cat \
    258232        $(foreach lang,$(VBOX_MANUAL_LANGUAGES),$(addprefix $(VBOX_PATH_MANUAL_OUTBASE)/$(lang)/, \
    259233        $(addprefix user_,$(VBOX_MANUAL_XML_REFENTRY_FILES)) \
     234         $(VBOX_MANUAL_XML_REFENTRY_FILES) \
    260235        $(patsubst man_%,%.1,$(basename $(VBOX_MANUAL_XML_REFENTRY_FILES))) \
    261236        isomakercmd-man.xml \
     
    872847                $$(VBOX_PATH_MANUAL_SRC)/$(1)/$(2) \
    873848                $$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manpage-preprocessing.xsl \
     849                $$(VBOX_XML_XREF_TO_TEXT) \
    874850                $$(VBOX_XML_CATALOG) $$(VBOX_XML_CATALOG_DOCBOOK)  $$(VBOX_XML_CATALOG_MANUAL) \
    875851                $$(VBOX_VERSION_STAMP) | $$$$(dir $$$$@)
     
    878854        $$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --output $$@ \
    879855                $$(VBOX_PATH_MANUAL_SRC)/docbook-refentry-to-manpage-preprocessing.xsl $$<
     856        $$(QUIET)$$(call VBOX_XSLTPROC_WITH_CAT) --output [email protected] $$(VBOX_XML_XREF_TO_TEXT) $$@
     857        $$(QUIET)$$(MV) -f -- "[email protected]" "$$@"
    880858if defined(VBOX_HAVE_XMLLINT)
    881859        $$(VBOX_XMLLINT_WITH_CAT) --dtdvalid $$(VBOX_PATH_DOCBOOK_DTD)/docbookx.dtd $$@
  • trunk/doc/manual/en_US/man_VBoxManage-debugvm.xml

    r73276 r77353  
    128128
    129129    <para>The "debugvm" commands are for experts who want to tinker with the
    130       exact details of virtual machine execution.  Like the VM debugger<remark role="help-manual">
    131       described in <xref linkend="ts_debugger" /></remark>, these commands are only useful if you are
     130      exact details of virtual machine execution.  Like the VM debugger
     131      described in <xref linkend="ts_debugger" />, these commands are only useful if you are
    132132      very familiar with the details of the PC architecture and how to debug
    133133      software.</para>
     
    151151      <para>
    152152        Creates a system dump file of the specified VM.  This file will have
    153         the standard ELF core format (with custom sections)<remark role="help-manual">; see
    154         <xref linkend="ts_guest-core-format" /></remark>.
     153        the standard ELF core format (with custom sections); see
     154        <xref linkend="ts_guest-core-format" />.
    155155      </para>
    156156      <para>
  • trunk/src/VBox/Frontends/VBoxManage/Makefile.kmk

    r76553 r77353  
    132132# Preprocess the xml files, applying remarks.
    133133$(foreach file,$(filter man_VBoxManage-%,$(VBOX_MANUAL_XML_REFENTRY_FILES)) \
    134 , $(evalcall2 def_vbox_refentry_preprocess_for_manpage,$(VBoxManage_0_OUTDIR),$(file),$(VBOX_PATH_MANUAL_SRC)/en_US/$(file)))
     134, $(evalcall2 def_vbox_refentry_preprocess_for_manpage,$(VBoxManage_0_OUTDIR),$(file),$(VBOX_PATH_MANUAL_SRC)/en_US/$(file),replace-xrefs))
    135135
    136136
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