# HG changeset patch
# User Franz Glasner <fzglas.hg@dom66.de>
# Date 1636508318 -3600
# Node ID b2c0550d5a44a7feef960b794867e71832ee7d6d
# Parent  d7dcd76c262a08e9a77db53e39c0450d121f16a4
Docs: minimal introduction for getfirstXXXl_s variants

diff -r d7dcd76c262a -r b2c0550d5a44 docs/introduction.rst
--- a/docs/introduction.rst	Wed Nov 10 02:12:37 2021 +0100
+++ b/docs/introduction.rst	Wed Nov 10 02:38:38 2021 +0100
@@ -247,6 +247,22 @@
 accept a *list* of possible variables names and return the first one
 that is found.
 
+And again --- with :py:meth:`.Configuration.getfirstvarl`,
+:py:meth:`.Configuration.getfirstvarl_s`,
+:py:meth:`.Configuration.getfirstintvarl_s`,
+:py:meth:`.Configuration.getfirstboolvarl_s` and
+:py:meth:`.Configuration.getfirstfloatvarl_s` there exist variants
+that accept a *list* of lists or tuples or dicts that describe
+possible variables names and return the first one that is found.
+
+For example -- these methods for retrieving the first found variables
+can be used and are equivalent::
+
+  value1 = config.getfirstvar_s("key1.subkey2", "key3.subkey4", default=None, namespace=None)
+  value2 = config.getfirstvarl_s(*[["key1", "subkey2"], ["key3", "subkey4"]], default=None)
+  value3 = config.getfirstvarl_s(*(("key1", "subkey2"), ("key3", "subkey4")), default=None)
+  value4 = config.getfirstvarl_s(*[{"namespace": None, "path": ["key1", "subkey2"]}, {"namespace": None, "path": ("key3", "subkey4")}], default=None)
+
 Looking at the example in chapter :ref:`yaml-files` -- when calling
 ``config.getvar_s("tree1.tree2.key4")`` you will get the value
 ``get this as `tree1.tree2.key4'``.