This plug-in adds support for the auto-generated bibliography feature that was added to Sandcastle by the Sandcastle Styles patch. The patch must have been applied to Sandcastle in order for this plug-in to work correctly.

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 presenation styles are located in the main Sandcastle installation folder in the .\Presentation folder. An example file is also shown below.

Defining Citation Identifiers and Bibliography Entries

  1. 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.

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

    CopySample Bibliography.xml File
    <?xml version="1.0" encoding="utf-8"?>
<bibliography>
  <reference name="sandcastle activity">
    <title>Sandcastle Activity Statistics</title>
    <author>Microsoft</author>
    <publisher>CodePlex.com</publisher>
    <link>http://Sandcastle.codeplex.com/stats/view</link>
  </reference>
  <reference name="sandcastle styles">
    <title>Sandcastle Styles</title>
    <author>Paul Selormey, Eric Woodruff, Dave Sexton</author>
    <publisher>CodePlex.com</publisher>
    <link>http://SandcastleStyles.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.

  3. 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

  1. Add a bibliography element to the topic, preferably just before the relatedTopics element (see example).

  2. 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.

CopySample Topic with Bibliography
<?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>Sandcastle Styles<cite>sandcastle styles</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 Sandcastle Styles<cite>sandcastle styles</cite>.</para>
      </content>
    </section>

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

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

See Also