This project has moved and is read-only. For the latest updates, please go here.

Mixing additional content and shared content

Topics: Developer Forum
Jan 19, 2007 at 1:21 PM
First off: great tool, Eric!

I have a lot of content that goes into my help file in addition to assembly references. A problem I see with the way this content is handled is that we loose the common look and feel used in the reference unless we do some cut-n-paste. This is especially painful for header and footer sections.

I was thinking of doing something similar to the way <pre> and <see> is handled, but it feels like re-implementing stuff that SandCastle is doing already.

So: what would it be like if the additional content were being worked out through the same pipeline as reference topics goes through? The content files would have to be xhtml, certainly. But thats ok. It would open up the world of sandcastle builder components to the additional content. I could have a hand-written <code lang="xml"> section and have the Code Block format it.
I would also think that such a system would ease implementing stuff like <pre> and <see>. Adding support for new tags would only require a build component instead of changing SHFB.
And, most important (to me at least), it would enable inserting shared content automatically into the content.

I'm certain that I do not see all intricacies here. Is it worth the work? Any better suggestions?
Jan 19, 2007 at 4:06 PM
The next release allows resolving shared content items and project option values in the additional content files. Project option values are resolved using a custom tag such as <@CopyrightInfo/>. Shared content items can be resolved using an include tag such as <include item="footer"/>. With these changes, you can get the same item values without cutting and pasting. In the current version, <pre> tags in additional content files support colorizing with the same set of options (excluding the source and region attributes) as the code block component. I think everything is covered. After the next release, take a look and see if there's something that isn't covered. If so, let me know.

Jan 19, 2007 at 7:32 PM
I have a perl script that styles my additional content (very plain HTML files) so they look like the API reference doc. It also adds the little breadcrumbs and a footer.

But I look forward to the next version all the same :-)
Feb 8, 2007 at 4:10 AM
That sounds great.
So when is the next release?
Feb 8, 2007 at 4:18 AM
Don't worry. found it myself
Feb 8, 2007 at 4:03 PM
The next official release will come out when the next Sandcastle CTP is released around the end of February.