VirtualBox

Changeset 56208 in vbox


Ignore:
Timestamp:
Jun 2, 2015 4:44:49 PM (10 years ago)
Author:
vboxsync
svn:sync-xref-src-repo-rev:
100750
Message:

hacking on built-in vboxmanage help.

Location:
trunk
Files:
1 added
2 edited
1 copied

Legend:

Unmodified
Added
Removed

  • trunk/doc/manual/Makefile.kmk

    r56197 r56208  
    876876                $(VBOX_PATH_MANUAL_SRC)/en_US/man_VBoxManage_extpack.xml
    877877
     878$(evalcall2 def_vbox_replace_paths_in_xslt,docbook-refentry-to-C-help.xsl,)
     879
     880help-experiment: \
     881                $(VBOX_PATH_MANUAL_SRC)/en_US/man_VBoxManage_extpack.xml \
     882                $(VBOX_PATH_MANUAL_OUTBASE)/docbook-refentry-to-C-help.xsl \
     883                $(VBOX_XML_CATALOG) $(VBOX_XML_CATALOG_DOCBOOK)
     884        $(VBOX_XSLTPROC_WITH_CAT) --xinclude --nonet --output /tmp/vboxmanage-help.cpp \
     885                $(VBOX_PATH_MANUAL_OUTBASE)/docbook-refentry-to-C-help.xsl \
     886                $(VBOX_PATH_MANUAL_SRC)/en_US/man_VBoxManage_extpack.xml
     887
    878888
    879889include $(FILE_KBUILD_SUB_FOOTER)

  • trunk/doc/manual/docbook-refentry-to-C-help.xsl

    r56200 r56208  
    2020  version="1.0"
    2121  xmlns:xsl="http://www.w3.org/1999/XSL/Transform"
     22  xmlns:str="http://xsltsl.org/string"
    2223  >
    2324
    24   <xsl:output method="xml" version="1.0" encoding="utf-8" indent="yes"/>
     25  <xsl:import href="@VBOX_PATH_MANUAL_SRC@/string.xsl"/>
     26
     27  <xsl:output method="text" version="1.0" encoding="utf-8" indent="yes"/>
    2528  <xsl:strip-space elements="*"/>
    2629
    2730
    28 <!-- Base operation is to copy. -->
    29 <xsl:template match="node()|@*">
    30   <xsl:copy>
    31      <xsl:apply-templates select="node()|@*"/>
    32   </xsl:copy>
    33 </xsl:template>
    34 
    35 <!--
    36   The refentry element is the top level one.  We only process the
    37   refsynopsisdiv sub element within it, since that is all we want.
    38   -->
    39 <xsl:template match="refentry">
    40   <xsl:apply-templates select="refsynopsisdiv"/>
    41 </xsl:template>
    42 
    43 <!--
    44   Translate the refsynopsisdiv into a refsect1. There is special handling
    45   of this in the HTML CSS and in the latex conversion XSLT.
    46   -->
    47 <xsl:template match="refsynopsisdiv">
    48   <refsect1>
    49      <xsl:apply-templates select="node()|@*"/>
    50   </refsect1>
    51 </xsl:template>
    52 
    53 <!-- Remove all remarks (for now). -->
    54 <xsl:template match="remark"/>
     31  <!-- Default action, do nothing. -->
     32  <xsl:template match="node()|@*"/>
     33
     34
     35  <!--
     36    main() - because we need to order the output in a specific manner
     37             that is contrary to the data flow in the refentry, this is
     38             going to look a bit more like a C program than a stylesheet.
     39    -->
     40  <xsl:template match="refentry">
     41    <!-- Assert refetry expectations. -->
     42    <xsl:if test="not(./refsynopsisdiv)"><xsl:message terminate="yes">refentry must have a refsynopsisdiv</xsl:message></xsl:if>
     43    <xsl:if test="not(./refsect1/title)"><xsl:message terminate="yes">refentry must have a refsynopsisdiv</xsl:message></xsl:if>
     44    <xsl:if test="not(@id) or @id = ''"><xsl:message terminate="yes">refentry must have an id attribute</xsl:message></xsl:if>
     45
     46    <!-- variables -->
     47    <xsl:variable name="sBaseId" select="@id"/>
     48    <xsl:variable name="sDataBaseSym" select="concat('g_', translate(@id, '-', '_'))"/>
     49
     50    <!--
     51      Convert the refsynopsisdiv into REFENTRY::Synopsis data.
     52      -->
     53    <xsl:text>
     54
     55static const REFENTRYSTR </xsl:text><xsl:value-of select="$sDataBaseSym"/><xsl:text>_synopsis[] =
     56{</xsl:text>
     57    <xsl:for-each select="./refsynopsisdiv/cmdsynopsis">
     58      <!-- Assert synopsis expectations -->
     59      <xsl:if test="not(@id) or substring-before(@id, '-') != 'synopsis'">
     60        <xsl:message terminate="yes">The refsynopsisdiv/cmdsynopsis elements must have an id starting with 'synopsis-'.</xsl:message>
     61      </xsl:if>
     62      <xsl:if test="not(../../refsect1/refsect2[@id=./@id])">
     63        <xsl:message terminate="yes">No refsect2 with id="<xsl:value-of select="@id"/>" found.</xsl:message>
     64      </xsl:if>
     65
     66      <!-- Do the work. -->
     67      <xsl:text>
     68    {   </xsl:text><xsl:call-template name="calc-scope"/><xsl:text>,
     69        "</xsl:text>
     70        <xsl:apply-templates select="."/>
     71        <xsl:text>" },
     72</xsl:text>
     73    </xsl:for-each>
     74    <xsl:text>
     75};
     76</xsl:text>
     77  </xsl:template>
     78
     79
     80  <!--
     81    Functions
     82    Functions
     83    Functions
     84    -->
     85
     86  <!-- Figures out the scope of an element. -->
     87  <xsl:template name="calc-scope">
     88    <xsl:param name="a_Element" select="."/>
     89    <xsl:param name="a_cRecursions" select="'1'"/>
     90
     91    <xsl:choose>
     92      <!-- Check for an explicit scope remark: <remark role='scope' condition='uninstall'/> -->
     93      <xsl:when test="$a_Element/remark[@role='scope']">
     94        <xsl:if test="not($a_Element/remark[@role='scope']/@condition)">
     95          <xsl:message terminate="yes">remark[role=scope] element must have a condition attribute.</xsl:message>
     96        </xsl:if>
     97        <xsl:call-template name="calc-scope-const">
     98          <xsl:with-param name="sId" select="concat(concat(ancestor::refentry[1]/@id, '-'),
     99                                                    $a_Element/remark[@role='scope']/@condition)"/>
     100        </xsl:call-template>
     101      </xsl:when>
     102
     103      <!-- Try derive it from the @id tag, if any. -->
     104      <xsl:when test="substring(@id, 1, 3) = 'vbox'">
     105        <xsl:call-template name="calc-scope-const">
     106          <xsl:with-param name="sId" select="$a_Element/@id"/>
     107        </xsl:call-template>
     108      </xsl:when>
     109      <xsl:when test="@id">
     110        <xsl:call-template name="calc-scope-const">
     111          <xsl:with-param name="sId" select="substring-after($a_Element/@id, '-')"/>
     112        </xsl:call-template>
     113      </xsl:when>
     114
     115      <!-- Recursively try the parent element. -->
     116      <xsl:when test="($a_cRecursions) > 10">
     117        <xsl:message terminal="yes">calc-scope recursion too deep.</xsl:message>
     118      </xsl:when>
     119      <xsl:otherwise>
     120        <xsl:call-template name="calc-scope">
     121          <xsl:with-param name="a_Element" select="$a_Element/.."/>
     122          <xsl:with-param name="a_cRecursions" select="$a_cRecursions + 1"/>
     123        </xsl:call-template>
     124      </xsl:otherwise>
     125    </xsl:choose>
     126  </xsl:template>
     127
     128  <!-- Calculates a scope constant from a ID like value. -->
     129  <xsl:template name="calc-scope-const">
     130    <xsl:param name="sId" select="@id"/>
     131    <xsl:if test="$sId = ''"><xsl:message terminate="yes">refentry: command Missing </xsl:message></xsl:if>
     132    <xsl:variable name="sTmp1" select="translate($sId, '-', '_')"/>
     133    <xsl:variable name="sTmp2">
     134      <xsl:call-template name="str:to-upper">
     135        <xsl:with-param name="text" select="$sTmp1"/>
     136      </xsl:call-template>
     137    </xsl:variable>
     138    <xsl:text>HELP_</xsl:text>
     139    <xsl:value-of select="$sTmp2"/>
     140  </xsl:template>
     141
     142
     143  <!--
     144    To text conversions.
     145    -->
     146  <xsl:template match="cmdsynopsis">
     147    <xsl:if test="text()"><xsl:message terminate="yes">cmdsynopsis with text is not supported.</xsl:message></xsl:if>
     148    <xsl:text>    </xsl:text>
     149    <xsl:apply-templates select="node()|@*"/>
     150  </xsl:template>
     151
     152  <xsl:template match="command">
     153    <!--xsl:choose>
     154      <xsl:when test=" ">
     155    </xsl:choose-->
     156    <xsl:apply-templates select="node()|@*"/>
     157  </xsl:template>
     158
     159  <xsl:template match="replaceable">
     160    <xsl:text>&lt;</xsl:text>
     161    <xsl:apply-templates select="text()|node()|@*"/>
     162    <xsl:text>&gt;</xsl:text>
     163  </xsl:template>
     164
     165  <xsl:template match="arg|group">
     166    <!-- separator char if we're not the first child -->
     167    <xsl:if test="position() > 1">
     168      <xsl:choose>
     169        <xsl:when test="ancestor-or-self::*/@sepchar"><xsl:value-of select="ancestor-or-self::*/@sepchar"/></xsl:when>
     170        <xsl:otherwise><xsl:text> </xsl:text></xsl:otherwise>
     171      </xsl:choose>
     172    </xsl:if>
     173    <!-- open wrapping -->
     174    <xsl:choose>
     175      <xsl:when test="@choice = 'opt' or not(@choice) or @choice = ''"> <xsl:text>[</xsl:text></xsl:when>
     176      <xsl:when test="@choice = 'req'">                                 <xsl:text></xsl:text></xsl:when>
     177      <xsl:when test="@choice = 'plain'"/>
     178      <xsl:otherwise><xsl:message terminate="yes">Invalid arg choice: "<xsl:value-of select="@choice"/>"</xsl:message></xsl:otherwise>
     179    </xsl:choose>
     180    <!-- render the arg (TODO: may need to do more work here) -->
     181    <xsl:apply-templates />
     182    <!-- repeat wrapping -->
     183    <xsl:choose>
     184      <xsl:when test="@rep = 'norepeat' or not(@rep) or @rep = ''"/>
     185      <xsl:when test="@rep = 'repeat'">                                 <xsl:text>...</xsl:text></xsl:when>
     186      <xsl:otherwise><xsl:message terminate="yes">Invalid rep choice: "<xsl:value-of select="@rep"/>"</xsl:message></xsl:otherwise>
     187    </xsl:choose>
     188    <!-- close wrapping -->
     189    <xsl:choose>
     190      <xsl:when test="@choice = 'opt' or not(@choice) or @choice = ''"> <xsl:text>]</xsl:text></xsl:when>
     191      <xsl:when test="@choice = 'req'">                                 <xsl:text></xsl:text></xsl:when>
     192    </xsl:choose>
     193  </xsl:template>
     194
     195  <!-- non-breaking strings -->
     196  <xsl:template match="command/text()">
     197    <xsl:call-template name="str:subst">
     198      <xsl:with-param name="text" select="."/>
     199      <xsl:with-param name="replace" select="' '"/>
     200      <xsl:with-param name="with" select="'\b'"/>
     201      <xsl:with-param name="disable-output-escaping" select="yes"/>
     202    </xsl:call-template>
     203  </xsl:template>
    55204
    56205

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

    r56171 r56208  
    3333
    3434  <refsynopsisdiv>
    35     <cmdsynopsis><remark role="usage"/>
     35    <cmdsynopsis id="synopsis-vboxmanage-extpack-install"> <!-- The 'id' is mandatory and must start with 'synopsis-'. -->
    3636      <command>VBoxManage extpack install</command>
    3737      <arg>--replace</arg>
    3838      <arg choice="req"><replaceable>tarball</replaceable></arg>
    3939    </cmdsynopsis>
    40     <cmdsynopsis><remark role="usage"/>
     40    <cmdsynopsis id="synopsis-vboxmanage-extpack-uninstall">
    4141      <command>VBoxManage extpack uninstall</command>
    4242      <arg>--force</arg>
    4343      <arg choice="req"><replaceable>name</replaceable></arg>
    4444    </cmdsynopsis>
    45     <cmdsynopsis><remark role="usage"/>
     45    <cmdsynopsis id="synopsis-vboxmanage-extpack-cleanup">
    4646      <command>VBoxManage extpack cleanup</command>
    4747    </cmdsynopsis>
Note: See TracChangeset for help on using the changeset viewer.

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