View
33
Download
0
Category
Preview:
Citation preview
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.
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
SandcastleMAMLGuide
KnownIssuesandBugs
ThistopiccoversknownissuesandbugswithSandcastleandconceptualcontent.Currently,theVS2013presentationstyleisthebestchoiceforconceptualcontentasitcontainsnoknownissuesbeyondthosenotedintheGeneralIssuessection.
GeneralIssuesThesearethecurrentlyknownissueswithSandcastleingeneralwhenusedtoproduceconceptualcontentregardlessofpresentationstyle.
TheredoesnotappeartobeanyformattingforseveraloftheWhitepapertopicelements.
SeveralelementsoftheXMLReferencetopictypedonotrendercorrectlyifatall.
Sandcastle'sXSLtransformationsremoveinter-elementwhitespace.Assuch,ifyouplacetwoMAMLelementsoneaftertheotherandrequireaseparatingspacebetweenthem,useanon-breakingspaceentity( ).Seethereplaceabletopicforanexample.
SeeAlsoOtherResourcesWelcome
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
SandcastleMAMLGuide
ConceptualContentFileTypes
Thetopicsinthissectiondefinethevariousfiletypesusedtoproduceconceptualcontenthelpfiles.IfyouareusingatoolsuchastheSandcastleHelpFileBuilder,onlythetopicfileinformationwillbeofinteresttoyou.Theotherfiletypesareusedbythebuildprocessandmayonlybeofinterestifyouwanttoseehoweverythingfitstogetherandisusedtobuildthehelptopics.
ConceptualContentFileTypesSelectoneofthetopicsbelowtolearnmoreaboutaparticularfiletype.
CodeSnippetsFile
MediaContentFile
TokenFile
TopicFile
CompanionFile
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
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"?>
<!--Thisisanexamplecodesnippetsfile-->
<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">
<sampleCodelanguage="CSharp">
CSharpClassx=newCSharpClass();
</sampleCode>
<sampleCodelanguage="VisualBasic">
DimxAsVBClass=NewVBClass()
</sampleCode>
</item>
<itemid="CreateInstance#Static">
<sampleCodelanguage="CSharp">
publicstaticCSharpClasssharedInstance=newCSharpClass();
</sampleCode>
<sampleCodelanguage="VisualBasic">
PublicSharedsharedInstanceAsVBClass=NewVBClass()
</sampleCode>
</item>
</examples>
notcase-sensitive.TheexampleIDdoesnothavetobeunique.However,whencombinedwithasampleID,theentirevaluemustbeunique.
EachitemmustcontainoneormoresampleCodeelementswithalanguageattributeidentifyingthelanguageofthesamplecode.ThevalidlanguageIDsarenotedabove.TheinnerXMLofthesampleCodeelementisthecodesnippet.
SeeAlsoOtherResourcesConceptualContentFileTypescodeReference
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
SandcastleMAMLGuide
MediaContentFile
Themedia(images)usedbyconceptualcontentinahelpfileprojectaredefinedinaseparatemediacontentfile.EachisassignedauniqueIDthatisusedtorefertotheimageinconceptualtopiclinks.Whenahelpfileisbuilt,allimagesreferencedbyanimagelinkarecopiedtothehelpfile's.\Mediafolder.Anyunusedimagesareomitted.
Note
TheSandcastleHelpFileBuilderdoesnotuseamediacontentfiledirectly.Instead,imagesaremanagedasprojectfileitemsandthemediacontentfileiscreatedforyouautomaticallyatbuildtimebasedonthepropertyvaluesonthoseitems.
MediaContentFileFormatBelowisanexampleofamediacontentfile.
<?xmlversion="1.0"encoding="utf-8"?>
<!--Thisisanexamplemediacontentfile-->
<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>
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
SandcastleMAMLGuide
TokenFile
Atokenisusedasareplaceabletagwithinatopicandisrepresentedusingatokenelement.Theinnertextoftheelementisatokenname.Thetokensaredefinedinaseparatetokenfile.Theyareaneasywaytorepresentcommonitemsthatyouuseregularlysuchasacommonphraseorexternallink.
TokenFileFormatBelowisanexampleofatokenfile.
Thefileconsistsofarootcontentnodethatcontainsoneormoreitemnodes.Besuretoaddthexml:spaceattributetopreserve
<?xmlversion="1.0"encoding="utf-8"?>
<!--Thisisanexampletokensfile-->
<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
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
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.
<!--ThetopicelementcontainstheuniqueIDandrevisionnumber-->
<topicid="303c996a-2911-4c08-b492-6496c82b3edb"revisionNumber
<!--Thiselementnamewillchangebasedonthedocumenttype-->
<developerConceptualDocument
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
xmlns:xlink="http://www.w3.org/1999/xlink">
<!--Thecontentgoeshere-->
</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
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
SandcastleMAMLGuide
Conceptual
Thisdocumenttypeisusedforgeneralconceptualtopics.
ConceptualFileFormatBelowisanexampleofaConceptualtopicfile.
<?xmlversion="1.0"encoding="utf-8"?>
<topicid="00000000-0000-0000-0000-000000000000"revisionNumber
<developerConceptualDocument
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
xmlns:xlink="http://www.w3.org/1999/xlink">
<!--
<summary>
<para>Optionalsummaryabstract</para>
</summary>
-->
<introduction>
<!--Uncommentthistogenerateanoutlineofthesectionandsub-section
titles.Specifyanumericvalueastheinnertexttolimititto
aspecificnumberofsub-topicswhencreatingtheoutline.Specify
zero(0)tolimitittotop-levelsectionsonly.-->
<!--<autoOutline/>-->
<para>Requiredintroduction</para>
</introduction>
<!--Addoneormoretop-levelsectionelements.Thesearecollapsible.
CopyConceptualTopic
Ifusing<autoOutline/>,addanaddressattributetoidentifyit
andspecifyatitlesothatitcanbejumpedtowithahyperlink.-->
<sectionaddress="Section1">
<title>Optionalsectiontitle</title>
<content>
<!--Uncommentthistocreateasub-sectionoutline
<autoOutline/>-->
<para>Addoneormoresectionswithcontent
</content>
<!--Ifasectioncontainsasectionselement,itscontentcreates
sub-sections.Thesearenotcollapsible.
<sections>
<sectionaddress="SubSection1">
<title>Sub-section1</title>
<content>
<para>Sub-sectioncontent.</para>
</content>
</section>
<sectionaddress="SubSection2">
<title>Sub-section2</title>
<content>
<para>Sub-sectioncontent.</para>
</content>
</section>
</sections>-->
</section>
<relatedTopics>
<!--Oneormoreofthefollowing:
-Alocallink
-Anexternallink
-Acodeentityreference
<linkxlink:href="OtherTopic'sID"/>
<linkxlink:href="OtherTopic'sID">Linkinnertext</link>
<externalLink>
<linkText>Linktext</linkText>
<linkAlternateText>Optionalalternatelinktext</linkAlternateText>
SeeAlsoOtherResourcesTopicFile
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
<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>
</developerConceptualDocument>
</topic>
SandcastleMAMLGuide
ErrorMessage
Thisdocumenttypeisusedforerrormessagetopics.
ErrorMessageFileFormatBelowisanexampleofanErrorMessagetopicfile.
<?xmlversion="1.0"encoding="utf-8"?>
<topicid="00000000-0000-0000-0000-000000000000"revisionNumber
<developerErrorMessageDocument
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
xmlns:xlink="http://www.w3.org/1999/xlink">
<!--<nonLocErrorTitle>Optionalnon-localizableerrortitle</nonLocErrorTitle>-->
<!--<secondaryErrorTitle>Optionallocalizablesecondaryerrortitle</secondaryErrorTitle>-->
<!--
<summary>
<para>Optionalsummaryabstract</para>
</summary>
-->
<introduction>
<para>Requiredintroduction</para>
</introduction>
<!--<procedure>Optional.Zeroormoreprocedures.</procedure>-->
<!--<codeExample>Optionalcodeexample.</codeExample>-->
<relatedTopics>
CopyErrorMessageTopic
SeeAlso
<!--Oneormoreofthefollowing:
-Alocallink
-Anexternallink
-Acodeentityreference
<linkxlink:href="OtherTopic'sID">Linktext</link>
<externalLink>
<linkText>Linktext</linkText>
<linkAlternateText>Optionalalternatelinktext</linkAlternateText>
<linkUri>URI</linkUri>
</externalLink>
<codeEntityReference>APImemberID</codeEntityReference>
Examples:
<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>
</developerErrorMessageDocument>
</topic>
OtherResourcesTopicFile
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
SandcastleMAMLGuide
Glossary
Thisdocumenttypeisusedtocreateaglossary.
GlossaryFileFormatBelowisanexampleofaGlossarytopicfile.
<?xmlversion="1.0"encoding="utf-8"?>
<topicid="00000000-0000-0000-0000-000000000000"revisionNumber
<developerGlossaryDocument
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
xmlns:xlink="http://www.w3.org/1999/xlink">
<glossary>
<!--<title>Optionaltitle</title>-->
<!--Glossarydivision.Youcanusethesetogroupentries.Ifyouonly
haveonegroup,youcanomititandlisttheglossaryEntryelements
directly.
Ifused,besuretogiveeachglossaryDivauniqueaddressattribute
andatitleelement.Thesewillbeusedtocreateanindexatthe
topoftheglossarypage.
Glossarydivisionswillappearintheorderdefinedinthetopic.
Glossaryentrieswillbesortedbythefirsttermfortheentry.
Termsaresortedbytheirvalue.-->
<glossaryDivaddress="Group1">
<title>Group#1</title>
CopyGlossaryTopic
SeeAlsoOtherResourcesTopicFile
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
<glossaryEntry>
<terms>
<!--Oneormoretermsassociatedwiththedefinition.AddatermId
attributeifyouneedtolinktoitfromarelatedEntryelement.
Otherwise,itcanbeomitted.Termsappearasacomma-separated
listabovethedefinition.-->
<termtermId="xyz">1stterm</term>
<term>Otherterm(ifany)</term>
</terms>
<definition>
<para>Thedefinitionoftheterm(s)</para
</definition>
<!--Oneormoreoptionalrelatedentries.Createsa"SeeAlso"
lineafterthedefinitionwithlinkstoeachrelatedterm.-->
<!--<relatedEntrytermId="xyz"/>-->
</glossaryEntry>
</glossaryDiv>
</glossary>
</developerGlossaryDocument>
</topic>
SandcastleMAMLGuide
How-To
Thisdocumenttypeisusedfor"howto"topics.
How-ToFileFormatBelowisanexampleofaHow-Totopicfile.
<?xmlversion="1.0"encoding="utf-8"?>
<topicid="00000000-0000-0000-0000-000000000000"revisionNumber
<developerHowToDocument
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
xmlns:xlink="http://www.w3.org/1999/xlink">
<!--
<summary>
<para>Optionalsummaryabstract</para>
</summary>
-->
<introduction>
<para>Requiredintroduction</para>
</introduction>
<!--Optionalproceduresfollowedbyoptionalcodeexamplebutmusthave
atleastoneprocedureorcodeexample-->
<procedure>
<title>Proceduretitle</title>
<stepsclass="ordered">
<step>
<content>
CopyHow-ToTopic
<para>Firststep</para>
</content>
</step>
<step>
<content>
<para>Secondstep</para>
</content>
</step>
</steps>
<!--<conclusion>Optionalconclusion</conclusion>-->
</procedure>
<!--<codeExample>Optionalcodeexample</codeExample>-->
<!--<buildInstructions>Optionalinstructionsforbuildinga
codeexample.</buildInstructions>-->
<!--<robustProgramming>Optionaldiscussionoferrorhandlingandother
issuesrelatedtowritingsolidcode.</robustProgramming>-->
<!--<security>Optionaldiscussionofsecurityissues.</security>-->
<relatedTopics>
<!--Oneormoreofthefollowing:
-Alocallink
-Anexternallink
-Acodeentityreference
<linkxlink:href="OtherTopic'sID">Linktext</link>
<externalLink>
<linkText>Linktext</linkText>
<linkAlternateText>Optionalalternatelinktext</linkAlternateText>
<linkUri>URI</linkUri>
</externalLink>
<codeEntityReference>APImemberID</codeEntityReference>
Examples:
<linkxlink:href="00e97994-e9e6-46e0-b420-5be86b2f8278">Someothertopic</link>
SeeAlsoOtherResourcesTopicFile
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
<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>
</developerHowToDocument>
</topic>
SandcastleMAMLGuide
Orientation
Thisdocumenttypeisusedfororientationtopics.
OrientationFileFormatBelowisanexampleofanOrientationtopicfile.
<?xmlversion="1.0"encoding="utf-8"?>
<topicid="00000000-0000-0000-0000-000000000000"revisionNumber
<developerOrientationDocument
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
xmlns:xlink="http://www.w3.org/1999/xlink">
<!--
<summary>
<para>Optionalsummaryabstract</para>
</summary>
-->
<introduction>
<para>Requiredintroduction</para>
</introduction>
<!--<inThisSection>Optionaldescriptionofcontentinthissection</inThisSection>-->
<!--<reference>Optionalreferencesection</reference>-->
<!--<relatedSections>Optionalrelatedsectionsinfo</relatedSections>-->
<!--<externalResources>Optionalexternalresourcessection</externalResources>-->
CopyOrientationTopic
<relatedTopics>
<!--Oneormoreofthefollowing:
-Alocallink
-Anexternallink
-Acodeentityreference
<linkxlink:href="OtherTopic'sID">Linktext</link>
<externalLink>
<linkText>Linktext</linkText>
<linkAlternateText>Optionalalternatelinktext</linkAlternateText>
<linkUri>URI</linkUri>
</externalLink>
<codeEntityReference>APImemberID</codeEntityReference>
Examples:
<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>
</developerOrientationDocument>
</topic>
SeeAlsoOtherResourcesTopicFile
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
SandcastleMAMLGuide
Reference
Thisdocumenttypeisusedforreferencetopics.
ReferenceFileFormatBelowisanexampleofaReferencetopicfile.
SeeAlso
<?xmlversion="1.0"encoding="utf-8"?>
<topicid="00000000-0000-0000-0000-000000000000"revisionNumber
<codeEntityDocument
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
xmlns:xlink="http://www.w3.org/1999/xlink">
<!--NOTE:ThisissimilartotheAPIreferencedocumentationwhichis
producedbythereferencebuild.Youshouldprobablyjustusethat
insteadofthis.-->
<assembly>
<assemblyName>Assemblyname</assemblyName>
</assembly>
<codeEntities>
<codeEntity>
<codeEntityReference>APImemberID</codeEntityReference
</codeEntity>
</codeEntities>
</codeEntityDocument>
</topic>
CopyReferenceTopic
OtherResourcesTopicFile
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
SandcastleMAMLGuide
ReferenceWithSyntax
Thisdocumenttypeisusedforreferencewithsyntaxtopics.
ReferenceWithSyntaxFileFormatBelowisanexampleofaReferenceWithSyntaxtopicfile.
<?xmlversion="1.0"encoding="utf-8"?>
<topicid="00000000-0000-0000-0000-000000000000"revisionNumber
<developerReferenceWithSyntaxDocument
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
xmlns:xlink="http://www.w3.org/1999/xlink">
<!--
<summary>
<para>Optionalsummaryabstract</para>
</summary>
-->
<!--NOTE:ThisissimilartotheAPIreferencedocumentationwhichis
producedbythereferencebuild.Youshouldprobablyjustusethat
insteadofthis.-->
<introduction>
<!--Uncommentthistogenerateanoutlineofthesectionandsub-section
titles.Specifyanumericvalueastheinnertexttolimititto
aspecificnumberofsub-topicswhencreatingtheoutline.Specify
zero(0)tolimitittotop-levelsectionsonly.-->
<!--<autoOutline/>-->
<para>Requiredintroduction</para>
CopyReferenceWithSyntaxTopic
</introduction>
<syntaxSection>
<sections>
<section>
<title>Syntaxsectiontitle</title>
<content>
<para>Syntaxcontent</para>
</content>
</section>
</sections>
<legacySyntax>
<parameterReference>Parameterreference</parameterReference
</legacySyntax>
</syntaxSection>
<!--<parameters>Optionalparametersinfo</parameters>-->
<!--<returnValue>Optionalreturnvalueinfo</returnValue>-->
<!--<exceptions>Optionalexceptioninfo</exceptions>-->
<!--<languageReferenceRemarks>Optionallanguagereferenceremarks</languageReferenceRemarks>-->
<!--<codeExample>Optionalcodeexample</codeExample>-->
<!--<dotNetFrameworkEquivalent>Optional.NETFrameworkequivalentinfo</dotNetFrameworkEquivalent>-->
<!--<requirements>Optionalrequirementsinfo</requirements>-->
<!--Addoneormoretop-levelsectionelements.Thesearecollapsible.
Ifusing<autoOutline/>,addanaddressattributetoidentify
itsothatitcanbejumpedtowithahyperlink.-->
<sectionaddress="Section1">
<title>Optionalsectiontitle</title>
<content>
<!--Uncommentthistocreateasub-sectionoutline
<autoOutline/>-->
<para>Addoneormoresectionswithcontent
</content>
</section>
<relatedTopics>
<!--Oneormoreofthefollowing:
-Alocallink
SeeAlsoOtherResourcesTopicFile
-Anexternallink
-Acodeentityreference
<linkxlink:href="OtherTopic'sID">Linktext</link>
<externalLink>
<linkText>Linktext</linkText>
<linkAlternateText>Optionalalternatelinktext</linkAlternateText>
<linkUri>URI</linkUri>
</externalLink>
<codeEntityReference>APImemberID</codeEntityReference>
Examples:
<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>
</developerReferenceWithSyntaxDocument>
</topic>
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
SandcastleMAMLGuide
ReferenceWithoutSyntax
Thisdocumenttypeisusedforreferencewithoutsyntaxtopics.
ReferenceWithoutSyntaxFileFormatBelowisanexampleofaReferenceWithoutSyntaxtopicfile.
<?xmlversion="1.0"encoding="utf-8"?>
<topicid="00000000-0000-0000-0000-000000000000"revisionNumber
<developerReferenceWithoutSyntaxDocument
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
xmlns:xlink="http://www.w3.org/1999/xlink">
<!--
<summary>
<para>Optionalsummaryabstract</para>
</summary>
-->
<!--NOTE:ThisissimilartotheAPIreferencedocumentationwhichis
producedbythereferencebuild.Youshouldprobablyjustusethat
insteadofthis.-->
<introduction>
<!--Uncommentthistogenerateanoutlineofthesectionandsub-section
titles.Specifyanumericvalueastheinnertexttolimititto
aspecificnumberofsub-topicswhencreatingtheoutline.Specify
zero(0)tolimitittotop-levelsectionsonly.-->
<!--<autoOutline/>-->
<para>Requiredintroduction</para>
CopyReferenceWithoutSyntaxTopic
</introduction>
<!--Addoneormoretop-levelsectionelements.Thesearecollapsible.
Ifusing<autoOutline/>,addanaddressattributetoidentifyit
andspecifyatitlesothatitcanbejumpedtowithahyperlink.-->
<sectionaddress="Section1">
<title>Optionalsectiontitle</title>
<content>
<!--Uncommentthistocreateasub-sectionoutline
<autoOutline/>-->
<para>Addoneormoresectionswithcontent
</content>
</section>
<!--<languageReferenceRemarks>Optionalreferenceremarks</languageReferenceRemarks>-->
<!--<codeExample>Optionalcodeexample</codeExample>-->
<relatedTopics>
<!--Oneormoreofthefollowing:
-Alocallink
-Anexternallink
-Acodeentityreference
<linkxlink:href="OtherTopic'sID">Linktext</link>
<externalLink>
<linkText>Linktext</linkText>
<linkAlternateText>Optionalalternatelinktext</linkAlternateText>
<linkUri>URI</linkUri>
</externalLink>
<codeEntityReference>APImemberID</codeEntityReference>
Examples:
<linkxlink:href="00e97994-e9e6-46e0-b420-5be86b2f8278">Someothertopic</link>
<externalLink>
<linkText>SandcastleHelpFileBuilderonGitHub</linkText>
<linkAlternateText>GotoGitHub</linkAlternateText>
<linkUri>https://GitHub.com/EWSoftware/SHFB</linkUri>
SeeAlsoOtherResourcesTopicFile
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
</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>
</developerReferenceWithoutSyntaxDocument>
</topic>
SandcastleMAMLGuide
Sample
Thisdocumenttypeisusedforsampletopics.
SampleFileFormatBelowisanexampleofaSampletopicfile.
<?xmlversion="1.0"encoding="utf-8"?>
<topicid="00000000-0000-0000-0000-000000000000"revisionNumber
<developerSampleDocument
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
xmlns:xlink="http://www.w3.org/1999/xlink">
<!--
<summary>
<para>Optionalsummaryabstract</para>
</summary>
-->
<introduction>
<!--Uncommentthistogenerateanoutlineofthesectionandsub-section
titles.Specifyanumericvalueastheinnertexttolimititto
aspecificnumberofsub-topicswhencreatingtheoutline.Specify
zero(0)tolimitittotop-levelsectionsonly.-->
<!--<autoOutline/>-->
<para>Requiredintroduction</para>
</introduction>
<!--<procedure>Optionalprocedures.SeeHowTodocumentforprocedurelayoutexample.</procedure>-->
CopySampleTopic
<!--<requirements>Optionalrequirementssection</requirements>-->
<!--<demonstrates>Optionalinfoaboutwhatisdemonstrated</demonstrates>-->
<!--<codeExample>Optionalcodeexample</codeExample>-->
<!--Addoneormoretop-levelsectionelements.Thesearecollapsible.
Ifusing<autoOutline/>,addanaddressattributetoidentifyit
andspecifyatitlesothatitcanbejumpedtowithahyperlink.-->
<sectionaddress="Section1">
<title>Optionalsectiontitle</title>
<content>
<!--Uncommentthistocreateasub-sectionoutline
<autoOutline/>-->
<para>Addoneormoresectionswithcontent
</content>
</section>
<relatedTopics>
<!--Oneormoreofthefollowing:
-Alocallink
-Anexternallink
-Acodeentityreference
<linkxlink:href="OtherTopic'sID">Linktext</link>
<externalLink>
<linkText>Linktext</linkText>
<linkAlternateText>Optionalalternatelinktext</linkAlternateText>
<linkUri>URI</linkUri>
</externalLink>
<codeEntityReference>APImemberID</codeEntityReference>
Examples:
<linkxlink:href="00e97994-e9e6-46e0-b420-5be86b2f8278">Someothertopic</link>
<externalLink>
<linkText>SandcastleHelpFileBuilderonGitHub</linkText>
<linkAlternateText>GotoGitHub</linkAlternateText>
<linkUri>https://GitHub.com/EWSoftware/SHFB</linkUri>
</externalLink>
SeeAlsoOtherResourcesTopicFile
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
<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>
</developerSampleDocument>
</topic>
SandcastleMAMLGuide
SDKTechnologyArchitecture
Thisdocumenttypeisusedfortechnologyarchitecturetopics.
SDKTechnologyArchitectureFileFormatBelowisanexampleofanSDKTechnologyArchitecturetopicfile.
<?xmlversion="1.0"encoding="utf-8"?>
<topicid="00000000-0000-0000-0000-000000000000"revisionNumber
<developerSDKTechnologyOverviewArchitectureDocument
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
xmlns:xlink="http://www.w3.org/1999/xlink">
<!--
<summary>
<para>Optionalsummaryabstract</para>
</summary>
-->
<introduction>
<!--Uncommentthistogenerateanoutlineofthesectionandsub-section
titles.Specifyanumericvalueastheinnertexttolimititto
aspecificnumberofsub-topicswhencreatingtheoutline.Specify
zero(0)tolimitittotop-levelsectionsonly.-->
<!--<autoOutline/>-->
<para>Requiredintroduction</para>
</introduction>
<!--Addoneormoretop-levelsectionelements.Thesearecollapsible.
CopySDKTechnologyArchitectureTopic
Ifusing<autoOutline/>,addanaddressattributetoidentifyit
andspecifyatitlesothatitcanbejumpedtowithahyperlink.-->
<sectionaddress="Section1">
<title>Optionalsectiontitle</title>
<content>
<!--Uncommentthistocreateasub-sectionoutline
<autoOutline/>-->
<para>Addoneormoresectionswithcontent
</content>
</section>
<relatedTopics>
<!--Oneormoreofthefollowing:
-Alocallink
-Anexternallink
-Acodeentityreference
<linkxlink:href="OtherTopic'sID">Linktext</link>
<externalLink>
<linkText>Linktext</linkText>
<linkAlternateText>Optionalalternatelinktext</linkAlternateText>
<linkUri>URI</linkUri>
</externalLink>
<codeEntityReference>APImemberID</codeEntityReference>
Examples:
<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>
SeeAlsoOtherResourcesTopicFile
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
<codeEntityReference>M:TestDoc.TestClass.ToString</codeEntityReference>
<codeEntityReference>M:TestDoc.TestClass.FirstMethod</codeEntityReference>
<codeEntityReference>M:TestDoc.TestClass.SecondMethod(System.Int32,System.String)</codeEntityReference>
-->
</relatedTopics>
</developerSDKTechnologyOverviewArchitectureDocument
</topic>
SandcastleMAMLGuide
SDKTechnologyCodeDirectory
ThisdocumenttypeisusedforUIreferencetopics.
SDKTechnologyCodeDirectoryFileFormatBelowisanexampleofanSDKTechnologyCodeDirectorytopicfile.
<?xmlversion="1.0"encoding="utf-8"?>
<topicid="00000000-0000-0000-0000-000000000000"revisionNumber
<developerSDKTechnologyOverviewCodeDirectoryDocument
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
xmlns:xlink="http://www.w3.org/1999/xlink">
<!--
<summary>
<para>Optionalsummaryabstract</para>
</summary>
-->
<introduction>
<para>Requiredintroduction</para>
</introduction>
<codeList>
<content>
<para>Codelistcontent</para>
</content>
</codeList>
CopySDKTechnologyCodeDirectoryTopic
<relatedTopics>
<!--Oneormoreofthefollowing:
-Alocallink
-Anexternallink
-Acodeentityreference
<linkxlink:href="OtherTopic'sID">Linktext</link>
<externalLink>
<linkText>Linktext</linkText>
<linkAlternateText>Optionalalternatelinktext</linkAlternateText>
<linkUri>URI</linkUri>
</externalLink>
<codeEntityReference>APImemberID</codeEntityReference>
Examples:
<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>
</developerSDKTechnologyOverviewCodeDirectoryDocument
</topic>
SeeAlsoOtherResourcesTopicFile
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
SandcastleMAMLGuide
SDKTechnologyOrientation
Thisdocumenttypeisusedfortechnologyorientationtopics.
SDKTechnologyOrientationFileFormatBelowisanexampleofanSDKTechnologyOrientationtopicfile.
<?xmlversion="1.0"encoding="utf-8"?>
<topicid="00000000-0000-0000-0000-000000000000"revisionNumber
<developerSDKTechnologyOverviewOrientationDocument
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
xmlns:xlink="http://www.w3.org/1999/xlink">
<!--
<summary>
<para>Optionalsummaryabstract</para>
</summary>
-->
<introduction>
<para>Requiredintroduction</para>
</introduction>
<inThisSection>
<content>
<para>"InThisSection"info</para>
</content>
</inThisSection>
<!--<reference>Optionalreferenceinfo</reference>-->
CopySDKTechnologyOrientationTopic
SeeAlsoOtherResourcesTopicFile
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
<!--<relatedSections>Optionalrelatedsectionsinfo</relatedSections>-->
<!--<externalResources>Optionalexternalresourcesinfo</externalResources>-->
</developerSDKTechnologyOverviewOrientationDocument
</topic>
SandcastleMAMLGuide
SDKTechnologyScenarios
Thisdocumenttypeisusedfortechnologyscenariotopics.
SDKTechnologyScenariosFileFormatBelowisanexampleofanSDKTechnologyScenariostopicfile.
<?xmlversion="1.0"encoding="utf-8"?>
<topicid="00000000-0000-0000-0000-000000000000"revisionNumber
<developerSDKTechnologyOverviewScenariosDocument
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
xmlns:xlink="http://www.w3.org/1999/xlink">
<!--
<summary>
<para>Optionalsummaryabstract</para>
</summary>
-->
<introduction>
<!--Uncommentthistogenerateanoutlineofthesectionandsub-section
titles.Specifyanumericvalueastheinnertexttolimititto
aspecificnumberofsub-topicswhencreatingtheoutline.Specify
zero(0)tolimitittotop-levelsectionsonly.-->
<!--<autoOutline/>-->
<para>Requiredintroduction</para>
</introduction>
<!--Addoneormoretop-levelsectionelements.Thesearecollapsible.
CopySDKTechnologyScenariosTopic
Ifusing<autoOutline/>,addanaddressattributetoidentifyit
andspecifyatitlesothatitcanbejumpedtowithahyperlink.-->
<sectionaddress="Section1">
<title>Optionalsectiontitle</title>
<content>
<!--Uncommentthistocreateasub-sectionoutline
<autoOutline/>-->
<para>Addoneormoresectionswithcontent
</content>
</section>
<relatedTopics>
<!--Oneormoreofthefollowing:
-Alocallink
-Anexternallink
-Acodeentityreference
<linkxlink:href="OtherTopic'sID">Linktext</link>
<externalLink>
<linkText>Linktext</linkText>
<linkAlternateText>Optionalalternatelinktext</linkAlternateText>
<linkUri>URI</linkUri>
</externalLink>
<codeEntityReference>APImemberID</codeEntityReference>
Examples:
<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>
SeeAlsoOtherResourcesTopicFile
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
<codeEntityReference>M:TestDoc.TestClass.ToString</codeEntityReference>
<codeEntityReference>M:TestDoc.TestClass.FirstMethod</codeEntityReference>
<codeEntityReference>M:TestDoc.TestClass.SecondMethod(System.Int32,System.String)</codeEntityReference>
-->
</relatedTopics>
</developerSDKTechnologyOverviewScenariosDocument
</topic>
SandcastleMAMLGuide
SDKTechnologySummary
Thisdocumenttypeisusedfortechnologysummarytopics.
SDKTechnologySummaryFileFormatBelowisanexampleofanSDKTechnologySummarytopicfile.
<?xmlversion="1.0"encoding="utf-8"?>
<topicid="00000000-0000-0000-0000-000000000000"revisionNumber
<developerSDKTechnologyOverviewTechnologySummaryDocument
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
xmlns:xlink="http://www.w3.org/1999/xlink">
<!--
<summary>
<para>Optionalsummaryabstract</para>
</summary>
-->
<introduction>
<para>Requiredintroduction</para>
</introduction>
<keywords>
<content>
<para>Keywordcontent</para>
</content>
</keywords>
<namespaces>
CopySDKTechnologySummaryTopic
<content>
<para>Namespacescontent</para>
</content>
</namespaces>
<!--<relatedTechnologies>Optionalrelatedtechnologiesinfo</relatedTechnologies>-->
<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>
<!--<whatsNew>Optional"what'snew"information</whatsNew>-->
<relatedTopics>
<!--Oneormoreofthefollowing:
-Alocallink
-Anexternallink
-Acodeentityreference
<linkxlink:href="OtherTopic'sID">Linktext</link>
<externalLink>
<linkText>Linktext</linkText>
<linkAlternateText>Optionalalternatelinktext</linkAlternateText>
SeeAlsoOtherResourcesTopicFile
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
<linkUri>URI</linkUri>
</externalLink>
<codeEntityReference>APImemberID</codeEntityReference>
Examples:
<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>
</developerSDKTechnologyOverviewTechnologySummaryDocument
</topic>
SandcastleMAMLGuide
Troubleshooting
Thisdocumenttypeisusedfortroubleshootingtopics.
TroubleshootingFileFormatBelowisanexampleofaTroubleshootingtopicfile.
<?xmlversion="1.0"encoding="utf-8"?>
<topicid="00000000-0000-0000-0000-000000000000"revisionNumber
<developerTroubleshootingDocument
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
xmlns:xlink="http://www.w3.org/1999/xlink">
<!--
<summary>
<para>Optionalsummaryabstract</para>
</summary>
-->
<introduction>
<!--Uncommentthistogenerateanoutlineofthesectionandsub-section
titles.Specifyanumericvalueastheinnertexttolimititto
aspecificnumberofsub-topicswhencreatingtheoutline.Specify
zero(0)tolimitittotop-levelsectionsonly.-->
<!--<autoOutline/>-->
<para>Requiredintroduction</para>
</introduction>
<!--Zeroormoresections.Thesearecollapsible.Ifusing
CopyTroubleshootingTopic
<autoOutline/>,addanaddressattributetoidentifyitandspecify
atitlesothatitcanbejumpedtowithahyperlink.-->
<sectionaddress="Section1">
<title>Optionalsectiontitle</title>
<content>
<!--Uncommentthistocreateasub-sectionoutline
<autoOutline/>-->
<para>Sectioncontent</para>
<!--<procedure>Optionalprocedures.SeeHowTodocumentforprocedurelayoutexample.</procedure>-->
</content>
</section>
<relatedTopics>
<!--Oneormoreofthefollowing:
-Alocallink
-Anexternallink
-Acodeentityreference
<linkxlink:href="OtherTopic'sID">Linktext</link>
<externalLink>
<linkText>Linktext</linkText>
<linkAlternateText>Optionalalternatelinktext</linkAlternateText>
<linkUri>URI</linkUri>
</externalLink>
<codeEntityReference>APImemberID</codeEntityReference>
Examples:
<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>
SeeAlsoOtherResourcesTopicFile
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
<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>
</developerTroubleshootingDocument>
</topic>
SandcastleMAMLGuide
UserInterfaceReference
Thisdocumenttypeisusedforuserinterfacereferencetopics.
UserInterfaceReferenceFileFormatBelowisanexampleofaUserInterfaceReferencetopicfile.
<?xmlversion="1.0"encoding="utf-8"?>
<topicid="00000000-0000-0000-0000-000000000000"revisionNumber
<developerUIReferenceDocument
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
xmlns:xlink="http://www.w3.org/1999/xlink">
<!--
<summary>
<para>Optionalsummaryabstract</para>
</summary>
-->
<introduction>
<!--Uncommentthistogenerateanoutlineofthesectionandsub-section
titles.Specifyanumericvalueastheinnertexttolimititto
aspecificnumberofsub-topicswhencreatingtheoutline.Specify
zero(0)tolimitittotop-levelsectionsonly.-->
<!--<autoOutline/>-->
<para>Requiredintroduction</para>
</introduction>
<taskList>
CopyUserInterfaceReferenceTopic
<content>
<para>Tasklistcontent</para>
</content>
</taskList>
<!--Zeroormoresections.Thesearecollapsible.Ifusing
<autoOutline/>,addanaddressattributetoidentifyitandspecify
atitlesothatitcanbejumpedtowithahyperlink.-->
<sectionaddress="Section1">
<title>Optionalsectiontitle</title>
<content>
<!--Uncommentthistocreateasub-sectionoutline
<autoOutline/>-->
<para>Sectioncontent</para>
</content>
</section>
<uiElementList>
<content>
<para>UIelementlistcontent</para>
</content>
</uiElementList>
<relatedTopics>
<!--Oneormoreofthefollowing:
-Alocallink
-Anexternallink
-Acodeentityreference
<linkxlink:href="OtherTopic'sID">Linktext</link>
<externalLink>
<linkText>Linktext</linkText>
<linkAlternateText>Optionalalternatelinktext</linkAlternateText>
<linkUri>URI</linkUri>
</externalLink>
<codeEntityReference>APImemberID</codeEntityReference>
Examples:
SeeAlsoOtherResourcesTopicFile
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
<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>
</developerUIReferenceDocument>
</topic>
SandcastleMAMLGuide
Walkthrough
Thisdocumenttypeisusedforwalkthroughtopics.
WalkthroughFileFormatBelowisanexampleofaWalkthroughtopicfile.
<?xmlversion="1.0"encoding="utf-8"?>
<topicid="00000000-0000-0000-0000-000000000000"revisionNumber
<developerWalkthroughDocument
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
xmlns:xlink="http://www.w3.org/1999/xlink">
<!--
<summary>
<para>Optionalsummaryabstract</para>
</summary>
-->
<introduction>
<!--Uncommentthistogenerateanoutlineofthesectionandsub-section
titles.Specifyanumericvalueastheinnertexttolimititto
aspecificnumberofsub-topicswhencreatingtheoutline.Specify
zero(0)tolimitittotop-levelsectionsonly.-->
<!--<autoOutline/>-->
<para>Requiredintroduction</para>
</introduction>
<!--<prerequisites><content>Optionalprerequisitesinfo</content></prerequisites>-->
CopyWalkthroughTopic
<!--Oneormoreprocedureorsectionwithprocedure-->
<procedure>
<title>Proceduretitle</title>
<stepsclass="ordered">
<step>
<content>
<para>Firststep</para>
</content>
</step>
<step>
<content>
<para>Secondstep</para>
</content>
</step>
</steps>
<!--<conclusion>Optionalconclusion</conclusion>-->
</procedure>
<!--Optionaladditionalprocedureorsectionwithprocedure-->
<sectionaddress="Section1">
<title>Optionalsectiontitle</title>
<content>
<procedure>
<title>Procedure#2</title>
<stepsclass="ordered">
<step>
<content>
<para>Firststep</para>
</content>
</step>
<step>
<content>
<para>Secondstep</para>
</content>
</step>
</steps>
<!--<conclusion>Optionalconclusion</conclusion>-->
</procedure>
</content>
</section>
<!--Optionalnextstepsinfo
<nextSteps>
<content><para>Nextstepsinfogoeshere</para></content>
</nextSteps>
-->
<relatedTopics>
<!--Oneormoreofthefollowing:
-Alocallink
-Anexternallink
-Acodeentityreference
<linkxlink:href="OtherTopic'sID">Linktext</link>
<externalLink>
<linkText>Linktext</linkText>
<linkAlternateText>Optionalalternatelinktext</linkAlternateText>
<linkUri>URI</linkUri>
</externalLink>
<codeEntityReference>APImemberID</codeEntityReference>
Examples:
<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>
SeeAlsoOtherResourcesTopicFile
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
<codeEntityReference>M:TestDoc.TestClass.SecondMethod(System.Int32,System.String)</codeEntityReference>
-->
</relatedTopics>
</developerWalkthroughDocument>
</topic>
SandcastleMAMLGuide
Whitepaper
Thisdocumenttypeisusedforwhitepapers.
WhitepaperFileFormatBelowisanexampleofaWhitepapertopicfile.
<?xmlversion="1.0"encoding="utf-8"?>
<topicid="00000000-0000-0000-0000-000000000000"revisionNumber
<developerWhitePaperDocument
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
xmlns:xlink="http://www.w3.org/1999/xlink">
<!--
<summary>
<para>Optionalsummaryabstract</para>
</summary>
-->
<byline>
<para>Byline</para>
</byline>
<date>
<para>Date</para>
</date>
<summarySection>
<content>
<para>Summarycontent</para>
CopyWhitepaperTopic
</content>
</summarySection>
<!--<downloadCenterLink>Optionalinfoaboutdownloadablecontent</downloadCenterLink>-->
<!--<appliesTo>Optional"appliesto"info</appliesTo>-->
<!--<contents>Optionalcontentsinfo</contents>-->
<introduction>
<!--Uncommentthistogenerateanoutlineofthesectionandsub-section
titles.Specifyanumericvalueastheinnertexttolimititto
aspecificnumberofsub-topicswhencreatingtheoutline.Specify
zero(0)tolimitittotop-levelsectionsonly.-->
<!--<autoOutline/>-->
<para>Requiredintroduction</para>
</introduction>
<!--Addoneormoretop-levelsectionelements.Thesearecollapsible.
Ifusing<autoOutline/>,addanaddressattributetoidentifyit
andspecifyatitlesothatitcanbejumpedtowithahyperlink.-->
<sectionaddress="Section1">
<title>Optionalsectiontitle</title>
<content>
<!--Uncommentthistocreateasub-sectionoutline
<autoOutline/>-->
<para>Addoneormoresectionswithcontent
</content>
</section>
<!--<codeExample>Optionalcodeexample.</codeExample>-->
<conclusion>
<content>
<para>Conclusioncontent</para>
</content>
</conclusion>
<relatedTopics>
<!--Oneormoreofthefollowing:
-Alocallink
-Anexternallink
-Acodeentityreference
<linkxlink:href="OtherTopic'sID">Linktext</link>
<externalLink>
<linkText>Linktext</linkText>
<linkAlternateText>Optionalalternatelinktext</linkAlternateText>
<linkUri>URI</linkUri>
</externalLink>
<codeEntityReference>APImemberID</codeEntityReference>
Examples:
<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>
<!--<additionalInformation>Optionaladditionalinfo</additionalInformation>-->
<!--<authorBio>Optionalauthorbio</authorBio>-->
</developerWhitePaperDocument>
SeeAlsoOtherResourcesTopicFile
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
</topic>
SandcastleMAMLGuide
XMLReference
ThisdocumenttypeisusedforXMLreferencetopics.
XMLReferenceFileFormatBelowisanexampleofanXMLReferencetopicfile.
<?xmlversion="1.0"encoding="utf-8"?>
<topicid="00000000-0000-0000-0000-000000000000"revisionNumber
<developerXmlReference
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
xmlns:xlink="http://www.w3.org/1999/xlink">
<!--
<summary>
<para>Optionalsummaryabstract</para>
</summary>
-->
<introduction>
<para>Requiredintroduction</para>
</introduction>
<!--Optionalschemahierarchy
<schemaHierarchy>
<linkxlink:href="OtherTopic'sID">Link1</link>
<linkxlink:href="OtherTopic'sID">Link2</link>
</schemaHierarchy>-->
<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>
<!--<codeExample>Optionalcodeexample.</codeExample>-->
<!--<elementInformation>Optionalelementinfo</elementInformation>-->
<relatedTopics>
<!--Oneormoreofthefollowing:
-Alocallink
-Anexternallink
-Acodeentityreference
<linkxlink:href="OtherTopic'sID">Linktext</link>
<externalLink>
<linkText>Linktext</linkText>
<linkAlternateText>Optionalalternatelinktext</linkAlternateText>
<linkUri>URI</linkUri>
</externalLink>
<codeEntityReference>APImemberID</codeEntityReference>
Examples:
<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>
SeeAlsoOtherResourcesTopicFile
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
-->
</relatedTopics>
</developerXmlReference>
</topic>
SandcastleMAMLGuide
CompanionFile
Acompanionfileisusedduringthebuildprocesstoobtainthetopictitleandlinktextforaparticularconceptualtopic.Therewillbeonecompanionfileforeachconceptualcontenttopic.
Note
IfusingabuildtoolsuchastheSandcastleHelpFileBuilder,thecompanionfilesarecreatedforyouautomaticallyaspartofthebuildprocessandyoudonotneedtomaintainthemyourself.
CompanionFileFormatBelowisanexampleofacompanionfile.
Thefileconsistsofarootmetadatanodethatcontainsonetopicnodewithanidattributethatreferstothetopic'sGUID.
Thetitleelementisrequiredandcontainsthetitletouseforthetopic.Thiswillbeusedasthedefaultlinktext.Incaseswherethetitleisnotappropriateoristoolongforlinktextandyouusethetopicinalinkfrequently,youcanspecifyalinkTextelementthatcontainsdifferenttexttouseforthelink.Notethatifalinkelementhasinnertextspecifiedinthetopic,itwillalwaysbeusedinsteadofthevaluesfromthecompanionfile.
<?xmlversion="1.0"encoding="utf-8"?>
<metadata>
<topicid="303c996a-2911-4c08-b492-6496c82b3edb">
<title>WelcometotheSandcastleMAMLGuide</title
<linkText>Welcomepage</linkText>
</topic>
</metadata>
CopyExampleCompanionFile
Note
TheIDvaluemustbeintheformofaGloballyUniqueIdentifier(GUID).
SeeAlsoOtherResourcesConceptualContentFileTypeslink
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
SandcastleMAMLGuide
BlockElements
Thetopicsinthissectiondefinetheblockelementsthatcanbeusedinconceptualtopics.
BlockElementsSelectoneofthetopicsbelowtolearnmoreaboutaparticularblockelement.
alert
code
codeReference
definitionTable,definedTerm,definition
introduction
list,listItem
para
quote
relatedTopics
table,tableHeader,row,entry
title
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
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
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
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
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>
<!--#regionXAMLSnippet-->
<TriggerProperty="Button.IsMouseOver"Value="true">
<SetterProperty="Background"Value="Red"/>
</Trigger>
<!--#endregion-->
</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"/>
<codesource="..\Class1.vb"region="Snippet#2"/>
</code>
Copy
<codetitle="Nestedcodeelementsexample"language
<codesource="..\Class1.vb"region="Snippet#1"/>
'...Somestuffhappenshere...
<codesource="..\Class1.vb"region="Snippet#2"/>
</code>
Copy
NestedCodeElementsExample
NestedCodeElementsExample
OtherResourcesBlockElementscodeInlinecodeEntityReferencecodeReference
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
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
CSharpClassx=newCSharpClass();
Copy
publicstaticCSharpClasssharedInstance=newCSharpClass();
Copy
CSharpClassx=newCSharpClass();
...
Copy
C# VB
C# VB
C# VB
C# VB
SeeAlsoOtherResourcesBlockElementsCodeSnippetsFilecodecodeInlinecodeEntityReference
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
publicstaticCSharpClasssharedInstance=newCSharpClass();
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
<definedTerm>Term2</definedTerm>
<definition><para>Definition2</para></definition
<definedTerm>Term3</definedTerm>
Copy
ExampleOutputThislinktakesyoutoTerm#8.
Term1Definition1
Term2Definition2
Term3Definition3
Term4Definition4
Term5Definition5
Term6Definition6
<definition><para>Definition3</para></definition
<definedTerm>Term4</definedTerm>
<definition><para>Definition4</para></definition
<definedTerm>Term5</definedTerm>
<definition><para>Definition5</para></definition
<definedTerm>Term6</definedTerm>
<definition><para>Definition6</para></definition
<definedTerm>Term7</definedTerm>
<definition><para>Definition7</para></definition
<definedTermaddress="Term8">Term8</definedTerm>
<definition><para>Definition8.Theentry'stermhasan
attributethatcanbeusedasalinktarget.</para>
</definitionTable>
Term7Definition7
Term8Definition8.Theentry'stermhasanaddressattributethatcanbeusedasalinktarget.
SeeAlsoOtherResourcesBlockElementslist,listItemtable,tableHeader,row,entry
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
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
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
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>Item2</para></listItem>
<listItem><para>Item3</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-Item3</para></listItem>
<listItem><para>Sub-Item4</para></listItem>
<listItem><para>Sub-Item5-Thishasanested
<codeInline>nobullet</codeInline>list.</para>
<listclass="nobullet">
<listItem><para>No-bulletitem1</para></listItem
<listItem><para>No-bulletitem2</para></listItem
<listItem><para>No-bulletitem3</para></listItem
</list>
</listItem>
<listItem><para>Sub-Item6</para></listItem>
</list>
</listItem>
<listItem><para>Item5</para></listItem>
<listItem><para>Item6</para></listItem>
<listItem><para>Item7</para></listItem>
<listItem><para>Item8</para></listItem>
<listItem><para>Item9</para></listItem>
<listItem><para>Item10</para></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
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
SandcastleMAMLGuide
para
Thiselementcanbeusedtocreateparagraphsinconceptualcontent.
UsageEntertheelementinthetopicandspecifytheparagraphtextastheinnertext.Makingtheelementself-closingoremptywillcausetheelementtobeignoredunlessitcreatesaninitialparagraphbreak.
Example
ExampleOutputParagraph1.
Paragraph2.
Self-closingandemptyparagraphsareignored.
Paragraph4.
SeeAlso
<para>Paragraph1.</para>
<para>Paragraph2.</para>
<para/>
<para></para>
<para>Self-closingandemptyparagraphsareignored.
<para>Paragraph4.</para>
Copy
OtherResourcesBlockElements
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
SandcastleMAMLGuide
quote
Thiselementdescribesaquotation.
UsageEntertheelementinthetopicandspecifythequotationastheinnertext.
Example
ExampleOutputToquotetheschema:
Thequoteelementdescribesaquotation.
SeeAlsoOtherResourcesBlockElementsquoteInline
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
<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
ReferenceWithoutSyntax
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"
<linktopicType_id="1FE70836-AA7D-4515-B54B-E10C4B516E50"
xlink:href="bc490dbf-7d46-432d-a816-3ae16ab6af54"
<linktopicType_id="1FE70836-AA7D-4515-B54B-E10C4B516E50"
xlink:href="d0c9ce6d-115b-4c70-891c-69b4af944dea"
<linktopicType_id="1FE70836-AA7D-4515-B54B-E10C4B516E50"
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
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
</codeEntityReference>
<codeEntityReferencequalifyHint="true"autoUpgrade
M:System.IO.FileStream.Write(System.Byte[],System.Int32,System.Int32)
</codeEntityReference>
<codeEntityReferencequalifyHint="false">P:System.IO.FileStream.Length
</codeEntityReference>
<codeEntityReferencequalifyHint="false"autoUpgrade
M:System.IO.FileStream.Flush</codeEntityReference
</relatedTopics>
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>
<entry><para>Header2</para></entry>
<entry><para>Header3</para></entry>
</row>
</tableHeader>
<row>
<entry><para>Row1,Cell1</para></entry>
<entry><para>Row1,Cell2</para></entry>
<entry><para>Row1,Cell3</para></entry>
</row>
<row>
<entry><para>Row2,Cell1</para></entry>
<entry><para>Row2,Cell2</para></entry>
<entry><para>Row2,Cell3</para></entry>
</row>
Copy
<row>
<entryaddress="Row3Cell1"><para>Thisentryhasan
attributethatcanbeusedasalinktarget.</para>
<entry><para>Row3,Cell2</para></entry>
<entry><para>Row3,Cell3</para></entry>
</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>
<entry><para>Cell2</para></entry>
<entry><para>Cell3</para></entry>
<entry><para>Cell4</para></entry>
</row>
<row>
<entry><para>Cell5</para></entry>
<entry><para>Cell6</para></entry>
<entry><para>Cell7</para></entry>
<entry><para>Cell8</para></entry>
</row>
<row>
<entry><para>Cell9</para></entry>
<entry><para>Cell10</para></entry>
<entry><para>Cell11</para></entry>
<entry><para>Cell12</para></entry>
</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
Cell5 Cell6 Cell7 Cell8
Cell9 Cell10 Cell11 Cell12
Thetableabovedoesn'thaveatableHeader.
SeeAlsoOtherResources
</table>
<para>Thetableabovedoesn'thavea
<codeInline>tableHeader</codeInline>.</para>
</entry>
</row>
</table>
BlockElementsdefinitionTable,definedTerm,definitionlist,listItem
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
SandcastleMAMLGuide
title
Thiselementdescribesthenameofapartofadocument.
UsageEntertheelementinthetopicandspecifythetexttouseasthesection'stitle.
Example
ExampleOutputSeetheUsagesectionaboveforanexampleoftheoutput.
SeeAlsoOtherResourcesBlockElements
[v1.1.0.3]SandcastleMAMLGuide
<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
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
SandcastleMAMLGuide
application
ThiselementisusedtodescribethenameofanapplicationsuchasMicrosoftWindowsorNotepad.
UsageEntertheelementinthetopicandspecifytheapplicationnameastheinnertext.
Example
ExampleOutputUsetheSandcastleHelpFileBuildertocreatehelpfiles.
SeeAlsoOtherResourcesCommonInlineElements
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
Usethe<application>SandcastleHelpFileBuilder</
Copy
SandcastleMAMLGuide
codeInline
Thiselementdescribesastringofcodeorasinglekeyword.Formulti-linecodefragments,usethecodeelementinstead.
UsageEntertheelementinthetopicandspecifythecodeastheinnertext.
Example
ExampleOutputUseaforeachlooptoiterateoverthecollection.
SeeAlsoOtherResourcesCommonInlineElementscodecodeEntityReferencecodeReference
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
Usea<codeInline>foreach</codeInline>looptoiterateoverthecollection.
Copy
SandcastleMAMLGuide
command
Thiselementdescribesthenameofanexecutableorothersoftwareapplicationthancanberun.
UsageEntertheelementinthetopicandspecifytheapplicationnameastheinnertext.Thereplaceableelementcanbenestedwithinittorepresentreplaceableparameters.
Example
ExampleOutputXCOPY/s/esourceFileSpecdestFileSpec
SeeAlsoOtherResourcesCommonInlineElementsreplaceablesystem
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
<command>COPY<system>/s/e</system> <replaceable
 <replaceable>destFileSpec</replaceable></command
Copy
SandcastleMAMLGuide
computerOutputInline
ThiselementdescribesoutputfromeitheraconsolepromptorfromaUIform.
UsageEntertheelementinthetopicandspecifytheoutputastheinnertext.
Example
ExampleOutputTheresultofrunningHelloWorld.exeis:HelloWorld!
SeeAlsoOtherResourcesCommonInlineElements
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
Theresultofrunning<application>HelloWorld.exe</
<computerOutputInline>HelloWorld!</computerOutputInline
Copy
SandcastleMAMLGuide
database
Thiselementisusedtodescribeadatabase.
UsageEntertheelementinthetopicandspecifythedatabaseastheinnertext.
Example
ExampleOutputTheinformationisstoredintheContentdatabase.
SeeAlsoOtherResourcesCommonInlineElements
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
Theinformationisstoredinthe<database>Content</
Copy
SandcastleMAMLGuide
environmentVariable
Thiselementdescribesanenvironmentvariableinanoperatingsystem.
UsageEntertheelementinthetopicandspecifytheenvironmentvariableastheinnertext.
Example
ExampleOutputTheSandcastletoolsfindtheirinstalledlocationusingtheSHFBROOTenvironmentvariable.
SeeAlsoOtherResourcesCommonInlineElements
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
TheSandcastletoolsfindtheirinstalledlocationusingthe
<environmentVariable>SHFBROOT</environmentVariable>
Copy
SandcastleMAMLGuide
errorInline
Thiselementdescribesanerrororerrormessage.
UsageEntertheelementinthetopicandspecifytheerrorastheinnertext.
Example
ExampleOutputIfafiledoesnotexist,aFileNotFounderrorwilloccur.
SeeAlsoOtherResourcesCommonInlineElements
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
Ifafiledoesnotexist,a<errorInline>FileNotFound
errorwilloccur.
Copy
SandcastleMAMLGuide
fictitiousUri
Thiselementdescribesafictitiousinternetaddresssuchasaweboremailaddress.
UsageEntertheelementinthetopicandspecifythefictitiousURIastheinnertext.
Example
ExampleOutputThee-mailaddressjdoe@contoso.comisfakeasistheURLhttp://www.contoso.com.
SeeAlsoOtherResourcesCommonInlineElements
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
Thee-mailaddress<fictitiousUri>jdoe@contoso.com</
fakeasistheURL<fictitiousUri>http://www.contoso.com
Copy
SandcastleMAMLGuide
foreignPhrase
Thiselementisusedtodescribeaphrasethatisofalanguagethatisdifferentthantheprimarylanguageofthedocument.
UsageEntertheelementinthetopicandspecifythephraseastheinnertext.
Example
ExampleOutputIfitdoesn'tworkout,C'estlavie.
SeeAlsoOtherResourcesCommonInlineElementsphrasequoteInline
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
Ifitdoesn'tworkout,<foreignPhrase>C'estlavie
Copy
SandcastleMAMLGuide
hardware
Thiselementdescribesaphysicalpartofacomputersystem.
UsageEntertheelementinthetopicandspecifythehardwareastheinnertext.
Example
ExampleOutputPlugtheflashdriveintotheUSBport.
SeeAlsoOtherResourcesCommonInlineElements
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
Plugthe<hardware>flashdrive</hardware>intothe
<hardware>USBport</hardware>.
Copy
SandcastleMAMLGuide
legacyBold
Thiselementmarksboldtextinlegacydocuments.Theschemadoesnotrecommendusingthiselement.Instead,useoneoftheothercommoninlineelementsthatdescribeaspecifictypeofitemsuchasapplication,ui,etc.However,forgeneralitems,itisasimplewaytoboldtext.
UsageEntertheelementinthetopicandspecifythetexttoboldastheinnertext.
Example
ExampleOutputThistextwillberenderedinbold.
SeeAlsoOtherResourcesCommonInlineElements
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
Thistextwillberenderedin<legacyBold>bold</legacyBold
Copy
SandcastleMAMLGuide
legacyItalic
Thiselementmarksitalicizedtextinlegacydocuments.Theschemadoesnotrecommendusingthiselement.Instead,useoneoftheothercommoninlineelementsthatdescribeaspecifictypeofitemsuchasapplication,ui,etc.However,forgeneralitems,itisasimplewaytoitalicizetext.
UsageEntertheelementinthetopicandspecifythetexttoitalicizeastheinnertext.
Example
ExampleOutputThistextwillberenderedasitalicized.
SeeAlsoOtherResourcesCommonInlineElements
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
Thistextwillberenderedas<legacyItalic>italicized
Copy
SandcastleMAMLGuide
legacyUnderline
Thiselementmarksunderlinedtextinlegacydocuments.Theschemadoesnotrecommendusingthiselement.Instead,useoneoftheothercommoninlineelementsthatdescribeaspecifictypeofitemsuchasapplication,ui,etc.However,forgeneralitems,itisasimplewaytounderlinetext.
UsageEntertheelementinthetopicandspecifythetexttounderlineastheinnertext.
Example
ExampleOutputThistextwillberenderedwithanunderline.
SeeAlsoOtherResourcesCommonInlineElements
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
Thistextwillberenderedwithan<legacyUnderline
Copy
SandcastleMAMLGuide
literal
Thiselementdescribesaliteralvalue.
UsageEntertheelementinthetopicandspecifytheliteralvalueastheinnertext.
Example
ExampleOutputIfthepropertyisnotused,setittothestringNone.
SeeAlsoOtherResourcesCommonInlineElements
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
Ifthepropertyisnotused,setittothestring<
Copy
SandcastleMAMLGuide
localUri
Thiselementdescribesthepathtoalocalresourcesuchasafile.
UsageEntertheelementinthetopicandspecifythepathastheinnertext.
Example
ExampleOutputSandcastleisinstalledintheC:\ProgramFiles\Sandcastlefolderbydefault.
SeeAlsoOtherResourcesCommonInlineElements
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
Sandcastleisinstalledinthe<localUri>C:\ProgramFiles\Sandcastle
folderbydefault.
Copy
SandcastleMAMLGuide
math
Thiselementcanbeusedtomarkmathematicalexpressions.
UsageEntertheelementinthetopicandspecifythemathematicalexpressionastheinnertext.
Example
ExampleOutputAsimplemathexpression:1+1=2.
SeeAlsoOtherResourcesCommonInlineElementssubscriptsuperscript
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
Asimplemathexpression:<math>1+1=2</math>.
Copy
SandcastleMAMLGuide
newTerm
Thiselementisusedtointroducenewtermsortechnologies.
UsageEntertheelementinthetopicandspecifythenewtermastheinnertext.
Example
ExampleOutputTopicstocoverincludeLINQ,WPF,andWCF.
SeeAlsoOtherResourcesCommonInlineElements
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
Topicstocoverinclude<newTerm>LINQ</newTerm>,<newTerm
<newTerm>WCF</newTerm>.
Copy
SandcastleMAMLGuide
phrase
Thiselementisawrapperelementforarunoftext.Itissolelyacontaineranddoesnotspecifyanysemanticsonitsown.
UsageEntertheelementinthetopicandspecifythephraseastheinnertext.
Example
ExampleOutputIfitdoesn'tworkout,that'slife.
SeeAlsoOtherResourcesCommonInlineElementsforeignPhrasequoteInline
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
Ifitdoesn'tworkout,<phrase>that'slife</phrase
Copy
SandcastleMAMLGuide
placeholder
Thiselementisusedasaplaceholder.Bydefault,itrenderstextinastyledeterminedbythepresentationstyle.Itmayhavespecificuseincustombuildcomponents.
UsageEntertheelementinthetopic.It'sinnertextandtheendresultisimplementationdependent.
Example
ExampleOutputSomethingusefulcouldgohereifabuildcomponentmadeuseofit.
SeeAlsoOtherResourcesCommonInlineElements
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
Somethingusefulcouldgo<placeholder>here</placeholder
buildcomponentmadeuseofit.
Copy
SandcastleMAMLGuide
quoteInline
Thiselementisusedtodescribeaninlinequotation.
UsageEntertheelementinthetopicandspecifythequotationastheinnertext.
Example
ExampleOutputThisisanexampleofan"inlinequotation".
SeeAlsoOtherResourcesCommonInlineElementsquote
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
Thisisanexampleofan<quoteInline>inlinequotation
Copy
SandcastleMAMLGuide
replaceable
Thiselementdescribesapartofacommandorafunctionthatmustbereplacedbytheuser.
UsageEntertheelementinthetopicandspecifythereplaceableitemastheinnertext.
Example
ExampleOutputXCOPY/s/esourceFileSpecdestFileSpec
SeeAlsoOtherResourcesCommonInlineElementscommand
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
<command>COPY<system>/s/e</system> <replaceable
 <replaceable>destFileSpec</replaceable></command
Copy
SandcastleMAMLGuide
subscript
Thiselementcanbeusedtomarkasubscriptsuchasthosefoundinmathematicalexpressions.
UsageEntertheelementinthetopicandspecifythesubscripttextastheinnertext.
Example
ExampleOutputThechemicalformulaforwaterisH2O.
SeeAlsoOtherResourcesCommonInlineElementsmath
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
Thechemicalformulaforwateris<math>H<subscript
Copy
SandcastleMAMLGuide
superscript
Thiselementcanbeusedtomarkasuperscriptsuchasthosefoundinmathematicalexpressions.
UsageEntertheelementinthetopicandspecifythesuperscripttextastheinnertext.
Example
ExampleOutputCanyouexplainE=MC2?
SeeAlsoOtherResourcesCommonInlineElementsmath
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
Canyouexplain<math>E=MC<superscript>2</superscript
Copy
SandcastleMAMLGuide
system
Thiselementdescribessystemcommands,commandlineswitches,etc.
UsageEntertheelementinthetopicandspecifythecommandorswitchesastheinnertext.
Example
ExampleOutputXCOPY/s/esourceFileSpecdestFileSpec
SeeAlsoOtherResourcesCommonInlineElementscommandreplaceable
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
<command>COPY<system>/s/e</system> <replaceable
 <replaceable>destFileSpec</replaceable></command
Copy
SandcastleMAMLGuide
ui
Thiselementdescribesauserinterfaceelement.
UsageEntertheelementinthetopicandspecifytheuserinterfaceitemastheinnertext.
Example
ExampleOutputClicktheOKbuttontoclosethedialogbox.
SeeAlsoOtherResourcesCommonInlineElements
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
Clickthe<ui>OK</ui>buttontoclosethedialogbox.
Copy
SandcastleMAMLGuide
unmanagedCodeEntityReference
Thiselementisusedtorefertounmanagedcodeentityreferences.Unlikemanagedcodeentityreferences,thiselementdoesnotresultinalinktothereferenceditem.
UsageEntertheelementinthetopicandspecifytheentityastheinnertext.
Example
ExampleOutputYoucanusePInvoketocallSetWindowPlacement.
SeeAlsoOtherResourcesCommonInlineElements
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
YoucanusePInvoketocall
<unmanagedCodeEntityReference>SetWindowPlacement</unmanagedCodeEntityReference
Copy
SandcastleMAMLGuide
userInput
Thiselementdescribesdatathatisenteredbytheuser.
UsageEntertheelementinthetopicandspecifytheinputastheinnertext.
Example
ExampleOutputEnterYesorNo.
SeeAlsoOtherResourcesCommonInlineElements
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
Enter<userInput>Yes</userInput>or<userInput>No</
Copy
SandcastleMAMLGuide
MediaElements
Thetopicsinthissectiondefinethemedia(image)elementsthatcanbeusedinconceptualtopics.
MediaElementsSelectoneofthetopicsbelowtolearnmoreaboutaparticularmediaelement.
mediaLink
medialLinkInline
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
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
<!--Nocaption,defaultimageplacement-->
<mediaLink>
<imagexlink:href="6be7079d-a9d8-4189-9021-0f72d1642beb"
</mediaLink>
<!--Captionbefore,centeredimage-->
<mediaLink>
<caption>CaptionBefore</caption>
<imageplacement="center"xlink:href="6be7079d-a9d8-4189-9021-0f72d1642beb"
</mediaLink>
Copy
ExampleOutput
CaptionBefore
<!--Captionafterwithlead-intext,farimagealignment-->
<mediaLink>
<captionplacement="after"lead="Figure1">Captionafterwithlead-in
<imageplacement="far"xlink:href="6be7079d-a9d8-4189-9021-0f72d1642beb"
</mediaLink>
Figure1: Captionafterwithlead-in
SeeAlsoOtherResourcesMediaElementsMediaContentFilemedialLinkInline
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
SandcastleMAMLGuide
medialLinkInline
Thiselementisusedtoinsertanimageinlinewithinthetextofaconceptualtopic.
UsageTouseaninlinemedialink,inserttheelementwithinthetextofthetopicatthelocationthattheimageshouldappear.Thenestedimageelementisusedtodefinetheimagelink.Thexlink:hrefattributeshouldrefertotheuniqueIDofanimageintheproject'smediacontentfile.
Example
ExampleOutputTheinformationicon appearsnexttoanInformationmessage.
Animagetotheleftofthetext.
SeeAlsoOtherResources
Theinformationicon<mediaLinkInline>
<imagexlink:href="4cfacbe8-d100-471c-9d69-1dbcce50e316"
appearsnexttoanInformationmessage.
<mediaLinkInline><imagexlink:href="b5d069f7-5daf-45ae-882c-4596ab2b724a"
Animagetotheleftofthetext.
Copy
MediaElementsMediaContentFilemediaLink
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
SandcastleMAMLGuide
LinkElements
Thetopicsinthissectiondefinethelinkelementsthatcanbeusedinconceptualtopics.
LinkElementsSelectoneofthetopicsbelowtolearnmoreaboutaparticularlinkelement.
codeEntityReference
externalLink
link
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
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
<codeEntityReferencequalifyHint="true"autoUpgrade
M:System.IO.FileStream.#ctor(System.String,System.IO.FileMode)
</codeEntityReference>
<codeEntityReferencequalifyHint="true"autoUpgrade
M:System.IO.FileStream.Write(System.Byte[],System.Int32,System.Int32)
</codeEntityReference>
<codeEntityReferencequalifyHint="false">P:System.IO.FileStream.Length
</codeEntityReference>
<codeEntityReferencequalifyHint="false"autoUpgrade
M:System.IO.FileStream.Flush</codeEntityReference>
<codeEntityReferencelinkText="FileStream.FlushonMSDN"
M:System.IO.FileStream.Flush</codeEntityReference>
Copy
Length
Flush
FileStream.FlushonMSDN
SeeAlsoOtherResourcesLinkElementscodecodeInlinecodeReference
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
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>
<linkText>SandcastleHelpFileBuilder</linkText
<linkUri>https://GitHub.com/EWSoftware/SHFB</linkUri
</externalLink>
Addedalternatetext:<externalLink>
<linkText>SandcastleHelpFileBuilder</linkText
<linkAlternateText>VisitSHFBonGitHub</linkAlternateText
<linkUri>https://GitHub.com/EWSoftware/SHFB</linkUri
</externalLink>
Addedlinktarget:<externalLink>
<linkText>SandcastleHelpFileBuilder</linkText
<linkAlternateText>VisitSHFBonGitHub</linkAlternateText
<linkUri>https://GitHub.com/EWSoftware/SHFB</linkUri
<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
SeeAlsoOtherResourcesLinkElementslink
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
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
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
In-pagelinktointroduction:<linkxlink:href="#intro"
Linktoothertopicanchor:
<linkxlink:href="dc4fcc96-283e-4202-9ecc-08a65e0c9313#BuildTools"
SandcastleMAMLGuide
MiscellaneousElements
Thetopicsinthissectiondefinemiscellaneouselementsnotfittingoneoftheothercategoriesthatcanbeusedinconceptualtopics.
MiscellaneousElementsSelectoneofthetopicsbelowtolearnmoreaboutaparticularmiscellaneouselement.
autoOutline
markup
token
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
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
<?xmlversion="1.0"encoding="utf-8"?>
<topicid="1a817894-db7a-4c7f-bd67-cca896affa35"revisionNumber
<developerConceptualDocument
xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
xmlns:xlink="http://www.w3.org/1999/xlink">
<introductionaddress="Intro">
<!--Nodepthoptionsoonlyshowtop-levelsectionshere-->
<autoOutline/>
<para>Theintroduction.If<codeInline><autoOutline/>
isincluded,thisparagraphcanbeomitted.
</para>
<!--NotethatplacingtheautoOutlineelementherewouldplace
thesectionoutlinebelowtheintroparagraph.-->
</introduction>
<sectionaddress="S1">
<title>Section1</title>
<content>
<para>Thisissection1.</para>
<!--Thiswillincludesub-sectionsintheoutlineuptothree
levelsdown.Italsousescustomlead-intext.-->
<autoOutlinelead="Selectasub-section:">3
</content>
<sections>
<sectionaddress="SS1">
<title>Sub-section1</title>
<content>
<para>Thisissub-section1.</para>
</content>
</section>
<sectionaddress="SS2">
<title>Sub-section2</title>
<content>
<!--No<autoOutline/>inheresonooutline-->
<para>Thisissub-section2.</para>
</content>
<sections>
<sectionaddress="SSS1">
Copy
ExampleOutputSeeautoOutlineRenderedExample
SeeAlsoOtherResources
<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>
</developerConceptualDocument>
</topic>
MiscellaneousElementstoken
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
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
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
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
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
SandcastleMAMLGuide
token
Atokenisusedasareplaceabletagwithinatopicandisrepresentedusingatokenelement.Theinnertextoftheelementisatokenname.Thetokensaredefinedinaseparatetokenfile.Theyareaneasywaytorepresentcommonitemsthatyouuseregularlysuchasacommonphraseorexternallink.
UsageTouseatoken,simplyinsertitsnameastheinnertextofatokenelementanywherewithinatopic.
ExampleInthisexample,"Sandcastle"isatokenthatexpandstoanexternallinktoawebsite.
ExampleOutputThislink(SandcastleHelpFileBuilder)isstoredinatoken.
SeeAlsoOtherResourcesMiscellaneousElementsTokenFile
[v1.1.0.3]SandcastleMAMLGuide
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
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
<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>
<!--PATCHHERE-->
<anynamespace="##other"processContents="lax"
</choice>
<attributeGroupref="maml:contentIdentificationSharingAndConditionGroup"
</complexType>
<complexTypename="relatedTopicsType"mixed="false"
<choiceminOccurs="0"maxOccurs="unbounded">
<groupref="maml:relatedTopicLinkGroup"/>
<!--PATCHHERE-->
<anynamespace="##other"processContents="lax"
</choice>
<attributeGroupref="maml:contentIdentificationSharingAndConditionGroup"
</complexType>
Copy
SeeAlsoOtherResourcesVisualStudioIntelliSense
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
<complexTypename="sectionContentType"mixed="false"
<choiceminOccurs="0"maxOccurs="unbounded">
<groupref="maml:structureGroup"/>
<elementname="conditionalSection"type="maml:conditionalSectionType"
<!--PATCHHERE-->
<anynamespace="##other"processContents="lax"
</choice>
<attributeGroupref="maml:contentIdentificationSharingAndConditionGroup"
</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
Microsoft.NETFrameworksandSDKs.
TheHTMLHelpWorkshopforbuildingHTMLHelp1.x(.CHM)helpfiles.
SeeAlsoOtherResourcesWelcome
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
SandcastleMAMLGuide
MakingaDonation
Ifyouwouldliketosupportthisproject,youcanmakeadonationofanyamountyoulikebyclickingonthePayPaldonationbuttonbelow.Ifyouwouldprefertodonateviacheckormoneyorder(USD),pleasesendmeane-mailatEric@EWoodruff.usandIwillreplywithmymailingaddress.
Theabovemethodofdonatingissecure.PayPalguaranteesyourprivacyandsecurity.Ineverreceivedetailsofyourpaymentotherthantheamount,yourname,e-mailaddress,andanyoptionallyenteredinformation.
Thankstothoseofyouthathavemadeadonation.Itismuchappreciated!
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
SandcastleMAMLGuide
VersionHistory
ThetopicsinthissectiondescribethevariouschangesmadetotheMAMLGuideoverthelifeoftheproject.
VersionHistorySelectaversionbelowtoseeadescriptionofitschanges.
Version1.1.0.3
Version1.1.0.2
Version1.1.0.1
Version1.1.0.0
Version1.0.0.0
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
SandcastleMAMLGuide
Version1.1.0.3
Version1.1.0.3wasreleasedonDecember16th,2012.
ChangesinThisReleaseRemovedreferencestotheSandcastleHelpFileBuildercomponentsandfeaturesthathavebeenmovedintotheSandcastletoolsandpresentationstyleXSLtransformationsandrewordedtheaffectedsectionstoreflecttheiractualusewithSandcastlealone.
SeeAlsoOtherResourcesVersionHistory
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
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
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
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.
SeeAlsoOtherResourcesVersionHistory
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
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.
SeeAlsoOtherResources
VersionHistory
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
SandcastleMAMLGuide
Version1.0.0.0
Version1.0.0.0wasreleasedonJune4th,2008.
ChangesinThisReleaseInitialrelease.
SeeAlsoOtherResourcesVersionHistory
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
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.
[v1.1.0.3]SandcastleMAMLGuide
SendcommentsonthistopictoEricWoodruff
Recommended