VirtualBox

Changeset 99191 in vbox


Ignore:
Timestamp:
Mar 28, 2023 8:46:22 AM (19 months ago)
Author:
vboxsync
Message:

manual: More work on the refentry to dita converter - I forgot how much fun white space can be... bugref:10302

Location:
trunk/doc/manual
Files:
2 edited

Legend:

Unmodified
Added
Removed
  • trunk/doc/manual/docbook-refentry-to-manual-dita-pre.xsl

    r99099 r99191  
    3838
    3939  <xsl:output method="xml" version="1.0" encoding="utf-8" indent="yes"/>
    40   <xsl:strip-space elements="*"/>
     40  <xsl:preserve-space elements="*"/>
    4141
    4242
    4343<!-- - - - - - - - - - - - - - - - - - - - - - -
    44   base operation is to copy.
     44  base operation is to copy everything except for comments.
    4545 - - - - - - - - - - - - - - - - - - - - - - -->
    4646
     
    5151</xsl:template>
    5252
     53<xsl:template match="comment()"/>
    5354
    5455<!--
  • trunk/doc/manual/docbook-refentry-to-manual-dita.xsl

    r99181 r99191  
    3636
    3737  <xsl:output method="xml" version="1.0" encoding="utf-8" indent="no"/>
    38   <xsl:strip-space elements="*"/>
     38  <xsl:preserve-space elements="*"/>
     39  <!-- xsl:strip-space elements="*"/ - never -->
    3940
    4041
     
    276277                to condense stuff any more inside synblk elements, but then the
    277278                rending isn't much changed for PDFs anyway since its one element
    278                 per line.    -->
     279                per line.
     280           Update: Turns out the condensing was because we stripped element
     281                   whitespace instead of preserving it. svn copy. sigh. -->
    279282      <!-- <xsl:element name="synblk">
    280283        <xsl:attribute name="rev">sbr/<xsl:value-of select="position()"/></xsl:attribute> -->
     
    358361
    359362<!--
    360    arg -> groupseq; A bit complicated though...
     363   arg -> groupseq; A bit complicated though, because text needs to be wrapping
     364   in 'kwd' and any nested arguments needs explicit 'sep' elements containing a
     365   space or the nested arguments gets bunched up tight.
     366   Examples:
     367      {arg}-output={replaceable}file{/replaceable}{/arg}
     368    = {groupcomp importance="optional"}{kwd}-output{/kwd}{sep}={/sep}{var}file{/var}{/groupcomp}
     369
     370      {arg}-output {replaceable}file{/replaceable}{/arg}
     371    = {groupcomp importance="optional"}{kwd}-output{/kwd}{sep} {/sep}{var}file{/var}{/groupcomp}
     372
     373      {arg}-R {arg}-L{/arg}{/arg}
     374    = {groupseq importance="optional"}{groupcomp}{kwd}-R{/groupcomp}{sep} {/sep}
     375   or {groupseq importance="optional"}{kwd}-R{sep} {/sep}{groupcomp}{kwd}-L{/groupcomp}{/groupseq}
     376      note: Important to specify {sep} here as whitespace might otherwise be squashed.
    361377-->
    362378
    363379<!-- Plaintext within arg is generally translated to kwd, but value separators
    364      like '=' and ',' should be wrapped in a sep element. -->
     380     like '=' and ',' should be wrapped in a delim element. -->
    365381<xsl:template match="arg/text()">
    366382  <xsl:choose>
     383    <!-- put trailing '=' inside <sep> -->
    367384    <xsl:when test="substring(., string-length(.)) = '='">
    368385      <xsl:element name="kwd">
     
    370387        <xsl:value-of select="substring(., 1, string-length(.) - 1)"/>
    371388      </xsl:element>
    372       <xsl:element name="sep">
     389      <xsl:element name="delim">
    373390        <xsl:attribute name="rev">arg=</xsl:attribute>
    374391        <xsl:text>=</xsl:text>
     
    376393    </xsl:when>
    377394
     395    <!-- Special case, single space, assuming it's deliberate so put in inside a sep element. -->
     396    <xsl:when test=". = ' '">
     397      <xsl:element name="sep">
     398        <xsl:attribute name="rev">arg-space</xsl:attribute>
     399        <xsl:value-of select="."/>
     400      </xsl:element>
     401    </xsl:when>
     402
     403    <!-- Don't wrap other pure whitespace kwd sequences, but emit single space 'sep'
     404         element if a arg or groups follows.  If the whitespace includes a newline
     405         we'll emit it, but otherways we'll generally suppress it to avoid
     406         accidentally padding spaces between arguments.  -->
     407    <xsl:when test="normalize-space(.) = ''">
     408      <xsl:if test="following::*[position() = 1 and (self::arg or self::group)] and not(ancestor-or-self::*[@role='compact'])">
     409        <xsl:element name="sep">
     410          <xsl:attribute name="rev">arg-whitespace</xsl:attribute>
     411          <xsl:text> </xsl:text>
     412        </xsl:element>
     413      </xsl:if>
     414      <xsl:if test="contains(., '&#10;')">
     415        <xsl:value-of select="."/>
     416      </xsl:if>
     417    </xsl:when>
     418
     419    <!-- Remainder is all wrapped in kwd, after space normalization. -->
    378420    <xsl:otherwise>
    379421      <xsl:element name="kwd">
    380422        <xsl:attribute name="rev">arg</xsl:attribute>
    381         <xsl:value-of select="."/>
     423        <xsl:value-of select="normalize-space(.)"/>
    382424      </xsl:element>
     425      <xsl:if test="normalize-space(substring(., string-length(.), 1)) = ''
     426                and following::*[position() = 1 and (self::arg or self::group)]
     427                and not(ancestor-or-self::*[@role='compact'])">
     428        <xsl:element name="sep">
     429          <xsl:attribute name="rev">arg-trailing</xsl:attribute>
     430          <xsl:text> </xsl:text>
     431        </xsl:element>
     432      </xsl:if>
    383433    </xsl:otherwise>
    384434  </xsl:choose>
    385435</xsl:template>
    386436
    387 <!-- arg -> groupseq and optionally a repsep element if repeatable. -->
     437<!-- arg -> groupseq or groupcomp and optionally a repsep element if repeatable. -->
    388438<xsl:template match="arg" >
    389   <xsl:element name="groupseq">
     439  <!-- If it's a tighly packed arg, we use groupcomp instead of groupseq to try
     440       avoid it being split in the middle. -->
     441  <xsl:variable name="sGroupType">
     442    <xsl:call-template name="determine_arg_wrapper_element"/>
     443  </xsl:variable>
     444  <xsl:element name="{$sGroupType}">
    390445    <xsl:attribute name="rev">arg[<xsl:value-of select="concat(@choice,',',@rep)"/>]</xsl:attribute>
    391446    <xsl:choose>
     
    409464           PDF output plugin will place the '...' where it finds it and do
    410465           nothing if it's empty.  The XHTML output plugin ignores it, it seems. -->
    411       <xsl:text> </xsl:text>
    412       <xsl:element name="groupseq">
     466      <xsl:element name="sep">
     467        <xsl:attribute name="rev">arg[<xsl:value-of select="@choice"/>,repeat]</xsl:attribute>
     468        <xsl:text> </xsl:text>
     469      </xsl:element>
     470      <xsl:element name="groupcomp">
    413471        <xsl:attribute name="importance">optional</xsl:attribute>
    414472        <xsl:attribute name="rev">arg[<xsl:value-of select="@choice"/>,repeat]</xsl:attribute>
     
    428486</xsl:template>
    429487
     488<xsl:template name="determine_arg_wrapper_element">
     489  <xsl:choose>
     490    <xsl:when test="not(descendant::group) and not(descendant::text()[contains(.,' ') or normalize-space(.) != .])">
     491      <xsl:text>groupcomp</xsl:text>
     492    </xsl:when>
     493    <xsl:otherwise>
     494      <xsl:text>groupseq</xsl:text>
     495    </xsl:otherwise>
     496  </xsl:choose>
     497</xsl:template>
     498
    430499<!-- Plain (required) argument in group with only text() content -> kwd; -->
    431500<!--
     
    473542</xsl:template>
    474543
    475 <!-- Plain group under arg or cmdsynopsis -> groupchoice w/o importance attrib -->
    476 <xsl:template match="arg/group[@choice='plain'] | cmdsynopsis/group[@choice='plain']">
     544<!--
     545    DocBook 'group' elements are only ever used for multiple choice options
     546    in our refentry XML, it is never used for argument groupings.  For
     547    grouping arguments we use nested 'arg' elements.
     548
     549    This is because 'group' with 'group' parent is poorly defned/handled.
     550    Whether the DocBook HTML formatters uses ' | ' separators depends on what
     551    other elements are in the group and their order. arg1+group2+group3 won't
     552    get any, but group1+arg2+group3 will get one between the first two.
     553-->
     554
     555<xsl:template match="group[group]" priority="3.0">
     556  <xsl:message terminate="yes">
     557    <xsl:call-template name="error-prefix"/>Immediate group nesting is not allowed! Put nested group inside arg element.
     558  </xsl:message>
     559</xsl:template>
     560
     561<xsl:template match="group[count(arg) &lt; 2]" priority="3.0">
     562  <xsl:message terminate="yes">
     563    <xsl:call-template name="error-prefix"/>Group with fewer than two 'arg' elements is not allowed!
     564  </xsl:message>
     565</xsl:template>
     566
     567<!-- Required group under arg or cmdsynopsis -> groupchoice w/attrib -->
     568<xsl:template match="arg/group | cmdsynopsis/group">
    477569  <xsl:element name="groupchoice">
    478     <xsl:attribute name="rev">group[plain]</xsl:attribute>
    479     <xsl:apply-templates />
    480   </xsl:element>
    481 
    482   <xsl:if test="@rep and @rep!='norepeat'">
    483     <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>Not implemented: Repeating plain group</xsl:message>
    484   </xsl:if>
    485 </xsl:template>
    486 
    487 <!-- Required group under arg or cmdsynopsis -> groupchoice w/attrib -->
    488 <xsl:template match="arg/group[@choice='req'] | cmdsynopsis/group[@choice='req']">
    489   <xsl:element name="groupchoice">
    490     <xsl:attribute name="rev">group[req]</xsl:attribute>
    491     <xsl:attribute name="importance">required</xsl:attribute>
    492 
    493     <!-- This doesn't really work. Sigh. -->
     570    <xsl:choose>
     571      <xsl:when test="@choice = 'req'">
     572        <xsl:attribute name="rev">group[req]</xsl:attribute>
     573        <xsl:attribute name="importance">required</xsl:attribute>
     574      </xsl:when>
     575      <xsl:when test="@choice = 'plain'">
     576        <xsl:attribute name="rev">group[plain]</xsl:attribute>
     577        <!-- We don't set the importance here. @todo Check what it does to the output formatting -->
     578      </xsl:when>
     579      <xsl:otherwise>
     580        <xsl:attribute name="rev">group[opt]</xsl:attribute>
     581        <xsl:attribute name="importance">optional</xsl:attribute>
     582      </xsl:otherwise>
     583    </xsl:choose>
     584
     585    <xsl:apply-templates />
     586
    494587    <xsl:if test="@rep = 'repeat'">
    495       <xsl:element name="repsep">
    496         <xsl:attribute name="rev">group[req,repeat]</xsl:attribute>
    497         <xsl:text>...</xsl:text>
     588      <!-- repsep can only be placed at the start of a groupseq/whatever and
     589           the documenation and examples of the element is very sparse.  The
     590           PDF output plugin will place the '...' where it finds it and do
     591           nothing if it's empty.  The XHTML output plugin ignores it, it seems. -->
     592      <xsl:message terminate="no"><xsl:call-template name="error-prefix"/>Repeating group is not a good idea...</xsl:message>
     593      <xsl:element name="sep">
     594        <xsl:attribute name="rev">arg[<xsl:value-of select="@choice"/>,repeat]</xsl:attribute>
     595        <xsl:text> </xsl:text>
    498596      </xsl:element>
    499     </xsl:if>
    500 
    501     <xsl:apply-templates />
    502   </xsl:element>
    503 </xsl:template>
    504 
    505 <!-- Optional group under arg or cmdsynopsis -> groupchoice w/attrib -->
    506 <xsl:template match="cmdsynopsis/group[(@choice='opt' or not(@choice))]" >
    507   <xsl:if test="not(./arg[@choice='plain'])">
    508     <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>Did not expect group[@choice=opt] to have children other than arg[@choice=plain]:
    509       <xsl:for-each select="node()"><xsl:value-of select="concat(' ', name())"/>[@choice=<xsl:value-of select="@choice"/>]</xsl:for-each>
    510     </xsl:message>
    511   </xsl:if>
    512 
    513   <xsl:element name="groupchoice">
    514     <xsl:attribute name="rev">group[opt]</xsl:attribute>
    515     <xsl:attribute name="importance">optional</xsl:attribute>
    516     <xsl:apply-templates />
    517   </xsl:element>
    518 
    519   <xsl:if test="@rep and @rep!='norepeat'">
    520     <xsl:message terminate="yes"><xsl:call-template name="error-prefix"/>Not implemented: Repeating optional group</xsl:message>
    521   </xsl:if>
     597      <xsl:element name="groupcomp">
     598        <xsl:attribute name="importance">optional</xsl:attribute>
     599        <xsl:attribute name="rev">arg[<xsl:value-of select="@choice"/>,repeat]</xsl:attribute>
     600        <xsl:attribute name="outputclass">repeatarg</xsl:attribute> <!-- how to make xhtml pass these thru... -->
     601        <xsl:element name="repsep">
     602          <xsl:attribute name="rev">arg[<xsl:value-of select="@choice"/>,repeat]</xsl:attribute>
     603          <xsl:text>...</xsl:text>
     604        </xsl:element>
     605      </xsl:element>
     606    </xsl:if>
     607  </xsl:element>
    522608</xsl:template>
    523609
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