include .doc content into a topic

Topics: Features, Help 1.x/2.x
Nov 7, 2008 at 1:30 PM
What is the best way to include the content of .doc or a .docx into a topic?
Nov 7, 2008 at 5:17 PM
Edited Nov 7, 2008 at 5:48 PM

At this time Sandcastle does not provide XSLT that can transform .doc(x) files into HTML.

One option is to copy the content and paste it into DocProject's Topic Editor, if the target topic is a reference topic.

If the target topic is a conceptal topic, export the document as HTML and do one of two things:
  1. Try using a tool such as DocToMaml (my tool; hasn't left BETA yet) or HTML to MAML Converter (Eric Woodruff's newer tool; I haven't tried it yet) to convert the raw HTML doc to a MAML topic file.  Then use the Import Topics button in the Topic Explorer tool bar to import the new topic into the TOC.  See the DocToMaml help file for more information.
  2. Or simply add the raw HTML file to your project's, Help\Topics\Html folder (you'll probably have to create the Html folder yourself in Solution Explorer).  To include a raw HTML topic into the TOC you must manually edit the Help\Settings\topics.xml to add a new entry, such as <topic id="stuff" title="Additional Stuff" file="Html\stuff.htm" />.  Then click the Refresh button in Topic Explorer to see it.  Note that adding the file to the TOC isn't required though if you just want to link to the topic from another topic; e.g., <see href="html\stuff.htm">additional stuff</see> in reference topics or <externalLink>...</externalLink> in conceptual topics (see below for an example).
Alternatively, you can add a hyperlink into an existing topic and then distribute the .doc(x) file with the help.  How to do that depends on the type of output:

Help 2.x may support embedding binary files but I don't know how to do that.  If that's the type of output that you need then you may want to ask this question in the MSDN Developer Documentation and Help System forum.

Help 1.x supports embedded files:

  1. Open the DocProject Properties window for your DocProject or DocSite.
  2. Locate the Build | Help 1.x option and click the ellipses button (...) on the right.  The Help 1.x Settings dialog will open.
  3. The list at the bottom of the dialog allows you to add new file extensions that will be compiled into the .chm file.  (Modifications are saved to Help\Settings\Projects\help1x.config).  For example:
    1. Add a new entry to the Help 1.x Files list: AdditionalFiles\*.doc
    2. Add a new folder to your project, Help\AdditionalFiles, and then add your .doc(x) files.

To add a link in XML documentation comments: 

    <see href="..\AdditionalFiles\stuff.doc">additional stuff</see>

To add a link in conceptual topics: 

      <linkText>additional stuff</linkText>

Note: The examples above will work in your DocSite web application even if you don't add a new Help 1.x Files entry for *.doc.  Just don't forget to deploy your new Help\AdditionalFiles directory to the host server.

- Dave
Nov 8, 2008 at 6:29 PM
Thanks a bunch. I really appreciate your commitment and you promt and helpful answers :)