<page xmlns="http://projectmallard.org/1.0/"
      type="topic"
      id="mal_inline_em">

<info>
  <link type="guide" xref="mal_inline#elements"/>

  <revision version="0.1" date="2008-12-16" status="review"/>

  <credit type="author">
    <name>Shaun McCance</name>
    <email>shaunm@gnome.org</email>
  </credit>
  <copyright>
    <year>2008-2009</year>
    <name>Shaun McCance</name>
  </copyright>

  <include href="legal.xml" xmlns="http://www.w3.org/2001/XInclude" />

  <desc>Emphasize important text.</desc>
</info>

<title>Emphasis</title>

<synopsis><code mime="application/relax-ng-compact-syntax">
mal_inline_em = element em {
  <link xref="mal_attr_link">mal_attr_link</link> ?,
  attribute style { xsd:NMTOKENS } ?,
  attribute * - (mal:* | local:*) { text } *,

  <link xref="mal_inline">mal_inline</link>
}
</code></synopsis>

<p>Use the <code>em</code> element to emphasize text.  You may use <code>em</code>
to stress certain words in a sentence.  Do not use <code>em</code> to effect a
particular typographic style, since it may be rendered differently by different
display tools.</p>


<!-- BEGIN notes -->
<section id="notes">
  <title>Notes</title>
  <list>
    <item><p>The <code>em</code> element can contain a mixture of text and
    any <link xref="mal_inline">general inline elements</link>.</p></item>

    <item><p>The <code>em</code> element can occur in any
    general inline context, including inside most
    <link xref="mal_inline">inline elements</link>, some
    <link xref="mal_block#basic">basic block elements</link>, and certain
    <link xref="mal_info">informational elements</link>.</p></item>

    <item><p>The <code>em</code> element can link to other pages or documents.
    See <link xref="mal_attr_link"/> for more information.</p></item>

    <item><p>The <code>style</code> attribute takes a space-separated list of
    style hints.  Processing tools should adjust their behavior according to
    those style hints they understand.</p></item>

    <item><p>The <code>em</code> element can have attributes from external
    namespaces.  See <link xref="mal_external"/> for more information
    on external-namespace attributes.</p></item>
  </list>
</section>
<!-- END notes -->


<!-- BEGIN examples -->
<section id="examples">
  <title>Examples</title>

  <p>Use <code>em</code> to stress a word in a sentence:</p>

  <example>
    <code><![CDATA[
You should <em>never</em> run a graphical application as root.
]]></code>
    <p>You should <em>never</em> run a graphical application as root.</p>
  </example>

  <p>Use <code>em</code> to mark the first occurance of a term:</p>

  <example>
    <code><![CDATA[
Note that <em>accelerators</em> are different from <em>mnemonics</em>.
]]></code>
    <p>Note that <em>accelerators</em> are different from <em>mnemonics</em>.</p>
  </example>
</section>
<!-- END examples -->


<!-- BEGIN processing -->
<section id="processing">
  <title>Processing Expectations</title>
  <p>Emphasized text is traditionally presented in an italic or oblique font.
  Italic and oblique fonts stress a portion of text without making it stand
  out.  By contrast, bold text tends to draw the eye, which can be distracting
  when reading long passages of text.  In scripts without a distinction between
  roman and italic type styles, it may still be possible to use an oblique font
  or some other font variation.  Bold text may be used if necessary.</p>
  <p>Underlining should be avoided completely, since it hurts the legibility
  of the text.  This problem is especially pronounced in scripts which place
  diacritical marks below the text.  In these scripts, underlining can render
  the text completely illegible.</p>
</section>
<!-- END processing -->


<!-- BEGIN comparison -->
<section id="comparison">
  <title>Comparison to Other Formats</title>
  <p>The <code>em</code> element is similar to the
  <code href="http://www.docbook.org/tdg/en/html/emphasis.html">emphasis</code>
  element in DocBook.  Athough DocBook does not normatively specify a means of
  controlling the presentation, most DocBook display tools allow writers to
  set the <code>role</code> attribute to <code>bold</code> or <code>strong</code>
  to specify bold text.  No such recommendation is made for Mallard.</p>
</section>
<!-- END comparison -->

</page>
