codeExample code display

Apr 15, 2008 at 3:36 PM
Usig the <code> element with "language" (or even "lang") attribute, I cannot produce the language name at the LH end of the title bar of the light blue code section - the code is otherwise displayed ok.

Example xml:
...
<code language="c#">
// some code
</code>
</content>

I have tried other language names with no effect and am using the very helpful guidelines by Paul Selormey at http://www.codeproject.com/KB/winhelp/SandcastleConceptual.aspx

It is a smallish issue, but I need this display of the language, for max clarity

TIA,

James.
Editor
Apr 15, 2008 at 4:19 PM
Edited Apr 15, 2008 at 4:33 PM
It looks like the language attribute works in API content when using the VS2005 style but is broken in both the Hana and Prototype styles. It could be that it's not working correctly in conceptual content either. The Code Block Component in the Standalone Build Components can add a title among other things. It should work in conceptual content too but I haven't tried it yet.

Eric
Apr 15, 2008 at 5:51 PM
Hi James,

For Sandcastle conceptual content, your choices are (case-insensitive): visualbasic, csharp, managedcplusplus, jsharp, or jscript.

The first three options also provide automatic code colorization.

- Dave
Apr 15, 2008 at 5:51 PM

jxstewart wrote:
Usig the <code> element with "language" (or even "lang") attribute, I cannot produce the language name at the LH end of the title bar of the light blue code section - the code is otherwise displayed ok.


I am currently writing my documentations using the conceptual help. The "language" attribute works correctly, and I have compiled my help several times today. I only use the VS2005 style, since that is the only tested style for conceptual help
by the Sandcastle team.

That said, which style are you using?

Best regards,
Paul.
Apr 15, 2008 at 6:07 PM
Edited Apr 15, 2008 at 6:45 PM

davedev wrote:
For Sandcastle conceptual content, your choices are (case-insensitive): visualbasic, csharp, managedcplusplus, jsharp, or jscript.

The first three options also provide automatic code colorization.

If you are refering to the ExampleComponent support for colorization, your statement is not applicable. That component is used to render the codeReference not the code tag. In fact, that is actually meant for code snippet saved in files. The use of the code snippet is similar to the "media arts" in a file format:

<examples file="Your Snippets File"/>
<examples file="Your Snippets File"/>

Best regards,
Paul.
Apr 15, 2008 at 6:09 PM
Hi Paul,

You are correct. Actually, DocProject provides support for ExampleComponent in the next release. I've never used the <code> element myself since I prefer to keep examples external.

- Dave
Apr 15, 2008 at 6:12 PM
Hi Paul,

Your markup example appears to be incorrect though. Here's the template that DocProject uses in the next release, which includes a description of its usage:

<?xml version="1.0" encoding="utf-8" ?>
<!-- Overview
 
  This file is referenced by ExampleComponent in the conceptual configuration files, which are 
  located in Help\Presentation\Style\Configuration\.
  
  You can add additional example snippet files by registering them with ExampleComponent: 
  
  <examples file="..\..\Help\Settings\additional_snippets.xml"/> 
-->
 
<!-- About Examples and Snippets
 
  Example snippets allow you to define code samples outside of conceptual topic files.  An example
  can be referenced by an ID in multiple topics so that they don't have to be copied or rewritten.
  
  Automatic colorization and language filter synchronization is supported by specifying a language 
  identifier on code samples: VisualBasic, CSharp, ManagedCPlusPlus, JSharp, or JScript.
  
  You can add custom colorization rules to ExampleComponent and adjust Help\Styles\Presentation.css
  to apply different styles.
-->
 
<!-- Examples
 
  To use the following examples, add them to the root <examples> element of this file.
  
  <item id="ClassDefinition#1">
    <sampleCode language="CSharp">
      public sealed partial class MyClass() {
      }
    </sampleCode>
    <sampleCode language="VisualBasic">
      Public NotInheritable Partial Class MyClass
      End Class
    </sampleCode>
  </item>
  
  <item id="DimVariable#String">
    <sampleCode language="CSharp">
      string variable = "Hello, World";
    </sampleCode>
    <sampleCode language="VisualBasic">
      Dim variable As String = "Hello, World"
    </sampleCode>
  </item>
  
  <item id="DimVariable#Int32">
    <sampleCode language="CSharp">
      int variable = 21;
    </sampleCode>
    <sampleCode language="VisualBasic">
      Dim variable As Integer = 21
    </sampleCode>
  </item>
 
  An item ID is a case-sensitive string that consists of an example ID, a hash (#) and a snippet ID.
  All parts of the ID are required.
  
  The language attribute is a case-sensitive identifier that is defined in the presentation style
  itself.  By default, you can choose from VisualBasic, CSharp, ManagedCPlusPlus, JSharp, or JScript.
-->
 
<!-- Example Usage
 
  The ClassDefinition example consists of only a single snippet (#1) in multiple languages.
  Here's how to reference it in a conceptual topic: 
  
  <codeReference>ClassDefinition#1</codeReference>
  
  DimVariable is an example that consists of multiple snippets (String and Int32).
  Here's how to reference the String snippet: 
  
  <codeReference>DimVariable#String</codeReference>
  
  Here's how to generate a code sample of both DimVariable snippets combined: 
  
  <codeReference>DimVariable#String,Int32</codeReference>
  
  The following reference is invalid because the snippet ID is missing: 
  
  <codeReference>DimVariable</codeReference>    ** invalid **
-->
<examples>
  <!-- TODO: Add <item> elements that contain language-specific code snippets -->
  <item id="ClassDefinition#1">
    <sampleCode language="CSharp">
      public sealed partial class MyClass() {
      }
    </sampleCode>
    <sampleCode language="VisualBasic">
      Public NotInheritable Partial Class MyClass
      End Class
    </sampleCode>
  </item>
 
  <item id="DimVariable#String">
    <sampleCode language="CSharp">
      string variable = "Hello, World";
    </sampleCode>
    <sampleCode language="VisualBasic">
      Dim variable As String = "Hello, World"
    </sampleCode>
  </item>
 
  <item id="DimVariable#Int32">
    <sampleCode language="CSharp">
      int variable = 21;
    </sampleCode>
    <sampleCode language="VisualBasic">
      Dim variable As Integer = 21
    </sampleCode>
  </item>
 
</examples>
- Dave
Apr 15, 2008 at 6:12 PM

EWoodruff wrote:
The Code Block Component in the Standalone Build Components can add a title among other things. It should work in conceptual content too but I haven't tried it yet.


It will not work.

The conceptual file output or layout is different, and the simple implementation provided by the Code Block Component will not work. You will need a component that uses XPathNavigator. Also, currently there is not pass through support for "html" tags in conceptual help, so you will have to use the existing tags to get through.

Best regards,
Paul.
Apr 15, 2008 at 6:26 PM


davedev wrote:
You are correct. Actually, DocProject provides support for ExampleComponent in the next release. I've never used the <code> element myself since I prefer to keep examples external.


That is one component I will personally not used in my documentations. Keeping the examples external is a good practice, but I do not think the current ExampleComponent is a good support of the idea since it loads all snippets files and parsed all into memory. I restrict my developer machines to 1.5 GB max.

Best regards,
Paul.
Apr 15, 2008 at 6:29 PM
That's too bad. I've found it to be very useful.

- Dave
Apr 15, 2008 at 6:34 PM


davedev wrote:
Your markup example appears to be incorrect though.

Right, it contains some personal tags. I have removed them.

Best regards,
Paul.
Apr 17, 2008 at 11:35 AM

I am currently writing my documentations using the conceptual help. The "language" attribute works correctly, and I have compiled my help several times today. I only use the VS2005 style, since that is the only tested style for conceptual help
by the Sandcastle team. That said, which style are you using?

Today, I can see only the "C#" heading (with language="c#" attribute) but no others that I am using, like "xml" or "html". I assume that I should NOT have 'colourisation' and that the actual code format is irrelevant (I do use pseudo-code for some things, for a simpler appearance). xml and html are in CDATA sections.

Excuse ignorance, but how do I check which style I am using, or where is that setting?

Thanks

James.
Apr 17, 2008 at 12:30 PM
Hi James,


Today, I can see only the "C#" heading (with language="c#" attribute) but no others that I am using, like "xml" or "html"

That's because there is no support for XML or HTML as a heading. I already mentioned that your choices are: visualbasic, csharp, managedcplusplus, jsharp, or jscript.

To add support for XML or HTML you must update the codeSection template in the presentation's globalTemplates.xsl file and then add a new content item that provides a display string for the new codeLang.

Here's the relevant portion of globalTemplates.xsd that you must update:
<xsl:if test="$codeLangLC='visualbasic' or $codeLangLC='csharp' or $codeLangLC='managedcplusplus' or $codeLangLC='jsharp' or $codeLangLC='jscript'
  or $codeLangLC='xml' or $codeLangLC='html'">
  <include item="{$codeLang}"/>
</xsl:if>
And here's the new content item that you must add to the presentation style's shared_content.xml file, preferably in the devLangs filter section:

<item id="xml">xml</item>
NOTE: An item for html already exists in that section.


I assume that I should NOT have 'colourisation'

I believe that we should, but you're correct in believing that you won't :)


the actual code format is irrelevant

Correct.


Excuse ignorance, but how do I check which style I am using, or where is that setting?

If you're building conceptual help then you're probably using VS 2005, but to find out it depends on which tool that you're using to build the documentation.

If you're using DocProject, you selected the presentation style when you first created your project in VS and you can view your selection now in the DocProject Properties window under the Presentation category. If you're using SHFB, I believe that there's an option to change the presentation style, so just see which one you have selected. For other tools, refer to their documentation.

If you're building on the command-line then you're probably setting the presentation style in your command.

- Dave
Apr 17, 2008 at 2:14 PM

Thanks for the useful info on globalTemplates.xsl (though you said "xsd"). I had tested "csharp" before, and again today with no string resulting in the code panel header - also I am using a <code> tag which you said you don't use. The attribute value "c#" is working though. I note that the string "c#" does not occur in this xsl file, so I guess I am not using that transform.
For building, I use Paul's very useful CodeProject article http://www.codeproject.com/KB/winhelp/SandcastleConceptual.aspx

What confuses me at present is that the download from this article includes manual.chm (Paul's sample project output) which has the whole gamut of code-types shown, "xml", html" and all.

I shall continue investigations...

James.
Apr 17, 2008 at 3:50 PM
Edited Apr 17, 2008 at 3:52 PM
Hi James,

Yes, you are correct that I don't actually use the <code> element in my own documentation, which is why the values that I mentioned aren't working for you. My apologies :)

I just ran a test and I was able to reproduce the same results as you.

You can find the XSL template that matches ddue:code in utilities_dduexml.xsl. Note that all of the values that appear in IntelliSense for the language attribute seem to be handled by this template.

However, the template calls the codeSection template, which is found in globalTemplates.xsl. Unfortunately, codeSection doesn't handle some values: VBscript, xmlLang, HTML, visualbasicANDcsharp and XAML.

You can fix the codeSection by updating the xsl:if element so that it looks like this:

<xsl:if test="$codeLangLC='visualbasic' or $codeLangLC='csharp' or $codeLangLC='managedcplusplus' or $codeLangLC='jsharp' or $codeLangLC='jscript'
              or $codeLangLC='vbscript' or $codeLangLC='xmllang' or $codeLangLC='html' or $codeLangLC='visualbasicandcsharp' or $codeLangLC='xaml'">                  
    <include item="{$codeLang}"/>
</xsl:if>
I tried the following test with the changes applied:

            <code language="cpp">cpp</code>
            <code language="vb">vb</code>
            <code language="vbs">vbs</code>
            <code language="js">js</code>
            <code language="c#">c#</code>
            <code language="j#">j#</code>
            <code language="jscript#">jscript#</code>
            <code language="cpp#">cpp#</code>
            <code language="vb#">vb#</code>
            <code language="xml">xml</code>
            <code language="html">html</code>
            <code language="unstlib">unstlib</code>
            <code language="minterastlib">minterastlib</code>
            <code language="mintraastlib">mintraastlib</code>
            <code language="vb-c#">vb-c#</code>
            <code language="jscript">jscript</code>
            <code language="scr">scr</code>
            <code language="xaml">xaml</code>
Most of the code blocks had titles, although since the utilities_dduexml.xsl transformation doesn't handle unstlib, minterastlib, mintraastlib and scr, only these code blocks didn't. (Edit: But even if the transformation did handle them, they don't have related content items to provide titles anyway.)

I'll add the codeSection bug to the issue tracker.

- Dave
Apr 17, 2008 at 4:00 PM
Edited Apr 17, 2008 at 4:00 PM
Bug report:

Conceptual: codeSection template ignores valid code languages
Apr 18, 2008 at 2:02 AM
Hello James,
The default style used by that source is VS2005, you can change this in the project.bat file.


jxstewart wrote:
What confuses me at present is that the download from this article includes manual.chm (Paul's sample project output) which has the whole gamut of code-types shown, "xml", html" and all.

Sorry for the misunderstanding. I have recompiled that original work and could confirm the problem.
As Dave stated the January 2008 release seems to have introduced some changes or bugs. Here is
the results:

  • cpp success
  • vb success
  • vbs failed
  • js success
  • c# success
  • j# success
  • jscript# success
  • cpp# success
  • vb# success
  • xml failed
  • html failed
  • unstlib ?
  • minterastlib ?
  • mintraastlib ?
  • vb-c# failed
  • jscript success
  • scr ?

Dave has already filed a bug report.

Best regards,
Paul.


Apr 22, 2008 at 1:26 PM
Thanks to all for such voluminous and illuminating responses!

James.
Jul 17, 2008 at 9:34 AM
Hi,

what do

  • unstlib
  • minterastlib
  • mintraastlib

    stand for?

    Cheerio,


    Golo

  • Editor
    Jul 17, 2008 at 4:12 PM
    They are most likely related to something internal to Microsoft.  The only reference to them is in the MAML schemas and it refers to a "DDUELocTools bug fix".

    Eric
    Jul 18, 2008 at 7:39 AM
    Okay, thanks :-)