Alternative format and presentation styles

May 24, 2012 at 6:18 PM

I'm new to Sandcastle. I need to document a RESTful API and PowerShell cmdlets. I'd like the API to have online documentation, and the cmdlets need MAML for get-help. Both also need to be published to a framemaker document as well. They all share many of the same concepts so I want to make heavy use of shared content across them. I'm trying to get Sandcastle to help but don't see quite how to get things to come together. For example:

  • Can I have a build that simply replaces tokens in a MAML file (to doc the cmdlets)?
  • Is there a path to framemaker?

Or, should I be taking a totally different path?

May 30, 2012 at 8:41 PM

Sandcastle uses reflection data generated from assemblies along with the related XML comments files to produce help files in Help 1 (CHM), Help 2 (HxS), MS Help Viewer, or website formats.  MAML topics used for conceptual content can also be included but, like the reflection and comments data, they are converted to HTML files.  I'm not familiar with documenting PowerShell cmdlets so if they need raw MAML files, Sandcastle probably won't be of much help.  I don't know what FrameMaker is and Sandcastle doesn't support it as an end result or tool that can be used.



Jun 1, 2012 at 4:26 AM

Thanks Eric,

PowerShell cmdlets use MAML. I'd like to leverage Sandcastles tokens to eliminate redundancy. If only I could modify how it runs to produce MAML instead of HTML (shortcut most of the transforms, save the intermediate expanded token MAML). Before posting I thought I had an approach that might work but got blocked when the name I used didn't include one of the preexisting styles and it defaulted to prototype. For me it would be nice if the pipeline was more configurable.

FrameMaker is an adobe product used by some for documentation (not passing judgement either way here, I'm not trying to start anything :)). It supports an import/export mechanism called MIF. I was thinking that if I could figure out how to add my own transforms I could get there...

Before running into that, I set up two projects sharing the same folder structure (but different output folders) and that proved to me that I could leverage the same tokens for more than one output. That was sweet, but unfortunately I don't see how to add/extend the output formats to get what I need. And, my timeframe is probably too short to spend much more time on it. If anyone has some ideas, perhaps that could change?