From bdede53bbe1e4bebe3316621eb7d1b7dd697fe6e Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sat, 13 Jul 2019 02:40:21 -0400 Subject: Documentation tweaks --- docs/pango-docs.sgml | 16 +++-- docs/pango-sections.txt | 11 +++- pango/pango-bidi-type.c | 2 +- pango/pango-markup.c | 165 ++++++++++++++++++++++++++++++++++++++++++++++ pango/pangocairo-render.c | 4 +- pango/pangocoretext.c | 4 +- pango/pangoft2.c | 2 +- pango/pangowin32.c | 2 +- 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 @@ Pango Reference Manual - for Pango &version; + Internationalized text layout and rendering + for Pango &version;. + Online at + https://developer.gnome.org/pango/ + Basic Pango Interfaces - - - + @@ -27,15 +29,17 @@ Rendering with Pango + + - - Low Level Functionality + + 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 @@ -431,6 +428,14 @@ pango_color_get_type pango_attribute_get_type +
+Markup +markup +pango_parse_markup +pango_markup_parser_new +pango_markup_parser_finish +
+
Tab Stops tab-stops 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: + * |[ + * Blue text is cool! + * ]| + * + * 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. + * + * 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> 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: + * + * <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 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 Cairo library 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 -- cgit v1.2.1