Click here to Skip to main content
15,886,026 members
Articles / Programming Languages / MAML

Authoring Documentation with DocProject and Sandcastle

Rate me:
Please Sign up or sign in to vote.
4.91/5 (17 votes)
13 Apr 2012CPOL19 min read 55.3K   384   35  
Some of the features of DocProject and the offerings of MAML, the mark-up language used for writing conceptual documentation.
<?xml version="1.0" encoding="utf-8" ?> 
<!--
  This document specifies ID-to-URL mappings for external links in both conceptual and 
  auto-generated reference documentation.
  
  ResolveExternalLinksComponent
  http://www.codeplex.com/DocProject/Wiki/View.aspx?title=ResolveExternalLinksComponent
  
  Add url elements to this document to create mappings, as in the following examples.
  
  <url id="home" href="http://example.com/home.aspx" />
  <url id="contact" href="http://example.com/contact_us.aspx" />
  <url id="help" href="http://example.com/help.aspx" />
  
  Mappings are used in XML documentation comments by specifying see or seealso elements
  with xref attributes, as in the following examples.
  
  <remarks>
    <para>Visit our <see xref="home"/> page.</para>
    <para>You may <see xref="contact">contact us</see> for more information.</para>
  </remarks>
  <seealso xref="help">Online Assistance</seealso>
  
  Mappings are used in MAML topics by specifying a link element with an xref attribute, 
  as in the following examples.
  
  <section>
    <title/>
    <content>
      <para>Visit our <link xref="home"/> page.</para>
      <para>You may <link xref="contact">contact us</link> for more information.</para>
    </content>
  </section>
  <relatedTopics>
    <link xref="help">Online Assistance</link>
  </relatedTopics>
  
  - The id attribute is not case-sensitive.
  - The mappings in this file do not use a base URL by default (unless one is set on 
    the component level in the configuration file, which it's not by default).
  - Hyperlinks open in a new browser window or tab by default.
  - The default settings for these mappings may be changed by first expanding an 
    appropriate build component stack in the DocProject Properties window.  Then find 
    the "Resolve external links" component and invoke its editor.  Click the Mappings
    tab, select the appropriate mappings group from the list of mappings in the left 
    pane and then adjust the settings in the pane on the right.  You know you've 
    selected the appropriate mappings group if the File field is set to this file.
  - Additional mappings groups that are separate from this file may be added using the 
    editor (see the previous note).  For example, you can add a group that resolves 
    IDs to URLs that are stored in a relational database table.
  -->
<config>
  <!-- add <url> mappings here -->
</config>

By viewing downloads associated with this article you agree to the Terms of Service and the article's licence.

If a file you wish to view isn't highlighted, and is a text file (not binary), please let us know and we'll add colourisation support for it.

License

This article, along with any associated source code and files, is licensed under The Code Project Open License (CPOL)


Written By
Architect Visma Software
Romania Romania
Marius Bancila is the author of Modern C++ Programming Cookbook and The Modern C++ Challenge. He has been a Microsoft MVP since 2006, initially for VC++ and nowadays for Development technologies. He works as a system architect for Visma, a Norwegian-based company. He works with various technologies, both managed and unmanaged, for desktop, cloud, and mobile, mainly developing with VC++ and VC#. He keeps a blog at http://www.mariusbancila.ro/blog, focused on Windows programming. You can follow Marius on Twitter at @mariusbancila.

Comments and Discussions