Click here to Skip to main content
15,879,095 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.2K   384   35  
Some of the features of DocProject and the offerings of MAML, the mark-up language used for writing conceptual documentation.
<configuration>
  <dduetools>
    <builder>
      <components>

        <!-- Create skeleton document -->
        <component type="Microsoft.Ddue.Tools.CopyFromFileComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
          <data file="..\..\Help\Presentation\Style\transforms\skeleton_conceptual.xml" />
          <copy source="/*" target="/" />
        </component>

        <!-- Copy in comments -->
        <component type="Microsoft.Ddue.Tools.CopyFromIndexComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
          <index name="comments" value="/topic" key="@id">
            <data files=".\DdueXml\*.xml" />
          </index>
          <copy name="comments" source="/topic" target="/document" />
        </component>

        <!-- resolve tokens -->
        <component type="Microsoft.Ddue.Tools.SharedContentComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
          <context prefix="ddue" name="http://ddue.schemas.microsoft.com/authoring/2003/5" />
          <content file="..\..\Help\Settings\tokens.xml" />
          <replace elements="/*//ddue:token" item="string(.)" />
        </component>

        <!-- copy in metadata keywords -->
        <component type="Microsoft.Ddue.Tools.CopyFromFilesComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
          <copy base=".\XmlComp" file="concat($key,'.cmp.xml')" source="/metadata/topic[@id=$key]/*" target="/document/metadata" />
        </component>

        <!-- copy in metadata attributes -->
        <component type="Microsoft.Ddue.Tools.CopyFromIndexComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
          <index name="metadata" value="/metadata/topic" key="@id">
            <data files="..\..\Help\Settings\metadata.xml" />
          </index>
	  <index name="version" value="/metadata/topic" key="@id">
            <data files="..\..\Help\Settings\conceptual_version.xml" />
          </index>
          <copy name="metadata" source="*" target="/document/metadata" />
          <copy name="metadata" key="string('*')" source="*" target="/document/metadata" />
          <copy name="version" key="string('*')" source="*" target="/document/metadata" missing-target="error" />
        </component>

	<!-- Copy in metadata project settings -->
       <component type="Microsoft.Ddue.Tools.CopyFromIndexComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
	  <index name="projectSettings" value="/*/item" key="@id">
            <data files="..\..\Help\Settings\conceptual_project.xml" />
          </index>
          <copy name="projectSettings" key="string('PBM_FileVersion')" source="." target="/document/metadata" />
	</component>

	      <!-- Resolve code snippets -->
        <component type="Microsoft.Ddue.Tools.ExampleComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
          <examples file="..\..\Help\Settings\conceptual_snippets.xml" />
          <colors language="VisualBasic">
            <color pattern="^\s*'[^\r\n]*" class="comment" />
            <color pattern="\&quot;[^&quot;\r\n]*\&quot;" class="literal" />
            <color pattern="\b((AddHandler)|(AddressOf)|(Alias)|(And)|(AndAlso)|(As)|(Boolean)|(ByRef)|(Byte)|(ByVal)|(Call)|(Case)|(Catch)|(CBool)|(CByte)|(CChar)|(CDate)|(CDec)|(CDbl)|(Char)|(CInt)|(Class)|(CLng)|(CObj)|(Const)|(Continue)|(CSByte)|(CShort)|(CSng)|(CStr)|(CType)|(CUInt)|(CULng)|(CUShort)|(Date)|(Decimal)|(Declare)|(Default)|(Delegate)|(Dim)|(DirectCast)|(Do)|(Double)|(Each)|(Else)|(ElseIf)|(End)|(EndIf)|(Enum)|(Erase)|(Error)|(Event)|(Exit)|(False)|(Finally)|(For)|(Friend)|(From)|(Function)|(Get)|(GetType)|(GetXMLNamespace)|(Global)|(GoSub)|(GoTo)|(Handles)|(If)|(Implements)|(Imports)|(In)|(Inherits)|(Integer)|(Interface)|(Is)|(IsNot)|(Let)|(Lib)|(Like)|(Long)|(Loop)|(Me)|(Mod)|(Module)|(MustInherit)|(MustOverride)|(MyBase)|(MyClass)|(Namespace)|(Narrowing)|(New)|(Next)|(Not)|(Nothing)|(NotInheritable)|(NotOverridable)|(Object)|(Of)|(On)|(Operator)|(Option)|(Optional)|(Or)|(OrElse)|(Overloads)|(Overridable)|(Overrides)|(ParamArray)|(Partial)|(Private)|(Property)|(Protected)|(Public)|(RaiseEvent)|(ReadOnly)|(ReDim)|(REM)|(RemoveHandler)|(Resume)|(Return)|(SByte)|(Select)|(Set)|(Shadows)|(Shared)|(Short)|(Single)|(Static)|(Step)|(Stop)|(String)|(Structure)|(Sub)|(SyncLock)|(Then)|(Throw)|(To)|(True)|(Try)|(TryCast)|(TypeOf)|(Variant)|(Wend)|(UInteger)|(ULong)|(UShort)|(Until)|(Using)|(When)|(Where)|(While)|(Widening)|(With)|(WithEvents)|(WriteOnly)|(Xor)|(#Const)|(#Else)|(#ElseIf)|(#End)|(#If))\b" class="keyword" />
          </colors>
          <colors language="CSharp">
             <color pattern="/\*(.|\n)+?\*/" class="comment" />
	     <color pattern="\&quot;[^&quot;\r\n]*\&quot;" class="literal" />
             <color pattern="//[^\r\n]*" class="comment" />
             <color pattern="\b((abstract)|(as)|(ascending)|(base)|(bool)|(break)|(by)|(byte)|(case)|(catch)|(char)|(checked)|(class)|(const)|(continue)|(decimal)|(default)|(delegate)|(descending)|(do)|(double)|(else)|(enum)|(equals)|(event)|(explicit)|(extern)|(false)|(finally)|(fixed)|(float)|(for)|(foreach)|(from)|(get)|(goto)|(group)|(if)|(implicit)|(in)|(int)|(interface)|(internal)|(into)|(is)|(join)|(let)|(lock)|(long)|(namespace)|(new)|(null)|(object)|(operator)|(on)|(orderby)|(out)|(override)|(params)|(partial)|(private)|(protected)|(public)|(readonly)|(ref)|(return)|(sbyte)|(sealed)|(select)|(set)|(short)|(sizeof)|(stackalloc)|(static)|(string)|(struct)|(switch)|(this)|(throw)|(true)|(try)|(typeof)|(uint)|(ulong)|(unchecked)|(unsafe)|(ushort)|(using)|(value)|(var)|(vield)|(virtual)|(volatile)|(void)|(where)|(while))\b" class="keyword" />
          </colors>
          <colors language="ManagedCPlusPlus">
             <color pattern="/\*(.|\n)+?\*/" class="comment" />
             <color pattern="\&quot;[^&quot;\r\n]*\&quot;" class="literal" />
	     <color pattern="//[^\r\n]*" class="comment" />
             <color pattern="\b((abstract)|(array)|(bool)|(break)|(case)|(catch)|(char)|(class)|(const)|(continue)|(default)|(delegate)|(delete)|(deprecated)|(dllexport)|(dllimport)|(do)|(double)|(else)|(enum)|(event)|(explicit)|(extern)|(false)|(finally)|(float)|(for)|(friend)|(gcnew)|(generic)|(goto)|(if)|(initonly)|(inline)|(int)|(interface)|(literal)|(long)|(mutable)|(naked)|(namespace)|(new)|(noinline)|(noreturn)|(nothrow)|(novtable)|(nullptr)|(operator)|(private)|(property)|(protected)|(public)|(ref)|(register)|(return)|(safecast)|(sealed)|(selectany)|(short)|(signed)|(sizeof)|(static)|(struct)|(switch)|(template)|(this)|(thread)|(throw)|(true)|(try)|(typedef)|(typeid)|(typename)|(union)|(unsigned)|(using)|(uuid)|(value)|(virtual)|(void)|(volatile)|(while))\b" class="keyword" /> 
          </colors>
        </component>

	<!-- Copy in topicTypes -->
	<component type="Microsoft.Ddue.Tools.ForEachComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
	<context prefix="ddue" name="http://ddue.schemas.microsoft.com/authoring/2003/5" />
	<context prefix="xlink" name="http://www.w3.org/1999/xlink" />
        <variable expression="/document/topic/*/ddue:relatedTopics/*/@xlink:href" />
        <components>
  		<component type="Microsoft.Ddue.Tools.CopyFromIndexComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
		<context prefix="ddue" name="http://ddue.schemas.microsoft.com/authoring/2003/5" />
		<context prefix="xlink" name="http://www.w3.org/1999/xlink" />
	  		<index name="topicType" value="/metadata/topic" key="@id">
	    			<data files="..\..\Help\Settings\metadata.xml" />
	    		</index>
	  		<copy name="topicType" source="topicType" target="/document/topic/*/ddue:relatedTopics/*[@xlink:href='{0}' and not(@topicType_id)]" attribute="true" ignoreCase="true" missing-target="error" />             	
		</component>
        </components>
	</component>
           
           <!-- Resolve external links -->
           <component type="DaveSexton.Sandcastle.ResolveExternalLinksComponent" assembly="%DocProjectPath%\bin\DaveSexton.Sandcastle.dll" replaceSeeAlsoLinks="False" seeXPath="//ddue:link[@xref|@vref]">
             <seeLinkXml>
              <externalLink xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5">
                <linkText>{2}</linkText>
                <linkUri>{0}</linkUri>
              </externalLink>
             </seeLinkXml>
             <context prefix="ddue" name="http://ddue.schemas.microsoft.com/authoring/2003/5" />
             <mappings target="_blank" file="..\..\Help\Settings\links.xml" />
           </component>

        <!-- transform -->
        <component type="Microsoft.Ddue.Tools.TransformComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
          <transform file="..\..\Help\Presentation\Style\transforms\main_conceptual.xsl">
	          <argument key="metadata" value="true" />
	          <argument key="languages">
	      <language label="VisualBasic" name="VisualBasic" style="vb" />
              <language label="CSharp" name="CSharp" style="cs" />
              <language label="ManagedCPlusPlus" name="ManagedCPlusPlus" style="cpp" />
	      <language label="JSharp" name="JSharp" style="cs" />
              <language label="JScript" name="JScript" style="cs" />
            </argument>
	    
          <argument key="bibliographyData" value="../../../Settings/bibliography.xml" /></transform>
        </component>

        <!-- resolve art links -->
        <component type="Microsoft.Ddue.Tools.ResolveArtLinksComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
          <targets input="..\..\Help\Art" baseOutput=".\Output" outputPath="media" link="../Art" map="..\..\Help\Settings\conceptual_art.xml" />
        </component>

        <!-- resolve shared content -->
        <component type="Microsoft.Ddue.Tools.SharedContentComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
          <content file="..\..\Help\Presentation\Style\content\shared_content.xml" />
	  <content file="..\..\Help\Presentation\Style\content\feedBack_content.xml" />
          <content file="..\..\Help\Presentation\Style\content\conceptual_content.xml" />
        </component>

        <!-- resolve conceptual links -->
        <component type="Microsoft.Ddue.Tools.ResolveConceptualLinksComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
          <targets base=".\XmlComp" files="*.xml" type="local" />
          
        </component>

        <!-- resolve reference links -->
        <component type="Microsoft.Ddue.Tools.ResolveReferenceLinksComponent2" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
          <targets base="%DXROOT%\Data\Reflection\" recurse="true" files="*.xml" type="msdn" />
        <targets files=".\reflection.xml" type="index" /></component>

        <!-- save the result -->
        <component type="Microsoft.Ddue.Tools.SaveComponent" assembly="%DXROOT%\ProductionTools\BuildComponents.dll">
          <save base=".\Output\html" path="concat($key,'.htm')" link="../html" indent="true" omit-xml-declaration="true" />
        </component>

        <!-- record file creation events -->
        

      </components>
    </builder>
  </dduetools>
</configuration>

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