Updated documentation

scripts/create_drc_samples.rb

@@ -2,9 +2,45 @@
 # Run with:
 # ./klayout -z -r ./create_drc_samples.rb -t -c klayoutrc_drc_samples
 
+class QRCGenerator
+
+  def res_path 
+    "src/lay/lay"
+  end
+
+  def img_path
+    "doc/images"
+  end
+
+  def initialize
+    @path = res_path + "/" + "layDRCLVSHelpResources.qrc"
+    @file = File.open(@path, "w")
+    @file.puts("<RCC>")
+    @file.puts(" <qresource prefix=\"/help/images\">")
+  end
+
+  def <<(str)
+    @file.puts(str)
+  end
+
+  def finish
+    @file.puts(" </qresource>")
+    @file.puts("</RCC>")
+    @file.close
+    puts "---> resource file written to #{@path}"
+  end
+
+  def self.instance
+    @@inst ||= QRCGenerator::new
+    @@inst
+  end
+
+end
+
 def run_demo(gen, cmd, out)
 
-  img_path = "src/lay/lay/doc/images"
+  res_path = QRCGenerator::instance.res_path
+  img_path = QRCGenerator::instance.img_path
 
   mw = RBA::Application::instance::main_window
 
@@ -81,7 +117,9 @@ def run_demo(gen, cmd, out)
     input1 = input(1, 0)
     input = input1
     input2 = input(2, 0)
-    #{cmd}.data
+    labels1 = labels(1, 0)
+    labels = labels1
+    (#{cmd}).data
 SCRIPT
 
   if data.is_a?(RBA::Region)
@@ -101,15 +139,19 @@ SCRIPT
   elsif data.is_a?(RBA::EdgePairs)
     cell.shapes(lout_poly).insert_as_polygons(data, 1)
     cell.shapes(lout).insert(data.edges)
+  elsif data.is_a?(RBA::Texts)
+    cell.shapes(lout).insert(data)
   end
 
   view.update_content
-  view.save_image(img_path + "/" + out, 400, 400)
+  view.save_image(res_path + "/" + img_path + "/" + out, 400, 400)
 
-  puts "---> written #{img_path}/#{out}"
+  puts "---> written #{res_path}/#{img_path}/#{out}"
 
   mw.close_all
 
+  QRCGenerator::instance << "  <file alias=\"#{out}\">#{img_path}/#{out}</file>"
+
 end
 
 class Gen
@@ -631,3 +673,41 @@ run_demo gen, "input.corners.sized(0.1)", "drc_corners1.png"
 run_demo gen, "input.corners(90.0).sized(0.1)", "drc_corners2.png"
 run_demo gen, "input.corners(-90.0 .. -45.0).sized(0.1)", "drc_corners3.png"
 
+
+class Gen
+  def produce(s1, s2)
+    s1.insert(RBA::Text::new("ABC", RBA::Trans::new(RBA::Vector::new(0, 2000))))
+    s1.insert(RBA::Text::new("A", RBA::Trans::new(RBA::Vector::new(0, 6000))))
+    s1.insert(RBA::Text::new("XYZ", RBA::Trans::new(RBA::Vector::new(4000, 2000))))
+    s1.insert(RBA::Text::new("A*", RBA::Trans::new(RBA::Vector::new(4000, 6000))))
+  end
+end
+
+gen = Gen::new
+
+run_demo gen, "labels.texts(\"A*\")", "drc_texts1.png"
+run_demo gen, "labels.texts(text(\"A*\"))", "drc_texts2.png"
+
+class Gen
+  def produce(s1, s2)
+    s1.insert(RBA::Text::new("T1", RBA::Trans::new(RBA::Vector::new(0, 2000))))
+    s1.insert(RBA::Text::new("T2", RBA::Trans::new(RBA::Vector::new(2000, 2000))))
+    s1.insert(RBA::Text::new("T3", RBA::Trans::new(RBA::Vector::new(4000, 2000))))
+    pts = [ 
+      RBA::Point::new(2000, 0),
+      RBA::Point::new(2000, 4000),
+      RBA::Point::new(6000, 4000),
+      RBA::Point::new(6000, 0)
+    ];
+    s2.insert(RBA::Polygon::new(pts))
+  end
+end
+
+gen = Gen::new
+
+run_demo gen, "labels & input2", "drc_textpoly1.png"
+run_demo gen, "labels - input2", "drc_textpoly2.png"
+
+
+QRCGenerator::instance.finish
+

src/db/db/gsiDeclDbShapes.cc

@@ -419,6 +419,29 @@ static void insert_edge_pairs_with_dtrans (db::Shapes *sh, const db::EdgePairs &
   }
 }
 
+static void insert_texts (db::Shapes *sh, const db::Texts &r)
+{
+  for (db::Texts::const_iterator s = r.begin (); ! s.at_end (); ++s) {
+    sh->insert (*s);
+  }
+}
+
+static void insert_texts_with_trans (db::Shapes *sh, const db::Texts &r, const db::ICplxTrans &trans)
+{
+  for (db::Texts::const_iterator s = r.begin (); ! s.at_end (); ++s) {
+    sh->insert (s->transformed (trans));
+  }
+}
+
+static void insert_texts_with_dtrans (db::Shapes *sh, const db::Texts &r, const db::DCplxTrans &trans)
+{
+  db::CplxTrans dbu_trans (shapes_dbu (sh));
+  db::ICplxTrans itrans = dbu_trans.inverted () * trans * dbu_trans;
+  for (db::Texts::const_iterator s = r.begin (); ! s.at_end (); ++s) {
+    sh->insert (s->transformed (itrans));
+  }
+}
+
 static unsigned int s_all ()                 { return db::ShapeIterator::All; }
 static unsigned int s_all_with_properties () { return db::ShapeIterator::AllWithProperties; }
 static unsigned int s_properties ()          { return db::ShapeIterator::Properties; }
@@ -599,7 +622,7 @@ Class<db::Shapes> decl_Shapes ("db", "Shapes",
     "@param edges The edge pairs to insert\n"
     "@param trans The transformation to apply (displacement in micrometer units)\n"
     "\n"
-    "This method inserts all edge pairs from the edge collection into this shape container.\n"
+    "This method inserts all edge pairs from the edge pair collection into this shape container.\n"
     "Before an edge pair is inserted, the given transformation is applied.\n"
     "\n"
     "This method has been introduced in version 0.26.\n"
@@ -682,6 +705,34 @@ Class<db::Shapes> decl_Shapes ("db", "Shapes",
     "\n"
     "This method has been introduced in version 0.25.\n"
   ) +
+  gsi::method_ext ("insert", &insert_texts, gsi::arg ("texts"),
+    "@brief Inserts the texts from the text collection into this shape container\n"
+    "@param texts The texts to insert\n"
+    "\n"
+    "This method inserts all texts from the text collection into this shape container.\n"
+    "\n"
+    "This method has been introduced in version 0.27.\n"
+  ) +
+  gsi::method_ext ("insert", &insert_texts_with_trans, gsi::arg ("texts"), gsi::arg ("trans"),
+    "@brief Inserts the texts from the text collection into this shape container with a transformation\n"
+    "@param edges The texts to insert\n"
+    "@param trans The transformation to apply\n"
+    "\n"
+    "This method inserts all texts from the text collection into this shape container.\n"
+    "Before an text is inserted, the given transformation is applied.\n"
+    "\n"
+    "This method has been introduced in version 0.27.\n"
+  ) +
+  gsi::method_ext ("insert", &insert_texts_with_dtrans, gsi::arg ("texts"), gsi::arg ("trans"),
+    "@brief Inserts the texts from the text collection into this shape container with a transformation (given in micrometer units)\n"
+    "@param edges The text to insert\n"
+    "@param trans The transformation to apply (displacement in micrometer units)\n"
+    "\n"
+    "This method inserts all texts from the text collection into this shape container.\n"
+    "Before an text is inserted, the given transformation is applied.\n"
+    "\n"
+    "This method has been introduced in version 0.27.\n"
+  ) +
   gsi::method_ext ("transform", &transform_shapes, gsi::arg ("trans"),
     "@brief Transforms all shapes with the given transformation\n"
     "This method will invalidate all references to shapes inside this collection.\n\n"

src/drc/drc/built-in-macros/_drc_layer.rb

@@ -593,9 +593,11 @@ CODE
     # selected text. By using the "as_dots" option, degenerated point-like edges will be
     # produced.
     #
-    # This method can also be applied to true text layers obtained with \labels.
+    # The preferred method however is to use true text layers created with \labels.
     # In this case, without specifying "as_dots" or "as_boxes" retains the text
-    # objects as such. Only text filtering is applied.
+    # objects as such a text filtering is applied. In contrast to this, layers generated
+    # with \input cannot maintain the text nature of the selected objects and 
+    # produce dots or small polygon boxes in the \texts method.
     #
     # Texts can be selected either by exact match string or a pattern match with a 
     # glob-style pattern. By default, glob-style pattern are used. 
@@ -612,14 +614,22 @@ CODE
     #
     # @code
     #   # Selects all texts
-    #   t = input(1, 0).texts
+    #   t = labels(1, 0).texts
     #   # Selects all texts beginning with an "A"
-    #   t = input(1, 0).texts("A*")
-    #   t = input(1, 0).texts(pattern("A*"))
-    #   # Selects all texts whose string is "A*"
-    #   t = input(1, 0).texts(text("A*"))
+    #   t = labels(1, 0).texts("A*")
+    #   t = labels(1, 0).texts(pattern("A*"))
+    #   # Selects all texts whose string is "ABC"
+    #   t = labels(1, 0).texts(text("ABC"))
     # @/code
-    # 
+    #
+    # The effect of the operation is shown in these examples:
+    #  
+    # @table
+    #   @tr 
+    #     @td @img(/images/drc_texts1.png) @/td
+    #     @td @img(/images/drc_texts2.png) @/td
+    #   @/tr
+    # @/table
      
     def texts(*args)
       requires_texts_or_region("texts")
@@ -1168,7 +1178,7 @@ CODE
     # borders of the polygons of the second operand.
     #
     # The following images show the effect of the "and" method
-    # on polygons and edges (layer1: red, layer2: blue):
+    # on polygons and edges (input1: red, input2: blue):
     #
     # @table
     #   @tr 
@@ -1177,6 +1187,16 @@ CODE
     #     @td @img(/images/drc_and3.png) @/td
     #   @/tr
     # @/table
+    #
+    # The AND operation can be applied between a text and a polygon
+    # layer. In this case, the texts inside or at the border of the 
+    # polygons will be written to the output (labels: red, input2: blue):
+    #
+    # @table
+    #   @tr 
+    #     @td @img(/images/drc_textpoly1.png) @/td
+    #   @/tr
+    # @/table
     
     def and(other)
       self & other    
@@ -1195,7 +1215,7 @@ CODE
     # of the second operand.
     #
     # The following images show the effect of the "not" method
-    # on polygons and edges (layer1: red, layer2: blue):
+    # on polygons and edges (input1: red, input2: blue):
     #
     # @table
     #   @tr 
@@ -1204,6 +1224,16 @@ CODE
     #     @td @img(/images/drc_not3.png) @/td
     #   @/tr
     # @/table
+    #
+    # The NOT operation can be applied between a text and a polygon
+    # layer. In this case, the texts outside the polygons will be 
+    # written to the output (labels: red, input2: blue):
+    #
+    # @table
+    #   @tr 
+    #     @td @img(/images/drc_textpoly2.png) @/td
+    #   @/tr
+    # @/table
     
     def not(other)
       self - other    
@@ -1219,7 +1249,7 @@ CODE
     # This method is available for polygon and edge layers.
     #
     # The following images show the effect of the "xor" method
-    # on polygons and edges (layer1: red, layer2: blue):
+    # on polygons and edges (input1: red, input2: blue):
     #
     # @table
     #   @tr 
@@ -1242,7 +1272,7 @@ CODE
     # This method is available for polygon and edge layers.
     #
     # The following images show the effect of the "or" method
-    # on polygons and edges (layer1: red, layer2: blue):
+    # on polygons and edges (input1: red, input2: blue):
     #
     # @table
     #   @tr 
@@ -1265,7 +1295,7 @@ CODE
     # This method is available for polygon, edge and edge pair layers.
     #
     # The following images show the effect of the "join" method
-    # on polygons and edges (layer1: red, layer2: blue):
+    # on polygons and edges (input1: red, input2: blue):
     #
     # @table
     #   @tr 
@@ -1587,8 +1617,9 @@ CODE
     # It returns a new layer containing the selected shapes. A version which modifies self
     # is \select_interacting.
     #
-    # This method is available for polygon and edge layers. Edges can be selected
-    # with respect to other edges or polygons.
+    # This method is available for polygon, text and edge layers. Edges can be selected
+    # with respect to other edges or polygons. Texts can be selected with respect to 
+    # polygons.
     #
     # The following image shows the effect of the "interacting" method (input1: red, input2: blue):
     #
@@ -2502,7 +2533,7 @@ CODE
     # Distance values can be given as floating-point values (in micron) or integer values (in
     # database units). To explicitly specify the unit, use the unit denominators.
     #
-    # The following image shows the effect of the separation check (layer1: red, layer2: blue):
+    # The following image shows the effect of the separation check (input1: red, input2: blue):
     # 
     # @table
     #   @tr 
@@ -2537,7 +2568,7 @@ CODE
     # Distance values can be given as floating-point values (in micron) or integer values (in
     # database units). To explicitly specify the unit, use the unit denominators.
     #
-    # The following images show the effect of the overlap check (layer1: red, layer2: blue):
+    # The following images show the effect of the overlap check (input1: red, input2: blue):
     # 
     # @table
     #   @tr 

src/drc/drc/built-in-macros/_drc_netter.rb

@@ -76,13 +76,19 @@ module DRC
     # @name connect
     # @brief Specifies a connection between two layers
     # @synopsis connect(a, b)
-    # a and b must be polygon layers. After calling this function, the
+    # a and b must be polygon or text layers. After calling this function, the
     # Netter regards all overlapping or touching shapes on these layers
     # to form an electrical connection between the materials formed by
     # these layers. This also implies intra-layer connections: shapes
     # on these layers touching or overlapping other shapes on these
     # layers will form bigger, electrically connected areas.
     #
+    # Texts will be used to assign net names to the nets. The preferred
+    # method is to use \labels to create a text layer from a design 
+    # layer. When using \input, text labels are carried implicitly
+    # with the polygons but at the cost of small dummy shapes (2x2 DBU
+    # marker polygons) and limited functionality.
+    #
     # Multiple connect calls must be made to form larger connectivity
     # stacks across multiple layers. Such stacks may include forks and
     # joins.
@@ -112,7 +118,7 @@ module DRC
     # Connects the shapes from the given layer l to a global net with the given name.
     # Global nets are common to all cells. Global nets automatically connect to parent
     # cells throughs implied pins. An example is the substrate (bulk) net which connects
-    # to shapes belonging to tie-down diodes.
+    # to shapes belonging to tie-down diodes. "l" can be a polygon or text layer.
     
     def connect_global(l, name)
 

src/lay/lay/doc/about/drc_ref_global.xml

@@ -362,6 +362,24 @@ This function creates an edge object. The arguments are the same than for the
 The intention of that method is to create an empty layer which can be 
 filled with edge objects using <a href="/about/drc_ref_layer.xml#insert">Layer#insert</a>.
 </p>
+<a name="edge_pairs"/><h2>"edge_pairs" - Gets the edges from an original layer</h2>
+<keyword name="edge_pairs"/>
+<p>Usage:</p>
+<ul>
+<li><tt>edge_pairs(args)</tt></li>
+</ul>
+<p>
+See <a href="/about/drc_ref_source.xml#edge_pairs">Source#edge_pairs</a> for a description of that function.
+</p>
+<a name="edges"/><h2>"edges" - Gets the edges from an original layer</h2>
+<keyword name="edges"/>
+<p>Usage:</p>
+<ul>
+<li><tt>edges(args)</tt></li>
+</ul>
+<p>
+See <a href="/about/drc_ref_source.xml#edges">Source#edges</a> for a description of that function.
+</p>
 <a name="error"/><h2>"error" - Prints an error</h2>
 <keyword name="error"/>
 <p>Usage:</p>
@@ -446,7 +464,7 @@ See <a href="/about/drc_ref_netter.xml#l2n_data">Netter#l2n_data</a> for a descr
 <keyword name="labels"/>
 <p>Usage:</p>
 <ul>
-<li><tt>labels</tt></li>
+<li><tt>labels(args)</tt></li>
 </ul>
 <p>
 See <a href="/about/drc_ref_source.xml#labels">Source#labels</a> for a description of that function.

src/lay/lay/doc/about/drc_ref_layer.xml

@@ -76,7 +76,7 @@ result will be the edges of the first operand which are inside or on the
 borders of the polygons of the second operand.
 </p><p>
 The following images show the effect of the "and" method
-on polygons and edges (layer1: red, layer2: blue):
+on polygons and edges (input1: red, input2: blue):
 </p><p>
 <table>
 <tr>
@@ -85,6 +85,16 @@ on polygons and edges (layer1: red, layer2: blue):
 <td><img src="/images/drc_and3.png"/></td>
 </tr>
 </table>
+</p><p>
+The AND operation can be applied between a text and a polygon
+layer. In this case, the texts inside or at the border of the 
+polygons will be written to the output (labels: red, input2: blue):
+</p><p>
+<table>
+<tr>
+<td><img src="/images/drc_textpoly1.png"/></td>
+</tr>
+</table>
 </p>
 <a name="area"/><h2>"area" - Returns the total area of the polygons in the region</h2>
 <keyword name="area"/>
@@ -594,7 +604,7 @@ Returns the first edges of the edge pairs in the collection.
 If the layer already is a flat one, this method does nothing.
 If the layer is a hierarchical layer (an original layer or
 a derived layer in deep mode), this method will convert it
-to a flat collection of polygons, edges or edge pairs.
+to a flat collection of texts, polygons, edges or edge pairs.
 </p>
 <a name="holes"/><h2>"holes" - Selects all polygon holes from the input</h2>
 <keyword name="holes"/>
@@ -740,8 +750,9 @@ otherwise individual shapes are selected.
 It returns a new layer containing the selected shapes. A version which modifies self
 is <a href="#select_interacting">select_interacting</a>.
 </p><p>
-This method is available for polygon and edge layers. Edges can be selected
-with respect to other edges or polygons.
+This method is available for polygon, text and edge layers. Edges can be selected
+with respect to other edges or polygons. Texts can be selected with respect to 
+polygons.
 </p><p>
 The following image shows the effect of the "interacting" method (input1: red, input2: blue):
 </p><p>
@@ -860,7 +871,7 @@ It is an alias for the "+" operator.
 This method is available for polygon, edge and edge pair layers.
 </p><p>
 The following images show the effect of the "join" method
-on polygons and edges (layer1: red, layer2: blue):
+on polygons and edges (input1: red, input2: blue):
 </p><p>
 <table>
 <tr>
@@ -1030,7 +1041,7 @@ result will be the edges of the first operand which are outside the polygons
 of the second operand.
 </p><p>
 The following images show the effect of the "not" method
-on polygons and edges (layer1: red, layer2: blue):
+on polygons and edges (input1: red, input2: blue):
 </p><p>
 <table>
 <tr>
@@ -1039,6 +1050,16 @@ on polygons and edges (layer1: red, layer2: blue):
 <td><img src="/images/drc_not3.png"/></td>
 </tr>
 </table>
+</p><p>
+The NOT operation can be applied between a text and a polygon
+layer. In this case, the texts outside the polygons will be 
+written to the output (labels: red, input2: blue):
+</p><p>
+<table>
+<tr>
+<td><img src="/images/drc_textpoly2.png"/></td>
+</tr>
+</table>
 </p>
 <a name="not_in"/><h2>"not_in" - Selects shapes or regions of self which are not contained in the other layer</h2>
 <keyword name="not_in"/>
@@ -1216,7 +1237,7 @@ It is an alias for the "|" operator.
 This method is available for polygon and edge layers.
 </p><p>
 The following images show the effect of the "or" method
-on polygons and edges (layer1: red, layer2: blue):
+on polygons and edges (input1: red, input2: blue):
 </p><p>
 <table>
 <tr>
@@ -1318,7 +1339,7 @@ are the same than for <a href="#width">width</a>.
 Distance values can be given as floating-point values (in micron) or integer values (in
 database units). To explicitly specify the unit, use the unit denominators.
 </p><p>
-The following images show the effect of the overlap check (layer1: red, layer2: blue):
+The following images show the effect of the overlap check (input1: red, input2: blue):
 </p><p>
 <table>
 <tr>
@@ -1766,7 +1787,7 @@ are the same than for <a href="#width">width</a>.
 Distance values can be given as floating-point values (in micron) or integer values (in
 database units). To explicitly specify the unit, use the unit denominators.
 </p><p>
-The following image shows the effect of the separation check (layer1: red, layer2: blue):
+The following image shows the effect of the separation check (input1: red, input2: blue):
 </p><p>
 <table>
 <tr>
@@ -1985,6 +2006,12 @@ been created with <a href="#input">input</a>. By default, a small box (2x2 DBU)
 selected text. By using the "as_dots" option, degenerated point-like edges will be
 produced.
 </p><p>
+The preferred method however is to use true text layers created with <a href="#labels">labels</a>.
+In this case, without specifying "as_dots" or "as_boxes" retains the text
+objects as such a text filtering is applied. In contrast to this, layers generated
+with <a href="#input">input</a> cannot maintain the text nature of the selected objects and 
+produce dots or small polygon boxes in the <a href="#texts">texts</a> method.
+</p><p>
 Texts can be selected either by exact match string or a pattern match with a 
 glob-style pattern. By default, glob-style pattern are used. 
 The options available are:
@@ -2000,13 +2027,38 @@ Here are some examples:
 </p><p>
 <pre>
 # Selects all texts
-t = input(1, 0).texts
+t = labels(1, 0).texts
 # Selects all texts beginning with an "A"
-t = input(1, 0).texts("A*")
-t = input(1, 0).texts(pattern("A*"))
-# Selects all texts whose string is "A*"
-t = input(1, 0).texts(text("A*"))
+t = labels(1, 0).texts("A*")
+t = labels(1, 0).texts(pattern("A*"))
+# Selects all texts whose string is "ABC"
+t = labels(1, 0).texts(text("ABC"))
 </pre>
+</p><p>
+The effect of the operation is shown in these examples:
+</p><p>
+<table>
+<tr>
+<td><img src="/images/drc_texts1.png"/></td>
+<td><img src="/images/drc_texts2.png"/></td>
+</tr>
+</table>
+</p>
+<a name="texts_not"/><h2>"texts_not" - Selects texts from an original layer not matching a specific selection</h2>
+<keyword name="texts_not"/>
+<p>Usage:</p>
+<ul>
+<li><tt>layer.texts_not</tt></li>
+<li><tt>layer.texts_not(p)</tt></li>
+<li><tt>layer.texts_not([ options ])</tt></li>
+</ul>
+<p>
+This method can be applied to true text layers obtained with <a href="#labels">labels</a>.
+In this case, without specifying "as_dots" or "as_boxes" retains the text
+objects as such. Only text filtering is applied.
+</p><p>
+Beside that this method acts like <a href="#texts">texts</a>, but will select the text objects
+not matching the filter.
 </p>
 <a name="transform"/><h2>"transform" - Transforms a layer (modifies the layer)</h2>
 <keyword name="transform"/>
@@ -2388,7 +2440,7 @@ It is an alias for the "^" operator.
 This method is available for polygon and edge layers.
 </p><p>
 The following images show the effect of the "xor" method
-on polygons and edges (layer1: red, layer2: blue):
+on polygons and edges (input1: red, input2: blue):
 </p><p>
 <table>
 <tr>

src/lay/lay/doc/about/drc_ref_netter.xml

@@ -153,13 +153,19 @@ See <a href="#connect">connect</a> for more details.
 <li><tt>connect(a, b)</tt></li>
 </ul>
 <p>
-a and b must be polygon layers. After calling this function, the
+a and b must be polygon or text layers. After calling this function, the
 Netter regards all overlapping or touching shapes on these layers
 to form an electrical connection between the materials formed by
 these layers. This also implies intra-layer connections: shapes
 on these layers touching or overlapping other shapes on these
 layers will form bigger, electrically connected areas.
 </p><p>
+Texts will be used to assign net names to the nets. The preferred
+method is to use <a href="#labels">labels</a> to create a text layer from a design 
+layer. When using <a href="#input">input</a>, text labels are carried implicitly
+with the polygons but at the cost of small dummy shapes (2x2 DBU
+marker polygons) and limited functionality.
+</p><p>
 Multiple connect calls must be made to form larger connectivity
 stacks across multiple layers. Such stacks may include forks and
 joins.
@@ -177,7 +183,7 @@ can be cleared with <a href="#clear_connections">clear_connections</a>.
 Connects the shapes from the given layer l to a global net with the given name.
 Global nets are common to all cells. Global nets automatically connect to parent
 cells throughs implied pins. An example is the substrate (bulk) net which connects
-to shapes belonging to tie-down diodes.
+to shapes belonging to tie-down diodes. "l" can be a polygon or text layer.
 </p>
 <a name="connect_implicit"/><h2>"connect_implicit" - Specifies a search pattern for labels which create implicit net connections</h2>
 <keyword name="connect_implicit"/>

src/lay/lay/doc/about/drc_ref_source.xml

@@ -54,6 +54,48 @@ This method will create a new source which delivers the shapes
 from that region clipped to the rectangle. A method doing the 
 same but without clipping is <a href="#touching">touching</a> or <a href="#overlapping">overlapping</a>.
 </p>
+<a name="edge_pairs"/><h2>"edge_pairs" - Gets the edge pairs from an input layer</h2>
+<keyword name="edge_pairs"/>
+<p>Usage:</p>
+<ul>
+<li><tt>source.edge_pairs(layer)</tt></li>
+<li><tt>source.edge_pairs(layer, datatype)</tt></li>
+<li><tt>source.edge_pairs(layer_into)</tt></li>
+<li><tt>source.edge_pairs(filter, ...)</tt></li>
+</ul>
+<p>
+Creates a layer with the edge_pairs from the given layer of the source.
+Edge pairs are not supported by layout formats so far. So except if the source is
+a custom-built layout object, this method has little use. It is provided for future 
+extensions which may include edge pairs in file streams.
+</p><p>
+This method is identical to <a href="#input">input</a> with respect to the options supported.
+</p><p>
+Use the global version of "edge_pairs" without a source object to address the default source.
+</p><p>
+This method has been introduced in version 0.27.
+</p>
+<a name="edges"/><h2>"edges" - Gets the edge shapes (or shapes that can be converted edges) from an input layer</h2>
+<keyword name="edges"/>
+<p>Usage:</p>
+<ul>
+<li><tt>source.edges(layer)</tt></li>
+<li><tt>source.edges(layer, datatype)</tt></li>
+<li><tt>source.edges(layer_into)</tt></li>
+<li><tt>source.edges(filter, ...)</tt></li>
+</ul>
+<p>
+Creates a layer with the edges from the given layer of the source.
+Edge layers are formed from shapes by decomposing the shapes into edges: polygons
+for example are decomposed into their outline edges. Some file formats support egdes
+as native objects. 
+</p><p>
+This method is identical to <a href="#input">input</a> with respect to the options supported.
+</p><p>
+Use the global version of "edges" without a source object to address the default source.
+</p><p>
+This method has been introduced in version 0.27.
+</p>
 <a name="extent"/><h2>"extent" - Returns a layer with the bounding box of the selected layout</h2>
 <keyword name="extent"/>
 <p>Usage:</p>
@@ -95,7 +137,7 @@ Some filter expressions are:
 not have names)</li>
 </ul>
 </p><p>
-Layers created with "input" contain both texts and polygons. There is a subtle
+Layers created with "input" may contain both texts (labels) and polygons. There is a subtle
 difference between flat and deep mode: in flat mode, texts are not visible in polygon
 operations. In deep mode, texts appear as small 2x2 DBU rectangles. In flat mode, 
 some operations such as clipping are not fully supported for texts. Also, texts will
@@ -106,6 +148,11 @@ Texts can later be selected on the layer returned by "input" with the <a href="/
 If you don't want to see texts, use <a href="#polygons">polygons</a> to create an input layer with polygon data
 only. If you only want to see texts, use <a href="#labels">labels</a> to create an input layer with texts only.
 </p><p>
+<a href="#labels">labels</a> also produces a true "text layer" which contains text objects. A variety of 
+operations is available for these objects, such as boolean "and" and "not" with a polygon layer.
+True text layers should be preferred over mixed polygon/text layers if text object processing
+is required.
+</p><p>
 Use the global version of "input" without a source object to address the default source.
 </p>
 <a name="labels"/><h2>"labels" - Gets the labels (texts) from an input layer</h2>
@@ -118,10 +165,12 @@ Use the global version of "input" without a source object to address the default
 <li><tt>source.labels(filter, ...)</tt></li>
 </ul>
 <p>
-Creates a layer with the labels from the given layer of the source.
+Creates a true text layer with the labels from the given layer of the source.
 </p><p>
 This method is identical to <a href="#input">input</a>, but takes only texts from the given input
-layer.
+layer. Starting with version 0.27, the result is no longer a polygon layer that tries
+to provide text support but a layer type which is provided for carrying text objects
+explicitly.
 </p><p>
 Use the global version of "labels" without a source object to address the default source.
 </p>