[pango/gi-docs] Add some links to the markdown docs

From: Matthias Clasen <matthiasc src gnome org>
To: commits-list gnome org
Cc:
Subject: [pango/gi-docs] Add some links to the markdown docs
Date: Fri, 12 Feb 2021 01:57:12 +0000 (UTC)
commit 0c702549ecd420e30046508d907181bdf87e559f
Author: Matthias Clasen <mclasen redhat com>
Date:   Thu Feb 11 20:52:01 2021 -0500

    Add some links to the markdown docs
    
    This is using gi-docgen's syntax for explicit links.

 docs/pango_bidi.md      |  27 ++++++------
 docs/pango_cairo.md     |  53 +++++++++++------------
 docs/pango_fonts.md     |  33 +++++++-------
 docs/pango_markup.md    | 112 +++++++++++++++++++++++-------------------------
 docs/pango_rendering.md |  27 ++++++------
 5 files changed, 121 insertions(+), 131 deletions(-)
---
diff --git a/docs/pango_bidi.md b/docs/pango_bidi.md
index bb330d12..b8e76183 100644
--- a/docs/pango_bidi.md
+++ b/docs/pango_bidi.md
@@ -7,7 +7,7 @@ Title: Bidirectional and Vertical Text
 Pango supports bidirectional text (like Arabic and Hebrew) automatically.
 Some applications however, need some help to correctly handle bidirectional text.
 
-The #PangoDirection type can be used with pango_context_set_base_dir() to
+The [enum@Pango.Direction] type can be used with pango_context_set_base_dir() to
 instruct Pango about direction of text, though in most cases Pango detects
 that correctly and automatically. For application that need more direct
 control over bidirectional setting of text, Pango provides APIs such as
@@ -24,36 +24,35 @@ The way this is implemented is through the concept of *gravity*. Gravity of
 normal Latin text is south. A gravity value of east means that glyphs will be
 rotated ninety degrees counterclockwise. So, to render vertical text one needs
 to set the gravity and rotate the layout using the matrix machinery already in
-place. This has the huge advantage that most algorithms working on a #PangoLayout
+place. This has the huge advantage that most algorithms working on a `PangoLayout`
 do not need any change as the assumption that lines run in the X direction and
 stack in the Y direction holds even for vertical text layouts.
 
-Applications should only need to set base gravity on #PangoContext in use, and
+Applications should only need to set base gravity on `PangoContext` in use, and
 let Pango decide the gravity assigned to each run of text. This automatically
 handles text with mixed scripts. A very common use is to set the context base
 gravity to auto using pango_context_set_base_gravity() and rotate the layout
 normally. Pango will make sure that Asian languages take the right form, while
 other scripts are rotated normally.
 
-The correct way to set gravity on a layout is to set it on the context
-associated with it using pango_context_set_base_gravity(). The context
-of a layout can be accessed using pango_layout_get_context(). The currently
-set base gravity of the context can be accessed using
-pango_context_get_base_gravity() and the *resolved* gravity of it using
-pango_context_get_gravity(). The resolved gravity is the same as the base
-gravity for the most part, except that if the base gravity is set to
-%PANGO_GRAVITY_AUTO, the resolved gravity will depend on the current matrix
+The correct way to set gravity on a layout is to set it on the context associated
+with it using pango_context_set_base_gravity(). The context of a layout can be
+accessed using pango_layout_get_context(). The currently set base gravity of the
+context can be accessed using pango_context_get_base_gravity() and the *resolved*
+gravity of it using pango_context_get_gravity(). The resolved gravity is the same
+as the base gravity for the most part, except that if the base gravity is set to
+`PANGO_GRAVITY_AUTO`, the resolved gravity will depend on the current matrix
 set on context, and is derived using pango_gravity_get_for_matrix().
 
 The next thing an application may want to set on the context is the
-*gravity hint*. A #PangoGravityHint instructs how different scripts should
+*gravity hint*. A `PangoGravityHint` instructs how different scripts should
 react to the set base gravity.
 
 Font descriptions have a gravity property too, that can be set using
 pango_font_description_set_gravity() and accessed using
 pango_font_description_get_gravity(). However, those are rarely useful
-from application code and are mainly used by #PangoLayout internally.
+from application code and are mainly used by `PangoLayout` internally.
 
-Last but not least, one can create #PangoAttributes for gravity
+Last but not least, one can create `PangoAttributes` for gravity
 and gravity hint using pango_attr_gravity_new() and
 pango_attr_gravity_hint_new().
diff --git a/docs/pango_cairo.md b/docs/pango_cairo.md
index 42e93b94..7299064f 100644
--- a/docs/pango_cairo.md
+++ b/docs/pango_cairo.md
@@ -4,34 +4,31 @@ Title: Rendering with Cairo
 
 # Rendering with Cairo
 
-The Cairo library is a vector graphics library with a powerful rendering
-model. It has such features as anti-aliased primitives, alpha-compositing,
-and gradients. Multiple backends for Cairo are available, to allow
-rendering to images, to PDF files, and to the screen on X and on other
-windowing systems. The functions in this section allow using Pango
-to render to Cairo surfaces.
-
-Using Pango with Cairo is straightforward. A #PangoContext created
-with pango_cairo_font_map_create_context() can be used on any
-Cairo context (cairo_t), but needs to be updated to match the
-current transformation matrix and target surface of the Cairo context
-using pango_cairo_update_context(). The convenience functions
-pango_cairo_create_layout() and pango_cairo_update_layout() handle
-the common case where the program doesn't need to manipulate the
-properties of the #PangoContext.
-
-When you get the metrics of a layout or of a piece of a layout using
-functions such as pango_layout_get_extents(), the reported metrics
-are in user-space coordinates. If a piece of text is 10 units long,
-and you call cairo_scale (cr, 2.0), it still is more-or-less 10
-units long. However, the results will be affected by hinting
-(that is, the process of adjusting the text to look good on the
-pixel grid), so you shouldn't assume they are completely independent
-of the current transformation matrix. Note that the basic metrics
-functions in Pango report results in integer Pango units. To get
-to the floating point units used in Cairo divide by %PANGO_SCALE.
-
-## Using Pango with Cairo ## {#rotated-example}
+The Cairo library is a vector graphics library with a powerful rendering model.
+It has such features as anti-aliased primitives, alpha-compositing, and gradients.
+Multiple backends for Cairo are available, to allow rendering to images, to PDF
+files, and to the screen on X and on other windowing systems. The functions in
+this section allow using Pango to render to Cairo surfaces.
+
+Using Pango with Cairo is straightforward. A `PangoContext` created with
+pango_cairo_font_map_create_context() can be used on any Cairo context (`cairo_t`),
+but needs to be updated to match the current transformation matrix and target
+surface of the Cairo context using pango_cairo_update_context(). The convenience
+functions pango_cairo_create_layout() and pango_cairo_update_layout() handle
+the common case where the program doesn't need to manipulate the properties of
+the `PangoContext`.
+
+When you get the metrics of a layout or of a piece of a layout using functions
+such as pango_layout_get_extents(), the reported metrics are in user-space
+coordinates. If a piece of text is 10 units long, and you call
+`cairo_scale (cr, 2.0)`, it still is more-or-less 10 units long. However, the
+results will be affected by hinting (that is, the process of adjusting the text
+to look good on the pixel grid), so you shouldn't assume they are completely
+independent of the current transformation matrix. Note that the basic metrics
+functions in Pango report results in integer Pango units. To get to the floating
+point units used in Cairo divide by `PANGO_SCALE`.
+
+## Using Pango with Cairo
 
 ```
 #include <math.h>
diff --git a/docs/pango_fonts.md b/docs/pango_fonts.md
index 72651fdf..3a2d22a6 100644
--- a/docs/pango_fonts.md
+++ b/docs/pango_fonts.md
@@ -5,7 +5,7 @@ Title: Fonts and Glyphs
 # Fonts
 
 Pango supports a flexible architecture where a particular rendering architecture
-can supply an implementation of fonts. The PangoFont structure represents an
+can supply an implementation of fonts. The `PangoFont` structure represents an
 abstract rendering-system-independent font. Pango provides routines to list
 available fonts, and to load a font matching a given description.
 
@@ -19,12 +19,13 @@ family, and "Helvetica Bold 12pt" is a concrete font of this face.
 # Font Enumeration
 
 The central object for dealing with the available fonts on a system and caching
-loaded fonts is a PangoFontMap. An application typically uses a single font map.
+loaded fonts is a [class@Pango.FontMap]. An application typically uses a single
+font map.
 
 Since the font map depends on the rendering architecture in use, you'll need to
 use the backend function pango_cairo_font_map_get_default() to obtain the default
-fontmap. Depending on the platform, it will return a PangoCairoFcFontMap, a
-PangoCairoWin32FontMap or a PangoCairoCoreTextFontMap.
+fontmap. Depending on the platform, it will return a `PangoCairoFcFontMap`, a
+`PangoCairoWin32FontMap` or a `PangoCairoCoreTextFontMap`.
 
 Once you have a fontmap, you can enumerate the available font families with
 pango_font_map_list_familiies(). To enumerate the faces of a font family, use
@@ -33,8 +34,8 @@ pango_font_family_list_faces().
 # Font Descriptions
 
 Since loading fonts uses system resources, Pango provides a way to describe
-a font without loading it. A #PangoFontDescription is a struct that contains
-enough information to load a concrete font with pango_font_map_load_font()
+a font without loading it. A [struct@Pango.FontDescription] is a struct that
+contains enough information to load a concrete font with pango_font_map_load_font()
 or pango_context_load_font(). You can obtain a font description from a
 font face using pango_font_face_describe(), or by parsing a string such as
 
@@ -45,19 +46,19 @@ with pango_font_description_from_string().
 # Glyphs
 
 A font provides information about glyphs and how to position and render them.
-The Pango rendering pipeline uses this information to create a #PangoGlyphString,
-which contains the glyphs corresponding to the characters in the text and related
-information such as glyph positions and sizes, and clustering information (i.e.
-which glyphs correspond to which characters).
+The Pango rendering pipeline uses this information to create a
+[struct@Pango.GlyphString], which contains the glyphs corresponding to the
+characters in the text and related information such as glyph positions and sizes,
+and clustering information (i.e. which glyphs correspond to which characters).
 
 ![A glyph string](rects3.png)
 
-A glyph is identified by a PangoGlyph, which is a numeric ID. Note that glyph
-IDs are font-specific: the same character can be represented by diffferent glyph
-IDs in different fonts.
+A glyph is identified by a [alias@Pango.Glyph], which is a numeric ID. Note that
+glyph IDs are font-specific: the same character can be represented by diffferent
+glyph IDs in different fonts.
 
 The mapping between characters and glyphs is in general neither 1-1 nor a map:
 a single glyph may represent multiple characters (as is the case with ligatures),
-a single character may be represented by multiple glyphs (for example, when combining
-accents and base character), and in complex scripts, multiple characters may form
-clusters that get rearranged and represented by multiple glyphs.
+a single character may be represented by multiple glyphs (for example, when
+combining accents and base character), and in complex scripts, multiple characters
+may form clusters that get rearranged and represented by multiple glyphs.
diff --git a/docs/pango_markup.md b/docs/pango_markup.md
index d009673a..0c9625af 100644
--- a/docs/pango_markup.md
+++ b/docs/pango_markup.md
@@ -4,39 +4,37 @@ 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 #PangoLayout.
+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.
+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
-#PangoAttrColor or #PangoAttrFontDesc. Each attribute has a type, and
-a start and end index that determine the range of characters that the
-attribute applies to. See the #PangoAttrType enumeration for all the
-possible attribute types.
+[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 #PangoAttrList structure
+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
-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.
+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 PangoAttrList
-using either of pango_parse_markup() or pango_markup_parser_new().
+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
+pango_parse_markup() or pango_markup_parser_new().
 
 A simple example of a marked-up string might be:
 
@@ -56,8 +54,8 @@ tags.
 
 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
+: 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.
@@ -68,12 +66,11 @@ face
 
 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 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
@@ -81,8 +78,8 @@ style
 
 font_weight
 weight
-: One of 'ultralight', 'light', 'normal', 'bold',
-  'ultrabold', 'heavy', or a numeric weight.
+: One of 'ultralight', 'light', 'normal', 'bold', 'ultrabold', 'heavy', or a
+  numeric weight.
 
 font_variant
 variant
@@ -95,58 +92,55 @@ stretch
   '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'`.
+: 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.
+: 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.
+: 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%'.
+: 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%'.
+: 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'.
+: 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.
+: 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'.
+: 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.
+: '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.
diff --git a/docs/pango_rendering.md b/docs/pango_rendering.md
index 6be4e8ad..2fd61e93 100644
--- a/docs/pango_rendering.md
+++ b/docs/pango_rendering.md
@@ -11,26 +11,25 @@ various stages of this pipeline and the APIs that implement them.
 ![Pango Rendering Pipeline](pipeline.png)
 
 Itemization
-: breaks a piece of text into segments with consistent direction
-  and shaping properies. Among other things, this determines which font to use
-  for each character. Use pango_itemize() or pango_itemize_with_base_dir()
-  to itemize text.
+: breaks a piece of text into segments with consistent direction and shaping
+  properies. Among other things, this determines which font to use for each
+  character. Use pango_itemize() or pango_itemize_with_base_dir() to itemize text.
 
 Shaping
-: converts characters into glyphs. Use pango_shape(), pango_shape_full()
-  or pango_shape_with_flags() to shape text.
+: converts characters into glyphs. Use pango_shape(), pango_shape_full() or
+  pango_shape_with_flags() to shape text.
 
 Line Breaking
-: determines where line breaks should be inserted into a sequence
-  of glyphs. The function pango_break() determines possible line breaks. The
-  actual line breaking is done by PangoLayout.
+: determines where line breaks should be inserted into a sequence of glyphs.
+  The function pango_break() determines possible line breaks. The actual line
+  breaking is done by [class@Pango.Layout].
 
 Justification
-: adjusts inter-word spacing to form lines of even length. This
-  is done by PangoLayout.
+: adjusts inter-word spacing to form lines of even length. This is done by
+  [class@Pango.Layout].
 
 Rendering
-: takes a string of positioned glyphs, and renders them onto a
-  surface. This is accomplished by a PangoRenderer object. The functions
+: takes a string of positioned glyphs, and renders them onto a surface. This is
+  accomplished by a [class@Pango.Renderer] object. The functions
   pango_cairo_show_glyph_string() and pango_cairo_show_layout() use a
-  PangoRenderer to draw text onto a cairo surface.
+  [class@Pango.Renderer] to draw text onto a cairo surface.
[Date Prev][Date Next] [Thread Prev][Thread Next] [Thread Index] [Date Index] [Author Index]