Bibliography/Works Cited

Topics: Developer Forum, User Forum
Oct 21, 2008 at 7:20 PM
Hi,

We would like to create a bibliography or works cited for our help file.  Then reference or cite the source of our information at the Class/method/etc. that used that reference.  The helpfile reference should either be a hyperlink to the bibliography or a reproduction of the bibliography entry. 

Ideally, I would have an XML "bibliography" or some similar document that contains all the references, which would be added to the help file as additional content.  Then there would be some sort of XML <bibliography> tag that would create an expandable section in the help file (like <summary>,<remarks>, etc.). Then inside the tag, the coder could uses the <include> tag in something like this:

<include file='../Bibliogrphy.xml' path='member[@name="DesginPatterns"]/*'/>

where DesignPatters is the name of the bibliography entry that should be included in with the particular help file entry.  This way all referenced works are cited in a standardized way and kept in the same place. 

I think that I can do almost all of this, with the exception of having a "Bibliography" <bibliography> tag.  I am thinking that if I can't find a substitute <bibliography> tag, I'll just put the bibliography entries in the <remarks> section.

Can I make my own primary <bibliography> tag?  Is there something like this already out there?  Does anyone have any recommendations or methods for citing sources in code and the help file? 

Thank you very much!

cam
Coordinator
Oct 21, 2008 at 9:59 PM
Dave Sexton added bibliography support to the Sandcastle Styles patch (http://www.codeplex.com/SandcastleStyles).  Download and apply the patch to Sandcastle and post a message in the Discussion forum there asking for help.  Dave will most likely reply with info on how to go about using the elements and were to put the extra data file.

Eric
Oct 23, 2008 at 2:39 PM
Hi,

There's an uncompiled MAML help file on the subject in our C# class library example for the Sandcastle Styles project:

http://www.codeplex.com/SandcastleStyles/SourceControl/FileView.aspx?itemId=291362&changeSetId=19568

We also have an XML bibliography template that contains additional instructions and usage information:

http://www.codeplex.com/SandcastleStyles/SourceControl/FileView.aspx?itemId=268468&changeSetId=19568

I wrote a related blog post a while back, although it was posted before the bibliography feature was integrated into the Sandcastle Styles release, so it may be a bit outdated:

http://davesexton.com/blog/blogs/blog/archive/2008/04/25/sandcastle-auto-generated-bibliography.aspx

Here are some points to note about the Sandcastle Styles bibliography feature:

  1. You write all of the bibliography entries for the entire documentation set in a single XML document (see the links above for information about schema).  You can place the file in the chosen presentation style's Data folder or any other folder.  (Sandcastle Styles provides a Data folder with an empty bibliography.xml file for each of the three built-in presentation styles.)
  2. Depending upon the tool you are using to automate Sandcastle, you may have to modify the Sandcastle configuration files to include the XML file as an XSLT argument.  (Either sandcastle.config or conceptual.config must be updated, depending upon whether you want to use this feature in reference documentation, conceptual documentation or both).
    1. To configure Sandcastle, find the main XSLT component (Microsoft.Ddue.Tools.TransformComponent) in the configuration file and add a new argument to it: <argument key='bibliographyData' value='../Data/bibliography.xml' />
    2. Change the path in the value attribute if you want to store the file at a different location.
  3. While authoring documentation, you can use <cite>entry name</cite> elements in MAML topics and XML documentation comments to cite sources.  (Note that entry name is case-sensitive.)
  4. In MAML topics, you must also add a <bibliography/> element to the document.  I recommend placing it immediately before the <relatedTopics> ... </relatedTopics> element.
  5. When one or more <cite/> elements are found in any given topic, this feature will automatically add a Bibliography section to the end of the topic and then replace all of the <cite/> elements with appropriate hyperlinks.
  6. This feature does not support having a single auto-generated bibliography for the entire documentation set, although I imagine that authoring a new MAML document type for this wouldn't be too difficult.  If anyone is interested please add a feature request over at the Sandcastle Styles project.
- Dave
Oct 23, 2008 at 8:09 PM
Edited Oct 23, 2008 at 8:27 PM
Dave and Eric,

Thank you for responding!  That is exactly what I am looking for.  As you suggested, I am going to restart this post on the Sandcastle Styles Discussion board.

Here is a link to the new post:

http://www.codeplex.com/SandcastleStyles/Thread/View.aspx?ThreadId=38382

Thanks,
Cam