Bibliography Support Plug-In

This plug-in adds support for the auto-generated bibliography feature in Sandcastle.

Generating a Bibliography

The auto-generated bibliography feature allows an author to create an external bibliography XML file and then share it between multiple topics by specifying short identifiers in cite elements that match one of the references contained in the file. When one or more cite elements are used, Sandcastle will automatically generate a bibliography for the topic in the place that the bibliography element is specified and the cite elements themselves will be replaced with hyperlinks to corresponding bookmarked entries in the bibliography.

Tip
The bibliography element is typically specified immediately before the relatedTopics section that appears at the bottom of the topic.

To use citations, a bibliography XML file must be created to store the identifiers and entries. A default bibliography file named, bibliography.xml can be found in each presentation style's .\Data folder. The presentation styles are located in the main Sandcastle installation folder in the .\PresentationStyles folder. An example file is also shown below.

Defining Citation Identifiers and Bibliography Entries

If it does not already exist, create a new XML file and add it to the project. The suggested name is bibliography.xml but you can name it what you like. Set the BuildAction to None so that the build ignores it.

Add content similar to the following to the bibliography XML file.

Sample Bibliography.xml File

Copy

<?xml version="1.0" encoding="utf-8"?>
<bibliography>
  <reference name="sandcastle activity">
    <title>Sandcastle Help File Builder Activity Statistics</title>
    <author>Eric Woodruff</author>
    <publisher>CodePlex.com</publisher>
    <link>http://SHFB.codeplex.com/stats/view</link>
  </reference>
  <reference name="shfb">
    <title>Sandcastle Help File Builder</title>
    <author>Eric Woodruff</author>
    <publisher>CodePlex.com</publisher>
    <link>http://SHFB.codeplex.com</link>
  </reference>
</bibliography>

The previous example defines a bibliography XML file that contains two reference elements, which can be referred to by cite elements in a MAML topic using the values of the name attributes.

Tip
Reference names are not case-sensitive.

The title and author elements are required. The publisher and link elements are optional. The only supported content type for each element is plain text.

Add the plug-in to the project's PlugInConfigurations project property. Once added, click the Configure button to specify the path to the bibliography XML file. You can use a replacement tag in the path to specify a special folder such as the project folder (i.e. {@ProjectFolder}Bibliography.xml).

Using the Bibliography in a MAML Topic

Add a bibliography element to the topic, preferably just before the relatedTopics element (see example).
Use cite elements to reference items in the bibliography. The inner text of the element is the value of the name attribute for the entry.

Using the Bibliography in XML Code Comments

Use cite elements to reference items in the bibliography. The inner text of the element is the value of the name attribute for the entry. The Sandcastle transformations will add a bibliography section to the API member's page automatically if any cite elements are found.

Example

The following example MAML topic uses multiple cite elements to reference bibliography entries defined in the bibliography.xml file.

Important
The bibliography element is also specified so that a bibliography section is generated automatically near the bottom of the topic.

Sample Topic with Bibliography

Copy

<?xml version="1.0" encoding="utf-8"?>
<topic id="00000000-0000-0000-0000-000000000000" revisionNumber="1">
  <developerConceptualDocument xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
    xmlns:xlink="http://www.w3.org/1999/xlink">

    <introduction>
      <para>This topic discusses Sandcastle's popularity.</para>
    </introduction>

    <section>
      <title>Sandcsatle's Popularity</title>

      <content>
        <para>Sandcastle is a popular download<cite>sandcastle activity</cite>.</para>

        <para>The Sandcastle Help File Builder<cite>shfb</cite> adds even more value.</para>

        <para>I expect Sandcastle's popularity<cite>sandcastle activity</cite>
to increase as more community members become aware of its usefulness, with the
help of projects like the Sandcastle Help File Builder<cite>shfb</cite>.</para>
      </content>
    </section>

    <!-- Place the bibliography before the relatedTopics section -->
    <bibliography/>

    <relatedTopics/>
  </developerConceptualDocument>
</topic>

Other Resources

Build Process Plug-Ins