| |
  |
Note: Notice the news of 2005-04-12!
Microsoft Assistance Markup Language (MAML) is a XML based markup language used by "Longhorn" Help. The current help system HTMLHelp 1.x is using HTML topic files. HTML is a markup language that combines presentational and semantic elements.The most significant aspect of MAML is the shift to a structured authoring model. Documents and their constituent elements are defined semantically, placing the focus on content rather than formatting. Presentation is controlled at rendering time, adding a new degree of flexibility.
MAML consists of several distinct content types, each one specific to a type of document. The MAML content types include: conceptual, FAQ, glossary, procedural, reference, reusable content, task, troubleshooting, and tutorial.
Content authored in MAML can be output to many different formats, including DHTML, XAML, RTF, and print. When MAML content is presented online, there are three levels of run-time transformation: structural, presentational, and rendering. Structural transformation uses reusable content and applies conditional logic, determining the content that will appear, and the structure of that content. The resulting MAML format document is then ready to move onto the presentational transformation stage. At this point, the content is transformed into one of the presentation formats (DHTML, XAML, or RTF). Rendering transformation is the final stage where stylesheets are applied and the content is displayed in its final form.
The conceptual content type is the most generic of all the content types.
Simple Structure Example
<conceptual>
<title />
<content>
<para />
...
</content>
<sections>
<section>
<title />
<content>
<para />
...
</content>
</section>
...
</sections>
</conceptual>
Code Example
Use the FAQ content type to create frequently asked question (FAQ) documents. A document that uses the FAQ content type can consist of one or more sets of questions and answers.
Documents based on the FAQ content type are composed of one or more faqDiv elements, which can in turn contain one or more faqEntry elements. Each faqDiv element requires a title element. Use an introduction element to provide introductory text for the topic. Transitional text can be added between faqDiv elements using the transition element.
Open the XSL Stylesheet for this example or the presentation mode.
Simple Structure Example
<?xml version="1.0" encoding="UTF-8"?>
<faq>
<title />
<faqDiv>
<title />
<introduction>
<para />
</introduction>
<faqEntry>
<question>
<para />
</question>
<answer>
<para />
</answer>
<crossReference />
</faqEntry>
..
</faqDiv>
..
</faq>
Code Example
<?xml version="1.0" encoding="UTF-8"?>
<faq>
<title>Frequently Asked Questions</title>
<faqDiv>
<title>Getting Started</title>
<introduction>
<para>This section covers questions you may encounter when beginning
to use our program.</para>
</introduction>
<faqEntry>
<question>
<para>How do I run setup?</para>
</question>
<answer>
<para>Double-click Setup.exe, and follow the instructions.</para>
</answer>
<crossReference/>
</faqEntry>
<transition>
<para>If you have additional questions, go to
"Getting Support" in this FAQ.</para>
</transition>
</faqDiv>
<faqDiv>
<title>Getting Support</title>
<introduction>
<para>This section covers questions related to technical support.</para>
</introduction>
<faqEntry>
<question>
<para>How can I get support?</para>
</question>
<answer>
<list class="bullet">
<listItem>
<para>Use our online form.</para>
</listItem>
<listItem>
<para>Send an e-mail request.</para>
</listItem>
<listItem>
<para>Call our toll-free number.</para>
</listItem>
</list>
</answer>
</faqEntry>
</faqDiv>
</faq>
The glossary content type is used to create glossary documents. A glossary consists of a series of sections that contain sets of terms and definitions. Topics can link to glossary terms using the element.
Documents based on the glossary content type are required to contain a title element. The document is composed of one or more glossaryDiv elements, which can each contain one or more glossaryEntry elements. Each glossaryEntry element can contain one or more terms, followed by a definition. The value of the address attribute of the glossaryEntry element links to the term using a element.
Open the XSL Stylesheet for this example or the presentation mode.
Simple Structure Example
<?xml version='1.0' encoding='UTF-8'?>
<glossary>
<title />
<glossaryDiv>
<title />
<glossaryEntry>
<terms>
<term />
</terms>
<definition>
<para />
</definition>
</glossaryEntry>
...
</glossaryDiv>
...
</glossary>
Code Example
<?xml version="1.0" encoding="UTF-8"?>
<?xml-stylesheet href="maml_glossary.xsl" type="text/xsl"?>
<glossary>
<!-- (c) 2004 Help Information, Ulrich Kulle -->
<title>Help Information - Microsoft Help Glossary</title>
<glossaryDiv>
<title>I</title>
<glossaryEntry address="glossary_integer">
<terms>
<term termClass="dev">Integer</term>
</terms>
<definition>
<para>
A whole number (not a fraction) that can be positive, negative, or zero.
The following numbers are examples of integers.
</para>
<list class="bullet">
<listItem>
<para>-254</para>
</listItem>
<listItem>
<para>5</para>
</listItem>
<listItem>
<para>3022</para>
</listItem>
</list>
<para>The following numbers are not integers:</para>
<list class="bullet">
<listItem>
<para>24.07</para>
</listItem>
<listItem>
<para>-318.001</para>
</listItem>
<listItem>
<para>.04267218</para>
</listItem>
</list>
</definition>
</glossaryEntry>
</glossaryDiv>
<glossaryDiv>
<title>M</title>
<glossaryEntry address="MAML">
<terms>
<term termClass="dev">MAML</term>
</terms>
<definition>
<para>Microsoft Assistance Markup Language</para>
</definition>
</glossaryEntry>
<glossaryEntry address="MFC">
<terms>
<term termClass="dev">MFC</term>
</terms>
<definition>
<para>Microsoft Foundation Classes</para>
<para>
Microsoft Foundation Class Library provides a framework
on which applications can be devAeloped for MS-Windows.
</para>
</definition>
</glossaryEntry>
</glossaryDiv>
<glossaryDiv>
<title>X</title>
<glossaryEntry address="XHTML">
<terms>
<term termClass="dev">XHTML</term>
</terms>
<definition>
<para>Extensible HyperText Markup Language</para>
</definition>
</glossaryEntry>
<glossaryEntry address="XML">
<terms>
<term termClass="dev">XML</term>
</terms>
<definition>
<para>Extensible Markup Language</para>
</definition>
</glossaryEntry>
</glossaryDiv>
</glossary>
Use the procedural content type to create topics consisting of one or more sets of numbered steps that show how to perform a particular task.
Simple Structure Example
<procedural>
<title />
<content>
<para />
</content>
<sections>
<section>
<content>
<procedure>
<steps>
<step>
<content>
<para />
</content>
</step>
...
</steps>
</procedure>
</content>
</section>
...
</sections>
</procedural>
Code Example
Use the reference content type to create developer reference topics.
Simple Structure Example
<?xml version="1.0" encoding="UTF-8"?>
<reference>
<title />
<content>
<para />
<para />
<code />
<para />
<para />
<para>
Text
<lineBreak/>
<codeInline> Text </codeInline>
</para>
<alert class="note"> Text </alert>
<para> Text </para>
<example>
<code>
For i=1 as int32 to 10 ..
</code>
<para>
Output:<lineBreak/>
</para>
</example>
</content>
<relatedTopics>
<navigationLink address="id string">
<linkText />
<summary/>
</navigationLink>
<navigationLink address="id string">
<linkText />
<summary/>
</navigationLink>
<navigationLink address="id string">
<linkText />
<summary/>
</navigationLink>
<navigationLink address="id string">
<linkText />
<summary/>
</navigationLink>
</relatedTopics>
</reference>
Code Example
<?xml version="1.0" encoding="UTF-8"?>
<reference>
<title>String</title>
<content>
<para>The string type represents a string of Unicode characters.
string is an alias for System.String in the .NET Framework. </para>
<para>Although string is a reference type, the equality operators (== and !=) are defined to compare the values of string objects, not references (7.9.7 String equality operators). This makes testing for string equality more intuitive. </para>
<code>
string a = "hello";
string b = "h";
b += "ello"; // append to b
Console.WriteLine( a == b ); // output: True -- same value
Console.WriteLine( (object)a == b ); // False -- different objects
</code>
<para>
The + operator concatenates strings:
<lineBreak/>
<codeInline>string a = "good " + "morning";</codeInline>
</para>
<para>
The [] operator accesses individual characters of a string:
<lineBreak/>
<codeInline>char x = "test"[2]; // x = 's';</codeInline>
</para>
<para>
String literals are of type string and can be written in two forms, quoted and @-quoted. Quoted string literals are enclosed in double quotation marks ("):
<lineBreak/>
<codeInline>"good morning" // a string literal</codeInline>
</para>
<para>
and can contain any character literal, including escape sequences:
<lineBreak/>
<codeInline> string a = "\\\u0066\n"; // backslash, letter f, new line </codeInline>
</para>
<alert class="note">The escape code \udddd (where dddd is a four-digit number) represents the Unicode character U+dddd. Eight-digit Unicode escape codes are also recognized: \udddd\udddd. </alert>
<para>
@-quoted string literals start with @ and are enclosed in double quotation marks. For example:
<lineBreak/>
<codeInline>@"good morning" // a string literal</codeInline>
</para>
<para>
The advantage of @-quoting is that escape sequences are not processed, which makes it easy to write, for example, a fully qualified file name:
<lineBreak/>
<codeInline> @"c:\Docs\Source\a.txt" // rather than "c:\\Docs\\Source\\a.txt" </codeInline>
</para>
<para>
To include a double quotation mark in an @-quoted string, double it:
<lineBreak/>
<codeInline> @"""Ahoy!"" cried the captain." // "Ahoy!" cried the captain. </codeInline>
</para>
<para>Another use of the @ symbol is to use referenced (/reference) identifiers that happen to be C# keywords. For more information, see 2.4.2 Identifiers. </para>
<example>
<code>
// keyword_string.cs
using System;
class test
{
public static void Main( String[] args )
{
string a = "\u0068ello ";
string b = "world";
Console.WriteLine( a + b );
Console.WriteLine( a + b == "hello world" );
}
}
</code>
<para>
Output:<lineBreak/>
hello world<lineBreak/>
True<lineBreak/>
</para>
</example>
</content>
<relatedTopics>
<navigationLink address="vclrfcsharpkeywords_pg">
<linkText>C# Keywords</linkText>
<summary/>
</navigationLink>
<navigationLink address="vcrefreferencetypes">
<linkText>Reference Types</linkText>
<summary/>
</navigationLink>
<navigationLink address="vcrefvaluetypes">
<linkText>Value Types</linkText>
<summary/>
</navigationLink>
<navigationLink address="vclrefnumericresultstableformatting">
<linkText>Formatting Numeric Results Table</linkText>
<summary/>
</navigationLink>
</relatedTopics>
</reference>
The reusable content content type enables Help authors to combine multiple
documents by defining blocks of linkable content. The only purpose of this content
type is to facilitate combining multiple documents. Any element that has the
replaceWith attribute can link to reusable content.
Simple Structure Example
<?xml version="1.0" encoding="UTF-8"?>
<reusableContent>
<reusableContentEntry address="id0001">
<para />
</reusableContentEntry>
..
</reusableContent>
Code Example
<?xml version="1.0" encoding="UTF-8"?>
<reusableContent>
<reusableContentEntry address="id0001">
<para>Microsoft Windows Help</para>
</reusableContentEntry>
<reusableContentEntry address="id0002">
<para>Microsoft HTMLHelp Workshop</para>
</reusableContentEntry>
<reusableContentEntry address="id0003">
<para>Microsoft Help2</para>
</reusableContentEntry>
</reusableContent>
Using Example
<para>Our operating system name is
<phrase replaceWith="help://microsoft.windows/default.aspx? _
version=6.0.0.0 _
&language=en-us _
&bundleid=helpdemo _
&topic=/brandinclude.xml#id0001">
operating system
(this text will be replaced with the contents of the referenced <entry> tag)
</phrase>.
</para>
Use the troubleshooting content type to create topics that guide users through solving problems.
Simple Structure Example
<troubleshooting>
<problem>
<symptom />
<cause />
<solution>
<para />
...
</solution>
</problem>
...
</troubleshooting>
Code Example
Use the tutorial content type to provide instructions for performing tasks that exceed the scope of a procedure. Typically, a tutorial encompasses two or more shorter procedures.
Simple Structure Example
<tutorial>
<title />
<content>
<para />
...
</content>
<sections>
<section>
<title />
<content>
<procedure>
<steps>
<step>
<content>
<para />
</content>
</step>
...
</steps>
</procedure>
<para />
<mediaLink>
<image />
</mediaLink>
<para />
</content>
</section>
...
</sections>
</tutorial>
Code Example
 |
The Help Pane. |
... the contents in MAML format:
<?xml version="1.0" encoding="UTF-8"?>
<conceptual xmlns="http://schemas.microsoft.com/maml/2003/5" xmlns:doc="http://schemas.microsoft.com/maml/internal" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:schemaLocation="http://schemas.microsoft.com/maml/2003/5
C:\Program Files\Microsoft Longhorn SDK\misc\MAML_Schema\Maml.xsd" xmlns:xlink="http://www.w3.org/1999/xlink">
<title> Longhorn Help Demo: Topic 2</title>
<copyright>
<trademark>Copyright</trademark>
<year>2004</year>
<holder>Help Information</holder>
</copyright>
<content>
<para>This is the second topic of the "Longhorn" Help authoring demo.</para>
<para>This demo is edited by Help Information (c) Ulrich Kulle</para>
<para>www.help-info.de</para>
</content>
<procedure>
<steps>
<step>
<content>
<para>Your first step with Longhorn Help: See this information.</para>
</content>
</step>
<step>
<content>
<para>Check our web site for a freeware GUI to compile Longhorn Help.</para>
<list class="bullet">
<listItem>
<para>To compile use the<ui>Compile</ui> tab.</para>
</listItem>
<listItem>
<para>To decompile use the <ui>Decompile</ui> tab.</para>
</listItem>
<listItem>
<para>To make the use of all the options easier use the <ui>Settings</ui> tab.</para>
</listItem>
</list>
</content>
</step>
</steps>
</procedure>
<sections>
<section expandCollapse="collapse">
<title>Section 1</title>
<content>
<para> The contents of this section will appear only after the arrow icon has been clicked, expanding the section. </para>
</content>
</section>
<section>
<title>Link demonstration</title>
<content>
<para>Here is a link back to <link xlink:href= "help://microsoft.windows/default.aspx?language=en-us& version=6.0.0.1&bundleid=LonghornHelpDemo& topic=/Topic1.xml">Topic 1</link>. </para>
</content>
</section>
<section>
<title>To position pictures with text</title>
<content>
<procedure>
<steps>
<step>
<content>
<para>Step 1</para>
</content>
</step>
<step>
<content>
<para>Step 2</para>
<alert class="note">This is a 'alert class=note'</alert>
<</step>
</steps>
</procedure>
<para>Your picture should now look like this:</para>
<mediaLink>
<image class="image" xlink:href="help://microsoft.windows/?language=en-us& version=6.0&bundle=media&topic=/images/carmen_img.jpg" mimeType="image/jpeg" width="241" height="355">
<summary>Carmen</summary>
</mediaLink>
<para> You can either place pictures one by one in this way, or you can import the pictures you will use on your pages all at once. While importing single files is done in <ui>Page</ui> view, inserting a group of files or entire folders is done in <ui>Folders</ui> view.</para>
</content>
</section>
</sections>
</conceptual>
 |