From 50cad403b27753d38df6be69d8654174be4b1cd8 Mon Sep 17 00:00:00 2001
From: Matthias Koefferlein <matthias@klayout.de>
Date: Thu, 4 Sep 2025 20:46:30 +0200
Subject: [PATCH] Doc updates (vias, paths)

---
 src/db/db/gsiDeclDbVia.cc                |  2 +-
 src/doc/doc/manual/create_path.xml       | 24 ++++++++++++++++++++----
 src/doc/doc/manual/editor_operations.xml |  1 +
 3 files changed, 22 insertions(+), 5 deletions(-)

diff --git a/src/db/db/gsiDeclDbVia.cc b/src/db/db/gsiDeclDbVia.cc
index 3b446bbe6..8e167435c 100644
--- a/src/db/db/gsiDeclDbVia.cc
+++ b/src/db/db/gsiDeclDbVia.cc
@@ -156,7 +156,7 @@ Class<db::ViaType> decl_dbViaType ("db", "ViaType",
     "@brief If non-zero, the top layer's dimensions will be rounded to this grid.\n"
   ),
   "@brief Describes a via type\n"
-  "These objects are used by PCellDeclaration#via_types to specify the via types a "
+  "These objects are used by \\PCellDeclaration#via_types to specify the via types a "
   "via PCell is able to provide.\n"
   "\n"
   "The basic parameters of a via type are bottom and top layers (the layers that are "
diff --git a/src/doc/doc/manual/create_path.xml b/src/doc/doc/manual/create_path.xml
index 1cee916cb..e6763c061 100644
--- a/src/doc/doc/manual/create_path.xml
+++ b/src/doc/doc/manual/create_path.xml
@@ -10,16 +10,16 @@
   <p>
   Select "Path" mode from the toolbar. The editor options dialog will open that additionally prompts for 
   basic path parameters, such as width and extension scheme. When a path is being drawn, it will receive
-  the settings entered into this dialog. The path properties can even be changed, while the path is 
-  being drawn. Don't forget to click "Apply" to take over the current entries. If the dialog has been
-  closed unintentionally, it can be reopened with the F3 shortcut.
+  the settings entered into this dialog. The path properties can be changed, while the path is 
+  being drawn. If the option page has been closed unintentionally, it can be reopened with the F3 shortcut.
   </p>
 
   <p>
   To actually draw a path, 
-  choose a layer from the layer panel in which to create a new box. 
+  choose a layer from the layer panel in which to create a new path. 
   Left click at the first vertex, move the mouse to the second vertex, click to place this one and continue 
   to the last vertex. Double-click at the last vertex to finish the path. Press the ESC key to cancel the operation.
+  Use the backspace key to remove the current segment and go back to the previous segment.
   </p>
 
   <p>
@@ -30,5 +30,21 @@
   also during editing.
   </p>
 
+  <p>
+  <keyword name="Via"/>
+  <keyword name="Vias"/>
+  Paths are often used for wires. KLayout can be configured to provide 
+  vias that allow switching from one layer to another and place a via 
+  between the layers where the paths overlap. Before you can use the via feature,
+  KLayout has to be equipped with via definitions. Vias are basically PCells which
+  need to support a specific set of parameters. Via PCells need to expose a number
+  of descriptors to define the options supported by a particular PCell (e.g. the
+  layers which are connected or the type of via if multiple flavors are available).
+  This scheme allows for a lot of flexibility, but needs some coding skills.
+  In the macro IDE, a code sample is provided which implements two simple vias
+  for a three-layer metal stack. For more details see <class_doc href="PCellDeclaration"/>,
+  method "via_types" and <class_doc href="ViaType"/>.
+  </p>
+
 </doc>
 
diff --git a/src/doc/doc/manual/editor_operations.xml b/src/doc/doc/manual/editor_operations.xml
index a6d47ad91..6ae56347b 100644
--- a/src/doc/doc/manual/editor_operations.xml
+++ b/src/doc/doc/manual/editor_operations.xml
@@ -15,6 +15,7 @@
     <topic href="/manual/create_cells.xml"/>
     <topic href="/manual/create_polygon.xml"/>
     <topic href="/manual/create_box.xml"/>
+    <topic href="/manual/create_path.xml"/>
     <topic href="/manual/create_text.xml"/>
     <topic href="/manual/create_instance.xml"/>
     <topic href="/manual/move_sel.xml"/>