May 11, 2011

XML file for Visual Studio HelpViewer 1.0

The following XML file is used in combination with the XSLT file posted in an earlier post. These 2 files transform into HMTL that views correctly in Visual Studio 2010 HelpViewer 1.0.

<?xml version="1.0" encoding="iso-8859-1"?>
<?xml-stylesheet type="text/xsl" href="../xslt/gravity.xslt"?>
Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.
      </summaryText>          </summary>     <syntax>       <codeSnippet>Lorem Ipsum is simply dummy text</codeSnippet>              <example>         <codeSnippetFull> Lorem Ipsum is simply dummy text of the printing and typesetting industry. Lorem Ipsum has been the industry's standard dummy text ever since the 1500s, when an unknown printer took a galley of type and scrambled it to make a type specimen book. It has survived not only five centuries, but also the leap into electronic typesetting, remaining essentially unchanged. It was popularised in the 1960s with the release of Letraset sheets containing Lorem Ipsum passages, and more recently with desktop publishing software like Aldus PageMaker including versions of Lorem Ipsum.

XSL XSLT file for Visual Studio HelpViewer 1.0

This XSL/XSLT file is based on a Visual Studio Help file found in "C:\ProgramData\Microsoft\HelpLibrary\content\Microsoft\store\Development_Frameworks_21823146_VS_100_en-us_9.msha"
I've stripped out the content and replaced with <xsl:if gt;
The values for this content are taken from XML files which have the corresponding XML element hierachy, e.g


To convert XML to HTML you need an XSL (XSLT) file and some application to transform the XML to HTML using this XSL file. Usually this work is done by the browser, by including a link to the XSL file in the XML file, when you open the file in a browser it runs the transform on the XML using the XSL file you've pointed to.
But I wanted to run this as a seperate step from a batch file so that I can create my .html files on disk but maintain their content using XML.
Here's how I've done it:

using System;
using System.Collections.Generic;
using System.Linq;
using System.Text;
using System.Xml.Xsl;
using System.IO;
namespace Tool.XMLToHTML
    class Program
        /// <summary>
        /// "Help\Help3\_HelpSource\gravity.xslt" "Help\Help3\_HelpSource"
        /// </summary>
        /// <param name="args"></param>
        static void Main(string[] args)
                Console.WriteLine("\tTransform xslt + xml to html.");
                if (args.Length != 2)
                    throw new ArgumentException("2 args required, .xslt file and the .xml file or directory");
                if (!args[0].ToString().Contains(".xslt"))
                    throw new ArgumentException(".xslt file expected as first arg");
                string xmlSourceLocation = Path.GetDirectoryName(args[1] + Path.DirectorySeparatorChar);
                if (!args[1].ToString().Contains(".xml"))
                    if (!Directory.Exists(Path.GetDirectoryName(args[1] + Path.DirectorySeparatorChar)))
                         throw new ArgumentException(string.Format("Directory {0} does not exist."Path.GetDirectoryName(args[1]+Path.DirectorySeparatorChar)));
                       if(Directory.GetFiles(args[1], "*.xml").Length ==0)
                           throw new ArgumentException(string.Format("Directory {0} does not contain .xml files."args[1]));
                Console.WriteLine("\tTakes the fullpath to the .xslt");
                Console.WriteLine("\tand the full path to the .xml or the directory containing the .xml.");
                Console.WriteLine("\tTransforms to .html files, in an output directory below the xml source location 'htmlOutput' i.e. {0}"Path.Combine(Path.GetDirectoryName(args[1]), "htmlOutput"));
                // Load the style sheet. 
                XslCompiledTransform xslt = new XslCompiledTransform();
                string rootPath = Path.GetDirectoryName(args[1] + Path.DirectorySeparatorChar);
                string htmlOutputPath = Path.Combine(rootPath"htmlOutput");
                if (Directory.Exists(xmlSourceLocation))
                    string[] fileNames = Directory.GetFiles(xmlSourceLocation"*.xml");
                    foreach (string xmlFileName in fileNames)
                        xslt.Transform(xmlFileNamePath.Combine(htmlOutputPathPath.GetFileNameWithoutExtension(xmlFileName) + ".html"));
                else//single file
                    xslt.Transform(args[1], Path.Combine(htmlOutputPathPath.GetFileNameWithoutExtension(args[1]) + ".html"));
                Console.WriteLine("\tSuccess. HTML output can be found at {0}\n"htmlOutputPath);
            catch (Exception e)
                Console.WriteLine("\tFailure. Transform to HMTL failed.");
                Console.WriteLine("\t" + e.Message);

Visual Studio 2010 HelpViewer 1.0 Custom Help Creation

Recently I've been working with our legacy HTML help files, trying to add them the the new Visual Studio 2010 HelpViewer. This is not a simple task.
  1. We wanted the styling of our html to be the same as .NET help files
  2. We would also like there to be little or no maintenance required to keep them up to date with the latest Visual Studio Help Styles etc.
  3. We have a custom development language so the code snippets require their own color coding and the Language should be "Gravity" and not C# or VB.
  4. The content itself should be easily maintained.
  5. Our own applications logos and copyright should appear instead of Visual Studios.
The requirements above proved to be not a simple to implement as you might think. Below I'll mention the snags I came across and describe how I overcame them.

1. Styling:
The styling information was not simple to find, there are documents on which explain some of the content of the help files, this is useful but where do you start to get a custom page up and running which looks like a .NET help file? The solution I found is by looking in the Help Store "C:\ProgramData\Microsoft\HelpLibrary\content\Microsoft\store". In here you'll find the help mshi files etc.
The .msha files are actually Zip files which have been renamed, these contain .html help files.
The trick is to find the correct .msha file unzip it and look through the HTML file for the content you require. I found the Int32.CompareTo help file and the Windows.Form help file of great use. These help files contain the bare HTML with CSS links before the HTML has been rendered, it's useless to start looking at the rendered HTML with "view source" from the browser, it's too large.
A Web Form class help file I found of great use was in the "Development_Frameworks_21823146_VS_100_en-us_9.msha" file. I renamed this to .zip and extracted it's contents (this can also be done with an application called FAR, it can read the contents of the .msha file and will give you the option to unzip the contents). I extracted the contents to "C:\Users\me\Documents\Development_Frameworks_21823146_VS_100_en-us_9" and in here searched the .html files for the content I wanted. The file with title <title>MenuStrip Class (System.Windows.Forms)</title>
was the file I chose. I've made a copy of this and used it as my template for most things.

3 & 5. Color coding and logos, Branding.
   There are issues here, it looks like you cannot mix and match, what I mean is you either go with the complete look and feel of Visual Studio's help including the logos and copyright or else you loose it all and provide your own styling. This is all controlled by one simple metadata tag provided in each html help file

<meta name="SelfBranded" content="false" >meta>

    Changing this to "true" results in you losing all the styles and logos etc that msdn gives you, you must then provide your own styles, this solution is not really feasable as the styling and layout of the msdn help is complex and also I'd imagine it's better to keep with the sytles provided by msdn and if they update them then they get pulled in hopefully without and work.
If you do change this setting to "true" applying styles for the color coding snippets is simple with adding html spans to the keywords etc, giving the Span a style class and adding the correct style to a linked stylesheet.

  <span class="kwrd">
            controlspan> Button BtnHelloWorld
            <span class="kwrd">eventspan> Click
             UI.ShowMessage(<span class="str">"Hello World"span>);  
            <span class="kwrd">propertyspan> Text := <span class="str">"Say Hello"span>;
            <span class="kwrd">propertyspan> ToolTip := <span class="str">"Say Hello!"span>;
              <span class="kwrd">propertyspan> NextControl := <span class="kwrd">nullspan>;
the class "kwrd" has a style like so


4. Easily maintained.
I've used XSL and XML to store my help content. The idea behind this is the XSL stores the HMTL, the .NET help files are chunky with alot of styling, so I have one large XSL file "gravity.xslt" which all the XML files reference.
The XML files are simple the text content and some links. This keeps the content files size to a minimum, they contain the title name, the description, the Help Meta information (keywords, id, parent, TocOrder) etc. When new content is required all that needs to be added is a new XML file, copy the content from another and change the text.
I've made the XSL file have as many <xsl:if> statements as possible
In order for XML to become (X)HTML it needs to be transformed using some application (usually a browser) and the XSL file. I wanted to do this in one go from command line so I've written a small application which takes the XSL file and a directory containing the XML files, this outputs a HTML file for each XML file. It's these HTML file's that I later add to my Zip and remame to a .msha file, my help file.