hexapdf 0.32.2 → 0.34.0

data/lib/hexapdf/content/canvas.rb

@@ -63,7 +63,7 @@ module HexaPDF
     # The PDF operators themselves are implemented as classes, see Operator. The canvas class uses
     # the Operator::BaseOperator#invoke and Operator::BaseOperator#serialize methods for applying
     # changes and serialization, with one exception: color setters don't invoke the corresponding
-    # operator implementation but directly work on the graphics state.
+    # operator implementation but work directly on the graphics state.
     #
     # === General Graphics State Manipulation Methods
     #
@@ -161,7 +161,7 @@ module HexaPDF
     # showing operators, and such groups of operators are allowed to be used only in certain
     # graphics objects or the page description level.
     #
-    # Have a look at the PDF specification (PDF1.7 s8.2) for more details.
+    # Have a look at the PDF specification (PDF2.0 s8.2) for more details.
     #
     # HexaPDF tries to ensure the proper use of the operators and graphics objects and if it
     # cannot do it, an error is raised. So if you don't modify a content stream directly but via
@@ -169,15 +169,20 @@ module HexaPDF
     #
     # === Graphics State
     #
-    # Some operators modify the so called graphics state (see Content::GraphicsState). The graphics
-    # state is a collection of settings that is used during processing or creating a content stream.
-    # For example, the path painting operators don't have operands to specify the line width or the
+    # Some operators modify the so called graphics state (see GraphicsState). The graphics state is
+    # a collection of settings that is used during processing or creating a content stream. For
+    # example, the path painting operators don't have operands to specify the line width or the
     # stroke color but take this information from the graphics state.
     #
     # One important thing about the graphics state is that it is only possible to restore a prior
     # state using the save and restore methods. It is not possible to reset the graphics state
     # while creating the content stream!
     #
+    # This means, for example, if you use a clipping path (see #clip_path) you should first save the
+    # graphics state (#save_graphics_state) and then restore it afterwards
+    # (#restore_graphics_state). Otherwise all following operations will be clipped to the clipping
+    # path.
+    #
     # === Paths
     #
     # A PDF path object consists of one or more subpaths. Each subpath can be a rectangle or can
@@ -200,7 +205,7 @@ module HexaPDF
     # In addition filling may be done using either the nonzero winding number rule or the even-odd
     # rule.
     #
-    # See: PDF1.7 s8, s9
+    # See: PDF2.0 s8, s9
     class Canvas
 
       include HexaPDF::Utils::MathHelpers
@@ -208,12 +213,20 @@ module HexaPDF
 
       # The context for which the canvas was created (a HexaPDF::Type::Page or HexaPDF::Type::Form
       # object).
+      #
+      # The context object is used for two things:
+      #
+      # * To store the resources (#resources) that are needed by the canvas (e.g. font references).
+      #
+      # * To access the HexaPDF::Document object to which this canvas and the context object
+      #   belongs. This is used internally but it is also useful in other situations since some
+      #   parts of HexaPDF only yield a canvas object, and not also the underlying document object.
       attr_reader :context
 
       # The serialized contents produced by the various canvas operations up to this point.
       #
       # Note that the returned string may not be a completely valid PDF content stream since a
-      # graphic object may be open or the graphics state not completely restored.
+      # graphic object may be open or the graphics state may not be completely restored.
       #
       # See: #stream_data
       attr_reader :contents
@@ -228,7 +241,7 @@ module HexaPDF
       # canvas!
       attr_reader :stream_data
 
-      # The Content::GraphicsState object containing the current graphics state.
+      # The GraphicsState object containing the current graphics state.
       #
       # The graphics state must not be changed directly, only by using the provided methods. If it
       # is changed directly, the output will not be correct.
@@ -236,7 +249,7 @@ module HexaPDF
 
       # The current graphics object.
       #
-      # The graphics object should not be changed directly. It is automatically updated by the
+      # The graphics object should not be changed directly! It is automatically updated by the
       # invoked methods.
       #
       # This attribute can have the following values:
@@ -246,13 +259,13 @@ module HexaPDF
       # :clipping_path:: The current graphics object is a clipping path.
       # :text:: The current graphics object is a text object.
       #
-      # See: PDF1.7 s8.2
+      # See: PDF2.0 s8.2
       attr_accessor :graphics_object
 
       # The current point [x, y] of the path.
       #
-      # This attribute holds the current point which is only valid if the current graphics objects
-      # is :path.
+      # This attribute holds the current point which is only valid if the current graphics object
+      # (see #graphic_object) is :path.
       #
       # When the current point changes, the array is modified in place instead of creating a new
       # array!
@@ -260,7 +273,8 @@ module HexaPDF
 
       # The operator name/implementation map used when invoking or serializing an operator.
       #
-      # Defaults to Content::Operator::DEFAULT_OPERATORS.
+      # Defaults to Operator::DEFAULT_OPERATORS, i.e. the standard implementation provided by
+      # HexaPDF.
       attr_reader :operators
 
       # Creates a new Canvas object for the given context object (either a HexaPDF::Type::Page or a
@@ -285,7 +299,7 @@ module HexaPDF
         @current_point = [0, 0]
         @start_point = [0, 0]
         @contents = ''.b
-        @stream_data = HexaPDF::StreamData.new do
+        source = HexaPDF::Filter.source_from_proc do
           case graphics_object
           when :path, :clipping_path then end_path
           when :text then end_text
@@ -293,6 +307,7 @@ module HexaPDF
           restore_graphics_state while graphics_state.saved_states?
           @contents
         end
+        @stream_data = HexaPDF::StreamData.new(source)
       end
 
       # Returns the resource dictionary of the context object.
@@ -302,11 +317,19 @@ module HexaPDF
         @context.resources
       end
 
+      # Returns the position (x,y) transformed by the current transformation matrix.
+      #
+      # The resulting position should be interpreted in terms of the coordinate system of the
+      # context object (e.g. the page or Form XObject).
+      def pos(x, y)
+        graphics_state.ctm.evaluate(x, y)
+      end
+
       # :call-seq:
       #   canvas.save_graphics_state              => canvas
       #   canvas.save_graphics_state { block }    => canvas
       #
-      # Saves the current graphics state and returns self.
+      # Saves the current graphics state and returns +self+.
       #
       # If invoked without a block a corresponding call to #restore_graphics_state must be done to
       # ensure proper nesting. Otherwise, i.e. when invoked with a block, the graphics state is
@@ -320,7 +343,7 @@ module HexaPDF
       #   #>pdf
       #   # With a block
       #   canvas.save_graphics_state do
-      #     canvas.stroke_color("red")                     # After the block the color is reset
+      #     canvas.stroke_color("hp-blue")             # After the block the color is reset
       #     canvas.line(20, 20, 70, 180).stroke
       #   end
       #   canvas.line(60, 20, 110, 180).stroke
@@ -332,7 +355,7 @@ module HexaPDF
       #     restore_graphics_state
       #   canvas.line(140, 20, 190, 180).stroke
       #
-      # See: PDF1.7 s8.4.2, #restore_graphics_state
+      # See: PDF2.0 s8.4.2, #restore_graphics_state
       def save_graphics_state
         raise_unless_at_page_description_level
         invoke0(:q)
@@ -347,11 +370,20 @@ module HexaPDF
       # :call-seq:
       #   canvas.restore_graphics_state      => canvas
       #
-      # Restores the current graphics state and returns self.
+      # Restores the graphics state to the last saved version and returns +self+.
       #
       # Must not be invoked more times than #save_graphics_state.
       #
-      # See: PDF1.7 s8.4.2, #save_graphics_state
+      # Example:
+      #
+      #   #>pdf
+      #   canvas.save_graphics_state
+      #   canvas.circle(100, 100, 50).clip_path.end_path
+      #   canvas.fill_color("hp-blue").rectangle(0, 0, 100, 100).fill
+      #   canvas.restore_graphics_state
+      #   canvas.rectangle(100, 0, 100, 100).fill
+      #
+      # See: PDF2.0 s8.4.2, #save_graphics_state
       def restore_graphics_state
         raise_unless_at_page_description_level
         invoke0(:Q)
@@ -363,7 +395,7 @@ module HexaPDF
       #   canvas.transform(a, b, c, d, e, f)              => canvas
       #   canvas.transform(a, b, c, d, e, f) { block }    => canvas
       #
-      # Transforms the user space by applying the given matrix to the current transformation
+      # Transforms the coordinate system by applying the given matrix to the current transformation
       # matrix and returns self.
       #
       # If invoked with a block, the transformation is only active during the block by saving and
@@ -375,16 +407,16 @@ module HexaPDF
       #   c d 0
       #   e f 1
       #
-      # Examples:
+      # Example:
       #
       #   #>pdf
       #   canvas.transform(1, 0, 0, 1, 100, 100) do  # Translate origin to (100, 100)
-      #     canvas.stroke_color("red").
+      #     canvas.stroke_color("hp-blue").
       #       line(0, 0, 100, 50).stroke             # Actually from (100, 100) to (200, 150)
       #   end
       #   canvas.line(0, 0, 100, 50).stroke          # Really from (0, 0) to (100, 50)
       #
-      # See: PDF1.7 s8.3, s8.4.4
+      # See: PDF2.0 s8.3, s8.4.4
       def transform(a, b, c, d, e, f)
         raise_unless_at_page_description_level
         save_graphics_state if block_given?
@@ -400,30 +432,31 @@ module HexaPDF
       #   canvas.rotate(angle, origin: nil)               => canvas
       #   canvas.rotate(angle, origin: nil) { block }     => canvas
       #
-      # Rotates the user space +angle+ degrees around the coordinate system origin or around the
-      # given point and returns self.
+      # Rotates the coordinate system +angle+ degrees around the origin or around the given point
+      # and returns +self+.
       #
-      # If invoked with a block, the rotation of the user space is only active during the block by
-      # saving and restoring the graphics state.
+      # If invoked with a block, the rotation of the coordinate system is only active during the
+      # block by saving and restoring the graphics state.
       #
       # Note that the origin of the coordinate system itself doesn't change even if the +origin+
       # argument is given!
       #
       # origin::
-      #   The point around which the user space should be rotated.
+      #   The point around which the coordinate system should be rotated.
       #
       # Examples:
       #
       #   #>pdf-center
-      #   canvas.stroke_color("lightgrey").
-      #     rectangle(0, 0, 60, 40).stroke
+      #   canvas.stroke_color("hp-gray-light").
+      #     rectangle(0, 0, 60, 40).stroke           # The rectangle that gets rotated
+      #
       #   canvas.rotate(45) do                       # Positive x-axis pointing to top-right corner
-      #     canvas.stroke_color("red").
+      #     canvas.stroke_color("hp-blue").
       #       rectangle(0, 0, 60, 40).stroke
       #   end
       #
       #   canvas.rotate(-45, origin: [-50, -50]) do  # Rotate around (-50,-50)
-      #     canvas.stroke_color("blue").
+      #     canvas.stroke_color("hp-orange").
       #       rectangle(0, 0, 60, 40).stroke
       #   end
       #
@@ -443,8 +476,8 @@ module HexaPDF
       #   canvas.scale(sx, sy = sx, origin: nil)              => canvas
       #   canvas.scale(sx, sy = sx, origin: nil) { block }    => canvas
       #
-      # Scales the user space +sx+ units in the horizontal and +sy+ units in the vertical
-      # direction and returns self. If the optional +origin+ is specified, scaling is done from
+      # Scales the coordinate system +sx+ units in the horizontal and +sy+ units in the vertical
+      # direction and returns +self+. If the optional +origin+ is specified, scaling is done from
       # that point.
       #
       # If invoked with a block, the scaling is only active during the block by saving and
@@ -454,20 +487,21 @@ module HexaPDF
       # argument is given!
       #
       # origin::
-      #   The point from which the user space should be scaled.
+      #   The point from which the coordinate system should be scaled.
       #
       # Examples:
       #
       #   #>pdf-center
-      #   canvas.stroke_color("lightgrey").
-      #     rectangle(10, 10, 10, 10).stroke
+      #   canvas.stroke_color("hp-gray-light").
+      #     rectangle(10, 10, 10, 10).stroke        # The rectangle that gets scaled
+      #
       #   canvas.scale(4, 2) do                     # Scale from origin
-      #     canvas.stroke_color("blue").
+      #     canvas.stroke_color("hp-blue").
       #       rectangle(10, 10, 10, 10).stroke      # Actually (40, 20) to (80, 40)
       #   end
       #
       #   canvas.scale(-2, 4, origin: [10, 10]) do  # Scale from (10, 10)
-      #     canvas.stroke_color("red").
+      #     canvas.stroke_color("hp-orange").
       #       rectangle(10, 10, 10, 10).stroke      # Actually (10, 10) to (-10, 40)
       #   end
       #
@@ -484,18 +518,19 @@ module HexaPDF
       #   canvas.translate(x, y)               => canvas
       #   canvas.translate(x, y) { block }     => canvas
       #
-      # Translates the user space coordinate system origin to the given +x+ and +y+ coordinates
-      # and returns self.
+      # Translates the coordinate system coordinate system origin to the given +x+ and +y+
+      # coordinates and returns +self+.
       #
-      # If invoked with a block, the translation of the user space is only active during the block
-      # by saving and restoring the graphics state.
+      # If invoked with a block, the translation of the coordinate system is only active during the
+      # block by saving and restoring the graphics state.
       #
       # Examples:
       #
       #   #>pdf-center
-      #   canvas.rectangle(0, 0, 40, 20).stroke     # Rectangle from (0, 0) to (40, 20)
+      #   canvas.stroke_color("hp-gray-light").
+      #     rectangle(0, 0, 40, 20).stroke          # Rectangle from (0, 0) to (40, 20)
       #   canvas.translate(50, 50) do               # Origin is now at (50, 50)
-      #     canvas.stroke_color("red").
+      #     canvas.stroke_color("hp-blue").
       #       rectangle(0, 0, 40, 20).stroke        # Actually (50, 50) to (90, 70)
       #   end
       #
@@ -508,7 +543,7 @@ module HexaPDF
       #   canvas.skew(a, b, origin: nil)               => canvas
       #   canvas.skew(a, b, origin: nil) { block }     => canvas
       #
-      # Skews the the x-axis by +a+ degrees and the y-axis by +b+ degress and returns self. If the
+      # Skews the the x-axis by +a+ degrees and the y-axis by +b+ degress and returns +self+. If the
       # optional +origin+ is specified, skewing is done from that point.
       #
       # If invoked with a block, the skewing is only active during the block by saving and
@@ -522,15 +557,16 @@ module HexaPDF
       # Examples:
       #
       #   #>pdf-center
-      #   canvas.stroke_color("lightgrey").
-      #     rectangle(10, 10, 40, 20).stroke
+      #   canvas.stroke_color("hp-gray-light").
+      #     rectangle(10, 10, 40, 20).stroke      # The rectangle that gets skewed
+      #
       #   canvas.skew(0, 30) do                   # Point (10, 10) is now actually (15, 10)
-      #     canvas.stroke_color("blue").
+      #     canvas.stroke_color("hp-blue").
       #       rectangle(10, 10, 40, 20).stroke    # Now a parallelogram
       #   end
       #
       #   canvas.skew(30, 30, origin: [-50, 50]) do  # Skew from (-50, 50)
-      #     canvas.stroke_color("red").
+      #     canvas.stroke_color("hp-orange").
       #       rectangle(-50, 50, 20, 20).stroke
       #   end
       #
@@ -553,9 +589,15 @@ module HexaPDF
       #
       # The line width determines the thickness of a stroked path.
       #
-      # Returns the current line width (see Content::GraphicsState#line_width) when no argument is
-      # given. Otherwise sets the line width to the given +width+ and returns self. The setter
-      # version can also be called in the line_width= form.
+      # Note that half the line width lies on either side of the path. For example, if a path from
+      # (0, 0) to (0, 100) is drawn with a line width of 20, the stroked path is actually 20 units
+      # wide, from -10 to 10. And if a rectangle is drawn stroked, but not filled, from (20, 20)
+      # with a width and height of 20 and a line width of 10, the "inside" of the rectangle would
+      # only be from (25, 25) to (35, 35). Also see the examples below.
+      #
+      # Returns the current line width (see GraphicsState#line_width) when no argument is given.
+      # Otherwise sets the line width to the given +width+ and returns +self+. The setter version
+      # can also be called in the line_width= form.
       #
       # If the +width+ and a block are provided, the changed line width is only active during the
       # block by saving and restoring the graphics state.
@@ -564,19 +606,22 @@ module HexaPDF
       #
       #   #>pdf
       #   canvas.line_width(10).
-      #     line(10, 10, 10, 190).stroke
+      #     line(10, 100, 10, 190).stroke
       #   canvas.line_width          # => 10
       #   canvas.line_width = 5      # => 5
-      #   canvas.line(60, 10, 60, 190).stroke
+      #   canvas.line(60, 100, 60, 190).stroke
       #
       #   canvas.line_width(10) do
       #     canvas.line_width        # => 10
-      #     canvas.line(110, 10, 110, 190).stroke
+      #     canvas.line(110, 100, 110, 190).stroke
       #   end
       #   canvas.line_width          # => 5
-      #   canvas.line(160, 10, 160, 190).stroke
+      #   canvas.line(160, 100, 160, 190).stroke
       #
-      # See: PDF1.7 s8.4.3.2
+      #   canvas.line_width(10).rectangle(20, 20, 20, 20).stroke      # The rectangle
+      #   canvas.fill_color("hp-blue").rectangle(25, 25, 10, 10).fill # The inside
+      #
+      # See: PDF2.0 s8.4.3.2
       def line_width(width = nil, &block)
         gs_getter_setter(:line_width, :w, width, &block)
       end
@@ -587,7 +632,7 @@ module HexaPDF
       #   canvas.line_cap_style(style)             => canvas
       #   canvas.line_cap_style(style) { block }   => canvas
       #
-      # The line cap style specifies how the ends of stroked open paths should look like.
+      # The line cap style specifies how the ends of stroked, open paths should look like.
       #
       # The +style+ parameter can be one of (also see LineCapStyle):
       #
@@ -598,11 +643,11 @@ module HexaPDF
       # :projecting_square or 2::
       #     The stroke continues half the line width beyond the endpoint of a path.
       #
-      # Note that the return value is always a normalized line cap style.
+      # Note that the return value is always a normalized line cap style (i.e. a NamedValue).
       #
-      # Returns the current line cap style (see Content::GraphicsState#line_cap_style) when no
-      # argument is given. Otherwise sets the line cap style to the given +style+ and returns self.
-      # The setter version can also be called in the line_cap_style= form.
+      # Returns the current line cap style (see GraphicsState#line_cap_style) when no argument is
+      # given. Otherwise sets the line cap style to the given +style+ and returns +self+. The setter
+      # version can also be called in the line_cap_style= form.
       #
       # If the +style+ and a block are provided, the changed line cap style is only active during
       # the block by saving and restoring the graphics state.
@@ -628,7 +673,7 @@ module HexaPDF
       #        line(50 + index * 50, 30, 50 + index * 50, 170).stroke
       #   end
       #
-      # See: PDF1.7 s8.4.3.3, Content::LineCapStyle
+      # See: PDF2.0 s8.4.3.3, Content::LineCapStyle
       def line_cap_style(style = nil, &block)
         gs_getter_setter(:line_cap_style, :J, style && LineCapStyle.normalize(style), &block)
       end
@@ -651,11 +696,11 @@ module HexaPDF
       #     The two segments are finished with butt caps and the space between the ends is filled
       #     with a triangle.
       #
-      # Note that the return value is always a normalized line join style.
+      # Note that the return value is always a normalized line join style (i.e. a NamedValue).
       #
-      # Returns the current line join style (see Content::GraphicsState#line_join_style) when no
-      # argument is given. Otherwise sets the line join style to the given +style+ and returns self.
-      # The setter version can also be called in the line_join_style= form.
+      # Returns the current line join style (see GraphicsState#line_join_style) when no argument is
+      # given. Otherwise sets the line join style to the given +style+ and returns +self+. The
+      # setter version can also be called in the line_join_style= form.
       #
       # If the +style+ and a block are provided, the changed line join style is only active during
       # the block by saving and restoring the graphics state.
@@ -681,7 +726,7 @@ module HexaPDF
       #        polyline(20 + index * 60, 30, 40 + index * 60, 170, 60 + index * 60, 30).stroke
       #   end
       #
-      # See: PDF1.7 s8.4.3.4, Content::LineJoinStyle
+      # See: PDF2.0 s8.4.3.4, Content::LineJoinStyle
       def line_join_style(style = nil, &block)
         gs_getter_setter(:line_join_style, :j, style && LineJoinStyle.normalize(style), &block)
       end
@@ -696,9 +741,9 @@ module HexaPDF
       # mitered line joins (see #line_join_style). When the limit is exceeded, a bevel join is
       # used instead of a miter join.
       #
-      # Returns the current miter limit (see Content::GraphicsState#miter_limit) when no argument is
-      # given. Otherwise sets the miter limit to the given +limit+ and returns self. The setter
-      # version can also be called in the miter_limit= form.
+      # Returns the current miter limit (see GraphicsState#miter_limit) when no argument is given.
+      # Otherwise sets the miter limit to the given +limit+ and returns +self+. The setter version
+      # can also be called in the miter_limit= form.
       #
       # If the +limit+ and a block are provided, the changed miter limit is only active during the
       # block by saving and restoring the graphics state.
@@ -722,7 +767,7 @@ module HexaPDF
       #                                     60 + index * 80, 30).stroke
       #   end
       #
-      # See: PDF1.7 s8.4.3.5
+      # See: PDF2.0 s8.4.3.5
       def miter_limit(limit = nil, &block)
         gs_getter_setter(:miter_limit, :M, limit, &block)
       end
@@ -740,7 +785,7 @@ module HexaPDF
       #
       # There are multiple ways to set the line dash pattern:
       #
-      # * By providing a Content::LineDashPattern object
+      # * By providing a LineDashPattern object
       # * By providing a single Integer/Float that is used for both dashes and gaps
       # * By providing an array of Integers/Floats that specify the alternating dashes and gaps
       #
@@ -749,10 +794,10 @@ module HexaPDF
       #
       # A solid line can be achieved by using 0 for the length or by using an empty array.
       #
-      # Returns the current line dash pattern (see Content::GraphicsState#line_dash_pattern) when no
-      # argument is given. Otherwise sets the line dash pattern using the given arguments and
-      # returns self. The setter version can also be called in the line_dash_pattern= form (but only
-      # without the second argument!).
+      # Returns the current line dash pattern (a LineDashPattern object, see
+      # GraphicsState#line_dash_pattern) when no argument is given. Otherwise sets the line dash
+      # pattern using the given arguments and returns +self+. The setter version can also be called
+      # in the line_dash_pattern= form (but only without the second argument!).
       #
       # If arguments and a block are provided, the changed line dash pattern is only active during
       # the block by saving and restoring the graphics state.
@@ -778,7 +823,7 @@ module HexaPDF
       #        stroke
       #   end
       #
-      # See: PDF1.7 s8.4.3.5, LineDashPattern
+      # See: PDF2.0 s8.4.3.5, LineDashPattern
       def line_dash_pattern(value = nil, phase = 0, &block)
         gs_getter_setter(:line_dash_pattern, :d, value && LineDashPattern.normalize(value, phase),
                          &block)
@@ -799,9 +844,9 @@ module HexaPDF
       # * +:Saturation+
       # * +:Perceptual+
       #
-      # Returns the current rendering intent (see Content::GraphicsState#rendering_intent) when no
-      # argument is given. Otherwise sets the rendering intent using the +intent+ argument and
-      # returns self. The setter version can also be called in the rendering_intent= form.
+      # Returns the current rendering intent (see GraphicsState#rendering_intent) when no argument
+      # is given. Otherwise sets the rendering intent using the +intent+ argument and returns
+      # +self+. The setter version can also be called in the rendering_intent= form.
       #
       # If the +intent+ and a block are provided, the changed rendering intent is only active
       # during the block by saving and restoring the graphics state.
@@ -817,7 +862,7 @@ module HexaPDF
       #   end
       #   canvas.rendering_intent                      # => :Saturation
       #
-      # See: PDF1.7 s8.6.5.8, RenderingIntent
+      # See: PDF2.0 s8.6.5.8, RenderingIntent
       def rendering_intent(intent = nil, &bk)
         gs_getter_setter(:rendering_intent, :ri, intent && RenderingIntent.normalize(intent), &bk)
       end
@@ -837,23 +882,30 @@ module HexaPDF
       #
       # There are several ways to define the color that should be used:
       #
-      # * A single numeric argument specifies a gray color (see
-      #   Content::ColorSpace::DeviceGray::Color).
-      # * Three numeric arguments specify an RGB color (see Content::ColorSpace::DeviceRGB::Color).
+      # * A single numeric argument specifies a gray color (see ColorSpace::DeviceGray::Color).
+      #
+      # * Three numeric arguments specify an RGB color (see ColorSpace::DeviceRGB::Color).
+      #
       # * A string in the format "RRGGBB" where "RR" is the hexadecimal number for the red, "GG"
       #   for the green and "BB" for the blue color value also specifies an RGB color.
+      #
       # * As does a string in the format "RGB" where "RR", "GG" and "BB" would be used as the
       #   hexadecimal numbers for the red, green and blue color values of an RGB color.
-      # * Any other string is treated as a CSS Color Module Level 3 color name, see
-      #   https://www.w3.org/TR/css-color-3/#svg-color.
-      # * Four numeric arguments specify a CMYK color (see Content::ColorSpace::DeviceCMYK::Color).
+      #
+      # * Any other string is treated as a color name. HexaPDF supports CSS Color Module Level 3
+      #   color names (see https://www.w3.org/TR/css-color-3/#svg-color) as well as HexaPDF design
+      #   colors.
+      #
+      # * Four numeric arguments specify a CMYK color (see ColorSpace::DeviceCMYK::Color).
+      #
       # * A color object is used directly (normally used for color spaces other than DeviceRGB,
       #   DeviceCMYK and DeviceGray).
+      #
       # * An array is treated as if its items were specified separately as arguments.
       #
-      # Returns the current stroke color (see Content::GraphicsState#stroke_color) when no argument
-      # is given. Otherwise sets the stroke color using the given arguments and returns self. The
-      # setter version can also be called in the stroke_color= form.
+      # Returns the current stroke color (see GraphicsState#stroke_color) when no argument is given.
+      # Otherwise sets the stroke color using the given arguments and returns +self+. The setter
+      # version can also be called in the stroke_color= form.
       #
       # If the arguments and a block are provided, the changed stroke color is only active during
       # the block by saving and restoring the graphics state.
@@ -896,7 +948,7 @@ module HexaPDF
       #     canvas.stroke_color                      # => ColorSpace::DeviceGray.color(0.4)
       #   end
       #
-      # See: PDF1.7 s8.6, ColorSpace
+      # See: PDF2.0 s8.6, ColorSpace
       def stroke_color(*color, &block)
         color_getter_setter(:stroke_color, color, :RG, :G, :K, :CS, :SCN, &block)
       end
@@ -922,10 +974,10 @@ module HexaPDF
       # the fill alpha value applies not just to fill values but to all non-stroking operations
       # (e.g. images, ...).
       #
-      # Returns the current fill alpha (see Content::GraphicsState#fill_alpha) and stroke alpha (see
-      # Content::GraphicsState#stroke_alpha) values using a hash with the keys +:fill_alpha+ and
+      # Returns the current fill alpha (see GraphicsState#fill_alpha) and stroke alpha (see
+      # GraphicsState#stroke_alpha) values using a hash with the keys +:fill_alpha+ and
       # +:stroke_alpha+ when no argument is given. Otherwise sets the fill and stroke alpha values
-      # and returns self. The setter version can also be called in the #opacity= form.
+      # and returns +self+. The setter version can also be called in the #opacity= form.
       #
       # If the values are set and a block is provided, the changed alpha values are only active
       # during the block by saving and restoring the graphics state.
@@ -944,15 +996,15 @@ module HexaPDF
       #   canvas.opacity                               # => {fill_alpha: 0.4, stroke_alpha: 0.9}
       #
       #   # visual example
-      #   canvas.opacity(fill_alpha: 1, stroke_alpha: 1) do   # background rectangle on right side
-      #     canvas.fill_color("lightgrey").rectangle(100, 0, 100, 200).fill
-      #   end
+      #   canvas.opacity(fill_alpha: 1, stroke_alpha: 1)
+      #   canvas.fill_color("hp-gray-light").                 # background rectangle on right side
+      #     rectangle(100, 0, 100, 200).fill
       #   canvas.opacity(fill_alpha: 0.5, stroke_alpha: 0.8). # foreground rectangle, with a thick
       #     line_width(20).                                   # stroke that also overlays the
-      #     fill_color("red").stroke_color("blue").           # inside of the rectangle, creating
+      #     fill_color("hp-blue").stroke_color("hp-blue").    # inside of the rectangle, creating
       #     rectangle(20, 20, 160, 160).fill_stroke           # multiple shadings due to opacity
       #
-      # See: PDF1.7 s11.6.4.4
+      # See: PDF2.0 s11.6.4.4
       def opacity(fill_alpha: nil, stroke_alpha: nil)
         if !fill_alpha.nil? || !stroke_alpha.nil?
           raise_unless_at_page_description_level_or_in_text
@@ -981,14 +1033,14 @@ module HexaPDF
       #   canvas.move_to(x, y)       => canvas
       #
       # Begins a new subpath (and possibly a new path) by moving the current point to the given
-      # point.
+      # point and returns +self+.
       #
       # Examples:
       #
       #   canvas.move_to(10, 50)
       #   canvas.current_point         # => [10, 50]
       #
-      # See: PDF1.7 s8.5.2.1
+      # See: PDF2.0 s8.5.2.1, #line_to, #curve_to, #rectangle
       def move_to(x, y)
         raise_unless_at_page_description_level_or_in_path
         invoke2(:m, x, y)
@@ -1001,17 +1053,20 @@ module HexaPDF
       #   canvas.line_to(x, y)       => canvas
       #
       # Appends a straight line segment from the current point to the given point (which becomes the
-      # new current point) to the current subpath.
+      # new current point) to the current subpath and returns +self+.
+      #
+      # If there is no current path when the method is invoked, an error is raised since a valid
+      # current point (#current_point) is needed.
       #
       # Examples:
       #
       #   #>pdf-center
-      #   canvas.move_to(10, 50).
-      #     line_to(80, 80)
-      #   canvas.current_point          # => [80, 80]
+      #   canvas.move_to(10, 50)
+      #   canvas.line_to(80, 80)
+      #   canvas.current_point                      # => [80, 80]
       #   canvas.stroke
       #
-      # See: PDF1.7 s8.5.2.1
+      # See: PDF2.0 s8.5.2.1, #move_to, #curve_to, #rectangle
       def line_to(x, y)
         raise_unless_in_path
         invoke2(:l, x, y)
@@ -1025,8 +1080,11 @@ module HexaPDF
       #   canvas.curve_to(x, y, p1:)            => canvas
       #   canvas.curve_to(x, y, p2:)            => canvas
       #
-      # Appends a cubic Bezier curve to the current subpath starting from the current point. The end
-      # point becomes the new current point.
+      # Appends a cubic Bezier curve to the current subpath starting from the current point and
+      # returns +self+. The end point becomes the new current point.
+      #
+      # If there is no current path when the method is invoked, an error is raised since a valid
+      # current point (#current_point) is needed.
       #
       # A Bezier curve consists of the start point, the end point and the two control points +p1+
       # and +p2+. The start point is always the current point and the end point is specified as the
@@ -1047,7 +1105,7 @@ module HexaPDF
       #   canvas.current_point                        # => [-30, 60]
       #   canvas.stroke
       #
-      # See: PDF1.7 s8.5.2.2
+      # See: PDF2.0 s8.5.2.2, #move_to, #line_to, #rectangle
       def curve_to(x, y, p1: nil, p2: nil)
         raise_unless_in_path
         if p1 && p2
@@ -1069,10 +1127,13 @@ module HexaPDF
       #
       # Appends a rectangle to the current path as a complete subpath (drawn in counterclockwise
       # direction), with the bottom left corner specified by +x+ and +y+ and the given +width+ and
-      # +height+.
+      # +height+. Returns +self+.
       #
       # If +radius+ is greater than 0, the corners are rounded with the given radius.
       #
+      # Note that the rectangle degrades to a line if either width or height is zero and to nothing
+      # if both are zero.
+      #
       # If there is no current path when the method is invoked, a new path is automatically begun.
       #
       # The current point is set to the bottom left corner if +radius+ is zero, otherwise it is set
@@ -1083,10 +1144,10 @@ module HexaPDF
       #   #>pdf
       #   canvas.rectangle(10, 110, 80, 50).stroke
       #   canvas.rectangle(110, 110, 80, 50, radius: 10).stroke
-      #   canvas.rectangle(10, 10, 80, 0).stroke      # Degraded: Just a line
-      #   canvas.rectangle(110, 10, 0, 0).stroke      # Degraded: Draws nothing
+      #   canvas.rectangle(10, 90, 80, 0).stroke      # Degraded: Just a line
+      #   canvas.rectangle(110, 90, 0, 0).stroke      # Degraded: Draws nothing
       #
-      # See: PDF1.7 s8.5.2.1
+      # See: PDF2.0 s8.5.2.1, #move_to, #line_to, #curve_to
       def rectangle(x, y, width, height, radius: 0)
         raise_unless_at_page_description_level_or_in_path
         if radius == 0
@@ -1103,7 +1164,10 @@ module HexaPDF
       #   canvas.close_subpath      => canvas
       #
       # Closes the current subpath by appending a straight line from the current point to the
-      # start point of the subpath which also becomes the new current point.
+      # start point of the subpath which also becomes the new current point. Returns +self+.
+      #
+      # If there is no current path when the method is invoked, an error is raised since a valid
+      # current point (#current_point) is needed.
       #
       # Examples:
       #
@@ -1114,7 +1178,7 @@ module HexaPDF
       #     close_subpath.           # Draws the line from (60, 60) to (10, 10)
       #     stroke
       #
-      # See: PDF1.7 s8.5.2.1
+      # See: PDF2.0 s8.5.2.1
       def close_subpath
         raise_unless_in_path
         invoke0(:h)
@@ -1126,13 +1190,16 @@ module HexaPDF
       #   canvas.line(x0, y0, x1, y1)        => canvas
       #
       # Moves the current point to (x0, y0) and appends a line to (x1, y1) to the current path.
+      # Returns +self+.
       #
-      # This method is equal to "canvas.move_to(x0, y0).line_to(x1, y1)".
+      # If there is no current path when the method is invoked, a new path is automatically begun.
       #
       # Examples:
       #
       #   #>pdf
       #   canvas.line(10, 10, 100, 100).stroke
+      #
+      # See: #move_to, #line_to
       def line(x0, y0, x1, y1)
         move_to(x0, y0)
         line_to(x1, y1)
@@ -1143,12 +1210,16 @@ module HexaPDF
       #
       # Moves the current point to (x0, y0) and appends line segments between all given
       # consecutive points, i.e. between (x0, y0) and (x1, y1), between (x1, y1) and (x2, y2) and
-      # so on. The last point becomes the new current point.
+      # so on. The last point becomes the new current point. Returns +self+.
+      #
+      # If there is no current path when the method is invoked, a new path is automatically begun.
       #
       # Examples:
       #
       #   #>pdf
       #   canvas.polyline(50, 50, 150, 50, 150, 150, 50, 150, 50, 50).stroke
+      #
+      # See: #move_to, #line_to, #polygon
       def polyline(*points)
         check_poly_points(points)
         move_to(points[0], points[1])
@@ -1163,8 +1234,8 @@ module HexaPDF
       # :call-seq:
       #   canvas.polygon(x0, y0, x1, y1, x2, y2, ..., radius: 0)          => canvas
       #
-      # Appends a polygon consisting of the given points to the path as a complete subpath. The
-      # point (x0, y0 + radius) becomes the new current point.
+      # Appends a polygon consisting of the given points to the path as a complete subpath and
+      # returns +self+. The point (x0, y0 + radius) becomes the new current point.
       #
       # If +radius+ is greater than 0, the corners are rounded with the given radius.
       #
@@ -1174,8 +1245,10 @@ module HexaPDF
       #
       #   #>pdf
       #   canvas.polygon(10, 10, 90, 10, 70, 90, 20, 100).stroke
-      #   canvas.stroke_color("red").
+      #   canvas.stroke_color("hp-blue").
       #     polygon(130, 130, 150, 100, 170, 150, 130, 190, radius: 10).stroke
+      #
+      # See: #polyline
       def polygon(*points, radius: 0)
         if radius == 0
           polyline(*points)
@@ -1195,16 +1268,19 @@ module HexaPDF
       #
       # Appends a circle with center (cx, cy) and the given radius (in degrees) to the path as a
       # complete subpath (drawn in counterclockwise direction). The point (center_x + radius,
-      # center_y) becomes the new current point.
+      # center_y) becomes the new current point. Returns +self+.
       #
       # If there is no current path when the method is invoked, a new path is automatically begun.
       #
       # Examples:
       #
       #   #>pdf
-      #   canvas.circle(100, 100, 30).stroke
+      #   canvas.circle(100, 100, 30)
+      #   cp = canvas.current_point
+      #   canvas.stroke
+      #   canvas.stroke_color("hp-orange").line(*cp, 180, 100).stroke
       #
-      # See: #arc (for approximation accuracy)
+      # See: #arc (for approximation accuracy), #ellipse
       def circle(cx, cy, radius)
         arc(cx, cy, a: radius)
         close_subpath
@@ -1215,7 +1291,8 @@ module HexaPDF
       #
       # Appends an ellipse with center (cx, cy), semi-major axis +a+, semi-minor axis +b+ and an
       # inclination from the x-axis of +inclination+ degrees to the path as a complete subpath. The
-      # outer-most point on the semi-major axis becomes the new current point.
+      # outer-most point on the positive semi-major axis becomes the new current point. Returns
+      # self.
       #
       # If there is no current path when the method is invoked, a new path is automatically begun.
       #
@@ -1225,11 +1302,15 @@ module HexaPDF
       #   # Ellipse aligned to x-axis and y-axis
       #   canvas.ellipse(50, 50, a: 20, b: 10).stroke
       #
-      #   # Inclined ellipse
-      #   canvas.stroke_color("red").
-      #     ellipse(150, 150, a: 20, b: 10, inclination: 30).stroke
+      #   # Inclined ellipse with line from the end point
+      #   canvas.stroke_color("hp-blue").
+      #     ellipse(150, 150, a: 20, b: 10, inclination: 30)
+      #   cp = canvas.current_point
+      #   x, y = 2 * canvas.current_point[0] - 150, 2 * canvas.current_point[1] - 150
+      #   canvas.stroke.
+      #     stroke_color("hp-orange").line(*cp, x, y).stroke
       #
-      # See: #arc (for approximation accuracy)
+      # See: #arc (for approximation accuracy), #circle
       def ellipse(cx, cy, a:, b:, inclination: 0)
         arc(cx, cy, a: a, b: b, inclination: inclination)
         close_subpath
@@ -1238,8 +1319,8 @@ module HexaPDF
       # :call-seq:
       #   canvas.arc(cx, cy, a:, b: a, start_angle: 0, end_angle: 360, clockwise: false, inclination: 0)   => canvas
       #
-      # Appends an elliptical arc to the path. The endpoint of the arc becomes the new current
-      # point.
+      # Appends an elliptical arc to the path and returns +self+. The endpoint of the arc becomes
+      # the new current point.
       #
       # +cx+::
       #   x-coordinate of the center point of the arc
@@ -1271,6 +1352,9 @@ module HexaPDF
       #
       # If there is no current path when the method is invoked, a new path is automatically begun.
       #
+      # This arc does *not* start from the current point (#current_point). If this functionality is
+      # needed, use #draw together with GraphicObject::EndpointArc.
+      #
       # Since PDF doesn't have operators for drawing elliptical or circular arcs, they have to be
       # approximated using Bezier curves (see #curve_to). The accuracy of the approximation can be
       # controlled using the configuration option 'graphic_object.arc.max_curves'.
@@ -1284,19 +1368,19 @@ module HexaPDF
       #   canvas.stroke
       #
       #   # Circular and elliptical arcs from 30 degrees to 160 degrees
-      #   canvas.stroke_color("red")
+      #   canvas.stroke_color("hp-blue")
       #   canvas.arc(50, 100, a: 10, start_angle: 30, end_angle: 160)
       #   canvas.arc(100, 100, a: 10, b: 5, start_angle: 30, end_angle: 160)
       #   canvas.stroke
       #
       #   # Arcs from 135 degrees to 30 degrees, the first in counterclockwise direction (i.e. the
       #   # big arc), the other in clockwise direction (i.e. the small arc)
-      #   canvas.stroke_color("blue")
+      #   canvas.stroke_color("hp-orange")
       #   canvas.arc(50, 50, a: 10, start_angle: 135, end_angle: 30)
       #   canvas.arc(100, 50, a: 10, start_angle: 135, end_angle: 30, clockwise: true)
       #   canvas.stroke
       #
-      # See: Content::GraphicObject::Arc
+      # See: #arc, #circle, #ellipse, GraphicObject::Arc, GraphicObject::EndpointArc
       def arc(cx, cy, a:, b: a, start_angle: 0, end_angle: 360, clockwise: false, inclination: 0)
         arc = GraphicObject::Arc.configure(cx: cx, cy: cy, a: a, b: b,
                                            start_angle: start_angle, end_angle: end_angle,
@@ -1314,18 +1398,18 @@ module HexaPDF
       # :call-seq:
       #   canvas.line_with_rounded_corner(x0 = current_point[0], y0 = current_point[1], x1, y1, x2, y2, in_radius:, out_radius: in_radius)
       #
-      # Appends a line with a rounded corner at (x1, y1) from the current point. The end point of
-      # the rounded corner (i.e. +out_radius+ units from (x1, y1) in the direction of (x2, y2))
-      # becomes the current point. In degraded cases the corner point (x1, y1) becomes the current
-      # point.
+      # Appends a line with a rounded corner at (x1, y1) from the current point and returns +self+.
+      # The end point of the rounded corner (i.e. +out_radius+ units from (x1, y1) in the direction
+      # of (x2, y2)) becomes the current point. In degraded cases the corner point (x1, y1) becomes
+      # the current point.
       #
       # The corner is specified by (x0, y0) which defaults to the #current_point of the path, (x1,
       # y1) and (x2, y2) - all of which need to be different points. The +in_radius+ specifies the
       # corner radius into the corner and the +out_radius+ the one out of the corner. Degraded
       # cases, like with (x0, y0) == (x1, y1), are handled gracefully.
       #
-      # There has to be a current path when this method is invoked. For example, the current point
-      # ould be estabilshed beforehand using #move_to.
+      # There has to be a current path when this method is invoked, otherwise an error is raised.
+      # For example, the current point could be estabilshed beforehand using #move_to.
       #
       # Examples:
       #
@@ -1338,10 +1422,15 @@ module HexaPDF
       #   canvas.line_with_rounded_corner(180, 120, 150, 100, in_radius: 0, out_radius: 10)
       #   canvas.stroke
       #
-      #   # Special effects when (x0, y0) is not the current point, like when the current point
-      #   # would be equal to the corner point
+      #   # Special effects when (x0, y0) is not the current point, like when the current
+      #   # point would be equal to the corner point. Rounded rectangle use this method
+      #   # internally, as high-lighted by the blue segment.
       #   canvas.rectangle(10, 10, 60, 60, radius: 60).stroke
-      #   canvas.rectangle(110, 10, 60, 60, radius: 70).stroke
+      #   canvas.stroke_color("hp-blue").
+      #     move_to(70, 10). # Start point at the end of the lower-left rounded corner
+      #     line_with_rounded_corner(10, 10, 70, 10, 70, 70, in_radius: 60).stroke
+      #   canvas.stroke_color("black").
+      #     rectangle(110, 10, 60, 60, radius: 70).stroke
       def line_with_rounded_corner(x0 = current_point[0], y0 = current_point[1], x1, y1, x2, y2,
                                    in_radius:, out_radius: in_radius)
         if in_radius == 0 || out_radius == 0
@@ -1367,9 +1456,9 @@ module HexaPDF
       #
       # Returns the named graphic object, configured with the given options.
       #
-      # If an object responding to :configure is given, it is used. Otherwise the graphic object
-      # is looked up via the given name in the configuration option 'graphic_object.map'. Then the
-      # graphic object is configured with the given options if at least one is given.
+      # If an object responding to :configure is given, it is used. Otherwise the graphic object is
+      # looked up via the given name in the configuration option 'graphic_object.map'. Either way,
+      # the graphic object is then configured with the given options if at least one is given.
       #
       # Examples:
       #
@@ -1378,7 +1467,7 @@ module HexaPDF
       #                               outer_a: 50, outer_b: 40, end_angle: 135)
       #   canvas.draw(obj).stroke
       #
-      # See: Content::GraphicObject
+      # See: #draw, GraphicObject
       def graphic_object(obj, **options)
         unless obj.respond_to?(:configure)
           obj = context.document.config.constantize('graphic_object.map', obj)
@@ -1404,7 +1493,7 @@ module HexaPDF
       # :call-seq:
       #   canvas.stroke    => canvas
       #
-      # Strokes the path.
+      # Strokes the path and returns +self+.
       #
       # Examples:
       #
@@ -1412,7 +1501,7 @@ module HexaPDF
       #   canvas.polyline(10, 10, 120, 40, 50, 160)
       #   canvas.stroke
       #
-      # See: PDF1.7 s8.5.3.1, s8.5.3.2
+      # See: PDF2.0 s8.5.3.1, s8.5.3.2, #close_stroke, #close_fill_stroke
       def stroke
         raise_unless_in_path_or_clipping_path
         invoke0(:S)
@@ -1422,7 +1511,7 @@ module HexaPDF
       # :call-seq:
       #   canvas.close_stroke    => canvas
       #
-      # Closes the last subpath and then strokes the path.
+      # Closes the last subpath and then strokes the path. Returns +self+.
       #
       # Examples:
       #
@@ -1430,7 +1519,7 @@ module HexaPDF
       #   canvas.polyline(10, 10, 120, 40, 50, 160)      # No line from the top to the left
       #   canvas.close_stroke
       #
-      # See: PDF1.7 s8.5.3.1, s8.5.3.2
+      # See: PDF2.0 s8.5.3.1, s8.5.3.2, #stroke, #close_fill_stroke
       def close_stroke
         raise_unless_in_path_or_clipping_path
         invoke0(:s)
@@ -1440,25 +1529,26 @@ module HexaPDF
       # :call-seq:
       #   canvas.fill(rule = :nonzero)    => canvas
       #
-      # Fills the path using the given rule.
+      # Fills the path using the given rule and returns +self+.
       #
       # The argument +rule+ may either be +:nonzero+ to use the nonzero winding number rule or
       # +:even_odd+ to use the even-odd rule for determining which regions to fill in. Details on
-      # how these rules work are found in the PDF 1.7 spec section 8.5.3.3 or via Internet search.
+      # how these rules work are found in the PDF 2.0 spec section 8.5.3.3 or via Internet search.
       #
       # Any open subpaths are implicitly closed before being filled.
       #
       # Examples:
       #
       #   #>pdf
-      #   canvas.polyline(20, 10, 90, 60, 10, 60, 80, 10, 50, 90)
-      #   canvas.fill
+      #   canvas.fill_color("hp-blue").
+      #     polyline(20, 10, 90, 60, 10, 60, 80, 10, 50, 90).
+      #     fill
       #
-      #   canvas.fill_color("red")
-      #   canvas.polyline(120, 110, 190, 160, 110, 160, 180, 110, 150, 190)
-      #   canvas.fill(:even_odd)
+      #   canvas.fill_color("hp-orange").
+      #     polyline(120, 110, 190, 160, 110, 160, 180, 110, 150, 190).
+      #     fill(:even_odd)
       #
-      # See: PDF1.7 s8.5.3.1, s8.5.3.3
+      # See: PDF2.0 s8.5.3.1, s8.5.3.3, #fill_stroke, #close_fill_stroke
       def fill(rule = :nonzero)
         raise_unless_in_path_or_clipping_path
         invoke0(rule == :nonzero ? :f : :'f*')
@@ -1468,26 +1558,27 @@ module HexaPDF
       # :call-seq:
       #   canvas.fill_stroke(rule = :nonzero)    => canvas
       #
-      # Fills and then strokes the path using the given rule.
+      # Fills and then strokes the path using the given rule. Returns +self+.
       #
       # The argument +rule+ may either be +:nonzero+ to use the nonzero winding number rule or
       # +:even_odd+ to use the even-odd rule for determining which regions to fill in. Details on
-      # how these rules work are found in the PDF 1.7 spec section 8.5.3.3 or via Internet search.
+      # how these rules work are found in the PDF 2.0 spec section 8.5.3.3 or via Internet search.
       #
-      # Note that any open subpaths are *not* closed!
+      # Note that any open subpaths are *not* closed concerning the stroking operation.
       #
       # Examples:
       #
       #   #>pdf
-      #   canvas.stroke_color("green").line_width(3)
-      #   canvas.polyline(20, 10, 90, 60, 10, 60, 80, 10, 50, 90)
-      #   canvas.fill_stroke                 # Note the missing stroke from the top corner
+      #   canvas.stroke_color("hp-orange").line_width(3)
+      #   canvas.fill_color("hp-blue").
+      #     polyline(20, 10, 90, 60, 10, 60, 80, 10, 50, 90).
+      #     fill_stroke                 # Note the missing stroke from the top corner
       #
-      #   canvas.fill_color("red")
-      #   canvas.polyline(120, 110, 190, 160, 110, 160, 180, 110, 150, 190)
-      #   canvas.fill_stroke(:even_odd)      # Note the missing stroke from the top corner
+      #   canvas.fill_color("hp-teal").
+      #     polyline(120, 110, 190, 160, 110, 160, 180, 110, 150, 190).
+      #     fill_stroke(:even_odd)      # Note the missing stroke from the top corner
       #
-      # See: PDF1.7 s8.5.3.1, s8.5.3.3
+      # See: PDF2.0 s8.5.3.1, s8.5.3.3, #fill, #close_fill_stroke
       def fill_stroke(rule = :nonzero)
         raise_unless_in_path_or_clipping_path
         invoke0(rule == :nonzero ? :B : :'B*')
@@ -1497,24 +1588,26 @@ module HexaPDF
       # :call-seq:
       #   canvas.close_fill_stroke(rule = :nonzero)    => canvas
       #
-      # Closes the last subpath and then fills and strokes the path using the given rule.
+      # Closes the last subpath and then fills and strokes the path using the given rule. Returns
+      # +self+.
       #
       # The argument +rule+ may either be +:nonzero+ to use the nonzero winding number rule or
       # +:even_odd+ to use the even-odd rule for determining which regions to fill in. Details on
-      # how these rules work are found in the PDF 1.7 spec section 8.5.3.3 or via Internet search.
+      # how these rules work are found in the PDF 2.0 spec section 8.5.3.3 or via Internet search.
       #
       # Examples:
       #
       #   #>pdf
-      #   canvas.stroke_color("green").line_width(3)
-      #   canvas.polyline(20, 10, 90, 60, 10, 60, 80, 10, 50, 90)
-      #   canvas.close_fill_stroke
+      #   canvas.stroke_color("hp-orange").line_width(3)
+      #   canvas.fill_color("hp-blue").
+      #     polyline(20, 10, 90, 60, 10, 60, 80, 10, 50, 90).
+      #     close_fill_stroke
       #
-      #   canvas.fill_color("red")
-      #   canvas.polyline(120, 110, 190, 160, 110, 160, 180, 110, 150, 190)
-      #   canvas.close_fill_stroke(:even_odd)
+      #   canvas.fill_color("hp-teal").
+      #     polyline(120, 110, 190, 160, 110, 160, 180, 110, 150, 190).
+      #     close_fill_stroke(:even_odd)
       #
-      # See: PDF1.7 s8.5.3
+      # See: PDF2.0 s8.5.3, #fill, #fill_stroke
       def close_fill_stroke(rule = :nonzero)
         raise_unless_in_path_or_clipping_path
         invoke0(rule == :nonzero ? :b : :'b*')
@@ -1524,17 +1617,17 @@ module HexaPDF
       # :call-seq:
       #   canvas.end_path     => canvas
       #
-      # Ends the path without stroking or filling it.
+      # Ends the path without stroking or filling it and returns +self+.
       #
-      # This method is normally used in conjunction with the clipping path methods to define the
-      # clipping.
+      # This method is usually used in conjunction with the clipping path methods to define the
+      # clipping path.
       #
       # Examples:
       #
       #   canvas.line(10, 10, 100, 100)
       #   canvas.end_path                    # Nothing to see here!
       #
-      # See: PDF1.7 s8.5.3.1, #clip_path
+      # See: PDF2.0 s8.5.3.1, #clip_path
       def end_path
         raise_unless_in_path_or_clipping_path
         invoke0(:n)
@@ -1544,11 +1637,11 @@ module HexaPDF
       # :call-seq:
       #   canvas.clip_path(rule = :nonzero)     => canvas
       #
-      # Modifies the clipping path by intersecting it with the current path.
+      # Modifies the clipping path by intersecting it with the current path. Returns +self+.
       #
       # The argument +rule+ may either be +:nonzero+ to use the nonzero winding number rule or
       # +:even_odd+ to use the even-odd rule for determining which regions lie inside the clipping
-      # path. Details on how these rules work are found in the PDF 1.7 spec section 8.5.3.3 or via
+      # path. Details on how these rules work are found in the PDF 2.0 spec section 8.5.3.3 or via
       # Internet search.
       #
       # The initial clipping path includes the entire canvas. Once the clipping path is reduced to a
@@ -1566,7 +1659,7 @@ module HexaPDF
       #     clip_path(:even_odd).end_path
       #   canvas.rectangle(0, 0, 200, 200).fill     # Fills everything inside the clipping path
       #
-      # See: PDF1.7 s8.5.4
+      # See: PDF2.0 s8.5.4, #end_path
       def clip_path(rule = :nonzero)
         raise_unless_in_path
         invoke0(rule == :nonzero ? :W : :'W*')
@@ -1583,8 +1676,8 @@ module HexaPDF
       # position and returns the XObject.
       #
       # Any image format for which a HexaPDF::ImageLoader object is available and registered with
-      # the configuration option 'image_loader' can be used. PNG and JPEG images are supported out
-      # of the box.
+      # the configuration option 'image_loader' can be used. PNG (lossless), JPEG (lossy) and PDF
+      # (vector) images are supported out of the box.
       #
       # If the filename or the IO specifies a PDF file, the first page of this file is used to
       # create a form XObject which is then drawn.
@@ -1608,18 +1701,18 @@ module HexaPDF
       #   #>pdf
       #   canvas.xobject(machu_picchu, at: [10, 10], width: 90)        # bottom left
       #
-      #   file = File.new(machu_picchu, 'rb')                         # top left
+      #   file = File.new(machu_picchu, 'rb')                          # top left
       #   canvas.xobject(file, at: [10, 110], height: 50)
       #
       #   image = doc.images.add(machu_picchu)
       #   canvas.xobject(image, at: [110, 10], width: 50, height: 90)  # bottom right
       #
       #   form = doc.add({Type: :XObject, Subtype: :Form, BBox: [0, 0, 100, 100]})
-      #   form.canvas.line(10, 10, 90, 90).stroke
+      #   form.canvas.stroke_color("hp-blue").line(10, 10, 90, 90).stroke
       #   canvas.line_width = 20
       #   canvas.xobject(form, at: [100, 100])                         # top right
       #
-      # See: PDF1.7 s8.8, s.8.10.1
+      # See: PDF2.0 s8.8, s.8.10.1, HexaPDF::Type::Image, HexaPDF::Type::Form, HexaPDF::ImageLoader
       def xobject(obj, at:, width: nil, height: nil)
         unless obj.kind_of?(HexaPDF::Stream)
           obj = context.document.images.add(obj)
@@ -1653,14 +1746,18 @@ module HexaPDF
       #   canvas.character_spacing(amount)               => canvas
       #   canvas.character_spacing(amount) { block }     => canvas
       #
-      # The character spacing determines how much additional space is added between two
-      # consecutive characters. For horizontal writing positive values increase the distance
-      # between two characters, whereas for vertical writing negative values increase the
+      # The character spacing determines how much additional space is added after each character
+      # (or, more correctly, after each glyph). For horizontal writing positive values increase the
+      # distance between two characters, whereas for vertical writing negative values increase the
       # distance.
       #
-      # Returns the current character spacing value (see Content::GraphicsState#character_spacing)
-      # when no argument is given. Otherwise sets the character spacing using the +amount+ argument
-      # and returns self. The setter version can also be called in the character_spacing= form.
+      # Note that the character spacing is applied to all characters that are rendered. This has the
+      # effect that there is also a space after the last character which might not be wanted in
+      # certain cases (e.g. when justifying text).
+      #
+      # Returns the current character spacing value (see GraphicsState#character_spacing) when no
+      # argument is given. Otherwise sets the character spacing using the +amount+ argument and
+      # returns +self+. The setter version can also be called in the character_spacing= form.
       #
       # If the +amount+ and a block are provided, the changed character spacing is only active
       # during the block by saving and restoring the graphics state.
@@ -1680,11 +1777,18 @@ module HexaPDF
       #   # visual example
       #   canvas.font("Helvetica", size: 10)
       #   canvas.character_spacing = 0                  # initial value
-      #   canvas.text("This is an example text.", at: [10, 150])
-      #   canvas.character_spacing = 3
-      #   canvas.text("This is an example text.", at: [10, 100])
-      #
-      # See: PDF1.7 s9.3.2
+      #   canvas.text("This is an example", at: [10, 150])
+      #   # show that the text cursor is directly after the last glyph
+      #   x, y = canvas.text_cursor
+      #   canvas.stroke_color("hp-blue").line(x, y, x, y + 10).stroke
+      #
+      #   canvas.character_spacing = 5
+      #   canvas.text("This is an example", at: [10, 100])
+      #   # visualize the spacing after the last glyph
+      #   x, y = canvas.text_cursor
+      #   canvas.stroke_color("hp-blue").line(x, y, x, y + 10).stroke
+      #
+      # See: PDF2.0 s9.3.2, #word_spacing, #horizontal_scaling
       def character_spacing(amount = nil, &bk)
         gs_getter_setter(:character_spacing, :Tc, amount, &bk)
       end
@@ -1703,9 +1807,9 @@ module HexaPDF
       # *Important*: In HexaPDF only the standard 14 PDF Type1 fonts support this property! When
       # using any other font, for example a TrueType font, this property has no effect.
       #
-      # Returns the current word spacing value (see Content::GraphicsState#word_spacing) when no
-      # argument is given. Otherwise sets the word spacing using the +amount+ argument and returns
-      # self. The setter version can also be called in the word_spacing= form.
+      # Returns the current word spacing value (see GraphicsState#word_spacing) when no argument is
+      # given. Otherwise sets the word spacing using the +amount+ argument and returns +self+. The
+      # setter version can also be called in the word_spacing= form.
       #
       # If the +amount+ and a block are provided, the changed word spacing is only active during
       # the block by saving and restoring the graphics state.
@@ -1729,7 +1833,7 @@ module HexaPDF
       #   canvas.word_spacing = 10
       #   canvas.text("This is an example text.", at: [10, 100])
       #
-      # See: PDF1.7 s9.3.3
+      # See: PDF2.0 s9.3.3, #character_spacing, #horizontal_scaling
       def word_spacing(amount = nil, &bk)
         gs_getter_setter(:word_spacing, :Tw, amount, &bk)
       end
@@ -1744,10 +1848,9 @@ module HexaPDF
       # compressing them in the horizontal direction. The value is specified as percent of the
       # normal width, so 100 means no scaling.
       #
-      # Returns the current horizontal scaling value (see Content::GraphicsState#horizontal_scaling)
-      # when no argument is given. Otherwise sets the horizontal scaling using the +percent+
-      # argument and returns self. The setter version can also be called in the horizontal_scaling=
-      # form.
+      # Returns the current horizontal scaling value (see GraphicsState#horizontal_scaling) when no
+      # argument is given. Otherwise sets the horizontal scaling using the +percent+ argument and
+      # returns +self+. The setter version can also be called in the horizontal_scaling= form.
       #
       # If the +percent+ and a block are provided, the changed horizontal scaling is only active
       # during the block by saving and restoring the graphics state.
@@ -1771,7 +1874,7 @@ module HexaPDF
       #   canvas.horizontal_scaling = 50
       #   canvas.text("This is an example text.", at: [10, 100])
       #
-      # See: PDF1.7 s9.3.4
+      # See: PDF2.0 s9.3.4, #character_spacing, #word_spacing
       def horizontal_scaling(amount = nil, &bk)
         gs_getter_setter(:horizontal_scaling, :Tz, amount, &bk)
       end
@@ -1789,8 +1892,8 @@ module HexaPDF
       # There are other PDF content stream operators that would be effected but those are not used
       # by the canvas.
       #
-      # Returns the current leading value (see Content::GraphicsState#leading) when no argument is
-      # given. Otherwise sets the leading using the +amount+ argument and returns self. The setter
+      # Returns the current leading value (see GraphicsState#leading) when no argument is given.
+      # Otherwise sets the leading using the +amount+ argument and returns +self+. The setter
       # version can also be called in the leading= form.
       #
       # If the +amount+ and a block are provided, the changed leading is only active during the
@@ -1813,7 +1916,7 @@ module HexaPDF
       #   canvas.leading = 15
       #   canvas.text("This is an example text.\nwith a second\nand thrid line", at: [10, 150])
       #
-      # See: PDF1.7 s9.3.5, #move_text_cursor
+      # See: PDF2.0 s9.3.5, #move_text_cursor
       def leading(amount = nil, &bk)
         gs_getter_setter(:leading, :TL, amount, &bk)
       end
@@ -1824,16 +1927,33 @@ module HexaPDF
       #   canvas.text_rendering_mode(mode)               => canvas
       #   canvas.text_rendering_mode(mode) { block }     => canvas
       #
-      # The text rendering mode determines if and how glyphs are rendered. The +mode+ parameter
-      # can either be a valid integer or one of the symbols +:fill+, +:stroke+, +:fill_stroke+,
-      # +:invisible+, +:fill_clip+, +:stroke_clip+, +:fill_stroke_clip+ or +:clip+ (see
-      # TextRenderingMode.normalize for details). Note that the return value is always a
-      # normalized text rendering mode value.
-      #
-      # Returns the current text rendering mode value (see
-      # Content::GraphicsState#text_rendering_mode) when no argument is given. Otherwise sets the
-      # text rendering mode using the +mode+ argument and returns self. The setter version can also
-      # be called in the text_rendering_mode= form.
+      # The text rendering mode determines if and how glyphs are rendered.
+      #
+      # The +mode+ parameter can be one of the following (also see TextRenderingMode):
+      #
+      # :fill or 0::
+      #     The text is filled (default)
+      # :stroke or 1::
+      #     The text is stroked.
+      # :fill_stroke or 2::
+      #     The test is filled, then stroked.
+      # :invisible or 3::
+      #     The text is neither filled nor stroked.
+      # :fill_clip or 4::
+      #     The text is filled and added to the clipping path.
+      # :stroke_clip or 5::
+      #     The text is stroked and added to the clipping path.
+      # :fill_stroke_clip or 6::
+      #     The text is filled, then stroked and added to the clipping path.
+      # :clip or 7::
+      #     The text is added to the clipping path.
+      # either be a valid integer or one of the symbols +:fill+, +:stroke+,
+      #
+      # Note that the return value is always a normalized text rendering mode value.
+      #
+      # Returns the current text rendering mode value (see GraphicsState#text_rendering_mode) when
+      # no argument is given. Otherwise sets the text rendering mode using the +mode+ argument and
+      # returns +self+. The setter version can also be called in the text_rendering_mode= form.
       #
       # If the +mode+ and a block are provided, the changed text rendering mode is only active
       # during the block by saving and restoring the graphics state.
@@ -1858,7 +1978,7 @@ module HexaPDF
       #     canvas.text("#{trm} text.", at: [20, 150 - 30 * index])
       #   end
       #
-      # See: PDF1.7 s9.3.6, Content::GraphicsState::TextRenderingMode
+      # See: PDF2.0 s9.3.6, GraphicsState::TextRenderingMode
       def text_rendering_mode(m = nil, &bk)
         gs_getter_setter(:text_rendering_mode, :Tr, m && TextRenderingMode.normalize(m), &bk)
       end
@@ -1872,9 +1992,9 @@ module HexaPDF
       # The text rise specifies the vertical distance to move the baseline up or down from its
       # default location. Positive values move the baseline up, negative values down.
       #
-      # Returns the current text rise value (see Content::GraphicsState#text_rise) when no argument
-      # is given. Otherwise sets the text rise using the +amount+ argument and returns self. The
-      # setter version can also be called in the text_rise= form.
+      # Returns the current text rise value (see GraphicsState#text_rise) when no argument is given.
+      # Otherwise sets the text rise using the +amount+ argument and returns +self+. The setter
+      # version can also be called in the text_rise= form.
       #
       # If the +amount+ and a block are provided, the changed text rise is only active during the
       # block by saving and restoring the graphics state.
@@ -1900,7 +2020,7 @@ module HexaPDF
       #   canvas.text_rise = -10
       #   canvas.text("and also down here")
       #
-      # See: PDF1.7 s9.3.7
+      # See: PDF2.0 s9.3.7
       def text_rise(amount = nil, &bk)
         gs_getter_setter(:text_rise, :Ts, amount, &bk)
       end
@@ -1909,7 +2029,7 @@ module HexaPDF
       # :call-seq:
       #   canvas.begin_text(force_new: false)      -> canvas
       #
-      # Begins a new text object.
+      # Begins a new text object and returns +self+.
       #
       # If +force+ is +true+ and the current graphics object is already a text object, it is ended
       # and a new text object is begun.
@@ -1917,7 +2037,7 @@ module HexaPDF
       # It is not necessary to invoke this method manually in most cases since it is automatically
       # called when needed by other methods, i.e. the #text method.
       #
-      # See: PDF1.7 s9.4.1
+      # See: PDF2.0 s9.4.1, #end_text, #text
       def begin_text(force_new: false)
         raise_unless_at_page_description_level_or_in_text
         end_text if force_new
@@ -1928,12 +2048,12 @@ module HexaPDF
       # :call-seq:
       #   canvas.end_text       -> canvas
       #
-      # Ends the current text object.
+      # Ends the current text object and returns +self+.
       #
       # It is not necessary to invoke this method manually in most cases since it is automatically
       # called when needed by other methods, i.e. when creating a new path.
       #
-      # See: PDF1.7 s9.4.1
+      # See: PDF2.0 s9.4.1, #begin_text
       def end_text
         raise_unless_at_page_description_level_or_in_text
         invoke0(:ET) if graphics_object == :text
@@ -1943,7 +2063,12 @@ module HexaPDF
       # :call-seq:
       #   canvas.text_matrix(a, b, c, d, e, f)     => canvas
       #
-      # Sets the text matrix (and the text line matrix) to the given matrix and returns self.
+      # Sets the text matrix (and the text line matrix) to the given matrix and returns +self+.
+      #
+      # The text matrix determines where and how the glyphs are rendered. The most common use is to
+      # translate the text space origin since the text drawing operations always use the text space
+      # origin as starting point for drawing the glyphs. This translation operation can more easily
+      # be specified using #move_text_cursor.
       #
       # The given values are interpreted as a matrix in the following way:
       #
@@ -1965,7 +2090,7 @@ module HexaPDF
       #   canvas.text_matrix(2, 1, 3, 0.5, 50, 50)
       #   canvas.text("This is some text")
       #
-      # See: PDF1.7 s9.4.2
+      # See: PDF2.0 s9.4.2, #move_text_cursor, #text_cursor
       def text_matrix(a, b, c, d, e, f)
         begin_text
         invoke(:Tm, a, b, c, d, e, f)
@@ -1975,7 +2100,7 @@ module HexaPDF
       # :call-seq:
       #   canvas.move_text_cursor(offset: nil, absolute: true)     -> canvas
       #
-      # Moves the text cursor by modifying the text and text line matrices.
+      # Moves the text cursor by modifying the text and text line matrices. Returns +self+.
       #
       # If +offset+ is not specified, the text cursor is moved to the start of the next text line
       # using #leading as vertical offset.
@@ -2010,7 +2135,7 @@ module HexaPDF
       #   canvas.move_text_cursor
       #   canvas.text("Text on next line with leading=30")
       #
-      # See: PDF1.7 s9.4.2, #show_glyphs
+      # See: PDF2.0 s9.4.2, #leading, #text_cursor, #text, #show_glyphs
       def move_text_cursor(offset: nil, absolute: true)
         begin_text
         if offset
@@ -2028,7 +2153,8 @@ module HexaPDF
       # :call-seq:
       #   canvas.text_cursor     -> [x, y]
       #
-      # Returns the position of the text cursor, i.e. the origin of the current text matrix.
+      # Returns the position of the text cursor, i.e. the origin of text space. This is where the
+      # first glyph of the next drawn text will be placed.
       #
       # Note that this method can only be called while the current graphic object is a text object
       # since the text matrix is otherwise undefined.
@@ -2038,10 +2164,11 @@ module HexaPDF
       #   #>pdf
       #   canvas.font("Helvetica", size: 10)
       #   canvas.text("Some sample text", at: [30, 150])
-      #   pos = canvas.text_cursor                          # Cursor is directly after the text
-      #   canvas.line_width(0.5).stroke_color("red").
-      #     polyline(pos[0], pos[1] + 10, pos[0], pos[1], pos[0] + 10, pos[1]).stroke
-      #   canvas.text("Last cursor: #{pos.map! {|f| f.round(2)}.join(", ")}", at: [30, 100])
+      #   tx, ty = canvas.text_cursor                    # Cursor is directly after the text
+      #   canvas.stroke_color("hp-blue").
+      #     circle(tx, ty, 0.5).
+      #     circle(tx, ty, 5).stroke
+      #   canvas.text("Last cursor: (#{tx.round(2)}, #{ty.round(2)})", at: [30, 100])
       #
       # See: #move_text_cursor
       def text_cursor
@@ -2055,7 +2182,7 @@ module HexaPDF
       #
       # Specifies the font and optional the font size that should be used when showing text.
       #
-      # A valid font size need to be provided on the first invocation, otherwise an error is raised
+      # A valid font size needs to be provided on the first invocation, otherwise an error is raised
       # (this is due to how setting a font works with PDFs).
       #
       # If +size+ is specified, the #font_size method is invoked with it as argument.
@@ -2065,8 +2192,9 @@ module HexaPDF
       # specifies the font variant to use, with standard values of :none, :italic, :bold and
       # :bold_italic.
       #
-      # Returns the current font object when no argument is given. *Note* that this is the font
-      # object itself, not the PDF dictionary representing the font.
+      # Returns the current font object when no argument is given, otherwise returns +self+. *Note*
+      # that this is the font object itself, not the PDF dictionary representing the font that is
+      # stored in the resources.
       #
       # Examples:
       #
@@ -2080,7 +2208,7 @@ module HexaPDF
       #   canvas.font("Times", variant: :bold_italic, size: 15)
       #   canvas.text("Times bold+italic at size 15", at: [10, 100])
       #
-      # See: PDF1.7 s9.2.2, #font_size
+      # See: PDF2.0 s9.2.2, #font_size, #text
       def font(name = nil, size: nil, **options)
         if name
           @font = (name.respond_to?(:pdf_object) ? name : context.document.fonts.add(name, **options))
@@ -2099,16 +2227,16 @@ module HexaPDF
       alias font= font
 
       # :call-seq:
-      #   canvas.font_size            => font_size
-      #   canvas.font_size(size       => canvas
+      #   canvas.font_size             => font_size
+      #   canvas.font_size(size)       => canvas
       #
       # Specifies the font size.
       #
       # Note that an error is raised if no font has been set before via #font (this is due to how
       # setting font and font size works in PDF).
       #
-      # Returns the current font size when no argument is given. The setter version can also
-      # be called in the font_size= form.
+      # Returns the current font size when no argument is given, otherwise returns +self+. The
+      # setter version can also be called in the font_size= form.
       #
       # Examples:
       #
@@ -2124,7 +2252,7 @@ module HexaPDF
       #     canvas.text("Text in size #{size}", at: [15, 180 - index * 20])
       #   end
       #
-      # See: PDF1.7 s9.2.2, #font
+      # See: PDF2.0 s9.2.2, #font, #text
       def font_size(size = nil)
         if size
           unless @font
@@ -2142,7 +2270,7 @@ module HexaPDF
       #   canvas.text(text)                  -> canvas
       #   canvas.text(text, at: [x, y])      -> canvas
       #
-      # Shows the given text string, either at the current or the provided position.
+      # Shows the given text string, either at the current or the provided position. Returns +self+.
       #
       # If no position is provided, the text is positioned at the current position of the text
       # cursor (see #text_cursor).
@@ -2152,21 +2280,24 @@ module HexaPDF
       # equal to the font size will be set..
       #
       # Note that there are no provisions to make sure that all text is visible! So if the text
-      # string is too long, it will just flow off the page and be cut off.
+      # string is too long, it may be outside the cropped page and be cut off.
       #
       # Examples:
       #
       #   #>pdf
       #   canvas.font('Times', size: 12)
-      #   canvas.text("This is a \n multiline text", at: [15, 150])  # Sets leading=12
-      #   canvas.text(". Some more text\nafter the newline.")   # Starts right after the last text
+      #   # Sets leading=12 because mulitple lines are drawn
+      #   canvas.text("This is a \n    multiline text", at: [15, 150])
+      #   # Starts right after the last text
+      #   canvas.text(". Some more text\nafter the newline.")
       #
-      # See: #leading, http://www.unicode.org/reports/tr18/#Line_Boundaries
+      # See: #leading, #font, #font_size, #show_glyphs,
+      # http://www.unicode.org/reports/tr18/#Line_Boundaries
       def text(text, at: nil)
         raise_unless_font_set
         move_text_cursor(offset: at) if at
-        leading(font_size) if leading == 0
         lines = text.split(/\u{D A}|(?!\u{D A})[\u{A}-\u{D}\u{85}\u{2028}\u{2029}]/, -1)
+        leading(font_size) if leading == 0 && lines.length > 1
         lines.each_with_index do |str, index|
           show_glyphs(@font.decode_utf8(str))
           move_text_cursor unless index == lines.length - 1
@@ -2177,7 +2308,7 @@ module HexaPDF
       # :call-seq:
       #   canvas.show_glyphs(glyphs)      -> canvas
       #
-      # Low-level method for actually showing text on the canvas.
+      # Low-level method for actually showing text on the canvas. Returns +self+.
       #
       # The argument +glyphs+ needs to be a an array of glyph objects valid for the current font,
       # optionally interspersed with numbers for kerning.
@@ -2200,6 +2331,8 @@ module HexaPDF
       #   canvas.move_text_cursor(offset: [15, 100])
       #   canvas.show_glyphs(glyphs)
       #   canvas.text(canvas.text_cursor.map(&:to_i).join(", "), at: [15, 80])
+      #
+      # See: #text, #text_cursor, #text_matrix, #move_text_cursor, #show_glyphs_only
       def show_glyphs(glyphs)
         return if glyphs.empty?
         raise_unless_font_set
@@ -2269,7 +2402,7 @@ module HexaPDF
       # :call-seq:
       #   canvas.marked_content_point(tag, property_list: nil)     -> canvas
       #
-      # Inserts a marked-content point, optionally associated with a property list.
+      # Inserts a marked-content point, optionally associated with a property list. Returns +self+.
       #
       # A marked-content point is used to identify a position in the content stream for later use by
       # other applications. The symbol +tag+ is used to uniquely identify the role of the
@@ -2284,7 +2417,7 @@ module HexaPDF
       #   canvas.marked_content_point(:Divider)
       #   canvas.marked_content_point(:Divider, property_list: {Key: 'value'})
       #
-      # See: PDF1.7 s14.6
+      # See: PDF2.0 s14.6,  #marked_content_sequence, #end_marked_content_sequence
       def marked_content_point(tag, property_list: nil)
         raise_unless_at_page_description_level_or_in_text
         if property_list
@@ -2300,7 +2433,8 @@ module HexaPDF
       #   canvas.marked_content_sequence(tag, property_list: nil)               -> canvas
       #   canvas.marked_content_sequence(tag, property_list: nil) { block }     -> canvas
       #
-      # Inserts a marked-content sequence, optionally associated with a property list.
+      # Inserts a marked-content sequence, optionally associated with a property list. Returns
+      # +self+.
       #
       # A marked-content sequence is used to identify a sequence of complete graphics objects in the
       # content stream for later use by other applications, e.g. for tagged PDF. The symbol +tag+ is
@@ -2327,7 +2461,7 @@ module HexaPDF
       #     # Other instructions
       #   end
       #
-      # See: PDF1.7 s14.6, #end_marked_content_sequence
+      # See: PDF2.0 s14.6, #end_marked_content_sequence, #marked_content_point
       def marked_content_sequence(tag, property_list: nil)
         raise_unless_at_page_description_level
         if property_list
@@ -2346,22 +2480,66 @@ module HexaPDF
       # :call-seq:
       #   canvas.end_marked_content_sequence       -> canvas
       #
-      # Ends a marked-content sequence.
+      # Ends a marked-content sequence and returns +self+.
       #
       # See #marked_content_sequence for details.
       #
-      # See: PDF1.7 s14.6, #marked_content_sequence
+      # See: PDF2.0 s14.6, #marked_content_sequence, #marked_content_point
       def end_marked_content_sequence
         raise_unless_at_page_description_level
         invoke0(:EMC)
         self
       end
 
-      # Creates a color object from the given color specification. See #stroke_color for details
-      # on the possible color specifications.
+      # :call-seq:
+      #   canvas.optional_content(ocg, &block)                              -> canvas
+      #   canvas.optional_content(name, use_existing_ocg: true, &block)     -> canvas
+      #
+      # Inserts an optional content sequence. Returns +self+.
+      #
+      # An optional content sequence marks part of the content stream as belonging to the given
+      # optional content group. See HexaPDF::Type::OptionalContentProperties for details.
+      #
+      # If the first argument is already an optional content group dictionary, it is used.
+      # Otherwise, the first argument needs to be the name of the optional content group. In that
+      # case, the +use_existing_ocg+ specifies whether the first found optional content group with
+      # that name should be used or whether a new OCG should always be created.
+      #
+      # If invoked without a block, a corresponding call to #end_optional_content must be done.
+      # Otherwise the optional content sequence automatically ends when the block is finished.
+      #
+      # Examples:
+      #
+      #   canvas.optional_content('Hints')
+      #   # Other instructions
+      #   canvas.end_optional_content
+      #
+      #   canvas.optional_content('Hints', use_existing_ocg: false) do
+      #     # Other instructions
+      #   end
+      #
+      # See: PDF2.0 s8.11, #end_optional_content, HexaPDF::Type::OptionalContentProperties
+      def optional_content(ocg, use_existing_ocg: true, &block)
+        ocg = if ocg.kind_of?(HexaPDF::Dictionary) || !use_existing_ocg
+                context.document.optional_content.add_ocg(ocg)
+              else
+                context.document.optional_content.ocg(ocg, create: true)
+              end
+        marked_content_sequence(:OC, property_list: ocg, &block)
+      end
+
+      # Ends an optional content sequence and returns +self+.
+      #
+      # See #optional_content for details.
+      #
+      # See: PDF2.0 s8.11
+      alias :end_optional_content :end_marked_content_sequence
+
+      # Creates and returns a color object from the given color specification. See #stroke_color for
+      # details on the possible color specifications.
       #
       # This utility method is meant for use by higher-level methods that need to convert a color
-      # specification into a color object for this Canvas object.
+      # specification into a color object.
       def color_from_specification(spec)
         spec = Array(spec)
         if spec.length == 1 && spec[0].kind_of?(String)