<list> with type="definition" fails to render

Topics: User Forum
Dec 24, 2009 at 7:21 PM

Comparing my original ndoc output with my candidate SHFB output, I notice that the <list> element renders correctly for type = "number' or "bullet" but not for "definition". There are no warnings or messages in the log file and there is no trace of any block-level formatting in the generated HTML. (That is, the text is all there but it is run together in a paragraph rather than formatted as a list.) Here is an example doc-comment fragment from a C# file:

    /// The available attributes are:
    /// <list type="definition">
    /// <item>
    /// <term>maxLen</term>
    /// <description>field must contain no more than the specified number
    /// of characters
    /// </description>
    /// </item>
    /// <item>
    /// <term>minLen</term>
    /// <description>field must contain at least the specified number
    /// of characters
    /// </description>
    /// </item>
    /// <item>
    /// <term>maxVal</term>
    /// <description>field must contain a number that is no larger than the
    /// specified value
    /// </description>
    /// </item>
    /// <item>
    /// <term>minVal</term>
    /// <description>field must contain a number that is no smaller than the
    /// specified value
    /// </description>
    /// </item>
    /// <item>
    /// <term>pattern</term>
    /// <description>field must match the specified regular expression
    /// </description>
    /// </item>
    /// </list>

 

Coordinator
Dec 24, 2009 at 8:36 PM
Edited Dec 24, 2009 at 8:38 PM

It must have gotten overlooked in the Sandcastle transformations.  It isn't listed as a parameter option on the list tag's MSDN page but the comments do reference a definition list.  You can add support for it by adding the following XSL template to the transforms\main_sandcastle.xsl file in each of the three main presentation style file folders under C:\Program Files\Sandcastle\Presentation.  Search for "list[@type='bullet']" and insert it after the other list templates:

<xsl:template match="list[@type='definition']">
  <dl class="authored">
    <xsl:for-each select="item">
      <dt><xsl:apply-templates select="term" /></dt>
      <dd><xsl:apply-templates select="description" /></dd>
    </xsl:for-each>
  </dl>
</xsl:template>

I'll be releasing an update to the Sandcastle Styles patch soon and will include it in there.

Eric

 

Dec 26, 2009 at 12:49 AM

Thanks for that patch, Eric. I have not tried it yet but found another related one that you will need to include in your Sandcastle Styles update. I found an instance of a list with type=bullet that also uses the //item/term and //item/description and those were also missing any formatting. So your above XSLT template would probably be better served by matching any list type.

 

Coordinator
Dec 26, 2009 at 7:40 PM

The term element is only useful within a definition list.  For bullet and numbered lists, it just renders each child element as a separate item and only the description is needed since there's no purpose in rendering a term.  The table type renders each child element as a cell and it'll render as many cells as there are child elements within the item element.  The way Sandcastle's transformations are written, it doesn't care whether you use a term or description element in those cases but typically, you use a description element as shown in the MSDN help topic for the list element.

Eric

 

Dec 28, 2009 at 2:33 PM

I realize that, as the spec states, "...a definition list... needs to specify both term and description... while a table, bulleted list, or numbered list, only needs ...a description." But what if one does include a term and a description in a bulleted list? Ndoc makes a better choice than SandCastle in this instance, following the best practice of doing something useful with the inputs provided (specifically, it starts with a bullet, then the term in bold, adds a dash, and concludes with the description, all on one line). Sandcastle, on the other hand, ignores the tag, just rendering the text of the term followed by the description.

I could patch this on my local copy, of course, but I am hoping that my completely unremarkable powers of persuasion :-) might convince you to add this bell (or is it a whistle?) to SHFB.

(BTW, is there a FAQ entry that provides guidelines for what might be a SandCastle question vs. an SHFB question? I do not yet have a feel where the separation lies...)

Coordinator
Dec 28, 2009 at 7:39 PM

Fair enough.  You can implement term support by replacing the "<li>" section of the bullet and number list type templates with the following:

<li>
  <xsl:if test="term">
    <b><xsl:apply-templates select="term" /></b><xsl:text> - </xsl:text>
  </xsl:if>
  <xsl:apply-templates select="description" />
</li>

I didn't bother with the table type since it renders the child elements in cells anyway and additional formatting probably isn't needed.  I'll make the changes in the Sandcastle Styles patch too.

There isn't a FAQ entry that defines what's part of Sandcastle and what's part of SHFB.  In general, if it concerns the layout of the topics, formatting, or how the XML comment and MAML elements are interpretted and rendered, it's usually a Sandcastle feature implemented in the XSL transformations or one of the components.  SHFB drives the various Sandcastle tools and supplies it the options defined in the project.  Anything that happens outside of the build is SHFB related (i.e. project management, designer support, etc).  Within the build, when it runs the external tools MRefBuilder, XslTransform, and BuildAssembler, their the Sandcastle tools.  All other build steps are part of SHFB with the exception of the steps that run the help compilers.  Sometimes, the line is blurred since SHFB supplies various extension components that the Sandcastle tools utilize (i.e. the components for code colorization, adding a logo, etc in the BuildAssembler step).

You can always ask here first.  If it's a problem in Sandcastle that can't be fixed by updating the transformations, I'll refer you to the Sandcastle project to open a work item there.

Eric