Sandcastle MAML Guide - Documentation & Help · Sandcastle MAML Guide Welcome Welcome to the Sandcastle MAML Guide. This is intended to be a reference that you can use to find out

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

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.

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

CodeSnippetsFileFormatBelowisanexampleofacodesnippetsfile.

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

<itemid="ClassDefinition#Define">

<sampleCodelanguage="CSharp">

publicclassCSharpClass()

CopyExampleCodeSnippetsFile

Thefileconsistsofarootexamplesnodethatcontainsoneormoreitemnodes.Theitemelementhasanidattributethatgiveseachoneauniqueidentifier.ThisisusedastheinnertextofthecodeReferenceelementinatopictorepresentthesnippet.

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.

TheSandcastleHelpFileBuilderdoesnotuseamediacontentfiledirectly.Instead,imagesaremanagedasprojectfileitemsandthemediacontentfileiscreatedforyouautomaticallyatbuildtimebasedonthepropertyvaluesonthoseitems.

MediaContentFileFormatBelowisanexampleofamediacontentfile.

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

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.

ThetokenIDisnotcase-sensitive.

TokenContentThecontentofatokenitemcanbeanythingyoulikeandmayincludeotherMAMLelements.Intheexampleabove,thefirstfourelementsareusedtodefinecommonexternallinksusedbythisproject.

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

TheautoOutlinetokenisaspecialcaseusedbyearlierversionsofSandcastletoinsertanauto-generatedsectionoutlinewithinatopic'sintroductionorsub-sections.SeetheautoOutlinetopicformoreinformation.

TheSandcastleHelpFileBuilderaddstheautoOutlinetokenaspartofthebuildautomatically.Assuch,youdonotneedtodefineitintheprojectyourself.

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

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

<para>Optionalsummaryabstract</para>

</summary>

<!--Uncommentthistogenerateanoutlineofthesectionandsub-section

titles.Specifyanumericvalueastheinnertexttolimititto

aspecificnumberofsub-topicswhencreatingtheoutline.Specify

zero(0)tolimitittotop-levelsectionsonly.-->

<para>Requiredintroduction</para>

</introduction>

<!--Addoneormoretop-levelsectionelements.Thesearecollapsible.

CopyConceptualTopic

Ifusing<autoOutline/>,addanaddressattributetoidentifyit

andspecifyatitlesothatitcanbejumpedtowithahyperlink.-->

<sectionaddress="Section1">

<title>Optionalsectiontitle</title>

<!--Uncommentthistocreateasub-sectionoutline

<para>Addoneormoresectionswithcontent

</content>

<!--Ifasectioncontainsasectionselement,itscontentcreates

sub-sections.Thesearenotcollapsible.

<sectionaddress="SubSection1">

<title>Sub-section1</title>

<para>Sub-sectioncontent.</para>

</content>

</section>

<sectionaddress="SubSection2">

<para>Sub-sectioncontent.</para>

</content>

</section>

</sections>-->

</section>

<!--Oneormoreofthefollowing:

-Alocallink

-Anexternallink

-Acodeentityreference

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

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

<linkText>Linktext</linkText>

<linkAlternateText>Optionalalternatelinktext</linkAlternateText>

SeeAlsoOtherResourcesTopicFile

</externalLink>

<codeEntityReference>APImemberID</codeEntityReference>

Examples:

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

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

<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

</summary>

</introduction>

CopyErrorMessageTopic

SeeAlso

-Alocallink

-Anexternallink

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

</externalLink>

Examples:

</externalLink>

</relatedTopics>

</developerErrorMessageDocument>

</topic>

OtherResourcesTopicFile

SandcastleMAMLGuide

Glossary

Thisdocumenttypeisusedtocreateaglossary.

GlossaryFileFormatBelowisanexampleofaGlossarytopicfile.

<developerGlossaryDocument

<!--Glossarydivision.Youcanusethesetogroupentries.Ifyouonly

haveonegroup,youcanomititandlisttheglossaryEntryelements

directly.

Ifused,besuretogiveeachglossaryDivauniqueaddressattribute

andatitleelement.Thesewillbeusedtocreateanindexatthe

topoftheglossarypage.

Glossarydivisionswillappearintheorderdefinedinthetopic.

Glossaryentrieswillbesortedbythefirsttermfortheentry.

Termsaresortedbytheirvalue.-->

<glossaryDivaddress="Group1">

<title>Group#1</title>

CopyGlossaryTopic

<terms>

<!--Oneormoretermsassociatedwiththedefinition.AddatermId

attributeifyouneedtolinktoitfromarelatedEntryelement.

Otherwise,itcanbeomitted.Termsappearasacomma-separated

listabovethedefinition.-->

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

<term>Otherterm(ifany)</term>

</terms>

<para>Thedefinitionoftheterm(s)</para

</definition>

<!--Oneormoreoptionalrelatedentries.Createsa"SeeAlso"

lineafterthedefinitionwithlinkstoeachrelatedterm.-->

</glossaryEntry>

</glossaryDiv>

</glossary>

</developerGlossaryDocument>

</topic>

SandcastleMAMLGuide

How-To

Thisdocumenttypeisusedfor"howto"topics.

How-ToFileFormatBelowisanexampleofaHow-Totopicfile.

<developerHowToDocument

</summary>

</introduction>

<!--Optionalproceduresfollowedbyoptionalcodeexamplebutmusthave

atleastoneprocedureorcodeexample-->

<title>Proceduretitle</title>

<stepsclass="ordered">

<step>

CopyHow-ToTopic

<para>Firststep</para>

</content>

</step>

<step>

<para>Secondstep</para>

</content>

</step>

</steps>

</procedure>

<!--<buildInstructions>Optionalinstructionsforbuildinga

codeexample.</buildInstructions>-->

<!--<robustProgramming>Optionaldiscussionoferrorhandlingandother

issuesrelatedtowritingsolidcode.</robustProgramming>-->

-Alocallink

-Anexternallink

</externalLink>

Examples:

</externalLink>

</relatedTopics>

</developerHowToDocument>

</topic>

SandcastleMAMLGuide

Orientation

Thisdocumenttypeisusedfororientationtopics.

OrientationFileFormatBelowisanexampleofanOrientationtopicfile.

<developerOrientationDocument

</summary>

</introduction>

CopyOrientationTopic

-Alocallink

-Anexternallink

</externalLink>

Examples:

</externalLink>

</relatedTopics>

</developerOrientationDocument>

</topic>

SandcastleMAMLGuide

Reference

Thisdocumenttypeisusedforreferencetopics.

ReferenceFileFormatBelowisanexampleofaReferencetopicfile.

SeeAlso

<codeEntityDocument

<!--NOTE:ThisissimilartotheAPIreferencedocumentationwhichis

producedbythereferencebuild.Youshouldprobablyjustusethat

insteadofthis.-->

<assemblyName>Assemblyname</assemblyName>

</assembly>

<codeEntityReference>APImemberID</codeEntityReference

</codeEntity>

</codeEntities>

</codeEntityDocument>

</topic>

CopyReferenceTopic

OtherResourcesTopicFile

SandcastleMAMLGuide

ReferenceWithSyntax

Thisdocumenttypeisusedforreferencewithsyntaxtopics.

ReferenceWithSyntaxFileFormatBelowisanexampleofaReferenceWithSyntaxtopicfile.

<developerReferenceWithSyntaxDocument

</summary>

insteadofthis.-->

CopyReferenceWithSyntaxTopic

</introduction>

<title>Syntaxsectiontitle</title>

<para>Syntaxcontent</para>

</content>

</section>

</sections>

<parameterReference>Parameterreference</parameterReference

</legacySyntax>

</syntaxSection>

Ifusing<autoOutline/>,addanaddressattributetoidentify

itsothatitcanbejumpedtowithahyperlink.-->

</content>

</section>

-Alocallink

-Anexternallink

</externalLink>

Examples:

</externalLink>

</relatedTopics>

</developerReferenceWithSyntaxDocument>

</topic>

SandcastleMAMLGuide

Thisdocumenttypeisusedforreferencewithoutsyntaxtopics.

ReferenceWithoutSyntaxFileFormatBelowisanexampleofaReferenceWithoutSyntaxtopicfile.

<developerReferenceWithoutSyntaxDocument

</summary>

insteadofthis.-->

CopyReferenceWithoutSyntaxTopic

</introduction>

</content>

</section>

-Alocallink

-Anexternallink

</externalLink>

Examples:

</externalLink>

</relatedTopics>

</developerReferenceWithoutSyntaxDocument>

</topic>

SandcastleMAMLGuide

Sample

Thisdocumenttypeisusedforsampletopics.

SampleFileFormatBelowisanexampleofaSampletopicfile.

<developerSampleDocument

</summary>

</introduction>

CopySampleTopic

</content>

</section>

-Alocallink

-Anexternallink

</externalLink>

Examples:

</externalLink>

</relatedTopics>

</developerSampleDocument>

</topic>

SandcastleMAMLGuide

SDKTechnologyArchitecture

Thisdocumenttypeisusedfortechnologyarchitecturetopics.

SDKTechnologyArchitectureFileFormatBelowisanexampleofanSDKTechnologyArchitecturetopicfile.

<developerSDKTechnologyOverviewArchitectureDocument

</summary>

</introduction>

CopySDKTechnologyArchitectureTopic

</content>

</section>

-Alocallink

-Anexternallink

</externalLink>

Examples:

</externalLink>

</relatedTopics>

</developerSDKTechnologyOverviewArchitectureDocument

</topic>

SandcastleMAMLGuide

SDKTechnologyCodeDirectory

ThisdocumenttypeisusedforUIreferencetopics.

SDKTechnologyCodeDirectoryFileFormatBelowisanexampleofanSDKTechnologyCodeDirectorytopicfile.

<developerSDKTechnologyOverviewCodeDirectoryDocument

</summary>

</introduction>

<para>Codelistcontent</para>

</content>

</codeList>

CopySDKTechnologyCodeDirectoryTopic

-Alocallink

-Anexternallink

</externalLink>

Examples:

</externalLink>

</relatedTopics>

</developerSDKTechnologyOverviewCodeDirectoryDocument

</topic>

SandcastleMAMLGuide

SDKTechnologyOrientation

Thisdocumenttypeisusedfortechnologyorientationtopics.

SDKTechnologyOrientationFileFormatBelowisanexampleofanSDKTechnologyOrientationtopicfile.

<developerSDKTechnologyOverviewOrientationDocument

</summary>

</introduction>

<para>"InThisSection"info</para>

</content>

</inThisSection>

CopySDKTechnologyOrientationTopic

</developerSDKTechnologyOverviewOrientationDocument

</topic>

SandcastleMAMLGuide

SDKTechnologyScenarios

Thisdocumenttypeisusedfortechnologyscenariotopics.

SDKTechnologyScenariosFileFormatBelowisanexampleofanSDKTechnologyScenariostopicfile.

<developerSDKTechnologyOverviewScenariosDocument

</summary>

</introduction>

CopySDKTechnologyScenariosTopic

</content>

</section>

-Alocallink

-Anexternallink

</externalLink>

Examples:

</externalLink>

</relatedTopics>

</developerSDKTechnologyOverviewScenariosDocument

</topic>

SandcastleMAMLGuide

SDKTechnologySummary

Thisdocumenttypeisusedfortechnologysummarytopics.

SDKTechnologySummaryFileFormatBelowisanexampleofanSDKTechnologySummarytopicfile.

<developerSDKTechnologyOverviewTechnologySummaryDocument

</summary>

</introduction>

<para>Keywordcontent</para>

</content>

</keywords>

CopySDKTechnologySummaryTopic

<para>Namespacescontent</para>

</content>

</namespaces>

<para>Backgroundcontent</para>

</content>

</background>

<title>"Implementing[TechnologyName]Classes"title

<para>Implementationcontent</para>

</content>

</implementingTechnologyNameClasses>

<title>"[TechnologyName]ClassesataGlance"title

<para>AtaGlancecontent</para>

</content>

</technologyNameClassesAtAGlance>

-Alocallink

-Anexternallink

</externalLink>

Examples:

</externalLink>

</relatedTopics>

</developerSDKTechnologyOverviewTechnologySummaryDocument

</topic>

SandcastleMAMLGuide

Troubleshooting

Thisdocumenttypeisusedfortroubleshootingtopics.

TroubleshootingFileFormatBelowisanexampleofaTroubleshootingtopicfile.

<developerTroubleshootingDocument

</summary>

</introduction>

<!--Zeroormoresections.Thesearecollapsible.Ifusing

CopyTroubleshootingTopic

<autoOutline/>,addanaddressattributetoidentifyitandspecify

atitlesothatitcanbejumpedtowithahyperlink.-->

<para>Sectioncontent</para>

</content>

</section>

-Alocallink

-Anexternallink

</externalLink>

Examples:

</externalLink>

</relatedTopics>

</developerTroubleshootingDocument>

</topic>

SandcastleMAMLGuide

UserInterfaceReference

Thisdocumenttypeisusedforuserinterfacereferencetopics.

UserInterfaceReferenceFileFormatBelowisanexampleofaUserInterfaceReferencetopicfile.

<developerUIReferenceDocument

</summary>

</introduction>

CopyUserInterfaceReferenceTopic

<para>Tasklistcontent</para>

</content>

</taskList>

<!--Zeroormoresections.Thesearecollapsible.Ifusing

<autoOutline/>,addanaddressattributetoidentifyitandspecify

atitlesothatitcanbejumpedtowithahyperlink.-->

<para>Sectioncontent</para>

</content>

</section>

<para>UIelementlistcontent</para>

</content>

</uiElementList>

-Alocallink

-Anexternallink

</externalLink>

Examples:

</externalLink>

</relatedTopics>

</developerUIReferenceDocument>

</topic>

SandcastleMAMLGuide

Walkthrough

Thisdocumenttypeisusedforwalkthroughtopics.

WalkthroughFileFormatBelowisanexampleofaWalkthroughtopicfile.

<developerWalkthroughDocument

</summary>

</introduction>

CopyWalkthroughTopic

<title>Proceduretitle</title>

<step>

</content>

</step>

<step>

</content>

</step>

</steps>

</procedure>

<title>Procedure#2</title>

<step>

</content>

</step>

<step>

</content>

</step>

</steps>

</procedure>

</content>

</section>

<!--Optionalnextstepsinfo

<content><para>Nextstepsinfogoeshere</para></content>

</nextSteps>

-Alocallink

-Anexternallink

</externalLink>

Examples:

</externalLink>

</relatedTopics>

</developerWalkthroughDocument>

</topic>

SandcastleMAMLGuide

Whitepaper

Thisdocumenttypeisusedforwhitepapers.

WhitepaperFileFormatBelowisanexampleofaWhitepapertopicfile.

<developerWhitePaperDocument

</summary>

<para>Byline</para>

</byline>

<date>

</date>

<para>Summarycontent</para>

CopyWhitepaperTopic

</content>

</summarySection>

</introduction>

</content>

</section>

<para>Conclusioncontent</para>

</content>

</conclusion>

-Alocallink

-Anexternallink

</externalLink>

Examples:

</externalLink>

</relatedTopics>

</developerWhitePaperDocument>

</topic>

SandcastleMAMLGuide

XMLReference

ThisdocumenttypeisusedforXMLreferencetopics.

XMLReferenceFileFormatBelowisanexampleofanXMLReferencetopicfile.

<developerXmlReference

</summary>

</introduction>

<!--Optionalschemahierarchy

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

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

</schemaHierarchy>-->

CopyXMLReferenceTopic

<title>Syntaxsectiontitle</title>

<para>Syntaxcontent</para>

</content>

</section>

</sections>

<parameterReference>Parameterreference</parameterReference

</legacySyntax>

</syntaxSection>

<para>Attributesandelementssyntaxintroduction

<para>Attributessyntax</para>

</attributes>

<title>Syntaxtitle</title>

<table>

<entry>

<para>Attributeheader</para>

</entry>

</row>

</tableHeader>

<entry>

<para>Attributevalue</para>

</entry>

</row>

</table>

</attribute>

<para>Childelementsyntax</para>

</childElement>

<para>Parentelementsyntax</para>

</parentElement>

</attributesandElements>

-Alocallink

-Anexternallink

</externalLink>

Examples:

</externalLink>

</relatedTopics>

</developerXmlReference>

</topic>

SandcastleMAMLGuide

CompanionFile

Acompanionfileisusedduringthebuildprocesstoobtainthetopictitleandlinktextforaparticularconceptualtopic.Therewillbeonecompanionfileforeachconceptualcontenttopic.

IfusingabuildtoolsuchastheSandcastleHelpFileBuilder,thecompanionfilesarecreatedforyouautomaticallyaspartofthebuildprocessandyoudonotneedtomaintainthemyourself.

CompanionFileFormatBelowisanexampleofacompanionfile.

Thefileconsistsofarootmetadatanodethatcontainsonetopicnodewithanidattributethatreferstothetopic'sGUID.

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

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

<title>WelcometotheSandcastleMAMLGuide</title

<linkText>Welcomepage</linkText>

</topic>

</metadata>

CopyExampleCompanionFile

TheIDvaluemustbeintheformofaGloballyUniqueIdentifier(GUID).

SeeAlsoOtherResourcesConceptualContentFileTypeslink

SandcastleMAMLGuide

BlockElements

Thetopicsinthissectiondefinetheblockelementsthatcanbeusedinconceptualtopics.

BlockElementsSelectoneofthetopicsbelowtolearnmoreaboutaparticularblockelement.

codeReference

definitionTable,definedTerm,definition

introduction

list,listItem

relatedTopics

table,tableHeader,row,entry

SandcastleMAMLGuide

Thiselementcanbeusedtocreateanote-likesectionwithinaconceptualtopictodrawattentiontosomeimportantinformation.

UsageEntertheelementinthetopicandspecifythetypeofalertusingtheclassattribute.Thecontentofthealertelementisusuallyoneormoreparagraphsoftextdescribingtheimportantinformation.

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>

OtherResourcesBlockElements

SandcastleMAMLGuide

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

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

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

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

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"

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

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

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

VB.NETExample

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

PublicSubSomeMethod()

CopyCommentedRegionExamples

TheremoveRegionMarkersattributecanbeusedtospecify

'#Region"VB.NETSnippet"

DimxAsInteger

Forx=1To10

Console.WriteLine(x)

'#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>

<codetitle="Nestedcodeelementsexample"language

'...Somestuffhappenshere...

</code>

NestedCodeElementsExample

OtherResourcesBlockElementscodeInlinecodeEntityReferencecodeReference

SandcastleMAMLGuide

codeReference

AcodeReferenceelementisusedtoinsertacommonlyusedcodesnippetintoaconceptualtopic.Thecodesnippetsarestoredinanexternalfile.

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

UsageTouseacodereference,simplyinsertitsIDastheinnertextofacodeReferenceelementanywherewithinatopic.YoucancombinemultiplesnippetswithacommonexampleIDintoonecodereferencebyspecifyingtheirsampleIDsasacomma-separatedlistafterthehashcharacter.

ExampleThisexampleusesthesamplesfromtheexamplefileabove.Thefirstthreearetheindividualsnippets.Thelastonecombinesthe"createinstance"snippetsintooneexample.

Defineaclass

<codeReference>ClassDefinition#Define</codeReference

Createalocalinstance

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

SeeAlsoOtherResourcesBlockElementsCodeSnippetsFilecodecodeInlinecodeEntityReference

SandcastleMAMLGuide

definitionTable,definedTerm,definition

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

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

ThedefinedTermelementsupportsanaddressattributethatcanbeusedtolinktoaspecificdefinedtermfromanotherlocation.

Example

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

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

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>

<title>ExampleOutput</title>

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

sectionabove.</para>

</content>

</section>

SeeAlsoOtherResourcesBlockElementslink

SandcastleMAMLGuide

list,listItem

Thiselementdescribescontentthatshouldbedisplayedasalist.

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

bullet-Astandardbulletedlistofitems.

ordered-Anumberedlistofitems.

nobullet-Alistofitemswithnosymbolprecedingtheitems.

Theclassattributevalueiscase-sensitive.Unrecognizedvalueswilldefaulttothenobulletliststyle.

ThelistItemelementsupportsanaddressattributethatcanbeusedtolinktoaspecificlistitemfromanotherlocation.

Example

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

<listclass="bullet">

ExampleOutput

<listItem><para>Item4-Thishasannested

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

<listclass="ordered">

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

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

Item10

SeeAlsoOtherResources

BlockElementsdefinitionTable,definedTerm,definitiontable,tableHeader,row,entry

SandcastleMAMLGuide

Thiselementcanbeusedtocreateparagraphsinconceptualcontent.

UsageEntertheelementinthetopicandspecifytheparagraphtextastheinnertext.Makingtheelementself-closingoremptywillcausetheelementtobeignoredunlessitcreatesaninitialparagraphbreak.

Example

ExampleOutputParagraph1.

Paragraph2.

Self-closingandemptyparagraphsareignored.

Paragraph4.

SeeAlso

<para>Paragraph1.</para>

<para/>

<para>Self-closingandemptyparagraphsareignored.

OtherResourcesBlockElements

SandcastleMAMLGuide

Thiselementdescribesaquotation.

UsageEntertheelementinthetopicandspecifythequotationastheinnertext.

Example

ExampleOutputToquotetheschema:

Thequoteelementdescribesaquotation.

SeeAlsoOtherResourcesBlockElementsquoteInline

<para>Toquotetheschema:</para>

<quote>Thequoteelementdescribesaquotation.</quote

SandcastleMAMLGuide

relatedTopics

Thiselementisusedtodefinealistoflinkstoothertopicsthatmaybeofinteresttothereader.

UsageEntertheelementinthetopicandspecifyoneormorelocallinks,externallinks,orcodeentityreferences.

Intopicsinwhichthiselementappears,itisarequiredelement.However,ifthetopichasnolinksofinterest,youcanleaveitemptyandtherelatedtopicssectionwillnotbeincludedinthetopic.

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

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

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

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

Reference

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

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

OtherResources

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

Reference

Example

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

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

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>

SandcastleMAMLGuide

table,tableHeader,row,entry

Thiselementisusedtoarrangedatainatableformatwithrowsandcolumns.Anoptionaltitleandtableheadercanalsobeincluded.

UsageAtableconsistsofthefollowingelements:

Thisisthemainelement.Allothertableelementsarenestedwithinitandithasnoattributes.

Thisisanoptionalelement.Ifspecified,itdefinesatitlethatwillappearabovethetable.

tableHeader

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

Thiselementisusedtodefineeachrowinthetable.Atablemustcontainatleastonerow.Eachrowmustcontainoneormoreentryelementsthatdefinethecolumnsintherow.

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

Theentryelementsupportsanaddressattributethatcanbeusedtolinktoaspecificentryfromanother

location.

Torenderanemptycell,useanon-breakingspaceentity( ).

TherearenoprovisionsforspanningrowsorcolumnsasthereisinHTMLtables.Assuch,eachrowmustcontainthesamenumberofcolumns.However,youcannesttableswithinanentryelementwhichcanbeusedtoachieveasimilareffect.

Example

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

inthefirsttable.</para>

<table>

<title>ASimpleTablewithTitleandHeaders</title

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

</row>

</tableHeader>

</row>

<entryaddress="Row3Cell1"><para>Thisentryhasan

attributethatcanbeusedasalinktarget.</para>

</row>

</table>

<table>

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

</row>

</tableHeader>

<entry><mediaLink><image

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

</mediaLink></entry>

<entry>

<table>

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

Thiselementdescribesthenameofapartofadocument.

UsageEntertheelementinthetopicandspecifythetexttouseasthesection'stitle.

Example

ExampleOutputSeetheUsagesectionaboveforanexampleoftheoutput.

SeeAlsoOtherResourcesBlockElements

<title>Usage</title>

<para>Entertheelementinthetopicandspecifythetexttouseasthe

section'stitle.</para>

</content>

</section>

SandcastleMAMLGuide

CommonInlineElements

Thetopicsinthissectiondefinethecommoninlineelementsthatcanbeusedinconceptualtopics.

CommonInlineElementsSelectoneofthetopicsbelowtolearnmoreaboutaparticularinlineelement.

application

codeInline

command

computerOutputInline

database

environmentVariable

errorInline

fictitiousUri

foreignPhrase

hardware

legacyBold

legacyItalic

legacyUnderline

literal

localUri

newTerm

phrase

placeholder

quoteInline

replaceable

subscript

superscript

system

unmanagedCodeEntityReference

userInput

SandcastleMAMLGuide

application

ThiselementisusedtodescribethenameofanapplicationsuchasMicrosoftWindowsorNotepad.

UsageEntertheelementinthetopicandspecifytheapplicationnameastheinnertext.

Example

ExampleOutputUsetheSandcastleHelpFileBuildertocreatehelpfiles.

SeeAlsoOtherResourcesCommonInlineElements

Usethe<application>SandcastleHelpFileBuilder</

SandcastleMAMLGuide

codeInline

Thiselementdescribesastringofcodeorasinglekeyword.Formulti-linecodefragments,usethecodeelementinstead.

UsageEntertheelementinthetopicandspecifythecodeastheinnertext.

Example

ExampleOutputUseaforeachlooptoiterateoverthecollection.

SeeAlsoOtherResourcesCommonInlineElementscodecodeEntityReferencecodeReference

Usea<codeInline>foreach</codeInline>looptoiterateoverthecollection.

SandcastleMAMLGuide

command

Thiselementdescribesthenameofanexecutableorothersoftwareapplicationthancanberun.

UsageEntertheelementinthetopicandspecifytheapplicationnameastheinnertext.Thereplaceableelementcanbenestedwithinittorepresentreplaceableparameters.

Example

ExampleOutputXCOPY/s/esourceFileSpecdestFileSpec

SeeAlsoOtherResourcesCommonInlineElementsreplaceablesystem

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

<replaceable>destFileSpec</replaceable></command

SandcastleMAMLGuide

computerOutputInline

ThiselementdescribesoutputfromeitheraconsolepromptorfromaUIform.

UsageEntertheelementinthetopicandspecifytheoutputastheinnertext.

Example

ExampleOutputTheresultofrunningHelloWorld.exeis:HelloWorld!

Theresultofrunning<application>HelloWorld.exe</

<computerOutputInline>HelloWorld!</computerOutputInline

SandcastleMAMLGuide

database

Thiselementisusedtodescribeadatabase.

UsageEntertheelementinthetopicandspecifythedatabaseastheinnertext.

Example

ExampleOutputTheinformationisstoredintheContentdatabase.

Theinformationisstoredinthe<database>Content</

SandcastleMAMLGuide

environmentVariable

Thiselementdescribesanenvironmentvariableinanoperatingsystem.

UsageEntertheelementinthetopicandspecifytheenvironmentvariableastheinnertext.

Example

ExampleOutputTheSandcastletoolsfindtheirinstalledlocationusingtheSHFBROOTenvironmentvariable.

TheSandcastletoolsfindtheirinstalledlocationusingthe

<environmentVariable>SHFBROOT</environmentVariable>

SandcastleMAMLGuide

errorInline

Thiselementdescribesanerrororerrormessage.

UsageEntertheelementinthetopicandspecifytheerrorastheinnertext.

Example

ExampleOutputIfafiledoesnotexist,aFileNotFounderrorwilloccur.

Ifafiledoesnotexist,a<errorInline>FileNotFound

errorwilloccur.

SandcastleMAMLGuide

fictitiousUri

Thiselementdescribesafictitiousinternetaddresssuchasaweboremailaddress.

UsageEntertheelementinthetopicandspecifythefictitiousURIastheinnertext.

Example

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

Thee-mailaddress<fictitiousUri>jdoe@contoso.com</

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

SandcastleMAMLGuide

foreignPhrase

Thiselementisusedtodescribeaphrasethatisofalanguagethatisdifferentthantheprimarylanguageofthedocument.

UsageEntertheelementinthetopicandspecifythephraseastheinnertext.

Example

ExampleOutputIfitdoesn'tworkout,C'estlavie.

SeeAlsoOtherResourcesCommonInlineElementsphrasequoteInline

Ifitdoesn'tworkout,<foreignPhrase>C'estlavie

SandcastleMAMLGuide

hardware

Thiselementdescribesaphysicalpartofacomputersystem.

UsageEntertheelementinthetopicandspecifythehardwareastheinnertext.

Example

ExampleOutputPlugtheflashdriveintotheUSBport.

Plugthe<hardware>flashdrive</hardware>intothe

<hardware>USBport</hardware>.

SandcastleMAMLGuide

legacyBold

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

UsageEntertheelementinthetopicandspecifythetexttoboldastheinnertext.

Example

ExampleOutputThistextwillberenderedinbold.

Thistextwillberenderedin<legacyBold>bold</legacyBold

SandcastleMAMLGuide

legacyItalic

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

UsageEntertheelementinthetopicandspecifythetexttoitalicizeastheinnertext.

Example

ExampleOutputThistextwillberenderedasitalicized.

Thistextwillberenderedas<legacyItalic>italicized

SandcastleMAMLGuide

legacyUnderline

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

UsageEntertheelementinthetopicandspecifythetexttounderlineastheinnertext.

Example

ExampleOutputThistextwillberenderedwithanunderline.

Thistextwillberenderedwithan<legacyUnderline

SandcastleMAMLGuide

literal

Thiselementdescribesaliteralvalue.

UsageEntertheelementinthetopicandspecifytheliteralvalueastheinnertext.

Example

ExampleOutputIfthepropertyisnotused,setittothestringNone.

Ifthepropertyisnotused,setittothestring<

SandcastleMAMLGuide

localUri

Thiselementdescribesthepathtoalocalresourcesuchasafile.

UsageEntertheelementinthetopicandspecifythepathastheinnertext.

Example

ExampleOutputSandcastleisinstalledintheC:\ProgramFiles\Sandcastlefolderbydefault.

Sandcastleisinstalledinthe<localUri>C:\ProgramFiles\Sandcastle

folderbydefault.

SandcastleMAMLGuide

Thiselementcanbeusedtomarkmathematicalexpressions.

UsageEntertheelementinthetopicandspecifythemathematicalexpressionastheinnertext.

Example

ExampleOutputAsimplemathexpression:1+1=2.

SeeAlsoOtherResourcesCommonInlineElementssubscriptsuperscript

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

SandcastleMAMLGuide

newTerm

Thiselementisusedtointroducenewtermsortechnologies.

UsageEntertheelementinthetopicandspecifythenewtermastheinnertext.

Example

ExampleOutputTopicstocoverincludeLINQ,WPF,andWCF.

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

<newTerm>WCF</newTerm>.

SandcastleMAMLGuide

phrase

Thiselementisawrapperelementforarunoftext.Itissolelyacontaineranddoesnotspecifyanysemanticsonitsown.

UsageEntertheelementinthetopicandspecifythephraseastheinnertext.

Example

ExampleOutputIfitdoesn'tworkout,that'slife.

SeeAlsoOtherResourcesCommonInlineElementsforeignPhrasequoteInline

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

SandcastleMAMLGuide

placeholder

Thiselementisusedasaplaceholder.Bydefault,itrenderstextinastyledeterminedbythepresentationstyle.Itmayhavespecificuseincustombuildcomponents.

UsageEntertheelementinthetopic.It'sinnertextandtheendresultisimplementationdependent.

Example

ExampleOutputSomethingusefulcouldgohereifabuildcomponentmadeuseofit.

Somethingusefulcouldgo<placeholder>here</placeholder

buildcomponentmadeuseofit.

SandcastleMAMLGuide

quoteInline

Thiselementisusedtodescribeaninlinequotation.

UsageEntertheelementinthetopicandspecifythequotationastheinnertext.

Example

ExampleOutputThisisanexampleofan"inlinequotation".

SeeAlsoOtherResourcesCommonInlineElementsquote

Thisisanexampleofan<quoteInline>inlinequotation

SandcastleMAMLGuide

replaceable

Thiselementdescribesapartofacommandorafunctionthatmustbereplacedbytheuser.

UsageEntertheelementinthetopicandspecifythereplaceableitemastheinnertext.

Example

SeeAlsoOtherResourcesCommonInlineElementscommand

SandcastleMAMLGuide

subscript

Thiselementcanbeusedtomarkasubscriptsuchasthosefoundinmathematicalexpressions.

UsageEntertheelementinthetopicandspecifythesubscripttextastheinnertext.

Example

ExampleOutputThechemicalformulaforwaterisH2O.

SeeAlsoOtherResourcesCommonInlineElementsmath

Thechemicalformulaforwateris<math>H<subscript

SandcastleMAMLGuide

superscript

Thiselementcanbeusedtomarkasuperscriptsuchasthosefoundinmathematicalexpressions.

UsageEntertheelementinthetopicandspecifythesuperscripttextastheinnertext.

Example

ExampleOutputCanyouexplainE=MC2?

SeeAlsoOtherResourcesCommonInlineElementsmath

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

SandcastleMAMLGuide

system

Thiselementdescribessystemcommands,commandlineswitches,etc.

UsageEntertheelementinthetopicandspecifythecommandorswitchesastheinnertext.

Example

SeeAlsoOtherResourcesCommonInlineElementscommandreplaceable

SandcastleMAMLGuide

Thiselementdescribesauserinterfaceelement.

UsageEntertheelementinthetopicandspecifytheuserinterfaceitemastheinnertext.

Example

ExampleOutputClicktheOKbuttontoclosethedialogbox.

Clickthe<ui>OK</ui>buttontoclosethedialogbox.

SandcastleMAMLGuide

unmanagedCodeEntityReference

Thiselementisusedtorefertounmanagedcodeentityreferences.Unlikemanagedcodeentityreferences,thiselementdoesnotresultinalinktothereferenceditem.

UsageEntertheelementinthetopicandspecifytheentityastheinnertext.

Example

ExampleOutputYoucanusePInvoketocallSetWindowPlacement.

YoucanusePInvoketocall

<unmanagedCodeEntityReference>SetWindowPlacement</unmanagedCodeEntityReference

SandcastleMAMLGuide

userInput

Thiselementdescribesdatathatisenteredbytheuser.

UsageEntertheelementinthetopicandspecifytheinputastheinnertext.

Example

ExampleOutputEnterYesorNo.

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

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

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

</mediaLink>

<caption>CaptionBefore</caption>

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

</mediaLink>

ExampleOutput

CaptionBefore

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

MediaElementsMediaContentFilemediaLink

SandcastleMAMLGuide

LinkElements

Thetopicsinthissectiondefinethelinkelementsthatcanbeusedinconceptualtopics.

LinkElementsSelectoneofthetopicsbelowtolearnmoreaboutaparticularlinkelement.

codeEntityReference

externalLink

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>

Length

FileStream.FlushonMSDN

SeeAlsoOtherResourcesLinkElementscodecodeInlinecodeReference

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.

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

</externalLink>

IfthelinkcontainsXMLentities,theymustbeencoded(i.e.theampersand):

<linkText>MSDNDocumentationForum</linkText>

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

</externalLink>

SeeAlsoOtherResourcesLinkElementslink

SandcastleMAMLGuide

ThisisusedtoinsertalinktoanotherconceptualtopicusingitsIDvalue.Itcanalsobeusedtocreatelinkstoelementswithinthesamepagethathaveanaddressattributesuchastheintroductionandsectionelements.

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

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

WhenusedinarelatedTopicselement,anoptionaltopicType_idattributecanbeaddedthatspecifiesaGUIDvalueusedtoclassifythelinktypesothatitisgroupedwithothersimilarlinks.SeetherelatedTopicstopicformoreinformation.

Example

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

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

companionfile</link>

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

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

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

isincluded,thisparagraphcanbeomitted.

</para>

<!--NotethatplacingtheautoOutlineelementherewouldplace

thesectionoutlinebelowtheintroparagraph.-->

</introduction>

<sectionaddress="S1">

<title>Section1</title>

<para>Thisissection1.</para>

<!--Thiswillincludesub-sectionsintheoutlineuptothree

levelsdown.Italsousescustomlead-intext.-->

<autoOutlinelead="Selectasub-section:">3

</content>

<sectionaddress="SS1">

<para>Thisissub-section1.</para>

</content>

</section>

<sectionaddress="SS2">

<para>Thisissub-section2.</para>

</content>

<sectionaddress="SSS1">

ExampleOutputSeeautoOutlineRenderedExample

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

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

</content>

</section>

<sectionaddress="SSS2">

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

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

<para>

<linkxlink:href="#Intro">BacktotheTop

</para>

</content>

</section>

</sections>

</section>

</sections>

</section>

<sectionaddress="S2">

<title>Section2</title>

<para>Thisissection2.</para>

</content>

</section>

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

ItisrecommendedthatyouavoidusingthiselementunlessthereisnoMAMLequivalentforwhatyouaretryingtodo.Usageshouldberestrictedtotheoutputofcustombuildcomponentswhenneeded.

UsageEntertheelementinthetopicandspecifytheHTMLmarkupastheinnertext.Itcanbeusedasablockoraninlineelement.

Example

ExampleOutput

HereisapieceofliteralHTMLmarkup:

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

normalconceptualcontentwhenanequivalent<u>MAMLelement

Itsuseshouldberestrictedtocustombuildcomponents.

</markup>

HereisapieceofliteralHTMLmarkup:

ItisNOTrecommendedthatyouusethemarkupelementfornormalconceptualcontentwhenanequivalentMAMLelementalreadyexists.Itsuseshouldberestrictedtocustombuildcomponents.

SeeAlsoOtherResourcesMiscellaneousElements

SandcastleMAMLGuide

Atokenisusedasareplaceabletagwithinatopicandisrepresentedusingatokenelement.Theinnertextoftheelementisatokenname.Thetokensaredefinedinaseparatetokenfile.Theyareaneasywaytorepresentcommonitemsthatyouuseregularlysuchasacommonphraseorexternallink.

UsageTouseatoken,simplyinsertitsnameastheinnertextofatokenelementanywherewithinatopic.

ExampleInthisexample,"Sandcastle"isatokenthatexpandstoanexternallinktoawebsite.

ExampleOutputThislink(SandcastleHelpFileBuilder)isstoredinatoken.

SeeAlsoOtherResourcesMiscellaneousElementsTokenFile

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

SandcastleMAMLGuide

VisualStudioIntelliSense

ThistopiccovershowtointegrateMAMLschemafilesintoVisualStudio'sglobalschemacachetoprovideIntelliSensewheneditingMAMLtopicswithinVisualStudio.

TheguidedinstallerusedtoinstallSandcastleandtherelatedtoolsprovidesanoptiontoinstalltheMAMLschemasintheVisualStudioglobalschemacacheforyou.

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:

4. IntelliSenseshouldnowworkforallMAMLtopicsautomaticallyinVisualStudio.IfyouhadVisualStudioopenwhilemakingthechanges,youmayneedtorestartitinordertoseeIntelliSenseintheMAMLtopicfiles.

SeeAlsoOtherResourcesSchemaExtensibility

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

SandcastleMAMLGuide

SchemaExtensibility

ThistopicwillexplainhowyoucanchangetheMAMLschemasothatyoucanuseelementsfromothernamespacesaswell.ThisisusefulwhenextendingSandcastlewithbuildcomponentsthatprovidenewelementsbecauseitstillallowsyoutovalidateyourtopicfiles.

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"/>

paraelement.Examplesforsuchelementsare:

LinkingTheseareelementsthatallowyoutolinktoothertopics.MAMLitselfalreadyprovidesseveralelementsforthispurpose,suchasthelinkelementtolinktoconceptualtopics,thecodeEntityReferenceelementtolinktomanagedcodeAPIs,andtheexternalLinkelementtolinktosomelocationintheinternet.

SemanticsThiscategoryincludeselementsthatareusedtoassociatepiecesoftextwithsemantics.Inmanycasesthesesemanticsaremadevisiblethroughaconsistentformatting,suchasitalicsorboldtext.AmongstothersMAMLitselfprovidesthelocalUrielementformarkingtextasrepresentinglocalpathsandtheuielementformarkingtextasrepresentingelementsinyouruserinterface.

ToextendtheparaelementwewillextendtheunderlyingtypeinlineType.

Openthefileinline.xsd,gotoline60,andaddtheanyelementtothetype:

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

TheinlineTypecomplexTypedescribesasimpleinline-only

contentmodel.Itprovidesbothtextandelementswith

similarlysimplecontentmodels.

</documentation>

</annotation>

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

<groupref="maml:inlineGroup"/>

<elementref="maml:sharedContent"/>

<elementname="conditionalSection">

<elementref="maml:conditions"/>

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>

SeeAlsoOtherResourcesVisualStudioIntelliSense

<complexTypename="sectionContentType"mixed="false"

<groupref="maml:structureGroup"/>

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

</choice>

</complexType>

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

Microsoft.NETFrameworksandSDKs.

TheHTMLHelpWorkshopforbuildingHTMLHelp1.x(.CHM)helpfiles.

SeeAlsoOtherResourcesWelcome

SandcastleMAMLGuide

MakingaDonation

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

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

Thankstothoseofyouthathavemadeadonation.Itismuchappreciated!

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 Sandcastle MAML Guide. This is intended to be a reference that you can use to find out

Documents

Building a sandcastle 2

CSL–MAML-dependent Notch1 signaling controls T lineage ...

Morphology of the Adhesive System in the Sandcastle Worm...

For Grades: K-2Sandcastle+Draw.pdf · 3. Draw a rectangle.....

LDEQ Mobile Air Monitoring Lab (MAML) · In addition to...

The Mystery of the Sandcastle Stamper...

DASR 66 Military Aircraft Maintenance Licensing · • A...

Bioinspired Sandcastle Worm-Derived Peptide-Based Hybrid ...

CORONA DEL MAR SANDCASTLE CONTEST LIGHTING OF … ›...

Draw rectangle and square bubbles. triangle bubbles.Building...

10 Morphology of the Adhesive System in the Sandcastle Worm....

MAML Tutorial (MIUI Theme)

MAML (Metals Additive Manufacturing Lab) · 2021. 1. 1. ·...

Meta-Learning for User Cold-Start Recommendation · RS, by....

ROBUST MAML: PRIORITIZATION TASK BUFFER WITH ADAPTIVE...

THE BIGGEST SANDCASTLE COMPETITION IN NORTHERN...