How to use the code colorizer outside SHFB

Sep 23, 2007 at 6:07 AM
Please let me know how to use the code colorizer outside SHFB.

I am very irratated that you closed the issue about the code colorizer in the issue tracker even though SHFB has changed the HTML and has broken the MS styles. The last thing I want to do is modify SHFB to match the CSS of MS. If you would take the time and compile a sample to chm using the VS2005 template you would notice the problems I described. I can not believe the comment you left, then closed the ticket!

Thank you,
Noral
Coordinator
Sep 24, 2007 at 12:17 AM
I'm sorry if I offended you, it was not intentional. Perhaps my comments where too blunt and I could have noted what I did change in the closing comments. I did make a few tweaks to the stylesheet to shrink the gap between the title and the code block and did implement highlighting the icon and link on mouse hover. I did compile the VS2005 style and I really don't see the other issues that you reported. Vertical alignment appears to be okay. The title is flush left with the code block, not the page border, which as far as I can tell is how it should be. The code block title is the same width as the code block in API topics although the code block is slightly shorter or wider than the title in additional content pages depending on the browser (see below).

What you have to understand is that the code block component has to work with all three presentation styles in CHM/HXS output and website output. As such, there are some trade-offs in coming up with styles that work in all situations.

  • All three presentation styles do not have a title so that's added in by the component.
  • The prototype style doesn't have a Copy Code link at all, the Hana style left aligns it, the VS2005 style right aligns it.
  • The line where the Copy Code link is at in the Hana style has the same background color as the code block, the VS2005 style uses a different color. Since the component has to add a title, I chose to separate it from the code block and use the page background color as I feel it makes the title stand out better regardless of the presentation style.
  • I use the generic term "Copy" for the link as the code colorizer can be applied to non-code blocks in additional content files.
  • When dealing with website output, you have to consider that IE and FireFox do not render the pages identically. As such, there are some oddities in the stylesheet such as the code block width being set to 99.5%. With the VS2005 style, FireFox renders the code blocks slightly wider than IE does. If set to 100%, FireFox renders the code wider than the page and a horizontal scrollbar appear. Fixing this issue would involve messing with the presentation style stylesheet and may affect other stuff. It's not something I want to require in order to use the component. It doesn't appear to be an issue in the other two styles.

It's not pixel perfect for all three styles and, unfortunately, I don't think I can give you that. The highlighter's style sheet is replaceable via a configuration option on the code block component. If you want closer conformance with one particular presentation style, you can replace it. The colorizer part by itself can't be used with Sandcastle as you have to wrap it in a build component. The code block component can be used outside of SHFB. You just have to manually integrate it into your configuration file. See the Code Block Component topic in the help file for information on how to do that.

Eric
Sep 27, 2007 at 9:41 PM
Eric,

Could you please let me know how to use the code colorizer outside of SHFB.

TIA,
Noral
Coordinator
Sep 27, 2007 at 11:50 PM
As I said in the final paragraph of the reply above:

The colorizer part by itself can't be used with Sandcastle as you have to wrap it in a build component. The code block component can be used outside of SHFB. You just have to manually integrate it into your configuration file. See the Code Block Component topic in the help file for information on how to do that.

Eric
Oct 12, 2007 at 12:54 AM
Eric,

I was able to partially get the code colorizer to work outside of SHFB. For some reason the highlight.css and highlight.js keep getting copied into the html folder instead of the scripts and css folders. Also once chmbuilder is called highlight.css and highlight.js are not copied to the new chm\html folder, I assume because of their extensions. But interestingly since highlight.css is not in the CSS folder that line is removed but the highlight.js is not.

Can you shed some light on what might be happening. Here is a snippet of the sandcastle.config file. The only additions is the code colorizer in their correct spots:

--> Pre
<!-- Code block component configuration. This must appear before the
TransformComponent. See also: PostTransformComponent. -->
<component type="SandcastleBuilder.Components.CodeBlockComponent" assembly="C:\Test\Colorizer\SandcastleBuilder.Components.dll" id="Code Block Component">
<!-- Base path for relative filenames in source attributes (optional) -->
<!-- <basePath value="C:\Test\Colorizer\" /> -->
<!-- Connect to language filter (optional). If omitted,
language filtering is enabled by default. -->
<languageFilter value="true" />
<!-- Code colorizer options (required).
Attributes:
Language syntax configuration file (required)
XSLT style file (required)
"Copy Code" image file location (required)
Default language (optional)
Enable line numbering (optional)
Enable outlining (optional)
Tab size override (optional, 0 = Use syntax file setting)
Use language name as default title (optional) -->
<colorizer syntaxFile="C:\Test\Colorizer\highlight.xml" styleFile="C:\Test\Colorizer\highlight.xsl" copyImageUrl="../Icons/CopyCode.gif" language="cs" numberLines="true" outlining="true" tabSize="0" defaultTitle="true" />
</component>


--> Post
<!-- Post-transform component configuration. This must appear after the
TransformComponent. See also: CodeBlockComponent. -->
<component type="SandcastleBuilder.Components.PostTransformComponent" assembly="C:\Test\Colorizer\SandcastleBuilder.Components.dll" id="Post-transform Component">
<!-- Code colorizer files (required).
Attributes:
Stylesheet file (required)
Script file (required)
"Copy code" image file (required) -->
<colorizer stylesheet="C:\Test\Colorizer\highlight.css" scriptFile="C:\Test\Colorizer\highlight.js" copyImage="C:\Test\Colorizer\CopyCode.gif" />
<!-- Output path for the files (required). This should match the
output path of the HTML files (see SaveComponent below). -->
<outputPath value=".\Output\html" />
<!-- Logo image file (optional). Filename is required. The height,
width, altText, placement, and alignment attributes are
optional. -->
<!-- <logoFile filename=".\Sandcastle.jpg" height="69" width="71" altText="Test Logo" placement="left" alignment="left" /> -->
</component>

Thanks Eric,
Noral
Coordinator
Oct 12, 2007 at 3:42 AM
The PostTransformComponent copies them to the path indicated by the outputPath element which is the .\html folder. This was done as originally one of the styles used an .\art folder instead of an .\icons folder so it was easier to just copy them to the html\ folder and not have to deal with variations in the style folder names.

CHMBuilder probably only copies HTML files as that's all it parses. This is a bit shortsighted as there could be other content in the folder such as images, user-defined scripts, etc. besides the colorizer files. I'd report that as a bug to Anand. The removal of the link to the stylesheet could also be a bug. Looking at the output from CHMBuilder there appears to be a major problem as everything appears to get dumped into the <head> tag. There is no <body> tag in the CHMBuilder generated files.

Eric
Oct 12, 2007 at 4:35 PM
Can the component be modifed to put the javascript and css in the correct place? FYI - if the directory does not exist, for example output\colorizer then the component fails. I changed the outputPath to .\output\colorizer but the component still puts no path in the html file but the files are in the .\output\colorizer directory.

I am not seeing the body tag being removed, my chm\html htm files do have body tags but other stuff is removed see the new thread at http://forums.microsoft.com/MSDN/ShowPost.aspx?PostID=2263071&SiteID=1&mode=1

Thanks Eric,
Noral
Coordinator
Oct 13, 2007 at 9:43 PM
I'll modify it to be consistent with the existing folders.

Eric
Oct 16, 2007 at 12:27 AM
Edited Oct 16, 2007 at 12:59 AM
Sounds good, thanks.

However II have another question about changing the codecolorizer to work with the VS2005 presentation model...BTW - I now understand what you were saying about all three models being totally different! :D

I changed the codecolorizer.cs from this:

// Add the title div with the title text and Copy span
matchText = String.Format(CultureInfo.InvariantCulture,
"<div class=\"highlight-title\">" +
"<span class=\"highlight-copycode\" " +
"onkeypress=\"javascript:CopyColorizedCodeCheckKey(" +
"this.parentNode, event);\" tabindex=\"0\" " +
"onmouseover=\"CopyCodeChangeIcon(this)\" " +
"onmouseout=\"CopyCodeChangeIcon(this)\" " +
"onclick=\"javascript:CopyColorizedCode(" +
"this.parentNode);\"><img src=\"{0}\" " +
"style=\"margin-right: 5px;\" />{1}</span>{2}</div>{3}",
copyImageUrl, copyText, title, matchText);

to this:

// Add the title div with the title text and Copy span
matchText = String.Format(CultureInfo.InvariantCulture,
"<table width=\"100%\" cellspacing=\"0\" cellpadding=\"0\" >\n" +
"<div class=\"highlight-title\">" +
"<span class=\"highlight-copycode\" " +
"onkeypress=\"javascript:CopyColorizedCodeCheckKey(" +
"this.parentNode, event);\" tabindex=\"0\" " +
"onmouseover=\"CopyCodeChangeIcon(this)\" " +
"onmouseout=\"CopyCodeChangeIcon(this)\" " +
"onclick=\"javascript:CopyColorizedCode(" +
"this.parentNode);\"><img src=\"{0}\" " +
"style=\"margin-right: 5px;\" />{1}</span>{2}</div>{3}" +
"</table>\n",
copyImageUrl, copyText, title, matchText);

I only added one tag and now there is a <pre> tag just before <span class="highlight-lineno">, if your using line numbers that should not be there with the closing </pre> just after the title name. This is part of the problem with the table alignment problem. And interestingly the table tag has been removed...I tried this with other tags and the same thing happens.

Any thoughts?

TIA,
Noral
Coordinator
Oct 16, 2007 at 1:57 AM
Sorry, I don't know. I'd have to play around with it to find out but it's not an change I'm interested in making.

Eric