Recipe documentation draft, part 12

- implemented suggestions from Dan Marek's review
- additional links to make navigation easier
- various fixes and reformulations to make the text
  more understandable
- previously overlooked element paths + descriptions

doc/recipe_elements/advanced_partitioning.rst

@@ -532,12 +532,12 @@ Configures details for selected partition(s)/LV(s) in the same way as
 
 /installation/hub/partitioning/advanced/select/remove
 =====================================================
-Equivalent to `/installation/hub/partitioning/advanced/select/remove`_.
+Equivalent to `/installation/hub/partitioning/advanced/remove`_.
 
 
 /installation/hub/partitioning/advanced/select/remove/also_related
 ==================================================================
-Equivalent to `/installation/hub/partitioning/advanced/select/remove/also_related`_.
+Equivalent to `/installation/hub/partitioning/advanced/remove/also_related`_.
 
 /installation/hub/partitioning/advanced/summary
 ===============================================

doc/recipe_elements/configuration.rst

@@ -8,8 +8,8 @@ Used for *configuration* spoke that appears during installation process and disp
 notice and Reboot button when installation is complete.
 
 .. note::
-    Originally it provided options to create a user and set root password. The elements for
-    user/root configuration are internally equivalent to
+    This element originally provided options to create a user and set root password.
+    The elements for user/root configuration are internally equivalent to
     :ref:`recipe_elements/hub:/installation/hub/create_user` and
     :ref:`recipe_elements/hub:/installation/hub/root_password`.
 
@@ -27,6 +27,15 @@ Handles button used for finishing configuration during installation process (RHE
 ==================================
 Clicks *Reboot* button after installation is complete.
 
+/installation/configuration/root
+================================
+A shortcut element usable only within the ``ez:`` namespace, functionally equivalent to
+:ref:`recipe_elements/hub:/installation/hub/root`.
+
+/installation/configuration/root_password
+=========================================
+Functionally equivalent to :ref:`recipe_elements/hub:/installation/hub/root_password`.
+
 /installation/configuration/wait_until_complete
 ===============================================
 A special element not used to directly handle any Anaconda's function, but to wait

doc/recipe_elements/connect_to_redhat.rst

@@ -56,6 +56,12 @@ Attributes:
 
 /installation/hub/connect_to_redhat/options/http_proxy
 ======================================================
+*Use HTTP proxy* checkbox (and related proxy settings handled
+in child elements - see below).
+
+Attributes:
+
+* ``used`` - ``yes`` = enabled, anything else = disabled
 
 /installation/hub/connect_to_redhat/options/http_proxy/location
 ===============================================================

doc/recipe_elements/hub.rst

@@ -8,45 +8,46 @@ Handles main Anaconda hub (main screen with buttons for configuration of various
 
 /installation/hub/autopart
 ==========================
-Shortcut element encompassing all steps necessary for automatic partitioning, as it
+Shortcut element encompassing the following steps necessary to complete automatic partitioning:
 
-* enters *Installation Destination* spoke,
-* selects all available standard and specialized disks,
-* opts for reclaiming additional space,
-* removes all available partitions in the reclaim dialog
-* and confirms the configuration.
+* Enter *Installation Destination* spoke,
+* select all available standard and specialized disks,
+* opt to reclaim additional space,
+* remove all available partitions in the reclaim dialog,
+* confirm the configuration.
 
 /installation/hub/begin_installation
 ====================================
 Clicks on *Begin installation* button.
 
 /installation/hub/connect_to_redhat
 ===================================
-Handles *Connect to Red Hat* spoke.
+Handles :doc:`Connect to Red Hat <connect_to_redhat>` spoke.
 
 /installation/hub/create_user
 =============================
-Handles *User Creation* spoke.
+Handles :doc:`User Creation <create_user>` spoke.
 
 /installation/hub/datetime
 ==========================
-Handles *Time & Date* spoke.
+Handles :doc:`Time & Date <datetime>` spoke.
 
 /installation/hub/installation_source
 =====================================
-Handles *Installation Source* spoke.
+Handles :doc:`Installation Source <installation_source>` spoke.
 
 /installation/hub/kdump
 =======================
-Handles *KDUMP* spoke. Only **entering/exiting** the spoke is implemented at this point.
+Handles *KDUMP* spoke. Only **entering/exiting** the spoke is implemented at this point,
+i. e. there are no subelements of ``/installation/hub/kdump``.
 
 /installation/hub/keyboard
 ==========================
-Handles *Keyboard* spoke.
+Handles :doc:`Keyboard <keyboard>` spoke.
 
 /installation/hub/language_spoke
 ================================
-Handles *Language Support* spoke.
+Handles :doc:`Language Support <language>` spoke.
 
 /installation/hub/luks_dialog
 =============================
@@ -78,7 +79,7 @@ It can be used in this place with kickstart installations using
 
 /installation/hub/oscap_addon
 =============================
-Handles *Security Profile* spoke.
+Handles `Security Profile <oscap_addon>` spoke.
 
 Attributes:
 
@@ -89,15 +90,29 @@ Attributes:
 
 /installation/hub/partitioning
 ==============================
-Handles *Installation Destination* spoke.
+Handles :doc:`Installation Destination <partitioning>` spoke.
+
+/installation/hub/root
+======================
+Shortcut element usable only within ``ez:`` :ref:`namespace <recipe_elements/index:the *ez* namespace>`
+to potentially make the recipe simpler by implicitly creating an `/installation/hub/root_password`_
+element after :ref:`preprocessing <recipe_elements/index:the *ez* namespace>`.
+
+It also creates necessary subelements to arrange for automatic filling in of password
+and confirmation password based on ``password`` attribute value and successfully exiting
+the spoke by clicking on Done button twice, using ``may_fail`` policy.
+
+Attributes:
+
+* ``password``
 
 /installation/hub/root_password
 ===============================
-Handles *Root Password* spoke.
+Handles :doc:`Root Password <root_password>` spoke.
 
 /installation/hub/software_selection
 ====================================
-Handles *Software Selection* spoke.
+Handles :doc:`Software Selection <software_selection>` spoke.
 
 Attributes:
 
@@ -107,5 +122,5 @@ Attributes:
 
 /installation/hub/syspurpose
 ============================
-Handles *System Purpose* spoke.
+Handles :doc:`System Purpose <syspurpose>` spoke.
 

doc/recipe_elements/index.rst

@@ -113,14 +113,14 @@ parts (``<kdump />``), with the rest generated automatically by preprocessor:
 The following elements can be used with the ``ez`` namespace (see specific sections for
 descriptions of particular elements):
 
-* /installation
-* /installation/welcome
-* /installation/hub
-* /installation/hub/autopart
-* /installation/hub/root_password
-* /installation/hub/root
-* /installation/configuration/root_password
-* /installation/configuration/root
+* `/installation`_
+* `/installation/welcome`_
+* :ref:`recipe_elements/hub:/installation/hub`
+* :ref:`recipe_elements/hub:/installation/hub/autopart`
+* :ref:`recipe_elements/hub:/installation/hub/root_password`
+* :ref:`recipe_elements/hub:/installation/hub/root`
+* :ref:`recipe_elements/configuration:/installation/configuration/root_password`
+* :ref:`recipe_elements/configuration:/installation/configuration/root`
 
 /installation
 =============

doc/recipe_elements/installation_source.rst

@@ -33,8 +33,8 @@ Reset the additional repositories to original state using the *Revert* button.
 ============================================================
 Selects repositories matching a name (fnmatchcase expression) and repo status
 and performs arbitrary changes on the selected set. Doesn't work with
-``policy="just_check*"``, as it relies on an existing action result
-in the check.
+``policy="just_check"`` or ``policy="just_check_fail"``, as it relies
+on an existing action result in the check.
 
 Attributes:
 

doc/recipe_elements/keyboard.rst

@@ -2,13 +2,32 @@
 Keyboard spoke
 ==============
 
+.. _layout-name-mapping:
+
+Keyboard layout name mapping
+============================
+The keyboard layout names used by Anabot to manipulate with layouts listed in the
+Keyboard spoke may not always be easy to figure out as they are taken from X11
+configuration.
+
+To find a low-level keyboard layout name, have a look under ``! layout`` and ``! variant``
+sections of ``/usr/share/X11/xkb/rules/base.lst`` file in the installer environment.
+For instance, a record under ``! layout`` section consisting of ``cz    Czech``
+appears as ``Czech`` in the layout list and is mapped to ``cz`` value of
+``name`` attribute of an element handling keyboard layout.
+
+In a similar way, a record ``rus    cz: Russian (Czech, phonetic)`` under ``! variant``
+section is listed as ``Russian (Czech, phonetic)`` in the layout list in Anaconda,
+and is mapped to ``cz (rus)`` value of the ``name`` attribute.
+
 /installation/hub/keyboard/add_layout
 =====================================
 Handles *add* (*+*) button and resulting dialog.
 
 Attributes:
 
-* ``name`` - name of the layout, e. g. ``cz`` or ``de (deadgraveacute)``
+* ``name`` - name of the layout, e. g. ``cz`` or ``de (deadgraveacute)`` (see
+  section about layout name :ref:`mapping <layout-name-mapping>`)
 * ``dialog`` - action to handle the dialog - ``accept`` (default) or ``reject``
 
 /installation/hub/keyboard/layout
@@ -18,6 +37,7 @@ Selects a layout from layouts list.
 Attributes:
 
 * ``name`` - name of the layout, e. g. ``de (nodeadkeys)``. A *glob* expression may be used.
+  Also see section about layout name :ref:`mapping <layout-name-mapping>`.
 
 /installation/hub/keyboard/layout/move_down
 ===========================================
@@ -55,7 +75,7 @@ Removes the selected layout from the list using *remove* (*-*) button.
 /installation/hub/keyboard/layout/show
 ======================================
 Displays keyboard layout in graphical form using the appropriate button.
-**No check if the displayed layout is correct is implemented at this point.**
+**There is no check to test whether the displayed layout is correct at this point.**
 
 /installation/hub/keyboard/layout/test
 ======================================
@@ -88,7 +108,8 @@ A shortcut to remove all existing layouts and add a new one.
 
 Attributes:
 
-* ``name`` - name of the layout, e. g. ``cz`` or ``de (deadgraveacute)``
+* ``name`` - name of the replacement layout, e. g. ``cz`` or ``de (deadgraveacute)``
+  (see section about layout name :ref:`mapping <layout-name-mapping>`)
 
 /installation/hub/keyboard/show
 ===============================

doc/recipe_elements/oscap_addon.rst

@@ -57,23 +57,26 @@ equivalent, as it's technically not possible to distinguish the exact type at th
 /installation/hub/oscap_addon/changes/error
 ===========================================
 Handles a line (message) in the changes list. Not specific for an error message at this
-point (see related `note </installation/hub/oscap_addon/changes_>`_).
+point (see related `note </installation/hub/oscap_addon/changes_>`_ for
+``/installation/hub/oscap_addon/changes`` element).
 
 Attributes:
 
 * ``text`` - message text in the raw form (unformatted string)
 * ``params`` (where applicable) - a space-separated list of parameters used for formatting
-    of the message string
+  of the message string
 
 /installation/hub/oscap_addon/changes/info
 ==========================================
 Functionally equivalent to `/installation/hub/oscap_addon/changes/error`_
-at this point (see related `note </installation/hub/oscap_addon/changes_>`_).
+at this point (see related `note </installation/hub/oscap_addon/changes_>`_ for
+``/installation/hub/oscap_addon/changes`` element).
 
 /installation/hub/oscap_addon/changes/warning
 =============================================
 Functionally equivalent to `/installation/hub/oscap_addon/changes/error`_
-at this point (see related `note </installation/hub/oscap_addon/changes_>`_).
+at this point (see related `note </installation/hub/oscap_addon/changes_>`_ for
+``/installation/hub/oscap_addon/changes`` element).
 
 /installation/hub/oscap_addon/choose
 ====================================
@@ -116,6 +119,6 @@ Attributes:
 
 /installation/hub/oscap_addon/use_ssg
 =====================================
-Functionally equivalent to `/installation/hub/oscap_addon/change_content/use_ssg`.
+Functionally equivalent to `/installation/hub/oscap_addon/change_content/use_ssg`_.
 Needs to be used from this path in special cases (e. g. kickstart installation
 with incorrect content fingerprint specified).

doc/recipe_elements/root_password.rst

@@ -4,7 +4,7 @@ Root Password spoke
 
 /installation/configuration/root_password
 =========================================
-Equivalent to `recipe_elements/hub:/installation/hub/root_password`.
+Equivalent to :ref:`recipe_elements/hub:/installation/hub/root_password`.
 
 /installation/configuration/root_password/confirm_password
 ==========================================================

doc/recipe_elements/software_selection.rst

@@ -11,8 +11,9 @@ Attributes:
 * ``action`` - ``select`` or ``deselect``
 * ``id`` - addon id (as defined in comps file) or glob pattern
 * ``subselect`` (optional)
-    * ``random`` - selects random subset of addons (``policy=just_check*`` conflicts
-        with ``subselect=random``).
+    * ``random`` - selects random subset of addons (``policy=just_check`` or
+        ``policy=just_check_fail`` logically conflicts with ``subselect=random``,
+        as it doesn't make sense to check a random selection).
 
 /installation/hub/software_selection/environment
 ================================================