Including Word document into CHM files...

Nov 9, 2012 at 10:10 AM

HI Sandcastle Community,

                 Thanks for providing such a great tool to extract the XML comments like MSDN help files. I have a requirement where i need to some supporting document into the CHM file which is being generated by the sandcastle. Can the word file be included into the output CHM file? If so can you provide some help?

 

Thanks.

Editor
Nov 12, 2012 at 7:32 PM

Please note that this project has been discontinued and may not be monitored as frequently.  For future questions concerning Sandcastle, post them over on the Sandcastle Help File Builder project's discussion page.  Thanks.

Regarding your question, you can embed the files in the help file.  If using SHFB, add the file to the project and set its BuildAction file property to Content.  How you get it to display is another issue.  A simple anchor link may work.  The path would be relative to the .\html folder.  For example, if it was in the Docs\ folder, the link URL would be something like "../Docs/Document.doc" or if you put the file in the root of the project, it would just be "../Document.doc".  I haven't tried it so I'm not sure if it will work or if you'll run into security issues.  In XML comments, you can put the anchor link in the XML comments as-is.  For MAML topics, you'd need to wrap the HTML anchor link in a <markup> element so that it passes through to the rendered topic.

If you're distributing a CHM file, it may be just as easy to distribute the documents as separate files rather than embedding them in the CHM file.

Eric

 

Nov 13, 2012 at 2:40 PM

Please continue to post here for Sandcastle specific issues. SHFB will not be the only tool based on Sandcastle.

Busy now, but now that the direction of the Sandcastle project is clear, I planned to release the tools I am working
on soon.

I will advice you to avoid using direct link as provided in Eric's answer. CHM way of linking is different from the new
help format, for instance, so using direct links may make it difficult for you in the future if you plan to create other formats.

Links are handled by build components, and I will advice you to create one to handle your needs if you cannot find
one that fits.

Best regards,
Paul. 

Nov 13, 2012 at 2:48 PM

Why the confusion?  Just curious.

I thought that this site was being deprecated and all activity (including the code fork) was moving to SHFB.

Please clarify.

Scott

 

Nov 13, 2012 at 3:06 PM

Hello Scott,

There is no confusion! We were all waiting for the official word on the direction of the project
and nothing finally came out of the efforts. I planned forking long ago and have said it here.

There was a claim that a new version was going to be released and I waited only for Eric to claim
all is now directed to SHFB. Clearly, Sandcastle is dead.

SHFB will be one fork of the Sandcastle, I have forked it too. It is different direction, I have eliminated all
the command-line stuff for instance, creating a set of libraries that any application or script
can use to create helps. I was a little busy in a new job, doing mostly C/Java :( but getting ready
to complete my stuff and provide alternative to creating help files. 

Best regards,
Paul. 

 

Nov 13, 2012 at 3:08 PM

I get it....thanks!

So will you be working off of this site....or are you creating a new project with your fork?

I love Sandcastle and want to stay on top of any new development / tools.

Thanks,

Scott

Nov 13, 2012 at 3:14 PM

Hello Scott,

It is an on-going project, was a little difficult to move on due to the uncertainty of the Sandcastle
directions. I love Sandcastle too and have being supporting it over the years :)

The project is Sandcastle Assist: http://sandassist.codeplex.com/

The new and updated sources with the forked Sandcastle is not yet checked into the repository.

Best regards,
Paul. 

Nov 14, 2012 at 8:31 AM
EWoodruff wrote:

Please note that this project has been discontinued and may not be monitored as frequently.  For future questions concerning Sandcastle, post them over on the Sandcastle Help File Builder project's discussion page.  Thanks.

Regarding your question, you can embed the files in the help file.  If using SHFB, add the file to the project and set its BuildAction file property to Content.  How you get it to display is another issue.  A simple anchor link may work.  The path would be relative to the .\html folder.  For example, if it was in the Docs\ folder, the link URL would be something like "../Docs/Document.doc" or if you put the file in the root of the project, it would just be "../Document.doc".  I haven't tried it so I'm not sure if it will work or if you'll run into security issues.  In XML comments, you can put the anchor link in the XML comments as-is.  For MAML topics, you'd need to wrap the HTML anchor link in a <markup> element so that it passes through to the rendered topic.

If you're distributing a CHM file, it may be just as easy to distribute the documents as separate files rather than embedding them in the CHM file.

Eric

 

Hi Eric,

         As you have said i had added my MS-Word file to the solution and changed its "BuildFile" property to Content. When i tried to refer the document from XML comments as <see cref="../Document1.docx"/> i get a warning. Can you please illustrate the correct way of referencing it ? But when i tried to refer any of my properties as <see cref="Task.property"/> i was able to produce it as an link and access it.

 

Thanks!

 

 

Nov 14, 2012 at 8:33 AM

Hello Paul,

Do I understand you right? You're planning another fork of the Sandcastle Codebase and create a different project? Why not joining the SHFB? Another Sandcastle Fork will clearly split significance, acceptance, number of users and stability of every Sandcastle-Successor.

We're very thankful to Eric that he care so much for the Sandcastle Project and tries to keep it running (Since MS isn't willing to do that any longer) - It would be great when SHFB and Sandcastle can be merged into one bigger community project as soon as possible. That would be a strong and clear statement about the future of Sandcastle (or whatever the name will be then)

Regards

Karl

 

Editor
Nov 14, 2012 at 3:10 PM
Edited Nov 14, 2012 at 3:59 PM

Use <see href="../Document1.docx">Other Docs</see> (href instead of cref, inner text if you want it) or use an HTML anchor tag (<a href="../Document1.docx">Other Docs</a>).  Since you're only producing a CHM file, the direct link should work fine in this case.  If not, let me know and I'll create a test and see if there's something I've forgotten.  If you're planning on producing Help 2 or MS Help Viewer formats, this method probably won't work.

Eric

 

Editor
Nov 14, 2012 at 3:57 PM

Hi Karl,

Sandcastle has been merged into the SHFB project so it has a new home and the latest release is available at the SHFB project site.  I'm handling all development of both SHFB and the Sandcastle tools there.  The Sandcastle tools are independent of SHFB so I haven't seen a reason to integrate them completely and force everyone to use SHFB.  Certain parts of SHFB will eventually be moved into the Sandcastle tools but they will still remain independent for those that want to use them in such a manner.  I haven't seen any reason to rename the project or create a new project since I think that would introduce unnecessary confusion.

Darren's final statement on the front page of this site directs people to the SHFB project as the successor but others are still free to fork their own version. It's not ideal but that's the nature of open source.  Paul and I have different ideas about how Sandcastle should evolve and what can and cannot be changed which is why he left the Sandcastle Styles project.  If he wants to pursue a different take on the tools he's free to do so.  His project has actually been around for a few years but he hasn't gotten to the point of an actual release yet.  SHFB has a long history, is well established, and managing and developing Sandcastle is no small task so I'm not forseeing a significant number of other forks if any.  Time will tell.

Eric