Hello.
I'm looking for a help/documentation generation tool which would satisfy such requirements:
- it should support xmldoc comment produced by c# compiler or (even better) directly support sandcastle
- it should support importing of MS Word documents.
- it should support creating links from conceptual documentation to reference documentation produced from source code.
- it'd be nice if it supports conceptual doc authoring in MS Word
More details. My project is a framework/library for .NET. It has several VS solutions with totally more than 50 C# projects. First of all I want to generate help (chm & help2 & help3 in the future) from the source code of my projects. I'll refer to that documentation as "reference doc". Sandcastle (especially with using SCFB) can do this in very nice way. But (I guess it's very common situation) I have some additional documentation for the framework/library. That documentation is in MS Word files (5-10 files). I'll refer to that documentation as "conceptual doc". I want to produce a solid help system with conceptual doc and reference doc (like MSDN). And I want conceptual part of the help contains links (URL) that refer to reference part of the help for every .NET type name from the framework/library. (Obviously any help system is just HTML eventually).
The problem is how to create these links. MS Word files do not know anything about C# xmldoc. Sandcastle doesn't support Word files. So I have to take some Help Authoring Tool (HAT). By the moment I can't find any aproprient tool for me. And I would be very appreciate for any help!
An stumbling block for all tool is links autocreation. I'd like links be created automatically durining generation (which can take place on build server). Why automatically ? Because it allow easy renaming of types. For an instance. I have some text in conceptual doc: "for accessing request processing context use static property Current of XOperationContext type". Here XOperationContext is a type name. I'd like it became a link (URL) to XOperationContext class's specification in result help system without any significant efforts. I'd like to mark it in Word (probably with some HAT's plugin installed) or in HAT's editor as something like "make this word link if possible". During generation each such word would became a link if there is a type name with such name.
I know about these tools:
Doc-o-Matic support links autocreation. Truly automatically. It tries create a link for each word in PascalCase - brilliantly. But it doesn't support MS Word. Innovasys' and ComponentOne's software do not support creating links automatically. Innovasys' software do not support MS Word (I'm not sure for 100% about this).
I tried to ask on Innovasys' and ComponentOne's forums. No luck so far. Innovasys' soft support scenario like mine: creating conceptual doc in separate tool - HelpStudio and generating help from source code with another tool - DocumentX. But there's no ability to create links automatically and import MS Word files.
So, please share your expirence for that common task (I'm sure it should be common).
p.s. please let me know if I haven't managed to explain my thoughts correctly from English grammar's point of view, I'll try one more.