bibliography/cite

The auto-generated bibliography feature, an extension provided by the presentation styles in the Sandcastle Help File Builder, allows an author to create an external bibliography data 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 section.

  Tip

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

Usage

To use citations, a bibliography data XML file must be created to store the identifiers and entries. Add the file to the project and specify the file's name in the Transformation Arguments section of the project properties, typically the BibliographyDataFile argument. An example file is shown below. Note that not all presentation styles support the bibliography elements such as Open XML-based styles. In such cases they will be ignored.

Defining Citation Identifiers and Bibliography Entries

  1. If it does not already exist, add a new bibliography data file to the project. An item template is supplied with the help file builder standalone GUI and Visual Studio package. 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.

    Sample Bibliography.xml File
    <?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>GitHub.com</publisher>
    <link>https://GitHub.com/EWSoftware/SHFB/pulse/monthly</link>
  </reference>
  <reference name="SHFB">
    <title>Sandcastle Help File Builder</title>
    <author>Eric Woodruff</author>
    <publisher>GitHub.com</publisher>
    <link>https://GitHub.com/EWSoftware/SHFB</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.

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.

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 in MAML topics so that a bibliography section is generated automatically near the bottom of the topic.

Sample 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>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>

Example Output

Sandcastle is a popular download[1].

The Sandcastle Help File Builder[2] adds even more value.

I expect Sandcastle's popularity[1] to increase as more community members become aware of its usefulness, with the help of projects like the Sandcastle Help File Builder[2].

Bibliography

[1] Eric Woodruff, Sandcastle Help File Builder Activity Statistics, GitHub.com, https://GitHub.com/EWSoftware/SHFB/pulse/monthly
[2] Eric Woodruff, Sandcastle Help File Builder, GitHub.com, https://GitHub.com/EWSoftware/SHFB

See Also

Other Resources