| |
  |
Hinweis: Beachten Sie die News vom 12.04.2005!
 |
Überblick |
|
Konzeptionstyp (Conceptual) |
|
Häufig gestellte Fragen Typ (FAQ) |
|
Glossartyp (Glossary) |
|
Prozedurtyp (Procedural) |
|
Verweistyp (Reference) |
|
Wiederverwendbarer Typ (Reusable) |
|
Problemlösungstyp (Troubleshooting) |
|
Anleitungstyp (Tutorial) |
|
Hilfefenster und Quelltext Beispiel |
Microsoft Assistance Markup Language (MAML) ist eine XML basierte Markierungssprache, die von der "Longhorn" Hilfe verwendet wird. Das momentane Hilfesysteme HTMLHelp 1.x verwendet HTML Themendateien. HTML ist eine Markierungssprache, die Semantik und Präsentation kombiniert. Der bedeutenste Aspekt von MAML ist nun der Wechsel zum Modell eines strukturierten Autorensystems. Dokumente und ihre einzelnen Elemente werden semantisch definiert und stellen den Fokus auf Inhalt statt auf die Formatierung. Die Präsentation der Inhalte wird während der Aufbereitung kontrolliert und ermögicht so einen neuen Grad an Flexibilität.
MAML besteht aus mehreren eindeutigen Inhaltstypen, jeder für sich speziell für eine Art von Dokument. Die MAML Inhaltstypen beinhalten: Konzepte, FAQ's, Glossare, Prozeduren, Verweise, wiederverwendbare Inhalte, Aufgaben, Fehlerbehebung und Anleitungen.
In MAML verfasster Inhalt kann in viele verschiedenen Formaten ausgegeben werden und schließt DHTML, XAML, RTF und Druck ein. Wenn Inhalt auf Basis von MAML online gezeigt werden, gibt es drei Stufen der Transformation: Struktur, Präsentation und Aufbereitung. Die strukturelle Umsetzung verwendet die wiederverwendbaren Inhalte und wendet aus der Struktur der Inhalte eine bedingte Logik an, um den erforderlichen Inhalt zu bestimmen. Das entstehende MAML Formatdokument ist dann für die Umsetzungsstufe der Präsentation im nächsten Schritt bereit. An dieser Stelle ist der Inhalt in eines der Präsentationsformate (DHTML, XAMLs oder RTF) umgewandelt. Die Umsetzung der Aufbereitung ist die letzte Stufe, wobei Stylesheets angewendet werden, um den Inhalt in seiner endgültigen Form anzuzeigen.
Der Konzeptionstyp ist der allgemeingültigste von all den Inhaltstypen.
Einfaches Strukturbeispiel
<conceptual>
<title />
<content>
<para />
...
</content>
<sections>
<section>
<title />
<content>
<para />
...
</content>
</section>
...
</sections>
</conceptual>
Quelltext Beispiel
Verwenden Sie den FAQ-Typ, um Dokumente mit häufig gestellten Fragen zu erstellen. Ein Dokument, das den FAQ Inhaltstyp verwendet, kann aus einem oder mehreren Datensätzen aus Fragen und Antworten bestehen.
Dokumente die auf dem FAQ Inhaltstyp basieren sind aus einem oder mehreren faqDiv Elementen zusammengesetzt, die wiederum ein oder mehrere faqEntry Elemente enthalten können. Jedes faqDiv Element erfordert ein title Element. Verwenden Sie ein introduction Element, um Einführungstext für das Thema zu liefern. Übergangstext kann zwischen faqDiv Elementen mit Hilfe des transition Elements hinzugefügt werden.
Öffnen Sie das XSL Stylesheet für dieses Beispiel oder die Präsentationsdarstellung.
Einfaches Strukturbeispiel
<?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>
Quelltext Beispiel
<?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>
Der Glossartyp wird verwendet, um Dokumente mit Wortlisten zu erstellen. Ein Glossar besteht aus einer Serie von Abschnitten, die Datensätze von Begriffen und Definitionen enthalten. Themen können mit Glossarbegriffe mit Hilfe des Elements verknüpft werden.
Dokumente die auf dem Glossar Inhaltstyp basieren benötigen ein title Element. Das Dokument ist aus einem oder mehreren glossaryDiv Elementen zusammengesetzt, die je ein oder mehrere glossaryEntry Elemente enthalten können. Jedes glossaryEntry Element kann eine oder mehrere Begriffe enthalten, gefolgt von einer Definition. Der Wert des address Attributes des glossaryEntry Elements verknüpft mit dem Begriff dieses Elements verwendet.
Öffnen Sie das XSL Stylesheet für dieses Beispiel oder die Präsentationsdarstellung.
Einfaches Strukturbeispiel
<?xml version='1.0' encoding='UTF-8'?>
<glossary>
<title />
<glossaryDiv>
<title />
<glossaryEntry>
<terms>
<term />
</terms>
<definition>
<para />
</definition>
</glossaryEntry>
...
</glossaryDiv>
...
</glossary>
Quelltext Beispiel
<?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 developed 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>
Verwenden Sie den Prozedurtyp für Themen, die aus einem oder mehreren Sätzen von nummerierten Schritten bestehen. Diese zeigen, wie eine besondere Aufgabe auszuführen ist.
Einfaches Strukturbeispiel
<procedural>
<title />
<content>
<para />
</content>
<sections>
<section>
<content>
<procedure>
<steps>
<step>
<content>
<para />
</content>
</step>
...
</steps>
</procedure>
</content>
</section>
...
</sections>
</procedural>
Quelltext Beispiel
Verwenden Sie den Verweistyp, um Referenzthemen der Software-Entwickler zu erstellen.
Einfaches Strukturbeispiel
<?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>
Quelltext Beispiel
<?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>
Der wiederverwendbare Typ ermöglicht Hilfeautoren in vielen Dokumenten gleichartige Inhalte durch Definition von Blöcken wiederzuverwenden. Der einzige Zweck dieses Inhaltstyps ist es, eine mehrfache Nutzung in Dokumenten zu ermöglichen. Jedes Element, das ein replaceWith Attribut hat, kann auf den wiederverwendbaren Inhalt verweisen.
Einfaches Strukturbeispiel
<?xml version="1.0" encoding="UTF-8"?>
<reusableContent>
<reusableContentEntry address="id0001">
<para />
</reusableContentEntry>
..
</reusableContent>
Quelltext Beispiel
<?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>
Anwendungsbeispiel
<para>Our online help name is
<phrase replaceWith="help://microsoft.windows/default.aspx? _
version=6.0.0.0 _
&language=en-us _
&bundleid=helpdemo _
&topic=/brandinclude.xml#id0002">
help system
(this text will be replaced with the contents of the referenced <entry> tag)
</phrase>.
</para>
Verwenden Sie den Problemlösungstyp, um Themen zu erstellen die den Benutzer zu Prolemlösungen leitet.
Einfaches Strukturbeispiel
<troubleshooting>
<problem>
<symptom />
<cause />
<solution>
<para />
...
</solution>
</problem>
...
</troubleshooting>
Quelltext Beispiel
Verwenden Sie den Anleitungstyp (Tutorial), um für Aufgaben Anweisungen zu liefern, die den Bereich einer Prozedur übersteigen. Normalerweise umfasst ein Anleitungstyp zwei oder mehr kürzere Prozeduren.
Einfaches Strukturbeispiel
<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>
Quelltext Beispiel
 |
Das Hilfefenster. |
... der Inhalt im 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>
 |