Conceptual Content

Topics: Developer Forum, User Forum
Feb 24, 2009 at 2:35 PM

Hi, I'm just getting into Sandcastle and the SHFB, and am experimenting with Conceptual Content.

I do have a specific issue, but I think this issue basically boils down to not being able to find a good enough resource regarding Sandcastle's use of MAML. And, yes, I have discovered the Sandcastle MAML Guide, but this doesn't have the depth to answer my question.

So I guess my general question is to ask if there is a definitive resource on this. I'm surprised that I can't find anything on the MSDN, but maybe I just didn't look hard enough...

(My specific issue is regarding the codeEntityReference tag. I can see the M:, T:, N: prefixes and obviously can follow what these are easily, from the examples in the MAML Guide. But what about when I want to link to an event? Or to an enum? I mean, if someone knows the answer to these specific questions, fine, but what I'm really looking for is the place where all of this syntax is actually defined.)

Thanks for any help that anyone can offer. I must say I have been very impressed with SHFB, which is why I'm willing to look at just how much documentation I can pack into one of these files.

TIA, Pete

Feb 24, 2009 at 3:30 PM
Edited Feb 24, 2009 at 3:32 PM
The IDs used with the code entity references are an exact match for the IDs you'll find in the XML comments file for the given member.  As such, the prefixes will correspond to the item.  Events use an "E:" prefix.  Since enumerations are types, they use "T:".  Properties use "P:" and fields use "F:".  The easiest way to use add code entity references is to use the Code Entity Window to search for them (hit F3 or select it off of the Window menu or toolbar).  Once you locate an item, just drag and drop it in the topic where you want it.

I'm not aware of any other definitive guides to MAML so if you have any questions or suggestions on how the MAML guide can be improved, let me know.

Feb 24, 2009 at 4:44 PM

Thanks Eric. I suspect if you aren't aware of things surrounding this topic, then no other guides exist!

For my part, I wasn't aware that the Code Entity window even existed, so that's for that.