Doing simple things <list> or <li> ?

Topics: Conceptual Topics, DocToMaml, General Discussion, General Questions, Help 1.x/2.x, Sandcastle
Aug 28, 2008 at 10:50 PM
I find Sandcastle very frustrating.  DocProject helps a lot but it's still very difficult to just write some text to be included into a .chm file.  I spend minutes writing and hours trying to get simple formatting to work.  I feel like I must be missing something (important).  For example today I was trying to include a list in a conceptual topic, something like this:

<developerConceptualDocument xmlns="" xmlns:xlink="">
  some text ....
  ... more text
  ... even more text

I also tried using the /// comment tag <list> ... it complained that it didn't understand 'list'.  The above markup <li> tag doesn't generate a complaint but it don't give me a bullet list either, it just produces a chm with a line that ends in "A B".

Surely what I'm doing isn't uncommon and I'm just missing something rather basic.  Could someone point me in the right direction?
Aug 28, 2008 at 11:30 PM
Edited Aug 28, 2008 at 11:32 PM

Here's what you may be missing:

How To Enable IntelliSense in Conceptual Topics To Enable IntelliSense in Conceptual Topics

MAML doesn't support HTML markup.  However, if you've already installed the Sandcaste Styles patch before creating your DocProject or DocSite then you can use the markup element to wrap raw HTML, although I don't recommend using it unless there's absolutely no replacement in MAML for what you need to do (note that MAML supports a list element so you should be fine without using raw HTML).

Also recommended is the MAML guide from the Sandcastle Styles releases page.

- Dave
Aug 29, 2008 at 6:12 PM
I followed the "How To" and installed the styles patch, but was still having trouble, so I uninstalled Sandcastle and reinstalled from codeplex.  I then reinstalled the styles patch and started a new project copying over my changes/additions.   I still can't get <list> working, but markup now works and that is good enough for me :-)    While I understand your encouragement to use <list> over markup I've already spend more time than expected, getting acceptable output. 

I've noticed that some doc's like the Sandcastle MAML Guide (codeplex)  doesn't include the <list> tag while XML Documentation Comments Guide ( does.

Thank you very much for your help!

Aug 29, 2008 at 6:40 PM
Edited Aug 29, 2008 at 6:43 PM

Thanks for the follow-up.

Note that installing the Sandcastle Styles patch does not patch existing DocProjects and DocSites, so simply creating a new project should have helped; i.e., you probably didn't need to reinstall Sandcastle, but no harm done.

The list element is certainly supported in MAML.  Perhaps you didn't specify a valid class attribute?  Note that IntelliSense offers suggested values for the class attribute.  Or maybe you were trying to use list in an invalid context?  The IntelliSense drop down will show where list is supported according to the MAML schema, although Sandcastle is actually much more lenient.

Sandcastle also comes with a working example of the list element within the step of a procedure

    {sandcastle install path}\Examples\conceptualExample\dduexml\f7913259-762e-4a73-a771-ac9e42903f44.xml

Here's a snippet from that file:

<list class="bullet">
    <para>Define the endpoint contract in the <languageKeyword>&lt;services&gt;</languageKeyword>
element and the service behavior in the <languageKeyword>&lt;behaviors&gt;</languageKeyword>
element. For more information about WCF endpoints, see Endpoints in WCF.</para>
    <para>Configure the <languageKeyword>&lt;serviceHostingEnvironment&gt;</languageKeyword>
element for ASP.NET compatibility. For more information about hosting WCF services, see WCF
Services and ASP.NET.</para>
    <para>Create a binding in the <languageKeyword>&lt;bindings&gt;</languageKeyword> element
that requires SSL. For more information about transport security in WCF, see Transport
You seem to be correct that the MAML guide doesn't mention the list element, which might be an oversight or it may have been deffered.  I'm sure Eric will include it in the next release.

The XML Documentation guide doesn't provide any information about MAML, so the list element that it refers to is for use within code comments only.

- Dave
Aug 29, 2008 at 6:56 PM
AH!  I see now what I did wrong.  I was trying to use the /// tag syntax, which isn't the same as the MAML syntax.   When I just cut and paste  your xml into my doc, I see the bullet list I'm looking for.  The /// tag syntax using <item><description> rather than <listItem>.  I dug about and looked in structureList.xsd and can (sort'a) see what's going on. 

Thanks for all the help.
Aug 29, 2008 at 7:26 PM
Edited Aug 29, 2008 at 7:26 PM

So I take it that MAML IntelliSense isn't working for you?

- Dave
Aug 29, 2008 at 7:54 PM

There's intellisense!?  Wow that would be useful :-)
Nope, I'm using VS 2005 TS, but editting a *.aml file I get no real intellisense, when I type '<' I get the choice of '<!', '<![CDATA[]' or '<?', but that's all.

Perhaps I still have something misconfigured?


Aug 29, 2008 at 8:14 PM

Yes, see the link in my first response ;)

- Dave
Aug 29, 2008 at 8:20 PM
<blush> ah yes, I did that little open developer.xsd this morning, but since I've reinstalled, re-project'ed and ... clearly ... forgot to do it again.  Yes, now I get intellisense.
Should I ask why that works :-)  ?

Aug 30, 2008 at 5:32 AM

I really don't know why it works, or rather, why it doesn't work ;)

I guess VS 2005 has the same duplicate schema issue as VS 2008 (described in my How To article) and by opening the schema it gives it priority which resolves the problem, unlike in VS 2008 which requires even more effort to get things working correctly.

According to the documentation, or at least my interpretation of it, simply having the schema in the current solution should do the trick and that's why I initially coded DocProject to import the schema files into new DocProjects and DocSites, while assuming an easy and permanent fix for this issue when I noticed that it wasn't working as expected.  Maybe I should have used a DTD instead - I'll try that for the next release.

You should check out the Global Schema Cache information in the last section of the How To article since it describes how to fix the problem once and for all, without having to manually open the schema file every time you restart VS.

- Dave