From 22dfeef4a26984ba81c6ff30117017dac372b706 Mon Sep 17 00:00:00 2001 From: Matthias Clasen Date: Sun, 4 Aug 2019 16:29:35 -0400 Subject: Add detail to docs Explain variation syntax and allowed values for other components of pango_font_description_from_string(). --- pango/fonts.c | 52 +++++++++++++++++++++++++++++++++++++++++----------- 1 file changed, 41 insertions(+), 11 deletions(-) diff --git a/pango/fonts.c b/pango/fonts.c index 2abe504e..4ffa0378 100644 --- a/pango/fonts.c +++ b/pango/fonts.c @@ -1215,17 +1215,47 @@ parse_variations (const char *word, * @str: string representation of a font description. * * Creates a new font description from a string representation in the - * form "[FAMILY-LIST] [STYLE-OPTIONS] [SIZE]", where FAMILY-LIST is a - * comma separated list of families optionally terminated by a comma, - * STYLE_OPTIONS is a whitespace separated list of words where each word - * describes one of style, variant, weight, stretch, or gravity, and SIZE - * is a decimal number (size in points) or optionally followed by the - * unit modifier "px" for absolute size. Any one of the options may - * be absent. If FAMILY-LIST is absent, then the family_name field of - * the resulting font description will be initialized to %NULL. If - * STYLE-OPTIONS is missing, then all style options will be set to the - * default values. If SIZE is missing, the size in the resulting font - * description will be set to 0. + * form + * + * "\[FAMILY-LIST] \[STYLE-OPTIONS] \[SIZE] \[VARIATIONS]", + * + * where FAMILY-LIST is a comma-separated list of families optionally + * terminated by a comma, STYLE_OPTIONS is a whitespace-separated list + * of words where each word describes one of style, variant, weight, + * stretch, or gravity, and SIZE is a decimal number (size in points) + * or optionally followed by the unit modifier "px" for absolute size. + * VARIATIONS is a comma-separated list of font variation + * specifications of the form "\@axis=value" (the = sign is optional). + * + * The following words are understood as styles: + * "Normal", "Roman", "Oblique", "Italic". + * + * The following words are understood as variants: + * "Small-Caps". + * + * The following words are understood as weights: + * "Thin", "Ultra-Light", "Extra-Light", "Light", "Semi-Light", + * "Demi-Light", "Book", "Regular", "Medium", "Semi-Bold", "Demi-Bold", + * "Bold", "Ultra-Bold", "Extra-Bold", "Heavy", "Black", "Ultra-Black", + * "Extra-Black". + * + * The following words are understood as stretch values: + * "Ultra-Condensed", "Extra-Condensed", "Condensed", "Semi-Condensed", + * "Semi-Expanded", "Expanded", "Extra-Expanded", "Ultra-Expanded". + * + * The following words are understood as gravity values: + * "Not-Rotated", "South", "Upside-Down", "North", "Rotated-Left", + * "East", "Rotated-Right", "West". + * + * Any one of the options may be absent. If FAMILY-LIST is absent, then + * the family_name field of the resulting font description will be + * initialized to %NULL. If STYLE-OPTIONS is missing, then all style + * options will be set to the default values. If SIZE is missing, the + * size in the resulting font description will be set to 0. + * + * A typical example: + * + * "Cantarell Italic Light 15 \@wght=200" * * Return value: a new #PangoFontDescription. **/ -- cgit v1.2.1