Visual Basic 2012 Voorbeelden
   

visual basic 2012 broncode voorbeelden

Blijf op de hoogte van de recente aanpassingen op vbvoorbeelden!

Microsoft Visual Studio 2012Microsoft Developers Network - Visual BasicMicrosoft .NET Framework

33.3. Conceptuele Documentatie met Sandcastle MAML

Print Email Deel op Twitter Deel op Facebook

Dit artikel is gepubliceerd op maandag 15 oktober 2012 op vbvoorbeelden, bezoek de website voor een recente versie van dit artikel of andere artikels.

Sandcastle is ook bruikbaar om conceptuele documentatie op basis van MAML te genereren.  Deze conceptuele documentatie of dus help informatie kunnen verklarende woordenlijsten (glossary), veelgestelde vragenlijsten ( FAQ), procedurale informatie of gebruiksaanwijzingen ( walkthrough/task/tutorial/how-to), probleemoplossing (troubleshooting) of overige documentatie zijn.

Microsoft Assistance Markup Language (MAML) is niet veel meer dan XML die voldoet aan een schema dat de structuur van de conceptuele informatie aangeeft.
MAML bevat geen presentatie informatie, wat HTML - die voorheen meestal werd gebruikt om conceptuele documentatie op te stellen - wel bevat.
De uiteindelijk gepresenteerde informatie, layout en stijl die gebruikt wordt in de output HTML/CHM/HxS/RTF/XAML/... wordt bekomen aan de hand van een aantal XSL transformaties die door Sandcastle BuildAssembler tool en eventuele third-party build componenten worden toegepast.
Dit staat ons dus toe de presentatie en data strikt gescheiden te houden.

Misschien - voorlopig nog - meer bekende structured authoring modellen ( XSDs/XML schemas) zijn DITA en DocBook.  MAML is hiermee vergelijkbaar.

MAML definieert verschillende content types, elk voor een specifiek soort van documentatie.  Hieronder vind je een aantal voorbeelden van de verschillende content types :

33.3.1. Voorbeeld van Conceptual Document

Een <section> kan meerdere <sections> bevatten die elk een <title> en <content> hebben.
XML Instantie
<?xml version="1.0" encoding="utf-8"?>
<developerConceptualDocument
  xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
  xmlns:xlink="http://www.w3.org/1999/xlink">
  <summary>
    <para>Abstract...</para>
  </summary>
  <introduction>
    <para>Introduction...</para>
  </introduction>
  <section address="Section1">
    <title>Section 1 Title</title>
    <content>
      <para>Main content for section 1...</para>
    </content>
    <sections>
      <section address="Section1A">
        <title>Section 1A Title</title>
        <content>
          <para>Section 1A content...</para>
        </content>
      </section>
      <section address="Section1B">
        <title>Section 1B Title</title>
        <content>
          <para>Section 1B content...</para>
        </content>
        <sections>
          <section address="Section1B1">
            <title>Section 1B1 Title</title>
            <content>
              <para>Section 1B1 content...</para>
            </content>
          </section>
        </sections>
      </section>
    </sections>
  </section>
  <relatedTopics>
    <link xlink:href="Topic ID">Link inner text</link>
    <externalLink>
        <linkText>Link text</linkText>
        <linkAlternateText>Optional alternate link text</linkAlternateText>
        <linkUri>URI</linkUri>
    </externalLink>
  </relatedTopics>
</developerConceptualDocument>

33.3.2. Voorbeeld van Glossary Document

Een verklarende woordenlijst waar voor verschillende <terms> een <definition> wordt gegeven.
XML Instantie
<?xml version="1.0" encoding="utf-8"?>
<developerGlossaryDocument
  xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
  xmlns:xlink="http://www.w3.org/1999/xlink">
  <glossary>
    <title>Glossary Title</title>
    <glossaryEntry>
      <terms>
        <term termId="Global Assembly Cache">Global Assembly Cache</term>
        <term termId="GAC">GAC</term>
      </terms>
      <definition>
        <para>Machine-wide storage location for .NET assemblies.</para>
      </definition>
    </glossaryEntry>
    <glossaryEntry>
      <terms>
        <term termId="Proxy">Proxy</term>
      </terms>
      <definition>
        <para>...</para>
      </definition>
      <relatedEntry termId="Stub" />
    </glossaryEntry>
    <glossaryEntry>
      <terms>
        <term termId="Stub">Stub</term>
      </terms>
      <definition>
        <para>...</para>
      </definition>
      <relatedEntry termId="Proxy" />
    </glossaryEntry>
  </glossary>
</developerGlossaryDocument>

33.3.3. Voorbeeld van How To Document

Een <procedure> kan verschillende <steps> definiëren.
XML Instantie
<?xml version="1.0" encoding="utf-8"?>
<developerHowToDocument
  xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
  xmlns:xlink="http://www.w3.org/1999/xlink">
  <summary>
    <para>Abstract...</para>
  </summary>
  <introduction>
    <para>Introduction...</para>
  </introduction>
  <procedure>
    <title>Procedure title</title>
    <steps class="ordered">
      <step>
        <content>
          <para>First step</para>
        </content>
      </step>
      <step>
        <content>
          <para>Second step</para>
        </content>
      </step>
    </steps>
  </procedure>
  <relatedTopics>
    <link xlink:href="Topic ID">Link inner text</link>
    <externalLink>
        <linkText>Link text</linkText>
        <linkAlternateText>Optional alternate link text</linkAlternateText>
        <linkUri>URI</linkUri>
    </externalLink>
  </relatedTopics>
</developerHowToDocument>

33.3.4. Voorbeeld van een Walkthrough Document

Eén of meerdere <procedure>s of <section>s met <procedure>s.
XML Instantie
<?xml version="1.0" encoding="utf-8"?>
<developerWalkthroughDocument
  xmlns="http://ddue.schemas.microsoft.com/authoring/2003/5"
  xmlns:xlink="http://www.w3.org/1999/xlink">
  <summary>
    <para>Abstract...</para>
  </summary>
  <introduction>
    <para>Introduction...</para>
  </introduction>
  <procedure>
    <title>Procedure 1 Title</title>
    <steps class="ordered">
      <step>
        <content>
          <para>First Step</para>
        </content>
      </step>
    </steps>
  </procedure>
  <procedure>
    <title>Procedure 2 Title</title>
    ...
  </procedure>
  <section address="Section1">
    <title>Section 1 Title</title>
    <content>
      <procedure>
        <title>Procedure 3 Title</title>
        <steps class="ordered">
          <step>
            <content>
              <para>First Step</para>
            </content>
          </step>
          <step>
            <content>
              <para>Second Step</para>
            </content>
          </step>
        </steps>
      </procedure>
    </content>
  </section>
  <nextSteps>Optional next steps ...</nextSteps>
  <relatedTopics>
    <link xlink:href="Topic ID">Link inner text</link>
    <externalLink>
        <linkText>Link text</linkText>
        <linkAlternateText>Optional alternate link text</linkAlternateText>
        <linkUri>URI</linkUri>
    </externalLink>
  </relatedTopics>
</developerWalkthroughDocument>
Nog vele andere document types bestaan, zoals <developerErrorMessageDocument>, <developerOrientationDocument>, <develeporTroubelshootingDocument>, ... .
Uitstekende detail informatie over bovenstaande schemas en het gebruik binnen Sandcastle is te vinden in de Sandcastle MAML Guide 1.1.0.0 :

Dit artikel is gepubliceerd op maandag 15 oktober 2012 op vbvoorbeelden, bezoek de website voor een recente versie van dit artikel of andere artikels.