Can you add html to topic files ?

Topics: Conceptual Topics, DocSites
Feb 22, 2008 at 1:46 AM
I'd like to add bulleted lists and tables to the topic files. Is there a way to add html directly to these files ? Is there a better way ?
Feb 22, 2008 at 5:27 AM
Hi,

Auto-generated reference documentation will include most HTML tags that you add to XML documentation comments, including <ul>, <ol>, <table> and related elements, although Sandcastle's conceptual transformations currently filter out all raw HTML.

If you're referring to conceptual topics that you've created yourself, then you can use <list class="..."> and <table> in place of <para> wherever <para> is supported.

The exact usage of these tags is specified in the MAML Schemas that come with Sandcastle. The schema files are included in new DocProjects and DocSites automatically, although you may have to actually open the Help\Schemas\Developer.xsd file before IntelliSense will be activated in your conceptual topics. Alternatively, you can reference the Schemas in Visual Studio's global schema cache so that you don't need to open Developer.xsd. See this discussion for more information.

If you're referring to auto-generated reference documentation, you can use raw HTML or the <list> documentation comment tag, which provide lists (e.g., bulleted, numbered) or simple table layouts.

See <list> (C# Programming Guide) or <list> (Visual Basic) for more information.

Dynicity LLC's XML Documentation Comments Guide also provides a reference to these tags, among others that don't appear in the MSDN documentation.

- Dave
Feb 23, 2008 at 10:14 PM
Edited Feb 23, 2008 at 10:15 PM
OK, I've got the intelliSense setup and I'm added my content, but that content doesn't get rendered properly. For examples....

{ <introduction>
<para>This help systems provides the code documentation for the Kobold Systems Enterprise Libraries. These
libraries are organised into the following categories...</para>
<list class="bullet">
<listItem>
<para>Framework Libraries including foundation, web and windows form components</para>
</listItem>
<listItem>
<para>Application Libraries including business object, web and windows forms components</para>
</listItem>
<listItem>
<para>Other Internal Libraries</para>
</listItem>
<listItem>
<para>Third Party Libraries Libraries</para>
</listItem>
</list>
</introduction>}

gets rendered as
{ <div class="introduction">
<p>This help systems provides the code documentation for the Kobold Systems Enterprise Libraries. These
libraries are organised into the following categories...
Framework Libraries including foundation, web and windows form components
Application Libraries including business object, web and windows forms components
Other Internal Libraries
Third Party Libraries Libraries

</p>

</div>}


I am getting similar problems with tables. I lose all of the TD/TR/TH etc tags. The TABLE however does remain.

Daniel.
Feb 24, 2008 at 12:48 AM
mmmmm, it looks like I have a build problem, because when I did a manual clean and rebuild, the list items are rendering properly.

The table is still a mess, but there are indications this might be a build issue as well. On one of my machines I'm building using nant and pn that machine I'm not even seeing the topic that contains the table.

I'll chase these build issues down and let you know of the outcome.
Feb 24, 2008 at 5:54 AM
Hi,

Glad to hear that you've got it working, almost ;)

Note that DocProject doesn't manipulate Sandcastle's XSL transformations at all. It does manipulate the configuration files though but only when they are first imported into a new project and when you explicitly change build component stack settings. If you haven't changed the configuration files or the XSL transformations yourself, then you've probably discovered a bug in Sandcastle.

You may want to report it to Microsoft. If you can repro the issue that would be helpful too as the Sandcastle team may request an example:

Sandcastle - Issue Tracker
http://www.codeplex.com/Sandcastle/WorkItem/List.aspx

- Dave
Mar 1, 2008 at 2:44 AM
After further investigation it looks like there were 3 problems going on:
  • I wasn't using correct table syntax. I was using html syntax
  • It appeared that when I did a build, it didn't rebuild all components that have changed. I haven't got a recipe to duplicate this yet, but I found that a well written clean.bat script helped me get around this problem
  • It also appeared that when I added new conceptual topics , the file gets created and I see the new topic in the topic manager, but it doesn't always get added to topics.xml. I've yet to determine the exact sequence of steps here.
Mar 1, 2008 at 3:55 AM
Hi,


I wasn't using correct table syntax. I was using html syntax

That would do it :)


It appeared that when I did a build, it didn't rebuild all components that have changed.

Do you mean that updates to conceptual topics aren't appearing in the compiled help? I can't reproduce this.

Make sure that you're editing XML topic files in the Help\Topics folder. If you double-click a file in Topic Explorer it should automatically open in Visual Studio's XML editor. Make some changes and save the file. Then build the project and you should see the changes that you've made in the compiled help.


It also appeared that when I added new conceptual topics , the file gets created and I see the new topic in the topic manager, but it doesn't always get added to topics.xml.

You have to save the changes to the project first for topics.xml to be updated:

  1. In Visual Studio you must use the Save All command for the changes in Topic Explorer to be committed to the topics.xml file.
  2. In the DocProject External UI simply use the normal Save command.
  3. When you build the project the topics.xml file is updated with the latest changes automatically.
- Dave