Custom Tag - RevisionHistory (for VS2010)

Topics: Developer Forum
Apr 11, 2014 at 2:48 PM
Hi Eric,

I added support for the "RevisionHistory" custom tag to my SFHB Version 2014.15.2.0 Beta setup, and thought I would share with the group in case anyone else utilized this functionality - or if you would like to inlcude it in the next release of SHFB.

This tag originated from the old NDoc and VBCommenter days, but is still useful today to communicate class | method | property revision history in the output documentation.

The Revision History output is displayed toward the bottom of the document, immediately before the "See Also" section.

Tag Syntax

    /// <revisionHistory>
    ///     <revision date="2014/04/11" version="9.0.1.0" author="THLUCAS">
    ///         This revision will be displayed since the "visible" attribute is not present (ie default).
    ///     </revision>
    ///     <revision date="2014/04/11" version="9.0.1.0" author="THLUCAS" visible="true">
    ///         This revision will be displayed due to it's "visible=true" attribute setting.
    ///     </revision>
    ///     <revision date="2014/04/11" version="9.0.1.0" author="THLUCAS" visible="false">
    ///         This revision will NOT be displayed due to it's "visible=false" attribute setting.
    ///     </revision>
    ///     <revision date="2014/04/11" version="9.0.1.0" author="THLUCAS">
    ///         This revision will be displayed since the "visible" attribute is not present (ie default).
    ///         It is also an extremely long line of text, which will test the styling of the revision
    ///         history table entries, to ensure that it utilizes the entire width of the screen when
    ///         the help document is resized.  Hopefully this will be enough text to display, as I am
    ///         quickly running out of phrases that will make this paragraph a little bit longer!
    ///     </revision>
    /// </revisionHistory>

RevisionHistory Attributes

visible [true|false] - controls visibility of the entire comment block. An omitted value defaults to "true". If not displayed, no "Revision History" title is displayed, nor any revision entries.

Revision Child Attributes

visible [true|false] - controls visibility of the comment. An omitted value defaults to "true".

date <string> - date when the revision was made. This is treated as a string field, and displayed as-is in the documentation output - ie no local date formatting is applied.

version <string> - version that the revision was applied for.

author <string> - author that applied the revision. this value is not displayed in the documentation output

SHFB File Changes

\presentationStyles\VS2010\Transforms\main_sandcastle.xsl

Add the following XSL to the "Global variables" section.
  <xsl:variable name="g_hasRevisionHistorySection"
        select="boolean((count(/document//revisionHistory) > 0))"/>
Add the following XSL just before the "<!-- bibliography -->" line item.
    <!-- revisions -->
    <xsl:call-template name="t_revisionHistory"/>
Add the following XSL after the "t_autogenBibliographyLinks" template listing.
  <!-- Revision History information template processing. -->
  <xsl:template name="t_revisionHistory" match="revisionHistory" >
    <xsl:if test="$g_hasRevisionHistorySection">
      <xsl:if test="not(/document//revisionHistory[@visible='false'])">
        <a name="revisionHistorySection"><!----></a>
        <div class="OH_CollapsibleAreaRegion">
          <div class="OH_regiontitle">Revision History</div>
          <div class="OH_CollapsibleArea_HrDiv">
            <hr class="OH_CollapsibleArea_Hr" />
          </div>
        </div>
        <div class="OH_clear"></div>
        <table class="header" cellspacing="0" width="100%" >
          <tr valign="top">
            <th width="10%">Date</th>
            <th width="10%">Version</th>
            <th width="80%">Description</th>
          </tr>
          <xsl:call-template name="t_revisionHistoryRevision"/>
        </table>
      </xsl:if>
    </xsl:if>
  </xsl:template>

  <xsl:template name="t_revisionHistoryRevision">
    <xsl:for-each select="/document//revisionHistory/revision">
      <xsl:if test="not(@visible='false')">
        <tr valign="top">
          <td>
            <xsl:value-of select="@date"/>
          </td>
          <td>
            <xsl:value-of select="@version"/>
          </td>
          <td>
            <xsl:apply-templates select="." mode="slashdoc"/>
          </td>
        </tr>
      </xsl:if>
    </xsl:for-each>
  </xsl:template>
Enjoy!
Coordinator
Apr 11, 2014 at 7:26 PM
Thanks for the contribution. I'm in the process of reworking the VS2010 style to get rid of the branding stuff so I'll merge your changes in while I'm at it.

Eric
Coordinator
May 24, 2014 at 11:00 PM
I've added support for the revision history section to the VS2005, VS2010, and VS2013 presentation styles for the next release.

Eric