Why so many conceptual templates?

Topics: User Forum
Sep 11, 2008 at 11:55 AM

I just started using the conceptual content of SHFB. I really like it!
But I was wondering why so many different templates were needed?
It looks as if all tags can be used in all document (type)s - is that true? - so one generic document would have suficed(?).
Or does the render engine do something special with each of these template instances?

Marc Jacobi
Sep 11, 2008 at 3:15 PM

The templates do have their differences and not all elements are valid in all document types.  For example, a Glossary document is entirely different from a general Conceptual document and the glossary-specific elements aren't valid in the other document types based on the schema.  That's not to say they wouldn't be processed by Sandcastle due to the way its XSL transformations works but topics should conform to the MAML schema.

There are a number of document types that do seem to overlap (i.e. the SDK types) and many may not even be used much if at all.  However, since they're in the MAML spec and are supported by Sandcastle, they are included for completeness.  You may find that you use the Conceptual topic type for most topics and one Glossary topic if you need a Glossary.  If you have how-to or troubleshooting information, those document types might be useful too.  If you haven't seen it yet, there's a MAML Guide available at the Sandcastle Styles project site that describes the MAML elements and how to use them.