Sandcastle MAML Guide - Documentation & Help · Sandcastle MAML Guide Welcome Welcome to the...

SandcastleMAMLGuide

Welcome

WelcometotheSandcastleMAMLGuide.ThisisintendedtobeareferencethatyoucanusetofindoutallthatyouneedtoknowaboutMicrosoftAssistanceMarkupLanguage(MAML)asusedwithSandcastletoproducehelpfilescontainingconceptualcontent.Currently,thereisverylittleinformationaboutMAMLandallofthefeaturesthatitoffers.Assuch,considerthisaworkinprogress.Ifyouhaveanyinformation,tips,updates,orcorrectionsthatyouwouldliketoseeaddedtotheguide,feelfreetosubmitthemtotheauthorusingtheSendFeedbacklinkatthetopofthepageorthee-maillinkinthepagefooter.

WhatisConceptualContent?Conceptualcontentallowsyoutodefinenon-APIdocumentationthatisincludedinthehelpfileforusagenotes,walkthroughs,tutorials,etc.InsteadofHTML,conceptualcontenttopicsuseMicrosoftAssistanceMarkupLanguage(MAML).ThisisbasicallyXMLconformingtoawelldefinedschemathatdescribesthestructureoftheconceptualcontentmuchlikeXMLcommentsdescribethestructureofthecodecomments.ThereisnolayoutorstyleinformationwithintheMAMLfiles.Instead,theyareranthroughaseriesofXSLtransformationsusingSandcastle'sBuildAssemblertoolsimilartothereference(API)contentsothattheymatchitinappearanceandfeatures.ThisallowsyoutoutilizethevariousSandcastleandthird-partybuildcomponentstoalterandextendthepresentationstyleusedinthetopics.

Theterm"conceptualcontent"isactuallyacatch-alltermusedtorefertothevarioustypesofcontentthatmayappearinthehelpfile.MAMLactuallydefinesseveraldifferentcontenttypes,eachusedforaspecifictypeofdocument(conceptual,glossary,how-to,reference,etc.).EachtypehasaspecificstructurewithvariousrequiredandoptionalXMLelements.Thishelpfilewillletyougettoknowthevariousdocumentandelementtypes.

CreatingConceptualContent

Creatingtheactualtopicfilesisjustamatterofenteringthecontentusingatexteditor.CreatingahelpfilefromthemrequiresseveralconfigurationfilesandtheSandcastletools.IfyouaregoingtobuildahelpfileusingSandcastlealone,seethetopicsintheConceptualContentFileTypessection.Theycoverthevariousfiletypesthatareusedinthebuildprocess.

Ifyoupreferamorevisualandautomatedapproachtomanagingandbuildinghelpfiles,itisstronglyrecommendedthatyouuseoneofthethird-partytoolssuchastheSandcastleHelpFileBuilder.TheycontainallofthenecessaryfeaturesandtoolsrequiredtomakebuildinghelpfileswithSandcastleamuchsimplerprocess.ThishelpfilewasproducedusingtheSandcastleHelpFileBuilderandisanexampleofwhattheVS2013presentationstylelookslike.

SeeAlsoOtherResourcesKnownIssuesandBugsLinkstoResourcesConceptualContentFileTypes

[v1.1.0.3]SandcastleMAMLGuide

SendcommentsonthistopictoEricWoodruff

https://GitHub.com/EWSoftware/SHFB



mailto:Eric%40EWoodruff.us?Subject=Sandcastle MAML Guide

SandcastleMAMLGuide

LicenseAgreement

Thislicensegovernsuseoftheaccompanyingsoftware.Ifyouusethesoftware,youacceptthislicense.Ifyoudonotacceptthelicense,donotusethesoftware.

MicrosoftPublicLicense(Ms-PL)1. Definitions

Theterms"reproduce,""reproduction,""derivativeworks,"and"distribution"havethesamemeaninghereasunderU.S.copyrightlaw.

A"contribution"istheoriginalsoftware,oranyadditionsorchangestothesoftware.

A"contributor"isanypersonthatdistributesitscontributionunderthislicense.

"Licensedpatents"areacontributor'spatentclaimsthatreaddirectlyonitscontribution.

2. GrantofRights

(A)CopyrightGrant-Subjecttothetermsofthislicense,includingthelicenseconditionsandlimitationsinsection3,eachcontributorgrantsyouanon-exclusive,worldwide,royalty-freecopyrightlicensetoreproduceitscontribution,preparederivativeworksofitscontribution,anddistributeitscontributionoranyderivativeworksthatyoucreate.

(B)PatentGrant-Subjecttothetermsofthislicense,includingthelicenseconditionsandlimitationsinsection3,eachcontributorgrantsyouanon-exclusive,worldwide,royalty-freelicenseunderitslicensedpatentstomake,havemade,use,sell,offerforsale,import,and/orotherwisedisposeofitscontributioninthesoftwareorderivativeworksofthecontributioninthesoftware.

3. ConditionsandLimitations

(A)NoTrademarkLicense-Thislicensedoesnotgrantyourightstouseanycontributors'name,logo,ortrademarks.

(B)Ifyoubringapatentclaimagainstanycontributoroverpatentsthatyouclaimareinfringedbythesoftware,yourpatentlicensefromsuchcontributortothesoftwareendsautomatically.

(C)Ifyoudistributeanyportionofthesoftware,youmustretainallcopyright,patent,trademark,andattributionnoticesthatarepresentinthesoftware.

(D)Ifyoudistributeanyportionofthesoftwareinsourcecodeform,youmaydosoonlyunderthislicensebyincludingacompletecopyofthislicensewithyourdistribution.Ifyoudistributeanyportionofthesoftwareincompiledorobjectcodeform,youmayonlydosounderalicensethatcomplieswiththislicense.

(E)Thesoftwareislicensed"as-is."Youbeartheriskofusingit.Thecontributorsgivenoexpresswarranties,guaranteesorconditions.Youmayhaveadditionalconsumerrightsunderyourlocallawswhichthislicensecannotchange.Totheextentpermittedunderyourlocallaws,thecontributorsexcludetheimpliedwarrantiesofmerchantability,fitnessforaparticularpurposeandnon-infringement.





SandcastleMAMLGuide

KnownIssuesandBugs

ThistopiccoversknownissuesandbugswithSandcastleandconceptualcontent.Currently,theVS2013presentationstyleisthebestchoiceforconceptualcontentasitcontainsnoknownissuesbeyondthosenotedintheGeneralIssuessection.

GeneralIssuesThesearethecurrentlyknownissueswithSandcastleingeneralwhenusedtoproduceconceptualcontentregardlessofpresentationstyle.

TheredoesnotappeartobeanyformattingforseveraloftheWhitepapertopicelements.

SeveralelementsoftheXMLReferencetopictypedonotrendercorrectlyifatall.

Sandcastle'sXSLtransformationsremoveinter-elementwhitespace.Assuch,ifyouplacetwoMAMLelementsoneaftertheotherandrequireaseparatingspacebetweenthem,useanon-breakingspaceentity( ).Seethereplaceabletopicforanexample.

SeeAlsoOtherResourcesWelcome





SandcastleMAMLGuide

ConceptualContentFileTypes

Thetopicsinthissectiondefinethevariousfiletypesusedtoproduceconceptualcontenthelpfiles.IfyouareusingatoolsuchastheSandcastleHelpFileBuilder,onlythetopicfileinformationwillbeofinteresttoyou.Theotherfiletypesareusedbythebuildprocessandmayonlybeofinterestifyouwanttoseehoweverythingfitstogetherandisusedtobuildthehelptopics.

ConceptualContentFileTypesSelectoneofthetopicsbelowtolearnmoreaboutaparticularfiletype.

CodeSnippetsFile

MediaContentFile

TokenFile

TopicFile

CompanionFile






SandcastleMAMLGuide

CodeSnippetsFile

Thecodesnippetsfileallowsyoutodefinecodesamplesoutsideofconceptualtopicfiles.EachsnippethasauniqueIDthatcanbereferencedinmultipletopicsusingacodeReferenceMAMLelementsothatthesnippetsdonothavetobecopiedintoeachone.Automaticcolorizationandlanguagefiltersynchronizationissupportedbyspecifyingalanguageidentifieronthecodesamples.

CurrentlysupportedidentifiersareVisualBasic,CSharp,ManagedCPlusPlus,JSharp,andJScript.CustomcolorizationrulescanbeaddedtotheconceptualconfigurationfilefortheExampleComponent.

Note

WhenusingtheSandcastleHelpFileBuilderorthestandalonebuildcomponentsfromit,theCodeBlockComponentoffersthesamesetoffeaturesandseveralothersforbothinlineandexternalcodesnippets.Inaddition,itsupportsmanyotherlanguagesandcanimportcodefromworkingsourcecodefileswhichallowsyoutopullinexamplesfromworkingprojectsthatyoucanmaintainandbuildwithouthavingtoupdateaseparateexamplesnippetsfile.Assuch,youmayprefertouseitratherthanthecodesnippetsfile.

CodeSnippetsFileFormatBelowisanexampleofacodesnippetsfile.

<?xmlversion="1.0"encoding="utf-8"?>



<examples>

<itemid="ClassDefinition#Define">

<sampleCodelanguage="CSharp">

publicclassCSharpClass()

CopyExampleCodeSnippetsFile

Thefileconsistsofarootexamplesnodethatcontainsoneormoreitemnodes.Theitemelementhasanidattributethatgiveseachoneauniqueidentifier.ThisisusedastheinnertextofthecodeReferenceelementinatopictorepresentthesnippet.

Note

TheIDvaluemustconsistsofanexampleID,ahashcharacter(#),andasampleID.TheexampleandsampleIDvaluesare

{

//Membersgohere

}

</sampleCode>

<sampleCodelanguage="VisualBasic">

PublicClassVBClass

'Membersgohere

EndClass

</sampleCode>

</item>

<itemid="CreateInstance#Local">


CSharpClassx=newCSharpClass();

</sampleCode>


DimxAsVBClass=NewVBClass()

</sampleCode>

</item>

<itemid="CreateInstance#Static">


publicstaticCSharpClasssharedInstance=newCSharpClass();

</sampleCode>


PublicSharedsharedInstanceAsVBClass=NewVBClass()

</sampleCode>

</item>

</examples>

notcase-sensitive.TheexampleIDdoesnothavetobeunique.However,whencombinedwithasampleID,theentirevaluemustbeunique.

EachitemmustcontainoneormoresampleCodeelementswithalanguageattributeidentifyingthelanguageofthesamplecode.ThevalidlanguageIDsarenotedabove.TheinnerXMLofthesampleCodeelementisthecodesnippet.

SeeAlsoOtherResourcesConceptualContentFileTypescodeReference





SandcastleMAMLGuide

MediaContentFile

Themedia(images)usedbyconceptualcontentinahelpfileprojectaredefinedinaseparatemediacontentfile.EachisassignedauniqueIDthatisusedtorefertotheimageinconceptualtopiclinks.Whenahelpfileisbuilt,allimagesreferencedbyanimagelinkarecopiedtothehelpfile's.\Mediafolder.Anyunusedimagesareomitted.

Note

TheSandcastleHelpFileBuilderdoesnotuseamediacontentfiledirectly.Instead,imagesaremanagedasprojectfileitemsandthemediacontentfileiscreatedforyouautomaticallyatbuildtimebasedonthepropertyvaluesonthoseitems.

MediaContentFileFormatBelowisanexampleofamediacontentfile.




<stockSharedContentDefinitions>

<itemid="4cfacbe8-d100-471c-9d69-1dbcce50e316">

<imagefile="..\ProjectImages\SmallInformation.png"

<altText>Information</altText>

</image>

</item>

<itemid="6be7079d-a9d8-4189-9021-0f72d1642beb">

<imagefile="..\ProjectImages\SandcastleLogoLarge.JPG"

<altText>Sandcastle</altText>

</image>

</item>

<itemid="98a8a8b7-c374-40c7-902a-91c947bf107c">

CopyExampleMediaContentFile

ThefileconsistsofarootstockSharedContentDefinitionsnodethatcontainsoneormoreitemnodesthatrepresenttheimages.

Theitemelementhasanidattributethatgiveseachoneauniqueidentifier.Thisisusedasthetargetofthemedialinkelementsinthetopics.Withintheitemelementisarequiredimageelementusedtodefinetheimage.Thefileattributeshouldpointtothelocationoftheimagefile.Arelativeorabsolutepathcanbeusedaslongasitcanbelocatedatbuildtime.Ifyouwouldliketodisplayalternatetextwhenthemousehoversovertheimage,nestanaltTextelementwithintheimageelementasshowninthefirstitemintheexampleabove.Theinnertextforitdefinesthealternatetexttodisplay.

Note

TheuniqueIDisnotcase-sensitive.TheexampleaboveusesGUIDvaluesfortheIDbutyouarefreetouseanyuniquevaluethatyoulike.

Caution

Unliketopics,imagefileswillretaintheirnamewhencopiedtothemediafolder.Assuch,ifyouaddtwoimagesfromdifferentlocationsthathavethesamename,onewilloverwritetheotherwhenthehelpfileisbuilt.

SeeAlsoOtherResourcesConceptualContentFileTypesmediaLinkmedialLinkInline

<imagefile="..\ProjectImages\SandcastleLogoSmall.jpg"

</item>

<itemid="b5d069f7-5daf-45ae-882c-4596ab2b724a">

<imagefile="..\ProjectImages\SecuritySuccess.png"

</item>

</stockSharedContentDefinitions>

SandcastleMAMLGuide

TokenFile

Atokenisusedasareplaceabletagwithinatopicandisrepresentedusingatokenelement.Theinnertextoftheelementisatokenname.Thetokensaredefinedinaseparatetokenfile.Theyareaneasywaytorepresentcommonitemsthatyouuseregularlysuchasacommonphraseorexternallink.

TokenFileFormatBelowisanexampleofatokenfile.

Thefileconsistsofarootcontentnodethatcontainsoneormoreitemnodes.Besuretoaddthexml:spaceattributetopreserve




<contentxml:space="preserve"

xmlns:ddue="http://ddue.schemas.microsoft.com/authoring/2003/5"

xmlns:xlink="http://www.w3.org/1999/xlink">

<itemid="Sandcastle"><ddue:externalLink>

<ddue:linkText>Sandcastle</ddue:linkText>

<ddue:linkUri>https://GitHub.com/EWSoftware/SHFB

</ddue:externalLink></item>

<itemid="SHFB"><ddue:externalLink>

<ddue:linkText>SandcastleHelpFileBuilder</ddue:linkText

<ddue:linkUri>https://GitHub.com/EWSoftware/SHFB

</ddue:externalLink></item>

<itemid="autoOutline"><autoOutline/></item>

</content>

CopyExampleTokenFile

whitespaceandthetwonamespaceattributesonthecontentelement.

Theitemelementhasanidattributethatgiveseachoneauniqueidentifier.Thisisusedastheinnertextofthetokenelementinatopictorepresentthetoken.TheinnerXMLoftheitemwillbeusedtoreplacethetokenatbuild-time.

Note

ThetokenIDisnotcase-sensitive.

TokenContentThecontentofatokenitemcanbeanythingyoulikeandmayincludeotherMAMLelements.Intheexampleabove,thefirstfourelementsareusedtodefinecommonexternallinksusedbythisproject.

Note

IfyouembedMAMLelementswithinatoken,youmustprefixeachelementnamewith"ddue:"(withoutthequotes)asshownintheexampleabove.Ifnot,theelementsareinsertedusingthedefaultemptynamespaceandtheywillnotbeprocessedbytheSandcastletransformations.

TheautoOutlinetokenisaspecialcaseusedbyearlierversionsofSandcastletoinsertanauto-generatedsectionoutlinewithinatopic'sintroductionorsub-sections.SeetheautoOutlinetopicformoreinformation.

Tip

TheSandcastleHelpFileBuilderaddstheautoOutlinetokenaspartofthebuildautomatically.Assuch,youdonotneedtodefineitintheprojectyourself.

Tip

SandcastlecontainsanextensiontotheMAMLschemaandtheautoOutlineelementcanbeaddeddirectlyinthetopicwithouttheneedforembeddingitinatoken.


SeeAlsoOtherResourcesConceptualContentFileTypesautoOutlinetoken





SandcastleMAMLGuide

TopicFile

Thetopicfileisusedtocontainasingleconceptualtopic.InsteadofHTML,conceptualcontenttopicsuseMicrosoftAssistanceMarkupLanguage(MAML).ThisisbasicallyXMLconformingtoawelldefinedschemathatdescribesthestructureoftheconceptualcontentmuchlikeXMLcommentsdescribethestructureofthecodecomments.ThereisnolayoutorstyleinformationwithintheMAMLfiles.Instead,theyareranthroughaseriesofXSLtransformationsusingSandcastle'sBuildAssemblertoolsimilartothereference(API)contentsothattheymatchitinappearanceandfeatures.Thisallowsyoutoutilizethevariousbuildcomponentstoalterandextendthepresentationstyleofthetopics.

TopicFileStructureMAMLdefinesseveraldifferentcontenttypes,eachusedforaspecifictypeofdocument(conceptual,glossary,how-to,reference,etc.).EachtypehasaspecificstructurewithvariousrequiredandoptionalXMLelements.Whenbuildingconceptualcontent,eachtopicrequiresauniqueIDintheformofagloballyuniqueidentifier(GUID)andarevisionnumber.Thesearespecifiedinacontainingtopicelementinthecontentfileasshowninthisexample.



<topicid="303c996a-2911-4c08-b492-6496c82b3edb"revisionNumber



<developerConceptualDocument

xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"




</developerConceptualDocument>

</topic>

CopyTopicExample

Note

ThetopicelementisnotpartoftheMAMLschemabutisrequiredinordertobuildthehelpfile.TheexampletopicsbelowincludeatopicelementwithplaceholderIDandRevisionNumbervalues.Ifyoucopythesefiles,besuretoreplacetheIDineachtopicwithauniquevalueofyourownforeachfilethatyoucreate.

DocumentTypesSelectoneofthetopicsbelowtolearnmoreaboutaparticulardocumenttype.

Conceptual

ErrorMessage

Glossary

How-To

Orientation

Reference

ReferenceWithSyntax

ReferenceWithoutSyntax

Sample

SDKTechnologyArchitecture

SDKTechnologyCodeDirectory

SDKTechnologyOrientation

SDKTechnologyScenarios

SDKTechnologySummary

Troubleshooting

UserInterfaceReference

Walkthrough

Whitepaper

XMLReference

SeeAlsoOtherResourcesConceptualContentFileTypes





SandcastleMAMLGuide

Conceptual

Thisdocumenttypeisusedforgeneralconceptualtopics.

ConceptualFileFormatBelowisanexampleofaConceptualtopicfile.


<topicid="00000000-0000-0000-0000-000000000000"revisionNumber






<introduction>





<para>Requiredintroduction</para>

</introduction>

<!--Addoneormoretop-levelsectionelements.Thesearecollapsible.

CopyConceptualTopic

Ifusing<autoOutline/>,addanaddressattributetoidentifyit

andspecifyatitlesothatitcanbejumpedtowithahyperlink.-->

<sectionaddress="Section1">

<title>Optionalsectiontitle</title>

<content>



<para>Addoneormoresectionswithcontent

</content>



</section>

<relatedTopics>

<!--Oneormoreofthefollowing:

-Alocallink

-Anexternallink

-Acodeentityreference

<linkxlink:href="OtherTopic'sID"/>

<linkxlink:href="OtherTopic'sID">Linkinnertext</link>

<externalLink>

<linkText>Linktext</linkText>

<linkAlternateText>Optionalalternatelinktext</linkAlternateText>

SeeAlsoOtherResourcesTopicFile



<linkUri>URI</linkUri>

</externalLink>

<codeEntityReference>APImemberID</codeEntityReference>

Examples:

<linkxlink:href="00e97994-e9e6-46e0-b420-5be86b2f8270"/>

<linkxlink:href="00e97994-e9e6-46e0-b420-5be86b2f8278">Someothertopic</link>

<externalLink>

<linkText>SandcastleHelpFileBuilderonGitHub</linkText>

<linkAlternateText>GotoGitHub</linkAlternateText>

<linkUri>https://GitHub.com/EWSoftware/SHFB</linkUri>

</externalLink>

<codeEntityReference>T:TestDoc.TestClass</codeEntityReference>

<codeEntityReference>P:TestDoc.TestClass.SomeProperty</codeEntityReference>

<codeEntityReference>M:TestDoc.TestClass.#ctor</codeEntityReference>

<codeEntityReference>M:TestDoc.TestClass.#ctor(System.String,System.Int32)</codeEntityReference>

<codeEntityReference>M:TestDoc.TestClass.ToString</codeEntityReference>

<codeEntityReference>M:TestDoc.TestClass.FirstMethod</codeEntityReference>

<codeEntityReference>M:TestDoc.TestClass.SecondMethod(System.Int32,System.String)</codeEntityReference>

-->

</relatedTopics>


</topic>



SandcastleMAMLGuide

ErrorMessage

Thisdocumenttypeisusedforerrormessagetopics.

ErrorMessageFileFormatBelowisanexampleofanErrorMessagetopicfile.



<developerErrorMessageDocument









<introduction>


</introduction>





<relatedTopics>

CopyErrorMessageTopic

SeeAlso


-Alocallink

-Anexternallink


<linkxlink:href="OtherTopic'sID">Linktext</link>

<externalLink>




</externalLink>


Examples:


<externalLink>




</externalLink>








-->

</relatedTopics>

</developerErrorMessageDocument>

</topic>

OtherResourcesTopicFile





SandcastleMAMLGuide

Glossary

Thisdocumenttypeisusedtocreateaglossary.

GlossaryFileFormatBelowisanexampleofaGlossarytopicfile.



<developerGlossaryDocument



<glossary>





<glossaryDivaddress="Group1">

<title>Group#1</title>

CopyGlossaryTopic

<glossaryEntry>

<terms>



<termtermId="xyz">1stterm</term>

<term>Otherterm(ifany)</term>

</terms>

<definition>

<para>Thedefinitionoftheterm(s)</para

</definition>





</glossaryEntry>

</glossaryDiv>

</glossary>

</developerGlossaryDocument>

</topic>

SandcastleMAMLGuide

How-To

Thisdocumenttypeisusedfor"howto"topics.

How-ToFileFormatBelowisanexampleofaHow-Totopicfile.



<developerHowToDocument





<introduction>


</introduction>



<procedure>

<title>Proceduretitle</title>

<stepsclass="ordered">

<step>

<content>

CopyHow-ToTopic

<para>Firststep</para>

</content>

</step>

<step>

<content>

<para>Secondstep</para>

</content>

</step>

</steps>



</procedure>









<relatedTopics>


-Alocallink

-Anexternallink



<externalLink>




</externalLink>


Examples:

SandcastleMAMLGuide

Orientation

Thisdocumenttypeisusedfororientationtopics.

OrientationFileFormatBelowisanexampleofanOrientationtopicfile.



<developerOrientationDocument





<introduction>


</introduction>









CopyOrientationTopic

<relatedTopics>


-Alocallink

-Anexternallink



<externalLink>




</externalLink>


Examples:


<externalLink>




</externalLink>








-->

</relatedTopics>

</developerOrientationDocument>

</topic>

SandcastleMAMLGuide

Reference

Thisdocumenttypeisusedforreferencetopics.

ReferenceFileFormatBelowisanexampleofaReferencetopicfile.

SeeAlso



<codeEntityDocument





<assembly>

<assemblyName>Assemblyname</assemblyName>

</assembly>

<codeEntities>

<codeEntity>

<codeEntityReference>APImemberID</codeEntityReference

</codeEntity>

</codeEntities>

</codeEntityDocument>

</topic>

CopyReferenceTopic

OtherResourcesTopicFile





SandcastleMAMLGuide

ReferenceWithSyntax

Thisdocumenttypeisusedforreferencewithsyntaxtopics.

ReferenceWithSyntaxFileFormatBelowisanexampleofaReferenceWithSyntaxtopicfile.



<developerReferenceWithSyntaxDocument







insteadofthis.-->

<introduction>







CopyReferenceWithSyntaxTopic

</introduction>

<syntaxSection>

<sections>

<section>

<title>Syntaxsectiontitle</title>

<content>

<para>Syntaxcontent</para>

</content>

</section>

</sections>

<legacySyntax>

<parameterReference>Parameterreference</parameterReference

</legacySyntax>

</syntaxSection>















Ifusing<autoOutline/>,addanaddressattributetoidentify

itsothatitcanbejumpedtowithahyperlink.-->



<content>


<autoOutline/>-->


</content>

</section>

<relatedTopics>


-Alocallink


-Anexternallink



<externalLink>




</externalLink>


Examples:


<externalLink>




</externalLink>








-->

</relatedTopics>

</developerReferenceWithSyntaxDocument>

</topic>

SandcastleMAMLGuide


Thisdocumenttypeisusedforreferencewithoutsyntaxtopics.

ReferenceWithoutSyntaxFileFormatBelowisanexampleofaReferenceWithoutSyntaxtopicfile.



<developerReferenceWithoutSyntaxDocument







insteadofthis.-->

<introduction>







CopyReferenceWithoutSyntaxTopic

</introduction>






<content>


<autoOutline/>-->


</content>

</section>




<relatedTopics>


-Alocallink

-Anexternallink



<externalLink>




</externalLink>


Examples:


<externalLink>




</externalLink>








-->

</relatedTopics>

</developerReferenceWithoutSyntaxDocument>

</topic>



SandcastleMAMLGuide

Sample

Thisdocumenttypeisusedforsampletopics.

SampleFileFormatBelowisanexampleofaSampletopicfile.



<developerSampleDocument





<introduction>







</introduction>



CopySampleTopic

<content>


<autoOutline/>-->


</content>

</section>

<relatedTopics>


-Alocallink

-Anexternallink



<externalLink>




</externalLink>


Examples:


<externalLink>




</externalLink>











-->

</relatedTopics>

</developerSampleDocument>

</topic>



SandcastleMAMLGuide

SDKTechnologyArchitecture

Thisdocumenttypeisusedfortechnologyarchitecturetopics.

SDKTechnologyArchitectureFileFormatBelowisanexampleofanSDKTechnologyArchitecturetopicfile.



<developerSDKTechnologyOverviewArchitectureDocument





<introduction>







</introduction>


CopySDKTechnologyArchitectureTopic





<content>


<autoOutline/>-->


</content>

</section>

<relatedTopics>


-Alocallink

-Anexternallink



<externalLink>




</externalLink>


Examples:


<externalLink>




</externalLink>











-->

</relatedTopics>

</developerSDKTechnologyOverviewArchitectureDocument

</topic>



SandcastleMAMLGuide

SDKTechnologyCodeDirectory

ThisdocumenttypeisusedforUIreferencetopics.

SDKTechnologyCodeDirectoryFileFormatBelowisanexampleofanSDKTechnologyCodeDirectorytopicfile.



<developerSDKTechnologyOverviewCodeDirectoryDocument





<introduction>


</introduction>

<codeList>

<content>

<para>Codelistcontent</para>

</content>

</codeList>

CopySDKTechnologyCodeDirectoryTopic

<relatedTopics>


-Alocallink

-Anexternallink



<externalLink>




</externalLink>


Examples:


<externalLink>




</externalLink>








-->

</relatedTopics>

</developerSDKTechnologyOverviewCodeDirectoryDocument

</topic>

SandcastleMAMLGuide

SDKTechnologyOrientation

Thisdocumenttypeisusedfortechnologyorientationtopics.

SDKTechnologyOrientationFileFormatBelowisanexampleofanSDKTechnologyOrientationtopicfile.



<developerSDKTechnologyOverviewOrientationDocument





<introduction>


</introduction>

<inThisSection>

<content>

<para>"InThisSection"info</para>

</content>

</inThisSection>



CopySDKTechnologyOrientationTopic

</developerSDKTechnologyOverviewOrientationDocument

</topic>

SandcastleMAMLGuide

SDKTechnologyScenarios

Thisdocumenttypeisusedfortechnologyscenariotopics.

SDKTechnologyScenariosFileFormatBelowisanexampleofanSDKTechnologyScenariostopicfile.



<developerSDKTechnologyOverviewScenariosDocument





<introduction>







</introduction>


CopySDKTechnologyScenariosTopic





<content>


<autoOutline/>-->


</content>

</section>

<relatedTopics>


-Alocallink

-Anexternallink



<externalLink>




</externalLink>


Examples:


<externalLink>




</externalLink>











-->

</relatedTopics>

</developerSDKTechnologyOverviewScenariosDocument

</topic>



SandcastleMAMLGuide

SDKTechnologySummary

Thisdocumenttypeisusedfortechnologysummarytopics.

SDKTechnologySummaryFileFormatBelowisanexampleofanSDKTechnologySummarytopicfile.



<developerSDKTechnologyOverviewTechnologySummaryDocument





<introduction>


</introduction>

<keywords>

<content>

<para>Keywordcontent</para>

</content>

</keywords>

<namespaces>

CopySDKTechnologySummaryTopic

<content>

<para>Namespacescontent</para>

</content>

</namespaces>



<background>

<content>

<para>Backgroundcontent</para>

</content>

</background>

<implementingTechnologyNameClasses>

<title>"Implementing[TechnologyName]Classes"title

<content>

<para>Implementationcontent</para>

</content>

</implementingTechnologyNameClasses>

<technologyNameClassesAtAGlance>

<title>"[TechnologyName]ClassesataGlance"title

<content>

<para>AtaGlancecontent</para>

</content>

</technologyNameClassesAtAGlance>



<relatedTopics>


-Alocallink

-Anexternallink



<externalLink>





</externalLink>


Examples:


<externalLink>




</externalLink>








-->

</relatedTopics>

</developerSDKTechnologyOverviewTechnologySummaryDocument

</topic>



SandcastleMAMLGuide

Troubleshooting

Thisdocumenttypeisusedfortroubleshootingtopics.

TroubleshootingFileFormatBelowisanexampleofaTroubleshootingtopicfile.



<developerTroubleshootingDocument





<introduction>







</introduction>

<!--Zeroormoresections.Thesearecollapsible.Ifusing

CopyTroubleshootingTopic

<autoOutline/>,addanaddressattributetoidentifyitandspecify

atitlesothatitcanbejumpedtowithahyperlink.-->



<content>


<autoOutline/>-->

<para>Sectioncontent</para>



</content>

</section>

<relatedTopics>


-Alocallink

-Anexternallink



<externalLink>




</externalLink>


Examples:


<externalLink>




</externalLink>








-->

</relatedTopics>

</developerTroubleshootingDocument>

</topic>



SandcastleMAMLGuide

UserInterfaceReference

Thisdocumenttypeisusedforuserinterfacereferencetopics.

UserInterfaceReferenceFileFormatBelowisanexampleofaUserInterfaceReferencetopicfile.



<developerUIReferenceDocument





<introduction>







</introduction>

<taskList>

CopyUserInterfaceReferenceTopic

<content>

<para>Tasklistcontent</para>

</content>

</taskList>





<content>


<autoOutline/>-->

<para>Sectioncontent</para>

</content>

</section>

<uiElementList>

<content>

<para>UIelementlistcontent</para>

</content>

</uiElementList>

<relatedTopics>


-Alocallink

-Anexternallink



<externalLink>




</externalLink>


Examples:

SandcastleMAMLGuide

Walkthrough

Thisdocumenttypeisusedforwalkthroughtopics.

WalkthroughFileFormatBelowisanexampleofaWalkthroughtopicfile.



<developerWalkthroughDocument





<introduction>







</introduction>



CopyWalkthroughTopic

<procedure>

<title>Proceduretitle</title>


<step>

<content>


</content>

</step>

<step>

<content>


</content>

</step>

</steps>


</procedure>





<content>

<procedure>

<title>Procedure#2</title>


<step>

<content>


</content>

</step>

<step>

<content>


</content>

</step>

</steps>


</procedure>

</content>

</section>



<relatedTopics>


-Alocallink

-Anexternallink



<externalLink>




</externalLink>


Examples:


<externalLink>




</externalLink>





-->

</relatedTopics>

</developerWalkthroughDocument>

</topic>



SandcastleMAMLGuide

Whitepaper

Thisdocumenttypeisusedforwhitepapers.

WhitepaperFileFormatBelowisanexampleofaWhitepapertopicfile.



<developerWhitePaperDocument





<byline>

<para>Byline</para>

</byline>

<date>

<para>Date</para>

</date>

<summarySection>

<content>

<para>Summarycontent</para>

CopyWhitepaperTopic

</content>

</summarySection>







<introduction>







</introduction>






<content>


<autoOutline/>-->


</content>

</section>


<conclusion>

<content>

<para>Conclusioncontent</para>

</content>

</conclusion>

<relatedTopics>


-Alocallink

-Anexternallink



<externalLink>




</externalLink>


Examples:


<externalLink>




</externalLink>








-->

</relatedTopics>





</developerWhitePaperDocument>




</topic>



SandcastleMAMLGuide

XMLReference

ThisdocumenttypeisusedforXMLreferencetopics.

XMLReferenceFileFormatBelowisanexampleofanXMLReferencetopicfile.



<developerXmlReference





<introduction>


</introduction>



<syntaxSection>

CopyXMLReferenceTopic

<sections>

<section>

<title>Syntaxsectiontitle</title>

<content>

<para>Syntaxcontent</para>

</content>

</section>

</sections>

<legacySyntax>

<parameterReference>Parameterreference</parameterReference

</legacySyntax>

</syntaxSection>

<attributesandElements>

<para>Attributesandelementssyntaxintroduction

<attributes>

<para>Attributessyntax</para>

</attributes>

<attribute>

<title>Syntaxtitle</title>

<table>

<tableHeader>

<row>

<entry>

<para>Attributeheader</para>

</entry>

</row>

</tableHeader>

<row>

<entry>

<para>Attributevalue</para>

</entry>

</row>

</table>

</attribute>

<childElement>

<para>Childelementsyntax</para>

</childElement>

<parentElement>

<para>Parentelementsyntax</para>

</parentElement>

</attributesandElements>




<relatedTopics>


-Alocallink

-Anexternallink



<externalLink>




</externalLink>


Examples:


<externalLink>




</externalLink>




-->

</relatedTopics>

</developerXmlReference>

</topic>



SandcastleMAMLGuide

CompanionFile

Acompanionfileisusedduringthebuildprocesstoobtainthetopictitleandlinktextforaparticularconceptualtopic.Therewillbeonecompanionfileforeachconceptualcontenttopic.

Note

IfusingabuildtoolsuchastheSandcastleHelpFileBuilder,thecompanionfilesarecreatedforyouautomaticallyaspartofthebuildprocessandyoudonotneedtomaintainthemyourself.

CompanionFileFormatBelowisanexampleofacompanionfile.

Thefileconsistsofarootmetadatanodethatcontainsonetopicnodewithanidattributethatreferstothetopic'sGUID.

Thetitleelementisrequiredandcontainsthetitletouseforthetopic.Thiswillbeusedasthedefaultlinktext.Incaseswherethetitleisnotappropriateoristoolongforlinktextandyouusethetopicinalinkfrequently,youcanspecifyalinkTextelementthatcontainsdifferenttexttouseforthelink.Notethatifalinkelementhasinnertextspecifiedinthetopic,itwillalwaysbeusedinsteadofthevaluesfromthecompanionfile.


<metadata>

<topicid="303c996a-2911-4c08-b492-6496c82b3edb">

<title>WelcometotheSandcastleMAMLGuide</title

<linkText>Welcomepage</linkText>

</topic>

</metadata>

CopyExampleCompanionFile


Note

TheIDvaluemustbeintheformofaGloballyUniqueIdentifier(GUID).

SeeAlsoOtherResourcesConceptualContentFileTypeslink





SandcastleMAMLGuide

BlockElements

Thetopicsinthissectiondefinetheblockelementsthatcanbeusedinconceptualtopics.

BlockElementsSelectoneofthetopicsbelowtolearnmoreaboutaparticularblockelement.

alert

code

codeReference

definitionTable,definedTerm,definition

introduction

list,listItem

para

quote

relatedTopics

table,tableHeader,row,entry

title





SandcastleMAMLGuide

alert

Thiselementcanbeusedtocreateanote-likesectionwithinaconceptualtopictodrawattentiontosomeimportantinformation.

UsageEntertheelementinthetopicandspecifythetypeofalertusingtheclassattribute.Thecontentofthealertelementisusuallyoneormoreparagraphsoftextdescribingtheimportantinformation.

Note

Theclassattributevalueiscase-sensitive.Unrecognizedvalueswilldefaulttothe"note"alertstyle.

Theclassattributecanbeanyofthefollowingvalueswhichfallintofourdifferentcategoriesthatusedifferenticonstotheleftofthealerttitle.Thetitlewillgenerallybethealertclassnameoranexpandedformofit.

Category ClassValueGeneralnote

note,tip,implement,caller,inherit

Cautionary caution,warning,important

Security security,securitynote

Languagenote

cs,CSharp,c#,C#,visualc#note,cpp,CPP,c++,C++,visualc++note,vb,VB,VisualBasic,visualbasicnote,JSharp,j#,J#,visualj#note

ExampleCopy

ExampleOutputNote

Thisisanote

Caution

Theclassattributevalueiscase-sensitive.

SecurityNote

Donottapeyourpasswordtotheundersideofyourkeyboard.

C#Note

ThiscouldcontainC#-specificusagenotes.

SeeAlso

<alertclass="note">

<para>Thisisanote</para>

</alert>

<alertclass="caution">

<para>Theclassattributevalueiscase-sensitive.

</alert>

<alertclass="security">

<para>Donottapeyourpasswordtotheundersideofyourkeyboard.

</alert>

<alertclass="cs">

<para>ThiscouldcontainC#-specificusagenotes.

</alert>

Copy

OtherResourcesBlockElements





SandcastleMAMLGuide

code

Thiselementcanbeusedtodisplayamulti-linecodefragmentinaconceptualtopic.Forsinglelinesorkeywords,youcanusethecodeInlineelement.

UsageLiteralXMLAndOtherSpecialCharactersAttributes

languagetitlesource,region,andremoveRegionMarkerstabSizenumberLinesoutliningkeepSeeTags

NestedCodeElementsSeeAlso

UsageEntertheelementinthetopicandspecifyalanguageusingthelanguageattribute.

<codelanguage="languageId"

[title="Optionaltitle"]

[source="externalCodeFile"[region="importRegion"

[tabsize="###"]

[numberLines="true|false"]

[outlining="true|false"]

[keepSeeTags="true|false"]>

///Codetodisplay

Copy

Note

ThelanguageandtitleattributesaresupportedbySandcastle.AllotherattributesareimplementedbytheCodeBlockComponentsuppliedwiththeSandcastleHelpFileBuilder.Refertoitshelpfileformoreinformationaboutthebuildcomponent.

LiteralXMLAndOtherSpecialCharactersIfyouwanttoincludeXMLorotherunencodedinformationyoucandooneofthefollowing:

Utilizethesourceattributetoreaditinfromanexternalfileinstead.

UseaCDATAsectiontoencapsulatethecodesothatspecialcharactersandformattingarepreserved.Forexample:

Besuretostarttheexamplecodeonanewlineaftertheopening"<![CDATA["tagasshownsothattheleadingwhitespacecanbenormalizedcorrectly.

</code>

///<example>

///<codelanguage="xml"title="ExampleConfiguration">

///<![CDATA[

///<?xmlversion="1.0"encoding="utf-8"?>

///<config>

///<path>C:\Test\</path>

///<filespecmask="*.txt"/>

///</config>]]>

///</code>

///</example>

CopyCDATAExample


Note

TheinclusionofaCDATAtaganywhereinthecodecommentscancauseVisualStudio2005tolockupwhenyoutypeananglebracketwithinacommentblock.Ifyouareaffectedbythisissue,thereisahotfixavailableat:https://connect.microsoft.com/VisualStudio/Downloads/DownloadDetails.aspx?DownloadID=9646.

AttributesThefollowingattributescanbeusedtocontrolhowthecodeblockishandled.

languageThisattributeallowsyoutodefinethecodelanguage.Althoughoptional,itisrecommendedthatyoualwaysspecifyalanguageattributeifusingSandcastlealone.Manyofthepresentationstylesrelyonthelanguageattributetoclassifythecodeblockandhandleitinsomewaysuchasattachingittoalanguagefilterorgroupingitwithlikecodeblocks.TheSandcastleHelpFileBuilder'scodeblockcomponentwillapplyadefaultlanguageifoneisnotspecified.Thepossiblelanguagevaluesareasfollows:

LanguageID(case-insensitive) LanguageSyntaxUsed

cs,C#,CSharp C#

cpp,cpp#,C++,CPlusPlus C++

c C

fs,f#,FSharp,fscript F#

EcmaScript,js,JavaScript JavaScript

jscript,jscript#,jscriptnet,JScript.NET

JScript.NET

VB,VB#,vbnet,VB.NET VB/VB.NET

vbs,vbscript VBScript

https://connect.microsoft.com/VisualStudio/Downloads/DownloadDetails.aspx?DownloadID=9646

htm,html,xml,xsl XML

XAML XAML

jsharp,J# J#

sql,sqlserver,sqlserver SQLscript

pshell,powershell,ps1 PowerShellscript

py,python Python

Anythingelse(i.e."none") Nolanguage,nospecialhandling.

Important

Thefullname"language"shouldbeusedfortheattributenameratherthantheabbreviatedform"lang".ThereasonisthattheXSLtransformationsusedbythepresentationstylesexpectthefullnamewhentheysearchforthelanguageattribute.Theabbreviatedformisalegacysyntaxthatshouldbeavoided.Thecodeblockcomponentwillauto-correcttheattributenamesothatitisnotmissedbythetransformations.Itisrecommendedthatyoualwaysspecifyalanguageattribute.

titleThisattributeallowsyoutoaddatitlethatappearsbeforethecodeblock.Anexampleofitsusewouldbetolabeltheexamplewithadescription.Ifomitted,thelanguagenamewillappearforthetitle.Ifyoudonotwantatitleonaparticularblock,setthetitleattributetoasinglespace("").

source,region,andremoveRegionMarkersThesethreeattributesareextensionsimplementedbythecodeblockbuildcomponent.Thesourceattributeisusedtospecifythatthecodeblock'scontentshouldbereadfromanexternalsourcecodefile.Ifusedalone,theentirefileisimported.Theoptionalregionattributecanbeusedtolimitthecodetoaspecificsectionofthefiledelimitedwiththenamed#region(#pragmaregionforC++).The#regionand#endregiontagsareexcludedfromthe

extractedsectionofcode.

ThisisnottobeconfusedwiththeXMLcommentsincludeelement.Thisextensionisintendedtoextractcodefromactualsourcefiles.Thisallowsyoutomanageyourcodeexamplesinbuildableprojectstotestthemforcorrectnessasaprojectisdevelopedandalteredinthefuture.ItalsosavesyoufrommanagingthecodeintheXMLcommentsanddoesnotrequirethatthecodebeHTMLencodedasitiswhenwritteninthecomments.ThecodewillbeHTMLencodedwhenitisreadinforprocessing.Whenused,itisassumedthatthereisnocodewithinthecodeelementitselfandthusitwillalwaysbeself-closing.Herearesomeexamples:

RetrieveallcodefromanexternalfileandusetheVB.NETsyntaxtocolorit.Thepathisrelativetothecodeblockcomponent'sbasePathconfigurationelement.Typically,thebasepathisthepathofthedocumentationprojectfile.So,ifyourdocumentationprojectisinasubfolderandthecodeisintheparentfolderinanExamplessubfolder,thepathwouldlooklikethefollowingexample.

Retrieveaspecific#regionfromanexternalfile.

NotethatVB.NETdoesnotallow#Regionand#EndRegionwithinamethodbody.OtherfiletypessuchasXML,XAML,andSQLscriptdonotunderstand#regionstatements.However,ifyouwanttoextractaregionfromaVB.NETmethodbodyorasectionofanotherfiletype,youcanaddtheregionstatementsincommentstoworkaroundthelimitation.Thecomponentwillstillfinditandextracttheregion.

<codesource="..\Examples\WholeDemo.vb"language="vbnet"

Copy

<codesource="..\Examples\SeveralExamples.vb"

region="Example1"language="vbnet"title="Example#1"

Copy

--------------------------------------------------------

VB.NETExample

--------------------------------------------------------

PublicSubSomeMethod()

CopyCommentedRegionExamples

TheremoveRegionMarkersattributecanbeusedtospecify

'#Region"VB.NETSnippet"

DimxAsInteger

Forx=1To10

Console.WriteLine(x)

Nextx

'#EndRegion

EndSub

--------------------------------------------------------

XAMLExample

--------------------------------------------------------

<Stylex:Key="SpecialButton"TargetType="{x:TypeButton}">

<Style.Triggers>



<TriggerProperty="Button.IsMouseOver"Value="true">

<SetterProperty="Background"Value="Red"/>

</Trigger>



</Style.Triggers>

</Style>

--------------------------------------------------------

SQLExample

--------------------------------------------------------

--#regionSQLsnippet

Select*

FromtblName

WhereLastName='SMITH'

--#endregion

/*#regionAnothersnippet*/

Select*

FromtblName

WhereFirstName='JOHN'

/*#endregion*/

whetherornotregionmarkerswithintheimportedcodefileorregionareremoved.Ifnotspecifiedorsettofalse,anynestedregionmarkersareleftintheimportedcodeblock.Ifspecifiedandsettotrue,nestedregionmarkersareremovedfromtheimportedcode.Thisisusefulforremovingnestedregionmarkersfromlargercodesamplesthatcontainsmallersnippetsofcodeusedinotherexamples.Thedefaultsetting(false)canbeoverriddenviathecomponentconfiguration.

tabSizeWhenthecodeblocksareformattedbythebuildcomponent,tabcharactersarereplacedwithasetnumberofspacestopreserveformatting.Thisattributecanbeusedtooverridethedefaultsettingforalanguagewhichisspecifiedinthesyntaxfile.Forexample,ifthedefaulttabsizeforalanguageisfour,addingtabSize="8"willforceittouseeightspacesinstead.Ifsettozero,thesyntaxfilesettingisused.Thisattributesetsthedefaulttabsizeforunknownlanguageswhenusedinthecomponent'sconfiguration.

numberLinesThisattributeallowsyoutooverridethedefaultsettinginthecomponent'sconfiguration.Forexample,ifthedefaultsettingisfalsetoturnofflinenumbering,youcanaddnumberLines="true"toenablenumberingonaspecificcodeexample.

outliningThisattributeallowsyoutooverridethedefaultsettinginthecomponent'sconfiguration.Forexample,ifthedefaultsettingisfalsetonotaddcollapsibleregions,youcanaddoutlining="true"toenablecollapsibleregionsonaspecificcodeexample.Notethatifacodeblockcontainsno#regionor#ifblocks,outliningisautomaticallydisabledanditwillnotreservespaceinthemarginforthemarkers.

keepSeeTagsWhensettotrue,thisattributeallowsyoutotellthebuildcomponent'scodecolorizertopreserveseetagswithinthecodesothattheycanberenderedasclickablelinkstotherelatedtopic.Ifsettofalse,thedefault,anyseetagswithinthecodewillbecolorizedandpassedthroughasliteraltext.Whenusingthisoption,youmayfindthatyouneedtospecifyinnertextfortheseetagsothatthelinktextappearsasyouwantit.Iftheself-closingversionofthetagisused,Sandcastlewillgenerallysetthelinktexttothenameoftheitemplusanyparametersifitisagenerictypeortakesparameterswhichmaynotbeappropriatewithinacodesample.

NestedCodeElementsYoucanimportmultiplecodesnippetsintoonecommoncolorizedcodeblockbynestingcodeelementswithinaparentcodeelement.Onnestedcodeelements,onlythesourceandregionattributeswillbeutilized.Allotherattributesthatcontrolcolorizationofthemergedcodeblockwillberetrievedfromtheparentcodeelement.

Literalcodecanalsobemixedinbetweenthenestedcodeelements.However,therearesomelimitations.Allelementsandliteralcodeshouldbeflushleftwithintheparentcodeelementoryouwillendupwithadditionalspacesbeforethefirstlineofeachnestedcodeelement.Theremaystillbeadditionalspacesbeforetheliteralcode.ThisiscausedbytheindentationincludedwhentheXMLcommentsfileiscreatedbythecompiler.Ifthisisaproblem,movetheexampletoanincludefileandremovetheexcessleadingwhitespace.UseanincludeelementtobringitintotheXMLcomments.Whendonethisway,thecompilerpreservesthespacingwhenwritingtheexampleouttotheXMLcommentsfile.

SeeAlso

<codetitle="Nestedcodeelementsexample"language

<codesource="..\Class1.vb"region="Snippet#1"/>


</code>

Copy

<codetitle="Nestedcodeelementsexample"language


'...Somestuffhappenshere...


</code>

Copy

NestedCodeElementsExample

NestedCodeElementsExample

OtherResourcesBlockElementscodeInlinecodeEntityReferencecodeReference





SandcastleMAMLGuide

codeReference

AcodeReferenceelementisusedtoinsertacommonlyusedcodesnippetintoaconceptualtopic.Thecodesnippetsarestoredinanexternalfile.

Note

WhenusingtheSandcastleHelpFileBuilderorthestandalonebuildcomponentsfromit,theCodeBlockComponentoffersthesamesetoffeaturesandseveralothersforbothinlineandexternalcodesnippets.Inaddition,itsupportsmanyotherlanguagesandcanimportcodefromworkingsourcecodefileswhichallowsyoutopullinexamplesfromworkingprojectsthatyoucanmaintainandbuildwithouthavingtoupdateaseparateexamplesnippetsfile.Assuch,youmayprefertouseitratherthanthecodesnippetsfile.

UsageTouseacodereference,simplyinsertitsIDastheinnertextofacodeReferenceelementanywherewithinatopic.YoucancombinemultiplesnippetswithacommonexampleIDintoonecodereferencebyspecifyingtheirsampleIDsasacomma-separatedlistafterthehashcharacter.

ExampleThisexampleusesthesamplesfromtheexamplefileabove.Thefirstthreearetheindividualsnippets.Thelastonecombinesthe"createinstance"snippetsintooneexample.

Defineaclass

<codeReference>ClassDefinition#Define</codeReference

Createalocalinstance

Copy


ExampleOutputDefineaclass

Createalocalinstance

Createastatic(shared)instance

AnexampleofcombiningsnippetswithacommonexampleID

<codeReference>CreateInstance#Local</codeReference>

Createastatic(shared)instance

<codeReference>CreateInstance#Static</codeReference

AnexampleofcombiningsnippetswithacommonexampleID

<codeReference>CreateInstance#Local,Static</codeReference

publicclassCSharpClass()

{

//Membersgohere

}

Copy


Copy


Copy


...

Copy

C# VB

C# VB

C# VB

C# VB

SeeAlsoOtherResourcesBlockElementsCodeSnippetsFilecodecodeInlinecodeEntityReference






SandcastleMAMLGuide

definitionTable,definedTerm,definition

Thiselementdescribesalistoftermsandtheirdefinitions.Technically,theMAMLschemadefinesthedefinitiontableasatwo-columntablewithoutaheaderorfooter.However,SandcastlerenderstheelementasanHTMLdefinitionlist(dl/dt/dd).

UsageEntertheelementinthetopicandspecifyoneormorenestedpairsofdefinedTermanddefinitionelements.ThedefinedTermelementdescribesthetermbeingdefined.Thedefinitionelementsuppliesthedefinition.EachdefinitionelementcancontainotherMAMLelements,nestedlists,tables,etc.Textshouldbecontainedinaparaelement.

Tip

ThedefinedTermelementsupportsanaddressattributethatcanbeusedtolinktoaspecificdefinedtermfromanotherlocation.

Example

<para>Thislinktakesyouto<linkxlink:href="#Term8"

<definitionTable>

<definedTerm>Term1</definedTerm>

<definition><para>Definition1</para></definition




Copy

ExampleOutputThislinktakesyoutoTerm#8.

Term1Definition1

Term2Definition2

Term3Definition3

Term4Definition4

Term5Definition5

Term6Definition6










<definedTermaddress="Term8">Term8</definedTerm>

<definition><para>Definition8.Theentry'stermhasan

attributethatcanbeusedasalinktarget.</para>

</definitionTable>

Term7Definition7

Term8Definition8.Theentry'stermhasanaddressattributethatcanbeusedasalinktarget.

SeeAlsoOtherResourcesBlockElementslist,listItemtable,tableHeader,row,entry





SandcastleMAMLGuide

introduction

Thiselementcontainsanintroductiontosomepartofthedocument.Mostconceptualdocumenttypeshavearequiredintroductionsection.

UsageEntertheelementinthetopicandspecifythetexttouseasthedocument'sintroduction.Anoptionaladdressattributecanbeaddedtomaketheintroductionaccessibleviaanin-pagelink.

Example

ExampleOutputSeetheIntroductionsectionaboveforanexampleoftheoutput.

<introductionaddress="intro">

<para>Thiselementcontainsanintroductiontosomepartofthedocument.

Mostconceptualdocumenttypeshavearequiredintroductionsection.

</introduction>

<section>

<title>ExampleOutput</title>

<content>

<para>Seethe<linkxlink:href="#intro">Introduction

sectionabove.</para>

</content>

</section>

Copy

SeeAlsoOtherResourcesBlockElementslink





SandcastleMAMLGuide

list,listItem

Thiselementdescribescontentthatshouldbedisplayedasalist.

UsageEntertheelementinthetopicandspecifythetypeoflistusingtheclassattribute.ThecontentofthelistelementisoneormorelistItemelementscontainingthecontentofthelistitems.ThelistitemscanthemselvescontainotherMAMLelements,nestedlists,tables,etc.Textshouldbecontainedinaparaelement.Theclassattributecanbeanyofthefollowingvalues:

bullet-Astandardbulletedlistofitems.

ordered-Anumberedlistofitems.

nobullet-Alistofitemswithnosymbolprecedingtheitems.

Note

Theclassattributevalueiscase-sensitive.Unrecognizedvalueswilldefaulttothenobulletliststyle.

Tip

ThelistItemelementsupportsanaddressattributethatcanbeusedtolinktoaspecificlistitemfromanotherlocation.

Example

<para>Thislinktakesyouto<linkxlink:href="#SubItem2"

<listclass="bullet">

Copy

ExampleOutput

<listItem><para>Item1</para></listItem>



<listItem><para>Item4-Thishasannested

<codeInline>ordered</codeInline>list.</para>

<listclass="ordered">

<listItem><para>Sub-Item1</para></listItem>

<listItemaddress="SubItem2"><para>Sub-Item2-Thishasan

<codeInline>address</codeInline>attributeandcanbeusedasa

linktarget.</para></listItem>



<listItem><para>Sub-Item5-Thishasanested

<codeInline>nobullet</codeInline>list.</para>

<listclass="nobullet">

<listItem><para>No-bulletitem1</para></listItem



</list>

</listItem>


</list>

</listItem>







</list>

ThislinktakesyoutoSub-Item#2.

Item1

Item2

Item3

Item4-Thishasannestedorderedlist.

1. Sub-Item1

2. Sub-Item2-Thishasanaddressattributeandcanbeusedasalinktarget.

3. Sub-Item3

4. Sub-Item4

5. Sub-Item5-Thishasanestednobulletlist.

No-bulletitem1

No-bulletitem2

No-bulletitem3

6. Sub-Item6

Item5

Item6

Item7

Item8

Item9

Item10

SeeAlsoOtherResources

BlockElementsdefinitionTable,definedTerm,definitiontable,tableHeader,row,entry





SandcastleMAMLGuide

para

Thiselementcanbeusedtocreateparagraphsinconceptualcontent.

UsageEntertheelementinthetopicandspecifytheparagraphtextastheinnertext.Makingtheelementself-closingoremptywillcausetheelementtobeignoredunlessitcreatesaninitialparagraphbreak.

Example

ExampleOutputParagraph1.

Paragraph2.

Self-closingandemptyparagraphsareignored.

Paragraph4.

SeeAlso

<para>Paragraph1.</para>


<para/>

<para></para>

<para>Self-closingandemptyparagraphsareignored.


Copy

OtherResourcesBlockElements





SandcastleMAMLGuide

quote

Thiselementdescribesaquotation.

UsageEntertheelementinthetopicandspecifythequotationastheinnertext.

Example

ExampleOutputToquotetheschema:

Thequoteelementdescribesaquotation.

SeeAlsoOtherResourcesBlockElementsquoteInline



<para>Toquotetheschema:</para>

<quote>Thequoteelementdescribesaquotation.</quote

Copy



SandcastleMAMLGuide

relatedTopics

Thiselementisusedtodefinealistoflinkstoothertopicsthatmaybeofinteresttothereader.

UsageEntertheelementinthetopicandspecifyoneormorelocallinks,externallinks,orcodeentityreferences.

Note

Intopicsinwhichthiselementappears,itisarequiredelement.However,ifthetopichasnolinksofinterest,youcanleaveitemptyandtherelatedtopicssectionwillnotbeincludedinthetopic.

Note

Thelinkswithintheelementcanappearinanyorder.Theywillbegroupedbytypewhenthetopicisbuilt.

ControllingLinkGroupingWhenusedinarelatedTopicselement,anoptionaltopicType_idattributecanbeaddedtolinkelementsthatspecifiesaGUIDvalueusedtoclassifythelinktypesothatitisgroupedwithothersimilarlinks.Ifnotspecified,thelinkswillbeplacedinthe"OtherResources"group.TheGUIDvaluescorrespondtothevariousMAMLtopicfiletypesandareasfollows:

TopicType GUIDValue GroupSection

Conceptual 1FE70836-AA7D-4515-B54B-E10C4B516E50

Concepts

CodeEntity 4A273212-0AC8-4D72-8349-EC11CD2FF8CD

OtherResources

ErrorMessage A635375F-98C2-4241-94E7-E427B47C20B6

Reference

Glossary A689E19C-2687-4881-8CE1-652FF60CF46C

OtherResources

How-To DAC3A6A0-C863-4E5B-8F65-79EFC6A4BA09

Tasks

Orientation B137C930-7BF7-48A2-A329-3ADCAEF8868E

OtherResources


F9205737-4DEC-4A58-AA69-0E621B1236BD

Reference

ReferenceWithSyntax 95DADC4C-A2A6-447A-AA36-B6BE3A4F8DEC

Reference

Sample 069EFD88-412D-4E2F-8848-2D5C3AD56BDE

Tasks

SDKTechnologyOverviewArchitecture

68F07632-C4C5-4645-8DFA-AC87DCB4BD54

Concepts

SDKTechnologyOverviewCodeDirectory

4BBAAF90-0E5F-4C86-9D31-A5CAEE35A416

Concepts

SDKTechnologyOverviewOrientation

CDB8C120-888F-447B-8AF8-F9540562E7CA

OtherResources

SDKTechnologyOverviewScenarios

356C57C4-384D-4AF2-A637-FDD6F088A033

Concepts

SDKTechnologyOverviewTechnologySummary

19F1BB0E-F32A-4D5F-80A9-211D92A8A715

Concepts

Troubleshooting 38C8E0D1-D601-4DBA-AE1B-5BEC16CD9B01

Tasks

UIReference B8ED9F21-39A4-4967-928D-160CD2ED9DCE

Reference

Walkthrough 4779DD54-5D0C-4CC3-9DB3-BF1C90B721B3

Tasks

Whitepaper 56DB00EC-28BA-4C0D-8694-28E8B244E236

OtherResources

XMLReference 3272D745-2FFC-48C4-9E9D-CF2B2B784D5F

Reference

Example

<relatedTopics>

<linktopicType_id="1FE70836-AA7D-4515-B54B-E10C4B516E50"

xlink:href="b32a73b8-fc26-4c98-912c-d595fc1a17c2"


xlink:href="bc490dbf-7d46-432d-a816-3ae16ab6af54"


xlink:href="d0c9ce6d-115b-4c70-891c-69b4af944dea"


xlink:href="53a2b7c6-a269-4916-9313-bdc301ee9398"

<externalLink>

<linkText>SandcastleHelpFileBuilder</linkText

<linkUri>https://GitHub.com/EWSoftware/SHFB</linkUri

<linkTarget>_blank</linkTarget>

</externalLink>

<codeEntityReferencequalifyHint="true">T:System.IO.FileStream

<codeEntityReferencequalifyHint="true"autoUpgrade

M:System.IO.FileStream.#ctor(System.String,System.IO.FileMode)

Copy

ExampleOutputSeebelow.

SeeAlsoReferenceSystem.IOFileStreamFileStreamFileStreamFileStreamWriteLengthFlushConceptsBlockElementscodeEntityReferenceexternalLinklinkOtherResourcesSandcastleHelpFileBuilder



</codeEntityReference>


M:System.IO.FileStream.Write(System.Byte[],System.Int32,System.Int32)


<codeEntityReferencequalifyHint="false">P:System.IO.FileStream.Length


<codeEntityReferencequalifyHint="false"autoUpgrade

M:System.IO.FileStream.Flush</codeEntityReference

</relatedTopics>

http://msdn2.microsoft.com/en-us/library/y0bs3w9t

http://msdn2.microsoft.com/en-us/library/98hy92k3

http://msdn2.microsoft.com/en-us/library/2t9z5e24

http://msdn2.microsoft.com/en-us/library/csws4bx5

http://msdn2.microsoft.com/en-us/library/ee474551




SandcastleMAMLGuide

table,tableHeader,row,entry

Thiselementisusedtoarrangedatainatableformatwithrowsandcolumns.Anoptionaltitleandtableheadercanalsobeincluded.

UsageAtableconsistsofthefollowingelements:

table

Thisisthemainelement.Allothertableelementsarenestedwithinitandithasnoattributes.

title

Thisisanoptionalelement.Ifspecified,itdefinesatitlethatwillappearabovethetable.

tableHeader

Thisisanoptionalelement.Ifspecified,itshouldcontainasinglerowelementthatdefinestheheaderrow.Thiscanbeusedtoaddtitlestoeachcolumn.Thetableheader,ifspecified,willbestyleddifferentlyintherenderedtopic.

row

Thiselementisusedtodefineeachrowinthetable.Atablemustcontainatleastonerow.Eachrowmustcontainoneormoreentryelementsthatdefinethecolumnsintherow.

entry

Thiselementisusedtodefinethecolumnsineachrow.TheentryitemscanthemselvescontainotherMAMLelements,nestedlists,tables,etc.Textshouldbecontainedinaparaelement.

Tip

Theentryelementsupportsanaddressattributethatcanbeusedtolinktoaspecificentryfromanother

location.

Tip

Torenderanemptycell,useanon-breakingspaceentity( ).

Note

TherearenoprovisionsforspanningrowsorcolumnsasthereisinHTMLtables.Assuch,eachrowmustcontainthesamenumberofcolumns.However,youcannesttableswithinanentryelementwhichcanbeusedtoachieveasimilareffect.

Example

<para>Thislinktakesyouto<linkxlink:href="#Row3Cell1"

inthefirsttable.</para>

<table>

<title>ASimpleTablewithTitleandHeaders</title

<tableHeader>

<row>

<entry><para>Header1</para></entry>



</row>

</tableHeader>

<row>

<entry><para>Row1,Cell1</para></entry>



</row>

<row>




</row>

Copy

<row>

<entryaddress="Row3Cell1"><para>Thisentryhasan

attributethatcanbeusedasalinktarget.</para>



</row>

</table>

<table>

<tableHeader>

<row>

<entry><para> </para></entry>

<entry><para>ANestedTableExample</para></entry

</row>

</tableHeader>

<row>

<entry><mediaLink><image

xlink:href="98a8a8b7-c374-40c7-902a-91c947bf107c"

</mediaLink></entry>

<entry>

<table>

<row>

<entry><para>Cell1</para></entry>




</row>

<row>





</row>

<row>





</row>

ExampleOutputThislinktakesyoutoRow3,Cell1inthefirsttable.

ASimpleTablewithTitleandHeaders

Header1 Header2

Header3

Row1,Cell1 Row1,Cell2

Row1,Cell3

Row2,Cell1 Row2,Cell2

Row2,Cell3

Thisentryhasanaddressattributethatcanbeusedasalinktarget.

Row3,Cell2

Row3,Cell3

ANestedTableExample

Cell1 Cell2 Cell3 Cell4



Thetableabovedoesn'thaveatableHeader.


</table>

<para>Thetableabovedoesn'thavea

<codeInline>tableHeader</codeInline>.</para>

</entry>

</row>

</table>

BlockElementsdefinitionTable,definedTerm,definitionlist,listItem





SandcastleMAMLGuide

title

Thiselementdescribesthenameofapartofadocument.

UsageEntertheelementinthetopicandspecifythetexttouseasthesection'stitle.

Example

ExampleOutputSeetheUsagesectionaboveforanexampleoftheoutput.

SeeAlsoOtherResourcesBlockElements


<section>

<title>Usage</title>

<content>

<para>Entertheelementinthetopicandspecifythetexttouseasthe

section'stitle.</para>

</content>

</section>

Copy


SandcastleMAMLGuide

CommonInlineElements

Thetopicsinthissectiondefinethecommoninlineelementsthatcanbeusedinconceptualtopics.

CommonInlineElementsSelectoneofthetopicsbelowtolearnmoreaboutaparticularinlineelement.

application

codeInline

command

computerOutputInline

database

environmentVariable

errorInline

fictitiousUri

foreignPhrase

hardware

legacyBold

legacyItalic

legacyUnderline

literal

localUri

math

newTerm

phrase

placeholder

quoteInline

replaceable

subscript

superscript

system

ui

unmanagedCodeEntityReference

userInput





SandcastleMAMLGuide

application

ThiselementisusedtodescribethenameofanapplicationsuchasMicrosoftWindowsorNotepad.

UsageEntertheelementinthetopicandspecifytheapplicationnameastheinnertext.

Example

ExampleOutputUsetheSandcastleHelpFileBuildertocreatehelpfiles.

SeeAlsoOtherResourcesCommonInlineElements



Usethe<application>SandcastleHelpFileBuilder</

Copy



SandcastleMAMLGuide

codeInline

Thiselementdescribesastringofcodeorasinglekeyword.Formulti-linecodefragments,usethecodeelementinstead.

UsageEntertheelementinthetopicandspecifythecodeastheinnertext.

Example

ExampleOutputUseaforeachlooptoiterateoverthecollection.

SeeAlsoOtherResourcesCommonInlineElementscodecodeEntityReferencecodeReference



Usea<codeInline>foreach</codeInline>looptoiterateoverthecollection.

Copy



SandcastleMAMLGuide

command

Thiselementdescribesthenameofanexecutableorothersoftwareapplicationthancanberun.

UsageEntertheelementinthetopicandspecifytheapplicationnameastheinnertext.Thereplaceableelementcanbenestedwithinittorepresentreplaceableparameters.

Example

ExampleOutputXCOPY/s/esourceFileSpecdestFileSpec

SeeAlsoOtherResourcesCommonInlineElementsreplaceablesystem



<command>COPY<system>/s/e</system> <replaceable

<replaceable>destFileSpec</replaceable></command

Copy



SandcastleMAMLGuide

computerOutputInline

ThiselementdescribesoutputfromeitheraconsolepromptorfromaUIform.

UsageEntertheelementinthetopicandspecifytheoutputastheinnertext.

Example

ExampleOutputTheresultofrunningHelloWorld.exeis:HelloWorld!




Theresultofrunning<application>HelloWorld.exe</

<computerOutputInline>HelloWorld!</computerOutputInline

Copy



SandcastleMAMLGuide

database

Thiselementisusedtodescribeadatabase.

UsageEntertheelementinthetopicandspecifythedatabaseastheinnertext.

Example

ExampleOutputTheinformationisstoredintheContentdatabase.




Theinformationisstoredinthe<database>Content</

Copy



SandcastleMAMLGuide

environmentVariable

Thiselementdescribesanenvironmentvariableinanoperatingsystem.

UsageEntertheelementinthetopicandspecifytheenvironmentvariableastheinnertext.

Example

ExampleOutputTheSandcastletoolsfindtheirinstalledlocationusingtheSHFBROOTenvironmentvariable.




TheSandcastletoolsfindtheirinstalledlocationusingthe

<environmentVariable>SHFBROOT</environmentVariable>

Copy



SandcastleMAMLGuide

errorInline

Thiselementdescribesanerrororerrormessage.

UsageEntertheelementinthetopicandspecifytheerrorastheinnertext.

Example

ExampleOutputIfafiledoesnotexist,aFileNotFounderrorwilloccur.




Ifafiledoesnotexist,a<errorInline>FileNotFound

errorwilloccur.

Copy



SandcastleMAMLGuide

fictitiousUri

Thiselementdescribesafictitiousinternetaddresssuchasaweboremailaddress.

UsageEntertheelementinthetopicandspecifythefictitiousURIastheinnertext.

Example

ExampleOutputThee-mailaddressjdoe@contoso.comisfakeasistheURLhttp://www.contoso.com.




Thee-mailaddress<fictitiousUri>[email protected]</

fakeasistheURL<fictitiousUri>http://www.contoso.com

Copy



SandcastleMAMLGuide

foreignPhrase

Thiselementisusedtodescribeaphrasethatisofalanguagethatisdifferentthantheprimarylanguageofthedocument.

UsageEntertheelementinthetopicandspecifythephraseastheinnertext.

Example

ExampleOutputIfitdoesn'tworkout,C'estlavie.

SeeAlsoOtherResourcesCommonInlineElementsphrasequoteInline



Ifitdoesn'tworkout,<foreignPhrase>C'estlavie

Copy



SandcastleMAMLGuide

hardware

Thiselementdescribesaphysicalpartofacomputersystem.

UsageEntertheelementinthetopicandspecifythehardwareastheinnertext.

Example

ExampleOutputPlugtheflashdriveintotheUSBport.




Plugthe<hardware>flashdrive</hardware>intothe

<hardware>USBport</hardware>.

Copy



SandcastleMAMLGuide

legacyBold

Thiselementmarksboldtextinlegacydocuments.Theschemadoesnotrecommendusingthiselement.Instead,useoneoftheothercommoninlineelementsthatdescribeaspecifictypeofitemsuchasapplication,ui,etc.However,forgeneralitems,itisasimplewaytoboldtext.

UsageEntertheelementinthetopicandspecifythetexttoboldastheinnertext.

Example

ExampleOutputThistextwillberenderedinbold.




Thistextwillberenderedin<legacyBold>bold</legacyBold

Copy



SandcastleMAMLGuide

legacyItalic

Thiselementmarksitalicizedtextinlegacydocuments.Theschemadoesnotrecommendusingthiselement.Instead,useoneoftheothercommoninlineelementsthatdescribeaspecifictypeofitemsuchasapplication,ui,etc.However,forgeneralitems,itisasimplewaytoitalicizetext.

UsageEntertheelementinthetopicandspecifythetexttoitalicizeastheinnertext.

Example

ExampleOutputThistextwillberenderedasitalicized.




Thistextwillberenderedas<legacyItalic>italicized

Copy



SandcastleMAMLGuide

legacyUnderline

Thiselementmarksunderlinedtextinlegacydocuments.Theschemadoesnotrecommendusingthiselement.Instead,useoneoftheothercommoninlineelementsthatdescribeaspecifictypeofitemsuchasapplication,ui,etc.However,forgeneralitems,itisasimplewaytounderlinetext.

UsageEntertheelementinthetopicandspecifythetexttounderlineastheinnertext.

Example

ExampleOutputThistextwillberenderedwithanunderline.




Thistextwillberenderedwithan<legacyUnderline

Copy



SandcastleMAMLGuide

literal

Thiselementdescribesaliteralvalue.

UsageEntertheelementinthetopicandspecifytheliteralvalueastheinnertext.

Example

ExampleOutputIfthepropertyisnotused,setittothestringNone.




Ifthepropertyisnotused,setittothestring<

Copy



SandcastleMAMLGuide

localUri

Thiselementdescribesthepathtoalocalresourcesuchasafile.

UsageEntertheelementinthetopicandspecifythepathastheinnertext.

Example

ExampleOutputSandcastleisinstalledintheC:\ProgramFiles\Sandcastlefolderbydefault.




Sandcastleisinstalledinthe<localUri>C:\ProgramFiles\Sandcastle

folderbydefault.

Copy



SandcastleMAMLGuide

math

Thiselementcanbeusedtomarkmathematicalexpressions.

UsageEntertheelementinthetopicandspecifythemathematicalexpressionastheinnertext.

Example

ExampleOutputAsimplemathexpression:1+1=2.

SeeAlsoOtherResourcesCommonInlineElementssubscriptsuperscript



Asimplemathexpression:<math>1+1=2</math>.

Copy



SandcastleMAMLGuide

newTerm

Thiselementisusedtointroducenewtermsortechnologies.

UsageEntertheelementinthetopicandspecifythenewtermastheinnertext.

Example

ExampleOutputTopicstocoverincludeLINQ,WPF,andWCF.




Topicstocoverinclude<newTerm>LINQ</newTerm>,<newTerm

<newTerm>WCF</newTerm>.

Copy



SandcastleMAMLGuide

phrase

Thiselementisawrapperelementforarunoftext.Itissolelyacontaineranddoesnotspecifyanysemanticsonitsown.

UsageEntertheelementinthetopicandspecifythephraseastheinnertext.

Example

ExampleOutputIfitdoesn'tworkout,that'slife.

SeeAlsoOtherResourcesCommonInlineElementsforeignPhrasequoteInline



Ifitdoesn'tworkout,<phrase>that'slife</phrase

Copy



SandcastleMAMLGuide

placeholder

Thiselementisusedasaplaceholder.Bydefault,itrenderstextinastyledeterminedbythepresentationstyle.Itmayhavespecificuseincustombuildcomponents.

UsageEntertheelementinthetopic.It'sinnertextandtheendresultisimplementationdependent.

Example

ExampleOutputSomethingusefulcouldgohereifabuildcomponentmadeuseofit.




Somethingusefulcouldgo<placeholder>here</placeholder

buildcomponentmadeuseofit.

Copy



SandcastleMAMLGuide

quoteInline

Thiselementisusedtodescribeaninlinequotation.

UsageEntertheelementinthetopicandspecifythequotationastheinnertext.

Example

ExampleOutputThisisanexampleofan"inlinequotation".

SeeAlsoOtherResourcesCommonInlineElementsquote



Thisisanexampleofan<quoteInline>inlinequotation

Copy



SandcastleMAMLGuide

replaceable

Thiselementdescribesapartofacommandorafunctionthatmustbereplacedbytheuser.

UsageEntertheelementinthetopicandspecifythereplaceableitemastheinnertext.

Example


SeeAlsoOtherResourcesCommonInlineElementscommand





Copy



SandcastleMAMLGuide

subscript

Thiselementcanbeusedtomarkasubscriptsuchasthosefoundinmathematicalexpressions.

UsageEntertheelementinthetopicandspecifythesubscripttextastheinnertext.

Example

ExampleOutputThechemicalformulaforwaterisH2O.

SeeAlsoOtherResourcesCommonInlineElementsmath



Thechemicalformulaforwateris<math>H<subscript

Copy



SandcastleMAMLGuide

superscript

Thiselementcanbeusedtomarkasuperscriptsuchasthosefoundinmathematicalexpressions.

UsageEntertheelementinthetopicandspecifythesuperscripttextastheinnertext.

Example

ExampleOutputCanyouexplainE=MC2?

SeeAlsoOtherResourcesCommonInlineElementsmath



Canyouexplain<math>E=MC<superscript>2</superscript

Copy



SandcastleMAMLGuide

system

Thiselementdescribessystemcommands,commandlineswitches,etc.

UsageEntertheelementinthetopicandspecifythecommandorswitchesastheinnertext.

Example


SeeAlsoOtherResourcesCommonInlineElementscommandreplaceable





Copy



SandcastleMAMLGuide

ui

Thiselementdescribesauserinterfaceelement.

UsageEntertheelementinthetopicandspecifytheuserinterfaceitemastheinnertext.

Example

ExampleOutputClicktheOKbuttontoclosethedialogbox.




Clickthe<ui>OK</ui>buttontoclosethedialogbox.

Copy



SandcastleMAMLGuide

unmanagedCodeEntityReference

Thiselementisusedtorefertounmanagedcodeentityreferences.Unlikemanagedcodeentityreferences,thiselementdoesnotresultinalinktothereferenceditem.

UsageEntertheelementinthetopicandspecifytheentityastheinnertext.

Example

ExampleOutputYoucanusePInvoketocallSetWindowPlacement.




YoucanusePInvoketocall

<unmanagedCodeEntityReference>SetWindowPlacement</unmanagedCodeEntityReference

Copy



SandcastleMAMLGuide

userInput

Thiselementdescribesdatathatisenteredbytheuser.

UsageEntertheelementinthetopicandspecifytheinputastheinnertext.

Example

ExampleOutputEnterYesorNo.




Enter<userInput>Yes</userInput>or<userInput>No</

Copy



SandcastleMAMLGuide

MediaElements

Thetopicsinthissectiondefinethemedia(image)elementsthatcanbeusedinconceptualtopics.

MediaElementsSelectoneofthetopicsbelowtolearnmoreaboutaparticularmediaelement.

mediaLink

medialLinkInline





SandcastleMAMLGuide

mediaLink

Thiselementisusedtoinsertanimagewithinaconceptualtopic.Thisisablockelementandtheimageappearsbyitselfoutofline.

UsageTouseamedialink,inserttheelementwithinthetopicatthelocationthattheimageshouldappear.

Thenestedimageelementisusedtodefinetheimagelink.Thexlink:hrefattributeshouldrefertotheuniqueIDofanimageintheproject'smediacontentfile.Anoptionalplacementattributecanbeusedtospecifytheplacementoftheimage(near(thedefault),center,orfar).

Thenestedcaptionelementisoptional.Ifspecified,acaptionwillappearwiththeimage.Anoptionalplacementattributecanbeusedtospecifytheplacementofthecaption(before(thedefault)orafter).Inaddition,anoptionalleadattributecanbespecifiedtodefinelead-intextthatwillprefixthecaption(i.e."Figure1").

Example



<mediaLink>

<imagexlink:href="6be7079d-a9d8-4189-9021-0f72d1642beb"

</mediaLink>



<mediaLink>

<caption>CaptionBefore</caption>

<imageplacement="center"xlink:href="6be7079d-a9d8-4189-9021-0f72d1642beb"

</mediaLink>

Copy

ExampleOutput

CaptionBefore



<mediaLink>

<captionplacement="after"lead="Figure1">Captionafterwithlead-in

<imageplacement="far"xlink:href="6be7079d-a9d8-4189-9021-0f72d1642beb"

</mediaLink>

Figure1: Captionafterwithlead-in

SeeAlsoOtherResourcesMediaElementsMediaContentFilemedialLinkInline





SandcastleMAMLGuide

medialLinkInline

Thiselementisusedtoinsertanimageinlinewithinthetextofaconceptualtopic.

UsageTouseaninlinemedialink,inserttheelementwithinthetextofthetopicatthelocationthattheimageshouldappear.Thenestedimageelementisusedtodefinetheimagelink.Thexlink:hrefattributeshouldrefertotheuniqueIDofanimageintheproject'smediacontentfile.

Example

ExampleOutputTheinformationicon appearsnexttoanInformationmessage.

Animagetotheleftofthetext.


Theinformationicon<mediaLinkInline>

<imagexlink:href="4cfacbe8-d100-471c-9d69-1dbcce50e316"

appearsnexttoanInformationmessage.

<mediaLinkInline><imagexlink:href="b5d069f7-5daf-45ae-882c-4596ab2b724a"

Animagetotheleftofthetext.

Copy

MediaElementsMediaContentFilemediaLink





SandcastleMAMLGuide

LinkElements

Thetopicsinthissectiondefinethelinkelementsthatcanbeusedinconceptualtopics.

LinkElementsSelectoneofthetopicsbelowtolearnmoreaboutaparticularlinkelement.

codeEntityReference

externalLink

link





SandcastleMAMLGuide

codeEntityReference

Thisisusedtoinsertareferencetoacodeentitysuchasatype,method,property,event,field,etc.Itcanbeareferencetoamemberinoneofyourclassesoroneinthe.NETFramework.

UsageTouseacodeentityreference,simplyinsertthefullyqualifiedmembernameastheinnertextofacodeEntityReferenceelementanywherewithinatopic.Formethods,includethedatatypesofanyparametersthatarepassedtothemethod.Themembernameshouldbeprefixedwithacodeindicatingthemembertype:

Prefix DescriptionN: Anamespace

T: Atypessuchasaclass,enumeration,interface,orstructure

F: Afieldmember

E: Aneventmember

P: Aproperty

M: Amethod

Therearethreeoptionalattributes.

Name DescriptionqualifyHint Ifsettofalseoromitted,thelinktextwillconsist

onlyofthemembernamewithoutanamespaceorclassqualifier.Ifsettotrue,typenamesare

fullyqualifiedwiththeirnamespace.Classmembersarequalifiedwiththeirclassname.

autoUpgrade Thisonlyhaspurposeonmethodclassmembers.Ifsettofalseoromitted,thelinkwilltakeyoudirectlytothereferencedmember.Ifsettotrueandthemethodhasoverloads,thelinkwilltakeyoutothemethodoverloadspageinstead.Ifthemethodhasnooverloads,itworksthesameasifsettofalseandittakesyoutothemethodpage.

linkText Thiscanbeusedtooverridethedefaultlinktextbasedonthemembernameandprovideyourownlinktext.

Example

ExampleOutputSystem.IOFileStream

FileStreamFileStream

FileStreamWrite

<codeEntityReferencequalifyHint="true">T:System.IO.FileStream


M:System.IO.FileStream.#ctor(System.String,System.IO.FileMode)



M:System.IO.FileStream.Write(System.Byte[],System.Int32,System.Int32)


<codeEntityReferencequalifyHint="false">P:System.IO.FileStream.Length


<codeEntityReferencequalifyHint="false"autoUpgrade

M:System.IO.FileStream.Flush</codeEntityReference>

<codeEntityReferencelinkText="FileStream.FlushonMSDN"

M:System.IO.FileStream.Flush</codeEntityReference>

Copy

http://msdn2.microsoft.com/en-us/library/y0bs3w9t

http://msdn2.microsoft.com/en-us/library/98hy92k3

http://msdn2.microsoft.com/en-us/library/2t9z5e24

Length

Flush

FileStream.FlushonMSDN

SeeAlsoOtherResourcesLinkElementscodecodeInlinecodeReference



http://msdn2.microsoft.com/en-us/library/csws4bx5

http://msdn2.microsoft.com/en-us/library/ee474551

http://msdn2.microsoft.com/en-us/library/2bw4h516



SandcastleMAMLGuide

externalLink

ThisisusedtoinsertalinktoanexternalURLofsomesortsuchasawebsite.

UsageAnexternallinkconsistsofthefollowingnestedelements.

Name DescriptionlinkText Thisisarequiredelementandisusedto

specifythetexttousefortheinnertextofthelink.

linkAlternateText Thisisanoptionalelement.Itisusedtospecifyalternatetextforthelinkthatwillbedisplayedwhenthemousehoversoverit.

linkUri ThisisarequiredelementandisusedtospecifytheURLtowhichthelinkrefers.Thiscanbeanysortoflink(HTTP,FTP,mail,etc).

linkTarget Thisisanoptionalelement.Itisusedtospecifythetargetwindowtousewhenthelinkisclicked.Ifomitted_blankisusedtoopentheexternallinkinanewwindow.Thevalue_selfcanbeusedtoopenthelinkinthesamewindowasthetopicthusreplacingit.

Note

IftheURLinthelinkUrielementcontainsXMLentitiessuchastheampersand(&),youmustencodethemorabuilderrorwilloccur.Seetheexamplebelow.

Example

ExampleOutputOnlylinktextandURI:SandcastleHelpFileBuilder

Addedalternatetext:SandcastleHelpFileBuilder

Addedlinktarget:SandcastleHelpFileBuilder

IfthelinkcontainsXMLentities,theymustbeencoded(i.e.theampersand):MSDNDocumentationForum

OnlylinktextandURI:<externalLink>



</externalLink>

Addedalternatetext:<externalLink>


<linkAlternateText>VisitSHFBonGitHub</linkAlternateText


</externalLink>

Addedlinktarget:<externalLink>


<linkAlternateText>VisitSHFBonGitHub</linkAlternateText


<linkTarget>_self</linkTarget>

</externalLink>

IfthelinkcontainsXMLentities,theymustbeencoded(i.e.theampersand):

<externalLink>

<linkText>MSDNDocumentationForum</linkText>

<linkUri>http://forums.microsoft.com/MSDN/ShowForum.aspx?ForumID=66&SiteID=1

</externalLink>

Copy




http://forums.microsoft.com/MSDN/ShowForum.aspx?ForumID=66&SiteID=1

SeeAlsoOtherResourcesLinkElementslink





SandcastleMAMLGuide

link

ThisisusedtoinsertalinktoanotherconceptualtopicusingitsIDvalue.Itcanalsobeusedtocreatelinkstoelementswithinthesamepagethathaveanaddressattributesuchastheintroductionandsectionelements.

UsageFortopiclinks,alinkconsistsofarequiredxlink:hrefattributethatcontainstheGUIDofthetopictowhichthelinkwillgoandoptionalinnertext.Ifnoinnertextisspecified,thetextwillberetrievedfromthereferencedtopic'scompanionfile.IfthecompanionfilecontainsalinkTextelement,itsvaluewillbeused.Ifnot,thevalueofthetitleelementwillbeused.

Youcanlinktoanchorswithinthetargettopicbyaddingahashcharacter(#)followedbytheanchornameafterthetopic'sGUID.Forin-pagelinks,simplyspecifyahashcharacter(#)followedbythenameoftheanchorfromanelement'saddressattribute.Innertextisrequiredforin-pagelinks.

Tip

WhenusedinarelatedTopicselement,anoptionaltopicType_idattributecanbeaddedthatspecifiesaGUIDvalueusedtoclassifythelinktypesothatitisgroupedwithothersimilarlinks.SeetherelatedTopicstopicformoreinformation.

Example

Self-closing:<linkxlink:href="cfd9dabf-22f3-4742-8b54-d84404610db1"

Withinnertext:<linkxlink:href="cfd9dabf-22f3-4742-8b54-d84404610db1"

companionfile</link>

Copy

ExampleOutputSelf-closing:CompanionFile

Withinnertext:companionfile

In-pagelinktointroduction:BacktoIntro

Linktoothertopicanchor:LinkstoResources

SeeAlsoOtherResourcesLinkElementsCompanionFileexternalLink



In-pagelinktointroduction:<linkxlink:href="#intro"

Linktoothertopicanchor:

<linkxlink:href="dc4fcc96-283e-4202-9ecc-08a65e0c9313#BuildTools"



SandcastleMAMLGuide

MiscellaneousElements

Thetopicsinthissectiondefinemiscellaneouselementsnotfittingoneoftheothercategoriesthatcanbeusedinconceptualtopics.

MiscellaneousElementsSelectoneofthetopicsbelowtolearnmoreaboutaparticularmiscellaneouselement.

autoOutline

markup

token





SandcastleMAMLGuide

autoOutline

TheautoOutlineelementisaspecialcaseusedbySandcastletoinsertanauto-generatedsectionoutlinewithinatopic'sintroductionorsub-sections.

UsagePlacetheelementwithinatopic'sintroductionelementtoproduceanoutlineofthetopic'ssectionheadingsorwithinasection'scontentelementtoproduceanoutlineofthesection'ssub-sections.Ineithercase,theoutlinewillbecreatedatthelocationoftheauto-outlineelement.Assuch,youcancontroltheplacementoftheoutlinewithinthetext.

Eachsectionmusthaveatitleelementasthatisthetextthatwillbeusedfortheoutlineentry.Inaddition,anaddressattributemustbeaddedtoeachsectionelementtogiveitauniqueIDthatcanbeusedasalink.Youcanalsoaddanoptionaladdressattributetotheintroductionelementsothatyoucanlinkbacktoitfromasub-section.

Anoptionalleadattributecanbespecifiedtodefinethelead-intextdisplayedbeforethelistoflinks.Ifnotspecified,defaultlead-intextisused.Ifsettothevaluenone,thelead-intextwillbeomitted.

AnoptionalexcludeRelatedTopicsattributecanbespecified.IfsettoTrue,thetop-levelauto-outlinewillexcludetheRelatedTopicslink.Thiscanbeusefulifyousimplywanttolistthemainsectionsofthetopicwithsomealternatelead-intextornolead-intextatall.

Ifanumericinnertextvalueisspecified,thesectionheadingsdowntotheindicateddepthwillbeincludedintheoutline.Zero(0),thedefault,specifiesthatonlytop-levelsectionheadingsshouldbeincludedintheoutline.

ExampleCopy

<topicid="1a817894-db7a-4c7f-bd67-cca896affa35"revisionNumber




<introductionaddress="Intro">



<autoOutline/>

<para>Theintroduction.If<codeInline><autoOutline/>

isincluded,thisparagraphcanbeomitted.

</para>



</introduction>

<sectionaddress="S1">

<title>Section1</title>

<content>

<para>Thisissection1.</para>



<autoOutlinelead="Selectasub-section:">3

</content>

<sections>

<sectionaddress="SS1">


<content>

<para>Thisissub-section1.</para>

</content>

</section>

<sectionaddress="SS2">


<content>



<para>Thisissub-section2.</para>

</content>

<sections>

<sectionaddress="SSS1">

Copy

ExampleOutputSeeautoOutlineRenderedExample


<title>Sub-sub-section1</title>

<content>

<para>Thisissub-sub-section1.</para

</content>

</section>

<sectionaddress="SSS2">

<title>Sub-sub-section2</title>

<content>

<para>Thisissub-sub-section2.</para

<para>

<linkxlink:href="#Intro">BacktotheTop

</para>

</content>

</section>

</sections>

</section>

</sections>

</section>

<sectionaddress="S2">

<title>Section2</title>

<content>

<para>Thisissection2.</para>

</content>

</section>

<relatedTopics>

<linkxlink:href="b9a1daac-a2d8-41b7-83b0-b7dc7b28b898"

</relatedTopics>


</topic>

MiscellaneousElementstoken





SandcastleMAMLGuide

autoOutlineRenderedExample

Thistopiccontainsthefollowingsections:

Section1Section2SeeAlso

Theintroduction.If<autoOutline/>isincluded,thisparagraphcanbeomitted.

Section1Thisissection1.

Selectasub-section:

Sub-section1Sub-section2

Sub-sub-section1Sub-sub-section2

Sub-section1Thisissub-section1.

Sub-section2Thisissub-section2.

Sub-sub-section1Thisissub-sub-section1.

Sub-sub-section2Thisissub-sub-section2.

BacktotheTop

Section2Thisissection2.

SeeAlsoOtherResourcesautoOutline





SandcastleMAMLGuide

markup

ThiselementcanbeusedtopassaliteralpieceofHTMLmarkupthroughtotherenderedtopic.Ingeneral,thiselementisonlyusedbycustombuildcomponentstopassHTMLthroughaftermodifyingtheconceptualtopicinsomemanner(i.e.tocolorizecode).Othernon-componentusesmightbetoincludeavideoorothersuchitemsinthetopicthatiscurrentlynothandledbyMAML.

Note

ItisrecommendedthatyouavoidusingthiselementunlessthereisnoMAMLequivalentforwhatyouaretryingtodo.Usageshouldberestrictedtotheoutputofcustombuildcomponentswhenneeded.

UsageEntertheelementinthetopicandspecifytheHTMLmarkupastheinnertext.Itcanbeusedasablockoraninlineelement.

Example

ExampleOutput

HereisapieceofliteralHTMLmarkup:

<markup>

<br/><br/>

Itis<b>NOT</b>recommendedthatyouusethe<em>markup

normalconceptualcontentwhenanequivalent<u>MAMLelement

Itsuseshouldberestrictedtocustombuildcomponents.

</markup>

Copy

HereisapieceofliteralHTMLmarkup:

ItisNOTrecommendedthatyouusethemarkupelementfornormalconceptualcontentwhenanequivalentMAMLelementalreadyexists.Itsuseshouldberestrictedtocustombuildcomponents.

SeeAlsoOtherResourcesMiscellaneousElements





SandcastleMAMLGuide

token

Atokenisusedasareplaceabletagwithinatopicandisrepresentedusingatokenelement.Theinnertextoftheelementisatokenname.Thetokensaredefinedinaseparatetokenfile.Theyareaneasywaytorepresentcommonitemsthatyouuseregularlysuchasacommonphraseorexternallink.

UsageTouseatoken,simplyinsertitsnameastheinnertextofatokenelementanywherewithinatopic.

ExampleInthisexample,"Sandcastle"isatokenthatexpandstoanexternallinktoawebsite.

ExampleOutputThislink(SandcastleHelpFileBuilder)isstoredinatoken.

SeeAlsoOtherResourcesMiscellaneousElementsTokenFile


Thislink(<token>SHFB</token>)isstoredinatoken.

Copy



SandcastleMAMLGuide

VisualStudioIntelliSense

ThistopiccovershowtointegrateMAMLschemafilesintoVisualStudio'sglobalschemacachetoprovideIntelliSensewheneditingMAMLtopicswithinVisualStudio.

Tip

TheguidedinstallerusedtoinstallSandcastleandtherelatedtoolsprovidesanoptiontoinstalltheMAMLschemasintheVisualStudioglobalschemacacheforyou.

Note

BecausechangesaremadetotheProgramFilesfolder,youwillneedadministrativeprivilegestoperformtheseupdates.Intheinstructionsbelow,%ProgramFiles%isusedtorefertotheProgramFilesfolder.ThiswilltypicallybeC:\ProgramFileson32-bitsystemsandC:\ProgramFiles(x86)on64-bitsystems.YoumayneedtoalterthepathsbelowifyouinstalledVisualStudioand/orSandcastleindifferentlocations.

IntegratingMAMLSchemaFilesintoVisualStudio1. CreateasubfoldernamedMAMLunderVisualStudio'sglobal

schemacachefolderwhichislocatedat%ProgramFiles%\MicrosoftVisualStudio[x.x]\Xml\Schemaswhere"[x.x]"iseachversionofVisualstudiosuchas"12.0"(VS2013)and"14.0"(VS2015).YoucanrepeatthefollowingstepsforeachversionofVisualStudiothatyouhaveinstalled.

2. CopyalloftheMAMLschemasandthecatalogfilefromthe%ProgramFiles%\Sandcastle\Schemas\AuthoringfolderintothenewMAMLschemasfolderthatyoucreatedinthepreviousstep.

3. Updatetheroot%ProgramFiles%\MicrosoftVisualStudio[x.x]\Xml\Schemas\catalog.xmlfilebyincludingthefollowingline:

Copy

4. IntelliSenseshouldnowworkforallMAMLtopicsautomaticallyinVisualStudio.IfyouhadVisualStudioopenwhilemakingthechanges,youmayneedtorestartitinordertoseeIntelliSenseintheMAMLtopicfiles.

SeeAlsoOtherResourcesSchemaExtensibility



<Cataloghref="%InstallRoot%/xml/schemas/MAML/catalog.xml"

Copy



SandcastleMAMLGuide

SchemaExtensibility

ThistopicwillexplainhowyoucanchangetheMAMLschemasothatyoucanuseelementsfromothernamespacesaswell.ThisisusefulwhenextendingSandcastlewithbuildcomponentsthatprovidenewelementsbecauseitstillallowsyoutovalidateyourtopicfiles.

Tip

TheSandcastleversionoftheMAMLschemafilesalreadycontainthenecessarychanges.

XMLSchemaExtensibilityIngeneral,XMLschemaprovidestheanyelementfordeclaringextensibilitypointsinyourschema.Theanyelementhastwoattributesthatcontroltheextensibilitycontract.

Thenamespaceattributeallowsyoutoeitherexplicitlyspecifyaclosedsetofnamespacesthatareallowedortospecifyoneofthesepseudo-URIs:

##localThisallowsonlytouseelementsthatdonotresideinanynamespace.Thisisnotwhatwewanttousebecauseitforcesbuildcomponentauthorstodeclareallelementsintheemptynamespace.Thiscouldeasilyleadtonameclashesbetweendifferentbuildcomponents.

##targetNamespaceThisonlyallowselementsfromthetargetnamespaceofthedeclaringschema.ForourpurposesthisisuselessbecauseitwouldonlyallowelementsfromtheMAMLnamespace(http://ddue.schemas.microsoft.com/authoring/2003/5).

##anyThisallowsanynamespace,includingthetargetnamespaceofthedeclaringschema.Wedonotwanttousethisbecauseit

wouldalsoallowtouseanyelementfromtheMAMLnamespace(http://ddue.schemas.microsoft.com/authoring/2003/5)itselfandhenceunderminetheschemavalidationforMAML.

##otherThisallowsanynamespacesexceptthetargetnamespaceofthedeclaringschema.ForourpurposesthisisidealbecauseitallowsonlytouseelementsfromanynamespaceexcepttheMAMLnamespace(http://ddue.schemas.microsoft.com/authoring/2003/5).

TheprocessContentsattributeallowsyoutocontrolthevalidationrequirements.Itcanhaveoneoffollowingvalues:

skipThisistheleastrestrictivevalue.Itspecifiesthattheschemaprocessorshouldnottrytovalidatethecontentsofthenewelement,evenifitisabletofindaschemaforit.

strictThisisthemostrestrictivesetting.Itrequirestheschemaprocessortoalwaysvalidatethecontentsofthenewelement.Ifitisnotabletofindsuchaschemaanerrorisreportedduringvalidation.

laxThisisacompromisebetweenthesettingsskipandstrict.Theschemaprocessorwillvalidatetheschemaifitisabletofindaschemaforthenewelementandwillskipitifcannotfindsuchaschema.Forourpurposesthisisidealbecauseitallowsbuildcomponentauthorstoprovideaschemaforvalidationbutdoesnotforcethemtodoso.

Therefore,ourextensibilitypointswillalllooklikethis:

ExtendingInlineTextBuildcomponentsmightaddelementsthatyoucanuseinsidea

<anynamespace="##other"processContents="lax"/>

Copy

paraelement.Examplesforsuchelementsare:

LinkingTheseareelementsthatallowyoutolinktoothertopics.MAMLitselfalreadyprovidesseveralelementsforthispurpose,suchasthelinkelementtolinktoconceptualtopics,thecodeEntityReferenceelementtolinktomanagedcodeAPIs,andtheexternalLinkelementtolinktosomelocationintheinternet.

SemanticsThiscategoryincludeselementsthatareusedtoassociatepiecesoftextwithsemantics.Inmanycasesthesesemanticsaremadevisiblethroughaconsistentformatting,suchasitalicsorboldtext.AmongstothersMAMLitselfprovidesthelocalUrielementformarkingtextasrepresentinglocalpathsandtheuielementformarkingtextasrepresentingelementsinyouruserinterface.

ToextendtheparaelementwewillextendtheunderlyingtypeinlineType.

Openthefileinline.xsd,gotoline60,andaddtheanyelementtothetype:

<complexTypename="inlineType"mixed="true">

<annotation>

<documentation>

TheinlineTypecomplexTypedescribesasimpleinline-only

contentmodel.Itprovidesbothtextandelementswith

similarlysimplecontentmodels.

</documentation>

</annotation>

<choiceminOccurs="0"maxOccurs="unbounded">

<groupref="maml:inlineGroup"/>

<elementref="maml:sharedContent"/>

<elementname="conditionalSection">

<complexType>

<sequence>

<elementref="maml:conditions"/>

Copy

ExtendingRelatedTopicsForbuildcomponentsthatprovideelementsforlinkingwealsowanttobeabletousetheminsidetherelatedTopicselement.Todothis,wewillextendthetyperelatedTopicsType.

Openthefilehierarchy.xsd,gotoline123andaddtheanyelementtothetype:

ExtendingSectionStructureLastbutnotleastbuildcomponentsmightalsoprovideelementsthatallowyoutobuildastructure.ForthispurposeMAMLitselfalreadyprovidesthetable,code,andparaelements.ToallownewstructuralelementswehavetoextendthetypesectionContentType.

Openthefilestructure.xsd,gotoline67andaddtheanyelementtothetype:

<elementname="conditionalContent"type="maml:inlineType"

</sequence>

</complexType>

</element>



<anynamespace="##other"processContents="lax"

</choice>

<attributeGroupref="maml:contentIdentificationSharingAndConditionGroup"

</complexType>

<complexTypename="relatedTopicsType"mixed="false"


<groupref="maml:relatedTopicLinkGroup"/>




</choice>


</complexType>

Copy

SeeAlsoOtherResourcesVisualStudioIntelliSense



<complexTypename="sectionContentType"mixed="false"


<groupref="maml:structureGroup"/>

<elementname="conditionalSection"type="maml:conditionalSectionType"




</choice>


</complexType>

Copy

SandcastleMAMLGuide

LinkstoResources

Thistopicscontainslinkstovariousresourcesthatyoumayfinduseful.

MAMLInformationandGuidesDiscussionGroups,Blogs,Etc.BuildTools

MAMLInformationandGuidesThemostrecentversionofthisguidecanbedownloadfromtheSandcastleHelpFileBuilderprojectonGitHub.

Forgeneralbackgroundinformation,seetheWikipediaentryMicrosoftAssistanceMarkupLanguageor,forschemainformation,seetheMAMLinformationathelp-info.de.

IfyouneedatooltoconvertHTMLfilestoMAML,theConvertingHTMLFilestoMAMLTopicsisincludedwiththehelpfilebuilderalongwiththisguide.

DiscussionGroups,Blogs,Etc.Todiscussthehelpfilebuilderandtools,suggestnewfeatures,reportbugsinthem,andrequesthelpusingthem,visittheSandcastleHelpFileBuilderprojectsite.

Fordiscussionandquestionsabouthelpsystemsingeneral,visittheVisualStudioGeneralQuestionsforum.

TheretiredMicrosoftDeveloperDocumentationandHelpSystemforummayalsoprovideinformationonolderhelpsystems.

BuildTools


http://en.wikipedia.org/wiki/Microsoft_Assistance_Markup_Language

http://www.help-info.de/en/Help_Info_AP_Help/longhorn_maml_example.htm

https://EWSoftware.GitHub.io/HtmlToMamlDocs


http://social.msdn.microsoft.com/Forums/en-US/visualstudiogeneral/threads/

http://social.msdn.microsoft.com/forums/en-US/devdocs/threads/

Microsoft.NETFrameworksandSDKs.

TheHTMLHelpWorkshopforbuildingHTMLHelp1.x(.CHM)helpfiles.

SeeAlsoOtherResourcesWelcome



https://msdn.microsoft.com/en-us/vstudio/aa496123

http://msdn2.microsoft.com/en-us/library/ms669985.aspx



SandcastleMAMLGuide

MakingaDonation

Ifyouwouldliketosupportthisproject,youcanmakeadonationofanyamountyoulikebyclickingonthePayPaldonationbuttonbelow.Ifyouwouldprefertodonateviacheckormoneyorder(USD),pleasesendmeane-mailatEric@EWoodruff.usandIwillreplywithmymailingaddress.

Theabovemethodofdonatingissecure.PayPalguaranteesyourprivacyandsecurity.Ineverreceivedetailsofyourpaymentotherthantheamount,yourname,e-mailaddress,andanyoptionallyenteredinformation.

Thankstothoseofyouthathavemadeadonation.Itismuchappreciated!



mailto:[email protected]?Subject=Sandcastle Help File Builder Donation

https://www.paypal.com/cgi-bin/webscr?cmd=_s-xclick&hosted_button_id=WBPB4ML7YBUHW



SandcastleMAMLGuide

VersionHistory

ThetopicsinthissectiondescribethevariouschangesmadetotheMAMLGuideoverthelifeoftheproject.

VersionHistorySelectaversionbelowtoseeadescriptionofitschanges.

Version1.1.0.3

Version1.1.0.2

Version1.1.0.1

Version1.1.0.0

Version1.0.0.0





SandcastleMAMLGuide

Version1.1.0.3

Version1.1.0.3wasreleasedonDecember16th,2012.

ChangesinThisReleaseRemovedreferencestotheSandcastleHelpFileBuildercomponentsandfeaturesthathavebeenmovedintotheSandcastletoolsandpresentationstyleXSLtransformationsandrewordedtheaffectedsectionstoreflecttheiractualusewithSandcastlealone.

SeeAlsoOtherResourcesVersionHistory





SandcastleMAMLGuide

Version1.1.0.2

Version1.1.0.2wasreleasedonApril7th,2012.

ChangesinThisReleaseAddedasolutionfileforuseineditingtheprojectwithinVisualStudiowiththeSandcastleHelpFileBuilderandupdatedtheprojecttothelatestreleaseformat.

Addednon-breakingspacestotheexamplesforthecommand,replaceable,andsystemelementtopicstofixtheirlayout.AddedanoteaboutthistotheKnownIssuestopic.

MovedthemarkupelementtotheMiscellaneousgroupsinceitcanserveaseitheraninlineorblockelement.

Fixedthedescriptionoftheparaelementtonotethatself-closingandemptyparagraphsareignoredratherthancreatingalinebreak.Thepriorimpliedusagewasincorrectanddidnotconformtotheschema.

FixedthecodeandcodeReferenceexamplestoincludeparaelementsintheproperplacestoconformtotheschema.

FixedupseveralothertopicssothattheyconformedtotheMAMLschema.

ReplacedallcodelangattributeswithlanguageattributestoconformtotheMAMLschema.

RemovedallreferencestotheSandcastleStylesproject.ThechangesthatitcontainedhavebeenmergedintothelatestreleaseofSandcastleitselfalongwiththisproject.

SeeAlso

OtherResourcesVersionHistory





SandcastleMAMLGuide

Version1.1.0.1

Version1.1.0.1wasreleasedonFebruary21st,2011.

ChangesinThisReleaseUpdatedthedefinitionTable,list,andtabletopicstonotethattextinthedefinition,listItem,andentryelementsshouldbecontainedinaparaelement.ThetopicsintheMAMLguidehavebeenupdatedtoreflectthisschemarule.

ConvertedtheprojecttousethenewSandcastleHelpFileBuilder1.9.0.0projectformat.

UpdatedreferencestothelatestreleaseofSandcastle(June2010)andfixedafewtypos.

AddedatopiconintegratingtheSandcastleMAMLschemafilesintotheVisualStudioglobalschemacachetoprovideIntelliSenseforMAMLtopicswhileeditingtheminVisualStudio.

AddedatopiconmakingtheSandcastleMAMLschemasextensibleforthird-partybuildcomponentelements.ThisinformationwassuppliedbyImmoLandwerth.






SandcastleMAMLGuide

Version1.1.0.0

Version1.1.0.0wasreleasedonOctober25th,2008.

ChangesinThisReleaseCorrectedtheorderofthelinkAlternateTextandlinkUrielementsintheexternalLinktopicandallusesofitthroughouttheguide.

Fixedafewbugsintheusageexamples.

Updatedtheconceptualtemplatestoreflectcorrectusageandtonotesomeelementsasbeingoptional.

UpdatedtherelatedTopicstopictoincludeinformationabouttheoptionaltopicType_idlinkattribute.

UpdatedtheautoOutlinetopictoincludeinformationabouttheoptionalleadandexcludeRelatedTopicsattributes.

Addedtopicsfor:

definitionTable,definedTerm,anddefinition

listandlistItem

table,tableHeader,row,andentry

ConvertedtheprojecttousethenewSandcastleHelpFileBuilder1.8.0.0projectformat.


VersionHistory





SandcastleMAMLGuide

Version1.0.0.0

Version1.0.0.0wasreleasedonJune4th,2008.

ChangesinThisReleaseInitialrelease.






SandcastleMAMLGuide

Glossary

A|B|C|D|E|F|G|H|I|J|K|L|M|N|O|P|Q|R|S|T|U|V|W|X|Y|Z

BBuildAssembler.exeThisisatoolsuppliedwithSandcastlethatisusedtobuildthehelptopicsforconceptualandreferencebuilds.ItispassedaconfigurationfilecontainingalistofbuildcomponentstouseintransformingthetopicsintoHTMLandamanifestfilethatliststhetopicstobuild.

SeeAlso:Sandcastle

CCodeBlockComponentAcustombuildcomponentthatcanbeusedtocolorizecode,addlinenumberingand/orcollapsiblesection,andimportcodefromworkingsourcecodefiles.Itcanbeusedinbothconceptualandreferencebuilds.ThecomponentisintegratedwiththeSandcastleHelpFileBuilderandisalsoavailableasastandalonecomponentfromthesameprojectsiteforuseinothertoolsoryourownbuildscripts.

SeeAlso:Sandcastle,SandcastleHelpFileBuilder

codesnippetsfileAfileusedtostorecommonlyusedcodesnippets.ThesnippetscanbeinsertedintoaconceptualtopicusingthecodeReferenceelement.

conceptualbuild


AbuildthatusesSandcastletoproducehelpfiletopicsusinginformationextractedfromconceptualcontenttopicsandtheirrelatedfiles.

SeeAlso:referencebuild,Sandcastle

conceptualcontentAtopicfilethatcontainsconceptualcontent.Thesecanbeusedtoaddusagenotes,walkthroughs,tutorials,etc.toahelpfile.

GGloballyUniqueIdentifier,GUIDAuniquevaluethatisassociatedwitheachconceptualtopicandimageinaproject.Wheninsertinglinkstotopicsorimages,theIDisusedtorefertothem.Thisallowsyoutoalterthenamesorlocationsofthetopicfileswithouthavingtochangethenameorlocationineachtopicthatreferencesthem.

MMAMLAnacronymthatstandsforMicrosoftAssistanceMarkupLanguage.ConceptualcontenttopicsarecomposedofMAMLelements.

RreferencebuildAbuildthatusesSandcastletoproducehelpfiletopicsusinginformationextractedfrommanagedassembliesandtheirassociatedXMLcommentsfiles.

SeeAlso:conceptualbuild,Sandcastle

SSandcastle

SandcastleisasetoftoolsoriginallyproducedbyMicrosoftthatcanbeusedtobuildhelpfilesfor.NETmanagedlibraries,conceptualcontent,oramixofboth.MicrosoftofficiallydiscontinueddevelopmentinOctober2012.TheSandcastletoolshavebeenmergedwiththeSandcastleHelpFileBuilderprojectandaredevelopedandsupportedtherenowaspartofthatproject.

SeeAlso:SandcastleHelpFileBuilder

SandcastleHelpFileBuilder,SHFBTheSandcastleHelpFileBuilderisastandalonetoolusedtoautomateSandcastle.ItconsistsofaGUIfrontendthathelpsyoumanageandbuildhelpfileprojects.ItusesastandardMSBuildformatprojectfilewhichcanalsobebuiltfromthecommandlineusingMSBuildorintegratedintoVisualStudiobuildsorotherbuildscriptstoproduceahelpfilewhenyourapplicationprojectsarebuilt.Inaddition,itprovidesasetofadditionalfeaturesbeyondthosesuppliedwithSandcastlethatcanimproveyourhelpfileandmakeiteasiertodeploy.AVisualStudiointegrationpackageisalsoavailableforitthatintegratestheprojectmanagementandbuildfeaturesintoVisualStudio2013orlater.

SeeAlso:Sandcastle

Ttoken,tokenfileAtokenisusedasareplaceabletagwithinatopicandisrepresentedusingatokenelement.Theinnertextoftheelementisatokenname.Thetokensaredefinedinaseparatetokenfile.Theyareaneasywaytorepresentcommonitemsthatyouuseregularlysuchasacommonphraseorexternallink.







Sandcastle MAML Guide - Documentation & Help · Sandcastle MAML Guide Welcome Welcome to the...

Documents

Transcript of Sandcastle MAML Guide - Documentation & Help · Sandcastle MAML Guide Welcome Welcome to the...