Documentation tweaks

8 files changed, 190 insertions, 16 deletions

diff --git a/docs/pango-docs.sgml b/docs/pango-docs.sgml
index 181f8aba..7c597542 100644
--- a/docs/pango-docs.sgml
+++ b/docs/pango-docs.sgml
@@ -8,17 +8,19 @@
 <book id="index" xmlns:xi="http://www.w3.org/2003/XInclude">
   <bookinfo>
     <title>Pango Reference Manual</title>
-    <releaseinfo>for Pango &version;</releaseinfo>
+    <abstract>Internationalized text layout and rendering</abstract>
+    <releaseinfo>for Pango &version;.
+      Online at
+      <ulink role="online-location" url="https://developer.gnome.org/pango/">https://developer.gnome.org/pango/</ulink>
+    </releaseinfo>
   </bookinfo>
 
   <chapter id="pango">
     <title>Basic Pango Interfaces</title>
     <xi:include href="xml/main.xml"/>
-    <xi:include href="xml/glyphs.xml"/>
     <xi:include href="xml/fonts.xml"/>
     <xi:include href="xml/text-attributes.xml"/>
-    <xi:include href="xml/tab-stops.xml"/>
-    <xi:include href="pango_markup.sgml"/>
+    <xi:include href="xml/markup.xml"/>
     <xi:include href="xml/layout.xml"/>
     <xi:include href="xml/scripts.xml"/>
     <xi:include href="xml/bidi.xml"/>
@@ -27,15 +29,17 @@
 
   <chapter id="rendering">
     <title>Rendering with Pango</title>
+    <xi:include href="xml/pangocairo.xml"/>
     <xi:include href="xml/win32-fonts.xml"/>
+    <xi:include href="xml/coretext-fonts.xml"/>
     <xi:include href="xml/freetype-fonts.xml"/>
     <xi:include href="xml/xft-fonts.xml"/>
-    <xi:include href="xml/pangocairo.xml"/>
-    <xi:include href="xml/coretext-fonts.xml"/>
   </chapter>
 
   <chapter id="lowlevel">
     <title>Low Level Functionality</title>
+    <xi:include href="xml/glyphs.xml"/>
+    <xi:include href="xml/tab-stops.xml"/>
     <xi:include href="xml/pango-renderer.xml"/>
     <xi:include href="xml/pangofc-fontmap.xml"/>
     <xi:include href="xml/pangofc-font.xml"/>
diff --git a/docs/pango-sections.txt b/docs/pango-sections.txt
index fc72a0bf..9bf20619 100644
--- a/docs/pango-sections.txt
+++ b/docs/pango-sections.txt
@@ -349,9 +349,6 @@ PangoAttrFontDesc
 PangoAttrShape
 PangoAttrSize
 PangoAttrFontFeatures
-pango_parse_markup
-pango_markup_parser_new
-pango_markup_parser_finish
 pango_attr_type_register
 pango_attr_type_get_name
 pango_attribute_init
@@ -432,6 +429,14 @@ pango_attribute_get_type
 </SECTION>
 
 <SECTION>
+<TITLE>Markup</TITLE>
+<FILE>markup</FILE>
+pango_parse_markup
+pango_markup_parser_new
+pango_markup_parser_finish
+</SECTION>
+
+<SECTION>
 <TITLE>Tab Stops</TITLE>
 <FILE>tab-stops</FILE>
 PangoTabArray
diff --git a/pango/pango-bidi-type.c b/pango/pango-bidi-type.c
index 5c02dbbb..d4d84e03 100644
--- a/pango/pango-bidi-type.c
+++ b/pango/pango-bidi-type.c
@@ -21,7 +21,7 @@
 
 /**
  * SECTION:bidi
- * @short_description:Types and functions to help with handling bidirectional text
+ * @short_description:Types and functions for bidirectional text
  * @title:Bidirectional Text
  * @see_also:
  * pango_context_get_base_dir(),
diff --git a/pango/pango-markup.c b/pango/pango-markup.c
index 7420fa85..2c509dac 100644
--- a/pango/pango-markup.c
+++ b/pango/pango-markup.c
@@ -30,6 +30,171 @@
 #include "pango-impl-utils.h"
 #include "pango-utils-internal.h"
 
+/**
+ * SECTION:markup
+ * @title:Markup
+ * @short_description:Simple markup language for text with attributes
+ *
+ * Frequently, you want to display some text to the user with attributes
+ * applied to part of the text (for example, you might want bold or
+ * italicized words). With the base Pango interfaces, you could create a
+ * #PangoAttrList and apply it to the text; the problem is that you'd
+ * need to apply attributes to some numeric range of characters, for
+ * example "characters 12-17." This is broken from an internationalization
+ * standpoint; once the text is translated, the word you wanted to
+ * italicize could be in a different position.
+ *
+ * The solution is to include the text attributes in the string to be
+ * translated. Pango provides this feature with a small markup language.
+ * You can parse a marked-up string into the string text plus a
+ * #PangoAttrList using either of pango_parse_markup() or
+ * pango_markup_parser_new().
+ *
+ * A simple example of a marked-up string might be:
+ * |[
+ * <span foreground="blue" size="x-large">Blue text</span> is <i>cool</i>!
+ * ]|
+ *
+ * Pango uses #GMarkup to parse this language, which means that XML
+ * features such as numeric character entities such as &amp;#169; for
+ * © can be used too.
+ *
+ * The root tag of a marked-up document is &lt;markup&gt;, but
+ * pango_parse_markup()allows you to omit this tag, so you will most
+ * likely never need to use it. The most general markup tag is &lt;span&gt;,
+ * then there are some convenience tags.
+ *
+ * &lt;span&gt; has the following attributes:
+ *
+ * font_desc
+ * : A font description string, such as "Sans Italic 12".
+ *   See pango_font_description_from_string() for a description of the
+ *   format of the string representation . Note that any other span
+ *   attributes will override this description. So if you have "Sans Italic"
+ *   and also a style="normal" attribute, you will get Sans normal,
+ *   not italic.
+ *
+ * font_family
+ * : A font family name
+ *
+ * font_size, size
+ * : Font size in 1024ths of a point, or one of the absolute
+ *   sizes 'xx-small', 'x-small', 'small', 'medium', 'large',
+ *   'x-large', 'xx-large', or one of the relative sizes 'smaller'
+ *   or 'larger'. If you want to specify a absolute size, it's usually
+ *   easier to take advantage of the ability to specify a partial
+ *   font description using 'font'; you can use |font='12.5'|
+ *   rather than |size='12800'|.
+ *
+ * font_style
+ * : One of 'normal', 'oblique', 'italic'
+ *
+ * font_weight
+ * : One of 'ultralight', 'light', 'normal', 'bold',
+ *   'ultrabold', 'heavy', or a numeric weight
+ *
+ * font_variant
+ * : One of 'normal' or 'smallcaps'
+ *
+ * font_stretch, stretch
+ * : One of 'ultracondensed', 'extracondensed', 'condensed',
+ *   'semicondensed', 'normal', 'semiexpanded', 'expanded',
+ *   'extraexpanded', 'ultraexpanded'
+ *
+ * font_features
+ * : A comma separated list of OpenType font feature
+ *   settings, in the same syntax as accepted by CSS. E.g:
+ *   |font_features='dlig=1, -kern, afrc on'|
+ *
+ * foreground, fgcolor
+ * : An RGB color specification such as '#00FF00' or a color
+ *   name such as 'red'. Since 1.38, an RGBA color specification such
+ *   as '#00FF007F' will be interpreted as specifying both a foreground
+ *   color and foreground alpha.
+ *
+ * background, bgcolor
+ * : An RGB color specification such as '#00FF00' or a color
+ *   name such as'red'.
+ *   Since 1.38, an RGBA color specification such as '#00FF007F' will
+ *   be interpreted as specifying both a background color and
+ *   background alpha.
+ *
+ * alpha, fgalpha
+ * : An alpha value for the foreground color, either a plain
+ *   integer between 1 and 65536 or a percentage value like '50%'.
+ *
+ * background_alpha, bgalpha
+ * : An alpha value for the background color, either a plain
+ *   integer between 1 and 65536 or a percentage value like '50%'.
+ *
+ * underline
+ * : One of 'none', 'single', 'double', 'low', 'error'
+ *
+ * underline_color
+ * : The color of underlines; an RGB color
+ *   specification such as '#00FF00' or a color name such as 'red'
+ *
+ * rise
+ * : Vertical displacement, in Pango units. Can be negative for
+ *   subscript, positive for superscript.
+ *
+ * strikethrough
+ * : 'true' or 'false' whether to strike through the text
+ *
+ * strikethrough_color
+ * : The color of strikethrough lines; an RGB
+ *   color specification such as '#00FF00' or a color name such as 'red'
+ *
+ * fallback
+ * : 'true' or 'false' whether to enable fallback. If
+ *   disabled, then characters will only be used from the closest
+ *   matching font on the system. No fallback will be done to other
+ *   fonts on the system that might contain the characters in the text.
+ *   Fallback is enabled by default. Most applications should not
+ *   disable fallback.
+ *
+ * lang
+ * : A language code, indicating the text language
+ *
+ * letter_spacing
+ * : Inter-letter spacing in 1024ths of a point.
+ *
+ * gravity
+ * : One of 'south', 'east', 'north', 'west', 'auto'.
+ *
+ * gravity_hint
+ * : One of 'natural', 'strong', 'line'.
+ *
+ * The following convenience tags are provided:
+ *
+ * &lt;b&gt;
+ * : Bold
+ *
+ * &lt;big&gt;
+ * : Makes font relatively larger, equivalent to &lt;span size="larger"&gt;
+ *
+ * &lt;i&gt;
+ * : Italic
+ *
+ * &lt;s&gt;
+ * : Strikethrough
+ *
+ * &lt;sub&gt;
+ * : Subscript
+ *
+ * &lt;sup&gt;
+ * : Superscript
+ *
+ * &lt;small&gt;
+ * : Makes font relatively smaller, equivalent to &lt;span size="smaller"&gt;
+ *
+ * &lt;tt&gt;
+ * : Monospace
+ *
+ * &lt;u&gt;
+ * : Underline
+ */
+
 /* FIXME */
 #define _(x) x
 
diff --git a/pango/pangocairo-render.c b/pango/pangocairo-render.c
index 99154e77..3db3de5e 100644
--- a/pango/pangocairo-render.c
+++ b/pango/pangocairo-render.c
@@ -21,8 +21,8 @@
 
 /**
  * SECTION:pangocairo
- * @short_description:Rendering with the Cairo backend
- * @title:Cairo Rendering
+ * @short_description:Font handling and rendering with Cairo
+ * @title:Cairo Fonts and Rendering
  *
  * The <ulink url="http://cairographics.org">Cairo library</ulink> is a
  * vector graphics library with a powerful rendering model. It has such
diff --git a/pango/pangocoretext.c b/pango/pangocoretext.c
index bc606757..a6eaa1fc 100644
--- a/pango/pangocoretext.c
+++ b/pango/pangocoretext.c
@@ -22,8 +22,8 @@
 
 /**
  * SECTION:coretext-fonts
- * @short_description:Font handling with CoreText fonts
- * @title:CoreText Fonts
+ * @short_description:Font handling and rendering on OS X
+ * @title:CoreText Fonts and Rendering
  *
  * The macros and functions in this section are used to access fonts natively on
  * OS X using the CoreText text rendering subsystem.
diff --git a/pango/pangoft2.c b/pango/pangoft2.c
index 20e73925..a5ac6fc5 100644
--- a/pango/pangoft2.c
+++ b/pango/pangoft2.c
@@ -22,7 +22,7 @@
 
 /**
  * SECTION:freetype-fonts
- * @short_description:Functions for shape engines to manipulate FreeType fonts
+ * @short_description:Font handling and rendering with FreeType
  * @title:FreeType Fonts and Rendering
  *
  * The macros and functions in this section are used to access fonts and render
diff --git a/pango/pangowin32.c b/pango/pangowin32.c
index 6f60a70c..80abb0b4 100644
--- a/pango/pangowin32.c
+++ b/pango/pangowin32.c
@@ -24,7 +24,7 @@
 
 /**
  * SECTION:win32-fonts
- * @short_description:Functions for shape engines to manipulate Win32 fonts
+ * @short_description:Font handling and rendering on Windows
  * @title:Win32 Fonts and Rendering
  *
  * The macros and functions in this section are used to access fonts natively on