Wouldn't it be cool if you could cite books and web sites while authoring MAML and XML documentation comments and have Sandcastle create a per-topic bibliography automatically?
Someone posted that question in the Sandcastle forums recently and I came up with a solution (in that discussion) that works for the VS 2005 presentation style and both reference and conceptual builds. Please add your vote to this feature request if you're interested in having this ability in Sandcastle.
This isn't a feature that I'm going to add specifically to DocProject since it requires updating XSL transformations. You can add it yourself for now though until it becomes a feature of Sandcastle (hopefully :). Just follow the instructions that I gave in my post in the Sandcastle forum.
Once you make the appropriate updates to the presentation style, here's what you can do to start using this feature in code comments. (Conceptual usage is similar, although you must add an empty <bibliography/> element somewhere in the root of your MAML, preferably before or after the relatedTopics element.)
First, author some XML documentation comments that contain citations.
<remarks>
<para>
The statistics show that Sandcastle is a popular tool on
CodePlex <cite>sandcastle activity stats</cite>.
</para>
<para>
DocProject can be used to automate Sandcastle <cite>DocProject</cite>.
</para>
<para>
The top referring sites are similar for DocProject and
Sandcastle <cite>sandcastle activity stats</cite><cite>docproject activity stats</cite>.
</para>
</remarks>
Next, create a bibliography.xml file that provides additional information. It will be used for all topics that you write in both conceptual and reference builds.
<?xml version="1.0" encoding="utf-8" ?>
<bibliography>
<reference name="sandcastle activity stats">
<title>Sandcastle Activity Statistics</title>
<author>WebTrends</author>
<publisher>CodePlex.com</publisher>
<link>http://www.codeplex.com/Sandcastle/stats/view</link>
</reference>
<reference name="docproject activity stats">
<title>DocProject Activity Statistics</title>
<author>WebTrends</author>
<publisher>CodePlex.com</publisher>
<link>http://www.codeplex.com/DocProject/stats/view</link>
</reference>
<reference name="DocProject">
<title>DocProject</title>
<author>Dave Sexton</author>
<link>http://www.codeplex.com/DocProject</link>
</reference>
</bibliography>
Each in-line citation will be replaced with a hyperlink and a number, which corresponds to an entry in the bibliography that is automatically generated at the bottom of each help topic when one or more <cite> elements are detected.
