Docs: improve formatting of markup description

* Place <span> attributes and convenience tags into lists to avoid
  a text wall.
* Add headings for each list
* Fix broken colour specifications (e.g. #FF0000 had lost the '#')
* Fix broken |piped| monospace sections
* `backticks` rather than 'quotes'

1 files changed, 103 insertions, 99 deletions

diff --git a/pango/pango-markup.c b/pango/pango-markup.c
index cdea3a98..a67e10fd 100644
--- a/pango/pango-markup.c
+++ b/pango/pango-markup.c
@@ -56,165 +56,169 @@
  * ]|
  *
  * Pango uses #GMarkup to parse this language, which means that XML
- * features such as numeric character entities such as © for
+ * features such as numeric character entities such as `©` for
  * © can be used too.
  *
- * The root tag of a marked-up document is <markup>, 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 <span>,
+ * The root tag of a marked-up document is `<markup>`, 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 `<span>`,
  * then there are some convenience tags.
  *
- * &lt;span&gt; has the following attributes:
+ * ## Span attributes
  *
- * font_desc
- * : A font description string, such as "Sans Italic 12".
+ * `<span>` 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,
+ *   and also a `style="normal"` attribute, you will get Sans normal,
  *   not italic.
  *
- * font_family
- * : A font family name
+ * * `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
+ * * `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 description using `font`; you can use `font='12.5'`
+ *   rather than `size='12800'`.
  *
- * font_style
- * : One of 'normal', 'oblique', 'italic'
+ * * `font_style`:
+ *   One of `normal`, `oblique`, `italic`
  *
- * font_weight
- * : One of 'ultralight', 'light', 'normal', 'bold',
- *   'ultrabold', 'heavy', or a numeric weight
+ * * `font_weight`:
+ *   One of `ultralight`, `light`, `normal`, `bold`,
+ *   `ultrabold`, `heavy`, or a numeric weight
  *
- * font_variant
- * : One of 'normal' or 'smallcaps'
+ * * `font_variant`:
+ *   One of `normal` or `smallcaps`
  *
- * font_stretch, stretch
- * : One of 'ultracondensed', 'extracondensed', 'condensed',
- *   'semicondensed', 'normal', 'semiexpanded', 'expanded',
- *   'extraexpanded', 'ultraexpanded'
+ * * `font_stretch`, `stretch`:
+ *   One of `ultracondensed`, `extracondensed`, `condensed`,
+ *   `semicondensed`, `normal`, `semiexpanded`, `expanded`,
+ *   `extraexpanded`, `ultraexpanded`
  *
- * font_features
- * : A comma separated list of OpenType font feature
+ * * `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'|
+ *   `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
+ * * `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
+ * * `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%'.
+ * * `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%'.
+ * * `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',
- *   'single-line', 'double-line' or 'error-line'.
+ * * `underline`:
+ *   One of `none`, `single`, `double`, `low`, `error`,
+ *   `single-line`, `double-line` or `error-line`.
  *
- * underline_color
- * : The color of underlines; an RGB color
- *   specification such as '#00FF00' or a color name such as 'red'
+ * * `underline_color`:
+ *   The color of underlines; an RGB color
+ *   specification such as `#00FF00` or a color name such as `red`
  *
- * overline
- * : One of 'none' or 'single'
+ * * `overline`:
+ *   One of `none` or `single`
  *
- * overline_color
- * : The color of overlines; an RGB color
- *   specification such as '#00FF00' or a color name such as 'red'
+ * * `overline_color`:
+ *   The color of overlines; an RGB color
+ *   specification such as `#00FF00` or a color name such as `red`
  *
- * rise
- * : Vertical displacement, in Pango units. Can be negative for
+ * * `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`
+ *   `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'
+ * * `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
+ * * `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.
  *
- * allow_breaks
- * : 'true' or 'false' whether to allow line breaks or not. If
+ * * `allow_breaks`:
+ *   `true` or `false` whether to allow line breaks or not. If
  *   not allowed, the range will be kept in a single run as far
  *   as possible. Breaks are allowed by default.
  *
- * insert_hyphens
- * : 'true' or 'false' whether to insert hyphens when breaking
+ * * `insert_hyphens`:`
+ *   `true` or `false` whether to insert hyphens when breaking
  *   lines in the middle of a word. Hyphens are inserted by default.
  *
- * show
- * : A value determining how invisible characters are treated.
- *   Possible values are 'spaces', 'line-breaks', 'ignorables'
- *   or combinations, such as 'spaces|line-breaks'.
+ * * `show`:
+ *   A value determining how invisible characters are treated.
+ *   Possible values are `spaces`, `line-breaks`, `ignorables`
+ *   or combinations, such as `spaces|line-breaks`.
+ *
+ * * `lang`:
+ *   A language code, indicating the text language
  *
- * lang
- * : A language code, indicating the text language
+ * * `letter_spacing`:
+ *   Inter-letter spacing in 1024ths of a point.
  *
- * letter_spacing
- * : Inter-letter spacing in 1024ths of a point.
+ * * `gravity`:
+ *   One of `south`, `east`, `north`, `west`, `auto`.
  *
- * gravity
- * : One of 'south', 'east', 'north', 'west', 'auto'.
+ * * `gravity_hint`:
+ *   One of `natural`, `strong`, `line`.
  *
- * gravity_hint
- * : One of 'natural', 'strong', 'line'.
+ * ## Convenience tags
  *
  * The following convenience tags are provided:
  *
- * &lt;b&gt;
- * : Bold
+ * * `<b>`:
+ *   Bold
  *
- * &lt;big&gt;
- * : Makes font relatively larger, equivalent to &lt;span size="larger"&gt;
+ * * `<big>`:
+ *   Makes font relatively larger, equivalent to `<span size="larger">`
  *
- * &lt;i&gt;
- * : Italic
+ * * `<i>`:
+ *   Italic
  *
- * &lt;s&gt;
- * : Strikethrough
+ * * `<s>`:
+ *   Strikethrough
  *
- * &lt;sub&gt;
- * : Subscript
+ * * `<sub>`:
+ *   Subscript
  *
- * &lt;sup&gt;
- * : Superscript
+ * * `<sup>`:
+ *   Superscript
  *
- * &lt;small&gt;
- * : Makes font relatively smaller, equivalent to &lt;span size="smaller"&gt;
+ * * `<small>`:
+ *   Makes font relatively smaller, equivalent to `<span size="smaller">`
  *
- * &lt;tt&gt;
- * : Monospace
+ * * `<tt>`:
+ *   Monospace
  *
- * &lt;u&gt;
- * : Underline
+ * * `<u>`:
+ *   Underline
  */
 
 /* FIXME */