I've put out an updated version of Html Help Builder today. Here are a few development perspective comments on this release.

Code Pasting

This update adds a handful of new features in regards to handling code in topic content. If you've been following my blog you've probably seen some of the struggling I've had with RTF conversion - that was for Html Help Builder's code pasting mechanism primarily.

Sounds like such a pedantic topic, but if you're writing developer documentation getting code into your documentation's content is actually quite important.

Html Help Builder supports two topic editing modes: A plain text based markup scheme that's mostly text with some 'special' HTML format markup, and a WYSIWYG edit mode using an HTML Edit control. In the text mode code posting is straight forward: Code is posted as text and you can then mark the block as code, select a markup language (such as C#, VB.NET, FoxPro, Html etc.) and then Html Help Builder actually handles the markup formatting. The syntax coloring parser works well - I use it for all code samples and it's very rare that there's a problem (most of the problems are related to XML and non-standard HTML tags). In WYSIWYG a similar process is used, except that you need to tell Html Help Builder explicitly that you want to paste code with a Paste Code or Formatted HTML (Ctrl-F6) option.

The problem in WYSIWYG edit mode is the following: The Html Edit control can easily paste formatted HTML and see it in its original formatting. However, it does not understand RTF  and if you paste RTF content - such as code copied from Visual Studio, Sql Management Studio or Visual FoxPro - the HTML Edit control completely mangles the embedded HTML.

Hence my quest to find a decent RTF -> HTML converter. As I mentioned in my recent post I looked at various different controls and components (about 10 of them) and only one of them came even close to working in most scenarios and this expensive tool has a few problems (it's VERY slow for one). Strike out there - generic RTF conversion is not going to happen at this point.

So I chose the next best thing which is only conversion of code from Visual Studio which is by far the most pressing issue. A number of users have requested the ability to paste text out of Visual Studio EXACTLY the way it is rendered in Visual Studio rather than using Html Help Builder's rendering. There are a some differences in Html Help Builders syntax coloring from source code especially for HTML and XML and so the explicit pasting.

What I ended up with is with was the CopySourceAsHtml Add-in which of the various free tools and snippets out seems to work the best and has many options (including the most useful strip leading space option). I had to make a few small modifications to get the component loaded just for RTF parsing, but short work.

So now in Html Help Builder when you paste code from Visual Studio in WYSIWYG mode is just pastes the code as is directly into the HTML Edit control. There's no prompt it just does what you'd expect. The old option (Ctrl-F6) to explicitly choose a language still works as well, but the default behavior is now more manageable.

How can you tell whether code comes from Visual Studio? There's no 'explicit' marker in the RTF but there's a header that I've only seen in Visual Studio that I check for. Here's a small RTF example from VS:

{\rtf1\ansi\ansicpg\lang1024\noproof1252\uc1 \deff0{\fonttbl{\f0\fnil\fcharset0\fprq1 Courier New;}}{\colortbl;
\red0\green0\blue255;\red255\green255\blue255;\red0\green0\blue0;}
\fs20 \cf1 namespace\cf0  Westwind.WebLog}

By checking for the \noproof in the RTF I can determine whether the content is from VS and if it is invoke the VS RTF conversion tool. Other RTF code from say Word Pad or Visual FoxPro needs to be treated just like before for now until I find a complete RTF -> HTML solution.

In WYSIWYG mode the above is a no-brainer, but I ended up also hooking this up for Text editing. In text edit mode when you paste code from Visual Studio now a dialog pops up which lets you either paste the raw HTML into the document (ie. true to VS.NET coloring) or choose a language directly by selecting a code language like C# or FoxPro etc.:

Although the dialog may seem really obtrusive it actually saves the extra step of having to reselect the code later and markup it up with a code language selection as you had to do before. If you choose any other option but Paste code from Visual Studio the code is embeded as plain text wrapped in the <code lang="C#"></code> tags. If the raw HTML is posted things are a bit more ugly:

<RAWHTML>
<div style="font-family: Courier New; font-size: 10pt; color: black; background: white;">
<pre style="margin: 0px;"><span style="color: blue;">protected</span> <span style="color: blue;">void</span> Application_Start(<span style="color: blue;">object</span> sender, <span style="color: #2b91af;">EventArgs</span> e)</pre>
<pre style="margin: 0px;">{</pre>
<pre style="margin: 0px;">&nbsp;&nbsp;&nbsp; <span style="color: blue;">if</span> (<span style="color: #2b91af;">App</span>.Configuration.LogErrors == <span style="color: #2b91af;">ErrorLogTypes</span>.SqlServer)</pre>
<pre style="margin: 0px;">&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; <span style="color: #2b91af;">WebRequestLog</span>.LogCustomMessage(<span style="color: #2b91af;">App</span>.Configuration.ConnectionString, <span style="color: #2b91af;">WebRequestLogMessageTypes</span>.ApplicationMessage, <span style="color: teal;">"WebLog Application Started"</span>);&nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; &nbsp;&nbsp;&nbsp; </pre>
<pre style="margin: 0px;">}</pre>
</div>
</RAWHTML>

but this in effect preserves the Visual Studio formatting. So you get to choose which style you prefer.

Which is better? Personally I prefer the plain text code mode. In text mode you can modify the code in the editor and the syntax coloring will actually properly syntax color your changes. With code pasted from VS.NET the code is HTML markup and while you can change it is nasty and won't reflect the syntax coloring choices. In the latter case changes usually require repasting the code into the document.

I also prefer the text mode because it's consistent. There are situations where you might be just writing a small bit of code without having it in Visual Studio and in that case the syntax coloring might look a  little different.

Unfortunately at the  moment this sort of 'code sniffing' only works with Visual Studio/IDEs. If you have code from other editors there's no true way to detect whether the code pasted is text or code even if it's RTF. For example, FoxPro code (which is also RTF) has no consistent marker that doesn't exist in other documents, which is kind of a bummer.

.NET Interop with .NET Runtime Hosting
Html Help Builder is not a .NET application - it's a FoxPro app that has worked well and frankly hasn't really been in need to be ported to .NET. There are a number of reasons for this which I talked about a while back. However, Html Help Builder has for quite some time used .NET functionality to integrate with .NET. For example, you can import .NET Types and Assemblies, there's a Html Help Builder Add-in that integrates Html Help Builder with Visual Studio, there's a .NET Automation wrapper around Html Help Builder so you can automate Html Help Builder with .NET code to just name a few things that use and integrate with .NET.

The original integration has been done with COM interop - the FoxPro code calls into a COM Registered assembly and then communicates through it to integrate with .NET code. While this works fine the COM registration issues have plagued Html Help Builder for a while. Ensuring that the right component is registered for each version of .NET etc. has been quite the hassle and the COM Interop requirement also made it harder to directly access components.

This release has moved a number of the these Interop features into a hosted copy of the .NET runtime to do away with the COM registration issues. The RTF converter for example runs through this mechanism now as do several of the .NET import routines and classes. Not everything has been converted yet - there's a distribution issue involved so it needs to wait for major redistro - but I've been running with this hosted runtime code which has opened up a host of .NET features that I was weary to use previously because it would have meant creating wrapper types.

This development is kind of exciting as it adds a number of things that can now be added integrating more easily with the .NET runtime.

Statics in .NET Imports

Html Help Builder's type import previously did not do a great job of identifying static types in the type listings or in the topic display. This was a real simple fix of an obvious (but curiously unmentioned) missing feature. Html Help Builder already checks for statics it just didn't explicitly set the static flag for topics nor display the static icon. It's there now.

Note if you're using Html Help Builder and you have existing imported .NET types and classes you might want to download the Fix Static Members Add-in which goes through the help file and fixes statics. It also cleans up old version Inheritance Tree markup from pre 4.20 versions removing the HTML tags that were placed in this field in those old versions. Simply copy the contents to your Add-ins directory and use the Add-in Manager to Import the Add-in:

Lots of little tweaks

In recent months there have been a lot of suggestions and few bug reports pouring in from users which is great. There's been a ton of valuable feedback which I appreciate very much and I've been able to add a number of small tweaks in the UI for many of these suggestions. This updates has quite a few of them implemented. Your feedback is very valuable so if you have comments, problems, ideas etc. please let me know. Even if you have constructive criticism I'd (even if you hate Html Help Builder) I'd love to hear about it.

The best place to get involved is on our message board. It's a no hassle message board that requires no registration so it's quick and easy to post messages. I love to hear from you...