diff options
| -rw-r--r-- | docs/meson.build | 1 | ||||
| -rw-r--r-- | docs/pango.toml.in | 1 | ||||
| -rw-r--r-- | docs/pango_markup.md | 184 | ||||
| -rw-r--r-- | docs/pango_markup.sgml | 301 | ||||
| -rw-r--r-- | pango/pango-attributes.c | 11 | ||||
| -rw-r--r-- | pango/pango-markup.c | 191 |
6 files changed, 186 insertions, 503 deletions
diff --git a/docs/meson.build b/docs/meson.build index bdea5e50..4e2c06e8 100644 --- a/docs/meson.build +++ b/docs/meson.build @@ -2,6 +2,7 @@ gidocgen = find_program('gi-docgen', required: get_option('gtk_doc')) pango_content_files = [ 'pango_rendering.md', + 'pango_markup.md', 'pango-name.png', 'layout.png', 'pipeline.png', diff --git a/docs/pango.toml.in b/docs/pango.toml.in index 2a0dbcc0..1e8c0048 100644 --- a/docs/pango.toml.in +++ b/docs/pango.toml.in @@ -56,6 +56,7 @@ base_url = "https://gitlab.gnome.org/GNOME/pango/-/blob/master/" [extra] content_files = [ "pango_rendering.md", + "pango_markup.md", ] content_images = [ diff --git a/docs/pango_markup.md b/docs/pango_markup.md new file mode 100644 index 00000000..dc6047d3 --- /dev/null +++ b/docs/pango_markup.md @@ -0,0 +1,184 @@ +--- +Title: Text Attributes and Markup +--- + +# Text Attributes + +Attributed text is used in a number of places in Pango. It is used as the +input to the itemization process and also when creating a [class@Pango.Layout]. + +Attributes can influence the various stages of the rendering pipeline. For example, +font or size attributes will influence the font selection that is happening during +itemization, font features and letterspacing attributes will influence shaping, and +color or underline attributes will be used for rendering. + +Pango uses a simple structs for individual attributes, such as +[struct@Pango.AttrColor] or [struct@Pango.AttrFontDesc]. Each attribute has a type, +and a start and end index that determine the range of characters that the attribute +applies to. See the [enum@Pango.AttrType] enumeration for all the possible +attribute types. + +Attributes rarely come alone. Pango uses the [struct@Pango.AttrList] structure +to hold all attributes that apply to a piece of text. + +# Pango Markup + +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 [struct@Pango.AttrList] 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 [struct@Pango.AttrList] using either of +[func@parse_markup] or [func@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 `©` 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>`, then there are some convenience +tags. + +## The `<span>` Attributes + +font +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 +face +: 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 +style +: One of 'normal', 'oblique', 'italic'. + +font_weight +weight +: One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a + numeric weight. + +font_variant +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 +color +: 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'. + +## Convenience Tags + +`<b>` +: Bold + +`<big>` +: Makes font relatively larger, equivalent to `<span size="larger">` + +`<i>` +: Italic + +`<s>` +: Strikethrough + +`<sub>` +: Subscript + +`<sup>` +: Superscript + +`<small>` +: Makes font relatively smaller, equivalent to `<span size="smaller">` + +`<tt>` +: Monospace font + +`<u>` +: Underline diff --git a/docs/pango_markup.sgml b/docs/pango_markup.sgml deleted file mode 100644 index c2ba377c..00000000 --- a/docs/pango_markup.sgml +++ /dev/null @@ -1,301 +0,0 @@ -<refentry id="PangoMarkupFormat" revision="11 Dec 2002"> -<refmeta> -<refentrytitle>Text Attribute Markup</refentrytitle> -<manvolnum>3</manvolnum> -<refmiscinfo>Pango Library</refmiscinfo> -</refmeta> - -<refnamediv> -<refname>Text Attribute Markup</refname><refpurpose>Simple -markup language to encode text with attributes</refpurpose> -</refnamediv> - -<refsect1 id="PangoMarkupFormatLanguage"> -<title>Pango Text Attribute Markup Language</title> - -<para> -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 -<link linkend="PangoAttrList">PangoAttrList</link> 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. -</para> - -<para> -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 -<link linkend="PangoAttrList">PangoAttrList</link> using either of -<link linkend="pango-parse-markup">pango_parse_markup()</link> or -<link linkend="pango-markup-parser-new">pango_markup_parser_new()</link>. -</para> - -<para> -A simple example of a marked-up string might be: -<literal>"<span foreground="blue" size="x-large">Blue text</span> is <i>cool</i>!"</literal> -</para> - -<para> -Pango uses #GMarkup to parse this language, which means that XML features -such as numeric character entities such as &#169; for © can -be used too. -</para> - -<para> -The root tag of a marked-up document is <markup>, but <link -linkend="pango-parse-markup">pango_parse_markup()</link> 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. <span> has the following attributes: -<variablelist><title><span> attributes</title> - -<varlistentry> -<term>font<footnote id='since_1_21'><para>Since 1.21</para></footnote></term> -<term>font_desc</term> -<listitem><para> -A font description string, such as "Sans Italic 12". See -<link linkend="pango-font-description-from-string">pango_font_description_from_string()</link> -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.</para></listitem> -</varlistentry> - -<varlistentry> -<term>font_family</term> -<term>face</term> -<listitem><para> -A font family name -</para></listitem> -</varlistentry> - -<varlistentry> -<term>font_size<footnoteref linkend='since_1_21'/></term> -<term>size</term> -<listitem><para> -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 -<literal>font='12.5'</literal> rather than -<literal>size='12800'</literal>. -</para></listitem> -</varlistentry> - -<varlistentry> -<term>font_style<footnoteref linkend='since_1_21'/></term> -<term>style</term> -<listitem><para> -One of 'normal', 'oblique', 'italic' -</para></listitem> -</varlistentry> - -<varlistentry> -<term>font_weight<footnoteref linkend='since_1_21'/></term> -<term>weight</term> -<listitem><para> -One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', -or a numeric weight -</para></listitem> -</varlistentry> - -<varlistentry> -<term>font_variant<footnoteref linkend='since_1_21'/></term> -<term>variant</term> -<listitem><para> -One of 'normal' or 'smallcaps' -</para></listitem> -</varlistentry> - -<varlistentry> -<term>font_stretch<footnoteref linkend='since_1_21'/></term> -<term>stretch</term> -<listitem><para> -One of 'ultracondensed', 'extracondensed', 'condensed', -'semicondensed', 'normal', 'semiexpanded', 'expanded', -'extraexpanded', 'ultraexpanded' -</para></listitem> -</varlistentry> - -<varlistentry> -<term>font_features<footnote id='since_1_38'><para>Since 1.38</para></footnote></term> -<listitem><para> -A comma separated list of OpenType font feature settings, in the same -syntax as accepted by CSS. E.g: <literal>font_features='dlig=1, -kern, afrc on'</literal> -</para></listitem> -</varlistentry> - -<varlistentry> -<term>foreground</term> -<term>fgcolor<footnoteref linkend='since_1_21'/></term> -<term>color</term> -<listitem><para> -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. -</para></listitem> -</varlistentry> - -<varlistentry> -<term>background</term> -<term>bgcolor<footnoteref linkend='since_1_21'/></term> -<listitem><para> -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. -</para></listitem> -</varlistentry> - -<varlistentry> -<term>alpha</term> -<term>fgalpha<footnoteref linkend='since_1_38'/></term> -<listitem><para> -An alpha value for the foreground color, either a plain integer between 1 and 65536 -or a percentage value like '50%'. -</para></listitem> -</varlistentry> - -<varlistentry> -<term>background_alpha</term> -<term>bgalpha<footnoteref linkend='since_1_38'/></term> -<listitem><para> -An alpha value for the background color, either a plain integer between 1 and 65536 -or a percentage value like '50%'. -</para></listitem> -</varlistentry> - -<varlistentry><term>underline</term> -<listitem><para> -One of 'none', 'single', 'double', 'low', 'error' -</para></listitem> -</varlistentry> - -<varlistentry><term>underline_color</term> -<listitem><para> -The color of underlines; an RGB color specification such as '#00FF00' -or a color name such as 'red' -</para></listitem> -</varlistentry> - -<varlistentry><term>rise</term> -<listitem><para> -Vertical displacement, in Pango units. Can be negative for -subscript, positive for superscript. -</para></listitem> -</varlistentry> - -<varlistentry><term>strikethrough</term> -<listitem><para> -'true' or 'false' whether to strike through the text -</para></listitem> -</varlistentry> - -<varlistentry><term>strikethrough_color</term> -<listitem><para> -The color of strikethrough lines; an RGB color specification such as -'#00FF00' or a color name such as 'red' -</para></listitem> -</varlistentry> - -<varlistentry><term>fallback</term> -<listitem><para> -'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. -</para></listitem> -</varlistentry> - -<varlistentry><term>lang</term> -<listitem><para> -A language code, indicating the text language -</para></listitem> -</varlistentry> - -<varlistentry><term>letter_spacing</term> -<listitem><para> -Inter-letter spacing in 1024ths of a point. -</para></listitem> -</varlistentry> - -<varlistentry><term>gravity</term> -<listitem><para> -One of 'south', 'east', 'north', 'west', 'auto'. -</para></listitem> -</varlistentry> - -<varlistentry><term>gravity_hint</term> -<listitem><para> -One of 'natural', 'strong', 'line'. -</para></listitem> -</varlistentry> - -</variablelist> - -</para> - -<para> -The following convenience tags are provided: - -<variablelist><title>Convenience tags</title> -<varlistentry><term>b</term> -<listitem><para> -Bold -</para></listitem> -</varlistentry> -<varlistentry><term>big</term> -<listitem><para> -Makes font relatively larger, equivalent to <span size="larger"> -</para></listitem> -</varlistentry> -<varlistentry><term>i</term> -<listitem><para> -Italic -</para></listitem> -</varlistentry> -<varlistentry><term>s</term> -<listitem><para> -Strikethrough -</para></listitem> -</varlistentry> -<varlistentry><term>sub</term> -<listitem><para> -Subscript -</para></listitem> -</varlistentry> -<varlistentry><term>sup</term> -<listitem><para> -Superscript -</para></listitem> -</varlistentry> -<varlistentry><term>small</term> -<listitem><para> -Makes font relatively smaller, equivalent to <span size="smaller"> -</para></listitem> -</varlistentry> -<varlistentry><term>tt</term> -<listitem><para> -Monospace font -</para></listitem> -</varlistentry> -<varlistentry><term>u</term> -<listitem><para> -Underline -</para></listitem> -</varlistentry> -</variablelist> - -</para> - -</refsect1> - -</refentry> diff --git a/pango/pango-attributes.c b/pango/pango-attributes.c index 49226da5..85640b34 100644 --- a/pango/pango-attributes.c +++ b/pango/pango-attributes.c @@ -19,17 +19,6 @@ * Boston, MA 02111-1307, USA. */ -/** - * SECTION:text-attributes - * @short_description:Font and other attributes for annotating text - * @title:Attributes - * - * Attributed text is used in a number of places in Pango. It - * is used as the input to the itemization process and also when - * creating a #PangoLayout. The data types and functions in - * this section are used to represent and manipulate sets - * of attributes applied to a portion of text. - */ #include "config.h" #include <string.h> diff --git a/pango/pango-markup.c b/pango/pango-markup.c index 1c074fd6..08d202a5 100644 --- a/pango/pango-markup.c +++ b/pango/pango-markup.c @@ -30,197 +30,6 @@ #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 `©` 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>`, - * then there are some convenience tags. - * - * ## Span attributes - * - * `<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, - * 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`, - * `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` - * - * * `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` - * - * * `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. - * - * * `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 - * 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`. - * - * * `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`. - * - * ## Convenience tags - * - * The following convenience tags are provided: - * - * * `<b>`: - * Bold - * - * * `<big>`: - * Makes font relatively larger, equivalent to `<span size="larger">` - * - * * `<i>`: - * Italic - * - * * `<s>`: - * Strikethrough - * - * * `<sub>`: - * Subscript - * - * * `<sup>`: - * Superscript - * - * * `<small>`: - * Makes font relatively smaller, equivalent to `<span size="smaller">` - * - * * `<tt>`: - * Monospace - * - * * `<u>`: - * Underline - */ - /* FIXME */ #define _(x) x |