Document! X 2022
Content Publishing / Deployment
In This Topic
    Deployment
    In This Topic
    Show All
    Hide All

    This topic describes how to deploy Help Systems generated by Document! X.

    Deploying HTML Help 1.x Help File

    There are two main issues you need to be aware of when deploying your help file to end users:

    Registering the location of your Help file

    As part of the HTML Help file generation process, Document! X registers the location of the generated .chm file in the Windows registry. Registering the help file tells Windows where the help file is located so that context sensitive help works correctly.

    When you distribute HTML Help files with your application, you should register the HTML Help location under the following registry key:

    HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\HTML Help\<filename.chm>

    Where filename.chm is the filename of your HTML Help file. The key value should be set to the full path (without filename) where you are installing the HTML Help file. Example:

    HKEY_LOCAL_MACHINE\Software\Microsoft\Windows\HTML Help\myhelpfile.chm = "c:\program files\myapp\help\myhelpfile\"

    Ensuring the availability of the HTML Help viewer

    The Microsoft HTML Help viewer used to view the HTML Help files generated by Document! X is an integral part of Windows and does not normally require you to distribute any supporting components with your help file. 

    If deploying to Windows 95, Windows 98, and Windows NT it is recommended that you distribute and install the HTML Help viewer update along with your component and HTML help file. The latest HTML Help viewer update can downloaded by following a link from our web site:

    http://www.innovasys.com/support/htmlhelpcompiler.asp

    As mentioned on the Microsoft HTML Help update download site, updates to the HTML Help viewer for users of Windows 2000 and later should be installed using the 'Windows Update' mechanism and therefore no update package is available for that operating system.

    Deploying Microsoft Help 2.x Files

    There is no freely distributable viewer available for Microsoft Help 2.x that is supported by Microsoft. You should only compile to Microsoft Help 2.x if you are creating Visual Studio Add-Ins or .NET components. Microsoft Help 2.x Help Systems can only be viewed from within Visual Studio, or by using the Microsoft Help 2.x Document Explorer which is installed only with Visual Studio and MSDN.

    Deployment of Microsoft Help 2.x files is more complex than HTML Help 1.x files as Microsoft Help 2.x files must be registered on the target machine in order that they can be viewed. In addition to registration, the help file must be 'Plugged-In' to the Visual Studio help collection in order to integrate with the Visual Studio help contents, index, or dynamic Help System. 

    Deployment using merge modules

    The Microsoft Visual Studio Help Integration Wizard (available from http://msdn.microsoft.com/vstudio/extend/) can be used to create Merge Modules to install, register, and plug-In Microsoft Help 2.x help files. This is the recommended way to deploy Microsoft Help 2.x help files.

    Deployment using InnovaHxReg

    An alternative method of deploying Microsoft Help 2.x files is to use the InnovaHxReg command line EXE provided with Document! X (installed into the \program files\innovasys\common directory). InnovaHxReg allows you to register / unregister and plug-in your Help 2 files on a target machine by providing a set of simple command line parameters. The EXE is dependency free and can be easily integrated into most installation scripts (e.g. WISE / InstallShield).

    Document! X automatically generates two batch files; RegisterHelp2.bat and UnRegisterHelp2.bat as part of every build. The files are created in the same directory as the .hxs. These batch files contain the InnovaHxReg commands necessary to register the generated Help System. You can edit the batch files to customize integration with Visual Studio 2002, 2003, 2005, or 2008.

    You can find more information about using InnovaHxReg in the InnovaHxReg introduction and InnovaHxReg Command Line Arguments Topics.

    Both deployment techniques support registering help files for integration with Visual Studio 2002, 2003, 2005, or 2008.

    Which files you need to deploy

    If you are using InnovaHxReg to deploy your Microsoft Help 2.x help system for integration with Visual Studio, you must copy the following files in addition to any .bat files you are using to actually execute the InnovaHxReg commands:

    • The .hxs file. This is the file that contains all your help content in a compressed format.
    • All generated files beginning COL_. These files are necessary in order to plug your .hxs file in to the Visual Studio help collection(s).

    Providing a shortcut link to your installed Help 2.x documentation

    When you deploy your documentation content to other machines it is common to provide a shortcut link to your documentation on the start menu. You can do this with Help 2.x by creating a shortcut to dexplore.exe (the Help 2.x viewer), passing your Help 2.x namespace as an argument.

    Example:

    "c:\Program Files\Common Files\Microsoft Shared\Help 8\Dexplore.exe" /HelpCol ms-help://My.Help2Namespace

    Deploying Microsoft Help Viewer files

    Microsoft Help Viewer is a help technology used by Visual Studio 2017, 2019, and 2022. You should only create Microsoft Help Viewer outputs if you are creating help for integration with the Visual Studio 2010 or later help system (i.e. help for Visual Studio 2017, 2019, or 2022 components, AddIns or extensions).

    Deployment of Microsoft Help Viewer files is more complex than HTML Help 1.x files as the files must be registered on the target machine in order that they can be viewed.

    When deploying a Microsoft Help Viewer book generated by Document! X, you will need both the HelpContentSetup.msha file and the .cab file (if you have opted to sign your book) or .mshc file (for unsigned content).

    Manual Registration

    You can register Microsoft Help Viewer files manually using the Help Library Management tools installed with Visual Studio 2017, 2019, and 2022:

    To register a Microsoft Help Viewer book

    Visual Studio 2010

    1. Open the Manage Help Settings tool from the Microsoft Visual Studio 2010\Visual Studio Tools Start Menu group.
    2. Choose Find content on disk.
    3. Navigate to the location containing your .msha and .cab/.mshc files.
    4. Select the HelpContentSetup.msha file and click Ok.
    5. Click Next.
    6. From the displayed list, click the Add link next to the book you want to register.
    7. Click Update.

    The book registers in the Visual Studio 2010 Microsoft Help Viewer catalog. You can use the Microsoft Visual Studio 2010\Microsoft Visual Studio 2010 Documentation start menu shortcut to open the Visual Studio 2010 Documentation to view your book content.

    Visual Studio 2012 and 2013

    1. Open the Microsoft Help Viewer tool from the Microsoft Visual Studio 2012 or 2013 Start Menu group.                       
    2. Select the Manage Content tab.                       
    3. Select Disk as the Installation Source.                       
    4. Click the "..." button to browse to the location containing your .msha and .cab/.mshc files.                       
    5. Click the Update button at the bottom right corner of the Help Viewer.

    Visual Studio 2015 - 2022

    1. Open the Microsoft Help Viewer tool using the Help\Add and Remove Help Content menu item from Visual Studio.
    2. Select the Manage Content tab.
    3. Select Disk as the Installation Source.                       
    4. Click the "..." button to browse to the location containing your .msha and .cab/.mshc files.                       
    5. Click the Update button at the bottom right corner of the Help Viewer.

    The book registers in the Visual Studio Microsoft Help Viewer catalog. You should immediately see the content appear in the Help Viewer Table of Contents.

    Silent Registration

    In order to silently register Microsoft Help Viewer content it must have been signed using a digital signing certificate. Document! X signs the Microsoft Help Viewer outputs you build if you identify the location on disk of your signing certificate in Document! X Options editor (click the Options button from the Application menu).

    To register a Microsoft Help Viewer book silently, you must launch the Microsoft Help Library Manager tool using a specific command line. Sample command lines for registering and removing your Microsoft Help Viewer book are generated by Document! X when you build and can be found in the install_to_mshv.bat and remove_from_mshv.bat files (install_to_mshv_vs2012.bat and remove_from_mshv_vs2012.bat for Visual Studio 2012). You should incorporate those command lines in your deployment tool.

    Linking to locally installed Microsoft Help Viewer Content

    If you are deploying Microsoft Help Viewer content for integration with Visual Studio 2017, 2019, or 2022 you may wish to create a shortcut for users to view your help.

    The method you use to link to your content differs for Visual Studio 2010 and 2012/2013/2015, but for all versions you need to define a custom F1 keyword against the landing topic you want to link to.

    To define a custom F1 keyword (e.g. "testf1link"), switch to the "Index Keywords" view in the Topic Editor and add a keyword "!InnovasysDocsStartPage". The ! prefix identifies that keyword as an F1 keyword. You must also select the Output index keyword meta tags option on the Compiled Help page in the Build Profile editor in order for the index keyword to be included in the generated output.

    Bear in mind that the F1 keywords you define need to be unique across the whole Microsoft Help Viewer catalog so it's good practice to include a company or product name in the keyword.

    Visual Studio 2010

    Microsoft Help Viewer uses a custom URL protocol to allow navigation to specific pages in the Microsoft Help Viewer catalog. In order to link to a page in content that you have registered with Microsoft Help Viewer you must therefore use a Microsoft Help Viewer URL that addresses a particular page in your content. Microsoft Help Viewer URLs can link to pages by page ID or by using a defined F1 keyword.

    The simplest way to link to a page is to define a custom F1 keyword (using the Topic editor or Content File editor to define a keyword that begins with the ! character to indicate that it is an F1 keyword) and then create a Microsoft Help Viewer URL that points to it. Here is an example using a custom F1 keyword of "InnovasysDocsStartPage":

    ms-xhelp:///?method=f1&query=InnovasysDocsStartPage&product=VS&productVersion=100

    Bear in mind that the F1 keywords you define need to be unique across the whole Microsoft Help Viewer catalog so it's good practice to include a company or product name in the keyword.

    Once you have your URL you can point to it from a Windows shortcut that you create as part of your setup package or other deployment process.

                                   

    Visual Studio 2012, 2013, 2015, 2017, and 2022

    Visual Studio 2012 ships with Help Viewer 2.0, Visual Studio 2013 ships with Help Viewer 2.1, Visual Studio 2015 ships with Help Viewer 2.2, and Visual Studio 2017, 2019 and 2022 ship with Help Viewer 2.3. Help Viewer 2.0 and later no longer support the ms-xhelp:/// protocol so you must call the help viewer directly with a specific command line parameter.

    In order to link to Microsoft Help Viewer 2.0 or later content you must launch the Help Viewer .exe passing a parameter identifying the F1 keyword - that then opens the target topic in the help viewer.

    Here's an example for Microsoft Help Viewer 2.3 (Visual Studio 2017, 2019, and 2022):

    "C:\Program Files (x86)\Microsoft Help Viewer\v2.3\HlpViewer.exe" /catalogName VisualStudio15 /helpQuery "method=f1&query=InnovasysDocsStartPage"

    Here's an example for Microsoft Help Viewer 2.2 (Visual Studio 2015):

    "C:\Program Files (x86)\Microsoft Help Viewer\v2.2\HlpViewer.exe" /catalogName VisualStudio14 /helpQuery "method=f1&query=InnovasysDocsStartPage"

    .. and for Microsoft Help Viewer 2.1 (Visual Studio 2013):

    "C:\Program Files (x86)\Microsoft Help Viewer\v2.1\HlpViewer.exe" /catalogName VisualStudio12 /helpQuery "method=f1&query=InnovasysDocsStartPage"

    .. and for Microsoft Help Viewer 2.0 (Visual Studio 2012):

    "C:\Program Files (x86)\Microsoft Help Viewer\v2.0\HlpViewer.exe" /catalogName VisualStudio11 /helpQuery "method=f1&query=InnovasysDocsStartPage"

    On 32bit versions of Windows, the path above is "\Program Files", not "\Program Files (x86)".

    Microsoft Help 2.0 Viewer Online Endpoints

    Deploying browser help output to a web or Intranet site

    Document! X automatically generates an additional set of HTML files to support publishing of the generated documentation to a web or Intranet site. The generated file webframe.html is the entry page to the browser help output - it displays an HTML frame containing your documentation together with an HTML based Table of Contents, Index, and Search.

    To deploy your generated documentation to a web or Intranet site:

    1. Copy all files (including subfolders) from your selected output directory to a directory on the web or Intranet site.
    2. Link to the webframe.html file, which displays and allows navigation through your documentation.

    You can link directly to a Topic without showing the webframe (i.e. Table of Contents, Index etc) using Name.html or with the webframe using webframe.html?TopicName.html or webframe.html#TopicName.html.

    You can use the Publishing Overview  feature to automate deployment of browser help output to a web site or directory.

     

     

    © 2023 Innovasys. All Rights Reserved.

    Send Feedback