docs/pango_markup.sgml

   1 <refentry id="PangoMarkupFormat" revision="11 Dec 2002">
   2 <refmeta>
   3 <refentrytitle>Text Attribute Markup</refentrytitle>
   4 <manvolnum>3</manvolnum>
   5 <refmiscinfo>Pango Library</refmiscinfo>
   6 </refmeta>
   7
   8 <refnamediv>
   9 <refname>Text Attribute Markup</refname><refpurpose>Simple
  10 markup language to encode text with attributes</refpurpose>
  11 </refnamediv>
  12
  13 <refsect1 id="PangoMarkupFormatLanguage">
  14 <title>Pango Text Attribute Markup Language</title>
  15
  16 <para>
  17 Frequently, you want to display some text to the user with attributes
  18 applied to part of the text (for example, you might want bold or
  19 italicized words). With the base Pango interfaces, you could create a
  20 <link linkend="PangoAttrList">PangoAttrList</link> and apply it to the
  21 text; the problem is that you'd need to apply attributes to some
  22 numeric range of characters, for example "characters 12-17." This is
  23 broken from an internationalization standpoint; once the text is
  24 translated, the word you wanted to italicize could be in a different
  25 position.
  26 </para>
  27
  28 <para>
  29 The solution is to include the text attributes in the string to be
  30 translated. Pango provides this feature with a small markup language.
  31 You can parse a marked-up string into the string text plus a
  32 <link linkend="PangoAttrList">PangoAttrList</link> using the function
  33 <link linkend="pango-parse-markup">pango_parse_markup()</link>.
  34 </para>
  35
  36 <para>
  37 A simple example of a marked-up string might be:
  38 <literal>"&lt;span foreground="blue" size="x-large"&gt;Blue text&lt;/span&gt; is &lt;i&gt;cool&lt;/i&gt;!"</literal>
  39 </para>
  40
  41 <para>
  42 Pango uses #GMarkup to parse this language, which means that XML features
  43 such as numeric character entities such as &amp;#169; for &#169; can
  44 be used too.
  45 </para>
  46
  47 <para>
  48 The root tag of a marked-up document is &lt;markup&gt;, but <link
  49 linkend="pango-parse-markup">pango_parse_markup()</link> allows you to
  50 omit this tag, so you will most likely never need to use it. The most
  51 general markup tag is &lt;span&gt;, then there are some convenience
  52 tags. &lt;span&gt; has the following attributes:
  53 <variablelist><title>&lt;span&gt; attributes</title>
  54
  55 <varlistentry>
  56 <term>font<footnote id='since_1_21'><para>Since 1.21</para></footnote></term>
  57 <term>font_desc</term>
  58 <listitem><para>
  59 A font description string, such as "Sans Italic 12". See
  60 <link linkend="pango-font-description-from-string">pango_font_description_from_string()</link>
  61 for a description of the format of the string representation . Note that any
  62 other span attributes will override this description. So if you have
  63 "Sans Italic" and also a style="normal" attribute, you will get Sans normal,
  64 not italic.</para></listitem>
  65 </varlistentry>
  66
  67 <varlistentry>
  68 <term>font_family</term>
  69 <term>face</term>
  70 <listitem><para>
  71 A font family name
  72 </para></listitem>
  73 </varlistentry>
  74
  75 <varlistentry>
  76 <term>font_size<footnoteref linkend='since_1_21'/></term>
  77 <term>size</term>
  78 <listitem><para>
  79 Font size in 1024ths of a point, or one of the absolute sizes
  80 'xx-small', 'x-small', 'small', 'medium', 'large', 'x-large',
  81 'xx-large', or one of the relative sizes 'smaller' or 'larger'.
  82 If you want to specify a absolute size, it's usually easier
  83 to take advantage of the ability to specify a partial
  84 font description using 'font'; you can use
  85 <literal>font='12.5'</literal> rather than
  86 <literal>size='12800'</literal>.
  87 </para></listitem>
  88 </varlistentry>
  89
  90 <varlistentry>
  91 <term>font_style<footnoteref linkend='since_1_21'/></term>
  92 <term>style</term>
  93 <listitem><para>
  94 One of 'normal', 'oblique', 'italic'
  95 </para></listitem>
  96 </varlistentry>
  97
  98 <varlistentry>
  99 <term>font_weight<footnoteref linkend='since_1_21'/></term>
 100 <term>weight</term>
 101 <listitem><para>
 102 One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy',
 103 or a numeric weight
 104 </para></listitem>
 105 </varlistentry>
 106
 107 <varlistentry>
 108 <term>font_variant<footnoteref linkend='since_1_21'/></term>
 109 <term>variant</term>
 110 <listitem><para>
 111 One of 'normal' or 'smallcaps'
 112 </para></listitem>
 113 </varlistentry>
 114
 115 <varlistentry>
 116 <term>font_stretch<footnoteref linkend='since_1_21'/></term>
 117 <term>stretch</term>
 118 <listitem><para>
 119 One of 'ultracondensed', 'extracondensed', 'condensed',
 120 'semicondensed', 'normal', 'semiexpanded', 'expanded',
 121 'extraexpanded', 'ultraexpanded'
 122 </para></listitem>
 123 </varlistentry>
 124
 125 <varlistentry>
 126 <term>foreground</term>
 127 <term>fgcolor<footnoteref linkend='since_1_21'/></term>
 128 <term>color</term>
 129 <listitem><para>
 130 An RGB color specification such as '#00FF00' or a color name such as
 131 'red'
 132 </para></listitem>
 133 </varlistentry>
 134
 135 <varlistentry>
 136 <term>background</term>
 137 <term>bgcolor<footnoteref linkend='since_1_21'/></term>
 138 <listitem><para>
 139 An RGB color specification such as '#00FF00' or a color name such as
 140 'red'
 141 </para></listitem>
 142 </varlistentry>
 143
 144 <varlistentry><term>underline</term>
 145 <listitem><para>
 146 One of 'none', 'single', 'double', 'low', 'error'
 147 </para></listitem>
 148 </varlistentry>
 149
 150 <varlistentry><term>underline_color</term>
 151 <listitem><para>
 152 The color of underlines; an RGB color specification such as '#00FF00'
 153 or a color name such as 'red'
 154 </para></listitem>
 155 </varlistentry>
 156
 157 <varlistentry><term>rise</term>
 158 <listitem><para>
 159 Vertical displacement, in 10000ths of an em. Can be negative for
 160 subscript, positive for superscript.
 161 </para></listitem>
 162 </varlistentry>
 163
 164 <varlistentry><term>strikethrough</term>
 165 <listitem><para>
 166 'true' or 'false' whether to strike through the text
 167 </para></listitem>
 168 </varlistentry>
 169
 170 <varlistentry><term>strikethrough_color</term>
 171 <listitem><para>
 172 The color of strikethrough lines; an RGB color specification such as
 173 '#00FF00' or a color name such as 'red'
 174 </para></listitem>
 175 </varlistentry>
 176
 177 <varlistentry><term>fallback</term>
 178 <listitem><para>
 179 'true' or 'false' whether to enable fallback. If disabled, then characters
 180 will only be used from the closest matching font on the system. No fallback
 181 will be done to other fonts on the system that might contain the characters
 182 in the text.  Fallback is enabled by default. Most applications should not
 183 disable fallback.
 184 </para></listitem>
 185 </varlistentry>
 186
 187 <varlistentry><term>lang</term>
 188 <listitem><para>
 189 A language code, indicating the text language
 190 </para></listitem>
 191 </varlistentry>
 192
 193 <varlistentry><term>letter_spacing</term>
 194 <listitem><para>
 195 Inter-letter spacing in 1024ths of a point.
 196 </para></listitem>
 197 </varlistentry>
 198
 199 <varlistentry><term>gravity</term>
 200 <listitem><para>
 201 One of 'south', 'east', 'north', 'west', 'auto'.
 202 </para></listitem>
 203 </varlistentry>
 204
 205 <varlistentry><term>gravity_hint</term>
 206 <listitem><para>
 207 One of 'natural', 'strong', 'line'.
 208 </para></listitem>
 209 </varlistentry>
 210
 211 </variablelist>
 212
 213 </para>
 214
 215 <para>
 216 The following convenience tags are provided:
 217
 218 <variablelist><title>Convenience tags</title>
 219 <varlistentry><term>b</term>
 220 <listitem><para>
 221 Bold
 222 </para></listitem>
 223 </varlistentry>
 224 <varlistentry><term>big</term>
 225 <listitem><para>
 226 Makes font relatively larger, equivalent to &lt;span size="larger"&gt;
 227 </para></listitem>
 228 </varlistentry>
 229 <varlistentry><term>i</term>
 230 <listitem><para>
 231 Italic
 232 </para></listitem>
 233 </varlistentry>
 234 <varlistentry><term>s</term>
 235 <listitem><para>
 236 Strikethrough
 237 </para></listitem>
 238 </varlistentry>
 239 <varlistentry><term>sub</term>
 240 <listitem><para>
 241 Subscript
 242 </para></listitem>
 243 </varlistentry>
 244 <varlistentry><term>sup</term>
 245 <listitem><para>
 246 Superscript
 247 </para></listitem>
 248 </varlistentry>
 249 <varlistentry><term>small</term>
 250 <listitem><para>
 251 Makes font relatively smaller, equivalent to &lt;span size="smaller"&gt;
 252 </para></listitem>
 253 </varlistentry>
 254 <varlistentry><term>tt</term>
 255 <listitem><para>
 256 Monospace font
 257 </para></listitem>
 258 </varlistentry>
 259 <varlistentry><term>u</term>
 260 <listitem><para>
 261 Underline
 262 </para></listitem>
 263 </varlistentry>
 264 </variablelist>
 265
 266 </para>
 267
 268 </refsect1>
 269
 270 </refentry>