doc: cleanup auto-converted "list" style mistake

Signed-off-by: Christian Hopps <chopps@labn.net>

doc/developer/northbound/advanced-topics.rst

@@ -34,13 +34,16 @@ CLI on a separate program
 
 The flexible design of the northbound architecture opens the door to
 move the CLI to a separate program in the long-term future. Some
-advantages of doing so would be: \* Treat the CLI as just another
+advantages of doing so would be:
-northbound client, instead of having CLI commands embedded in the
+
-binaries of all FRR daemons. \* Improved robustness: bugs in CLI
+* Treat the CLI as just another northbound client, instead of having CLI
-commands (e.g. null-pointer dereferences) or in the CLI code itself
+  commands embedded in the binaries of all FRR daemons.
-wouldn’t affect the FRR daemons. \* Foster innovation by allowing other
+
-CLI programs to be implemented, possibly using higher level programming
+* Improved robustness: bugs in CLI commands (e.g. null-pointer dereferences) or
-languages.
+  in the CLI code itself wouldn’t affect the FRR daemons.
+
+* Foster innovation by allowing other CLI programs to be implemented, possibly
+  using higher level programming languages.
 
 The problem, however, is that the northbound retrofitting process will
 convert only the CLI configuration commands and EXEC commands in a first
@@ -232,40 +235,42 @@ vtysh support
 As explained in the [[Transactional CLI]] page, all commands introduced
 by the transactional CLI are not yet available in *vtysh*. This needs to
 be addressed in the short term future. Some challenges for doing that
-work include: \* How to display configurations (running, candidates and
+work include:
-rollbacks) in a more clever way? The implementation of the
+
-``show running-config`` command in *vtysh* is not something that should
+* How to display configurations (running, candidates and rollbacks) in a more
-be followed as an example. A better idea would be to fetch the desired
+  clever way? The implementation of the ``show running-config`` command in
-configuration from all daemons (encoded in JSON for example), merge them
+  *vtysh* is not something that should be followed as an example. A better idea
-all into a single ``lyd_node`` variable and then display the combined
+  would be to fetch the desired configuration from all daemons (encoded in JSON
-configurations from this variable (the configuration merges would
+  for example), merge them all into a single ``lyd_node`` variable and then
-transparently take care of combining the shared configuration objects).
+  display the combined configurations from this variable (the configuration
-In order to be able to manipulate the JSON configurations, *vtysh* will
+  merges would transparently take care of combining the shared configuration
-need to load the YANG modules from all daemons at startup (this might
+  objects). In order to be able to manipulate the JSON configurations, *vtysh*
-have a minimal impact on startup time). The only issue with this
+  will need to load the YANG modules from all daemons at startup (this might
-approach is that the ``cli_show()`` callbacks from all daemons are
+  have a minimal impact on startup time). The only issue with this approach is
-embedded in their binaries and thus not accessible externally. It might
+  that the ``cli_show()`` callbacks from all daemons are embedded in their
-be necessary to compile these callbacks on a separate shared library so
+  binaries and thus not accessible externally. It might be necessary to compile
-that they are accessible to *vtysh* too. Other than that, displaying the
+  these callbacks on a separate shared library so that they are accessible to
-combined configurations in the JSON/XML formats should be
+  *vtysh* too. Other than that, displaying the combined configurations in the
-straightforward. \* With the current design, transaction IDs are
+  JSON/XML formats should be straightforward.
-per-daemon and not global across all FRR daemons. This means that the
+
-same transaction ID can represent different transactions on different
+* With the current design, transaction IDs are per-daemon and not global across
-daemons. Given this observation, how to implement the
+  all FRR daemons. This means that the same transaction ID can represent
-``rollback configuration`` command in *vtysh*? The easy solution would
+  different transactions on different daemons. Given this observation, how to
-be to add a ``daemon WORD`` argument to specify the context of the
+  implement the ``rollback configuration`` command in *vtysh*? The easy solution
-rollback, but per-daemon rollbacks would certainly be confusing and
+  would be to add a ``daemon WORD`` argument to specify the context of the
-convoluted to end users. A better idea would be to attack the root of
+  rollback, but per-daemon rollbacks would certainly be confusing and convoluted
-the problem: change configuration transactions to be global instead of
+  to end users. A better idea would be to attack the root of the problem: change
-being per-daemon. This involves a bigger change in the northbound
+  configuration transactions to be global instead of being per-daemon. This
-architecture, and would have implications on how transactions are stored
+  involves a bigger change in the northbound architecture, and would have
-in the SQL database (daemon-specific and shared configuration objects
+  implications on how transactions are stored in the SQL database
-would need to have their own tables or columns). \* Loading
+  (daemon-specific and shared configuration objects would need to have their own
-configuration files in the JSON or XML formats will be tricky, as
+  tables or columns).
-*vtysh* will need to know which sections of the configuration should be
+
-sent to which daemons. *vtysh* will either need to fetch the YANG
+* Loading configuration files in the JSON or XML formats will be tricky, as
-modules implemented by all daemons at runtime or obtain this information
+  *vtysh* will need to know which sections of the configuration should be sent
-at compile-time somehow.
+  to which daemons. *vtysh* will either need to fetch the YANG modules
+  implemented by all daemons at runtime or obtain this information at
+  compile-time somehow.
 
 Detecting type mismatches at compile-time
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

doc/developer/northbound/architecture.rst

@@ -42,30 +42,34 @@ and
 `CoAP <https://www.ietf.org/archive/id/draft-vanderstok-core-comi-11.txt>`__.
 
 In addition to being management-protocol independent, some other
-advantages of using YANG in FRR are listed below: \* Have a formal
+advantages of using YANG in FRR are listed below:
-contract between FRR and application developers (management clients). A
+
-management client that has access to the FRR YANG models knows about all
+* Have a formal contract between FRR and application developers (management
-existing configuration options available for use. This information can
+  clients). A management client that has access to the FRR YANG models knows
-be used to auto-generate user-friendly interfaces like Web-UIs, custom
+  about all existing configuration options available for use. This information
-CLIs and even code bindings for several different programming languages.
+  can be used to auto-generate user-friendly interfaces like Web-UIs, custom
-Using `PyangBind <https://github.com/robshakir/pyangbind>`__, for
+  CLIs and even code bindings for several different programming languages. Using
-example, it’s possible to generate Python class hierarchies from YANG
+  `PyangBind <https://github.com/robshakir/pyangbind>`__, for example, it’s
-models and use these classes to instantiate objects that mirror the
+  possible to generate Python class hierarchies from YANG models and use these
-structure of the YANG modules and can be serialized/deserialized using
+  classes to instantiate objects that mirror the structure of the YANG modules
-different encoding formats. \* Support different encoding formats for
+  and can be serialized/deserialized using different encoding formats.
-instance data. Currently only JSON and XML are supported, but
+
-`GPB <https://developers.google.com/protocol-buffers/>`__ and
+* Support different encoding formats for instance data. Currently only JSON and
-`CBOR <http://cbor.io/>`__ are other viable options in the long term.
+  XML are supported, but `GPB
-Additional encoding formats can be implemented in the *libyang* library
+  <https://developers.google.com/protocol-buffers/>`__ and `CBOR
-for optimal performance, or externally by translating data to/from one
+  <http://cbor.io/>`__ are other viable options in the long term. Additional
-of the supported formats (with a performance penalty). \* Have a formal
+  encoding formats can be implemented in the *libyang* library for optimal
-mechanism to introduce backward-incompatible changes based on `semantic
+  performance, or externally by translating data to/from one of the supported
-versioning <http://www.openconfig.net/docs/semver/>`__ (not part of the
+  formats (with a performance penalty).
-YANG standard, which allows backward-compatible module updates only). \*
+
-Provide seamless support to the industry-standard NETCONF/RESTCONF
+* Have a formal mechanism to introduce backward-incompatible changes based on
-protocols as alternative management APIs. If FRR configuration/state
+  `semantic versioning <http://www.openconfig.net/docs/semver/>`__ (not part of
-data is modeled using YANG, supporting YANG-based protocols like NETCONF
+  the YANG standard, which allows backward-compatible module updates only).
-and RESTCONF is much easier.
+
+* Provide seamless support to the industry-standard NETCONF/RESTCONF protocols
+  as alternative management APIs. If FRR configuration/state data is modeled
+  using YANG, supporting YANG-based protocols like NETCONF and RESTCONF is much
+  easier.
 
 As important as shifting to a model-driven management paradigm, the new
 northbound architecture also introduces the concept of configuration

doc/developer/northbound/operational-data-rpcs-and-notifications.rst

@@ -330,10 +330,12 @@ CLI can take too long, potentially long enough to the point of
 triggering some protocol timeouts and bringing sessions down.
 
 To avoid this kind of problem, northbound clients are encouraged to do
-one of the following: \* Create a separate pthread for handling requests
+one of the following:
-to fetch operational data. \* Iterate over YANG lists and leaf-lists
+
-asynchronously, returning a maximum number of elements per time instead
+* Create a separate pthread for handling requests to fetch operational data.
-of returning all elements in one shot.
+
+* Iterate over YANG lists and leaf-lists asynchronously, returning a maximum
+  number of elements per time instead of returning all elements in one shot.
 
 In order to handle both cases correctly, the ``get_next`` callbacks need
 to use locks to prevent the YANG lists from being modified while they

doc/developer/northbound/retrofitting-configuration-commands.rst

@@ -33,34 +33,41 @@ possible to facilitate the process of writing module translators using
 the [[YANG module translator]]. As an example, the frr-ripd YANG module
 incorporated several parts of the IETF RIP YANG module. The repositories
 below contain big collections of YANG models that might be used as a
-reference: \* https://github.com/YangModels/yang \*
+reference:
-https://github.com/openconfig/public
+
+* https://github.com/YangModels/yang
+
+* https://github.com/openconfig/public
 
 When writing a YANG module, it’s highly recommended to follow the
 guidelines from `RFC 6087 <https://tools.ietf.org/html/rfc6087>`__. In
 general, most commands should be modeled fairly easy. Here are a few
-guidelines specific to authors of FRR YANG models: \* Use
+guidelines specific to authors of FRR YANG models:
-presence-containers or lists to model commands that change the CLI node
+
-(e.g. ``router rip``, ``interface eth0``). This way, if the
+* Use presence-containers or lists to model commands that change the CLI node
-presence-container or list entry is removed, all configuration options
+  (e.g. ``router rip``, ``interface eth0``). This way, if the presence-container
-below them are removed automatically (exactly like the CLI behaves when
+  or list entry is removed, all configuration options below them are removed
-a configuration object is removed using a *no* command). This
+  automatically (exactly like the CLI behaves when a configuration object is
-recommendation is orthogonal to the `YANG authoring guidelines for
+  removed using a *no* command). This recommendation is orthogonal to the `YANG
-OpenConfig
+  authoring guidelines for OpenConfig models
-models <https://github.com/openconfig/public/blob/master/doc/openconfig_style_guide.md>`__
+  <https://github.com/openconfig/public/blob/master/doc/openconfig_style_guide.md>`__
-where the use of presence containers is discouraged. OpenConfig YANG
+  where the use of presence containers is discouraged. OpenConfig YANG models
-models however were not designed to replicate the behavior of legacy CLI
+  however were not designed to replicate the behavior of legacy CLI commands.
-commands. \* When using YANG lists, be careful to identify what should
+
-be the key leaves. In the ``offset-list WORD <in|out> (0-16) IFNAME``
+* When using YANG lists, be careful to identify what should be the key leaves.
-command, for example, both the direction (``<in|out>``) and the
+  In the ``offset-list WORD <in|out> (0-16) IFNAME`` command, for example, both
-interface name should be the keys of the list. This can be only known by
+  the direction (``<in|out>``) and the interface name should be the keys of the
-analyzing the data structures used to store the commands. \* For
+  list. This can be only known by analyzing the data structures used to store
-clarity, use non-presence containers to group leaves that are associated
+  the commands.
-to the same configuration command (as we’ll see later, this also
+
-facilitate the process of writing ``cli_show`` callbacks). \* YANG
+* For clarity, use non-presence containers to group leaves that are associated
-leaves of type *enumeration* should define explicitly the value of each
+  to the same configuration command (as we’ll see later, this also facilitate
-*enum* option based on the value used in the FRR source code. \* Default
+  the process of writing ``cli_show`` callbacks).
-values should be taken from the source code whenever they exist.
+
+* YANG leaves of type *enumeration* should define explicitly the value of each
+  *enum* option based on the value used in the FRR source code.
+
+* Default values should be taken from the source code whenever they exist.
 
 Some commands are more difficult to model and demand the use of more
 advanced YANG constructs like *choice*, *when* and *must* statements.
@@ -729,15 +736,17 @@ Configuration options are edited individually
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 Several CLI commands edit multiple configuration options at the same
-time. Some examples taken from ripd: \*
+time. Some examples taken from ripd:
-``timers basic (5-2147483647) (5-2147483647) (5-2147483647)`` -
+
-*/frr-ripd:ripd/instance/timers/flush-interval* -
+* ``timers basic (5-2147483647) (5-2147483647) (5-2147483647)``
-*/frr-ripd:ripd/instance/timers/holddown-interval* -
+  * */frr-ripd:ripd/instance/timers/flush-interval*
-*/frr-ripd:ripd/instance/timers/update-interval* \*
+  * */frr-ripd:ripd/instance/timers/holddown-interval*
-``distance (1-255) A.B.C.D/M [WORD]`` -
+  * */frr-ripd:ripd/instance/timers/update-interval*
-*/frr-ripd:ripd/instance/distance/source/prefix* -
+
-*/frr-ripd:ripd/instance/distance/source/distance* -
+* ``distance (1-255) A.B.C.D/M [WORD]``
-*/frr-ripd:ripd/instance/distance/source/access-list*
+  * */frr-ripd:ripd/instance/distance/source/prefix*
+  * */frr-ripd:ripd/instance/distance/source/distance*
+  * */frr-ripd:ripd/instance/distance/source/access-list*
 
 In the new northbound model, there’s one or more separate callbacks for
 each configuration option. This usually has implications when converting
@@ -1037,16 +1046,23 @@ changing the candidate configuration.
    the northbound callbacks are not involved).
 
 Other important details to keep in mind while rewriting the CLI
-commands: \* ``nb_cli_cfg_change()`` returns CLI errors codes
+commands:
-(e.g. ``CMD_SUCCESS``, ``CMD_WARNING``), so the return value of this
+
-function can be used as the return value of CLI commands. \* Calls to
+* ``nb_cli_cfg_change()`` returns CLI errors codes (e.g. ``CMD_SUCCESS``,
-``VTY_PUSH_CONTEXT`` and ``VTY_PUSH_CONTEXT_SUB`` should be converted to
+  ``CMD_WARNING``), so the return value of this function can be used as the
-calls to ``VTY_PUSH_XPATH``. Similarly, the following macros aren’t
+  return value of CLI commands.
-necessary anymore and can be removed: ``VTY_DECLVAR_CONTEXT``,
+
-``VTY_DECLVAR_CONTEXT_SUB``, ``VTY_GET_CONTEXT`` and
+* Calls to ``VTY_PUSH_CONTEXT`` and ``VTY_PUSH_CONTEXT_SUB`` should be converted
-``VTY_CHECK_CONTEXT``. The ``nb_cli_cfg_change()`` functions uses the
+  to calls to ``VTY_PUSH_XPATH``. Similarly, the following macros aren’t
-``VTY_CHECK_XPATH`` macro to check if the data node being edited still
+  necessary anymore and can be removed:
-exists before doing anything else.
+
+  * ``VTY_DECLVAR_CONTEXT``
+  * ``VTY_DECLVAR_CONTEXT_SUB``
+  * ``VTY_GET_CONTEXT``
+  * ``VTY_CHECK_CONTEXT``.
+
+  The ``nb_cli_cfg_change()`` functions uses the ``VTY_CHECK_XPATH`` macro to
+  check if the data node being edited still exists before doing anything else.
 
 The examples below provide additional details about how the conversion
 should be done.
@@ -1788,10 +1804,13 @@ Implementation of the ``cli_show`` callback:
    }
 
 This is the most complex ``cli_show`` callback we have in ripd. Its
-complexity comes from the following: \* The
+complexity comes from the following:
-``ip rip authentication mode ...`` command changes two YANG leaves at
+
-the same time. \* Part of the command should be hidden when the
+* The ``ip rip authentication mode ...`` command changes two YANG leaves at the
-``show_defaults`` parameter is set to false.
+  same time.
+
+* Part of the command should be hidden when the ``show_defaults`` parameter is
+  set to false.
 
 This is the behavior we want to implement:
 
@@ -1841,19 +1860,27 @@ As mentioned in the fourth step, the northbound retrofitting process can
 happen gradually over time, since both “old” and “new” commands can
 coexist without problems. Once all commands from a given daemon were
 converted, we can proceed to the consolidation step, which consists of
-the following: \* Remove the vty configuration lock, which is enabled by
+the following:
-default in all daemons. Now multiple users should be able to edit the
+
-configuration concurrently, using either shared or private candidate
+* Remove the vty configuration lock, which is enabled by default in all daemons.
-configurations. \* Reference commit:
+  Now multiple users should be able to edit the configuration concurrently,
-`57dccdb1 <https://github.com/opensourcerouting/frr/commit/57dccdb18b799556214dcfb8943e248c0bf1f6a6>`__.
+  using either shared or private candidate configurations.
-\* Stop using the qobj infrastructure to keep track of configuration
+
-objects. This is not necessary anymore, the northbound uses a similar
+* Reference commit: `57dccdb1
-mechanism to keep track of YANG data nodes in the candidate
+  <https://github.com/opensourcerouting/frr/commit/57dccdb18b799556214dcfb8943e248c0bf1f6a6>`__.
-configuration. \* Reference commit:
+
-`4e6d63ce <https://github.com/opensourcerouting/frr/commit/4e6d63cebd988af650c1c29d0f2e5a251c8d2e7a>`__.
+* Stop using the qobj infrastructure to keep track of configuration objects.
-\* Make the daemon SIGHUP handler re-read the configuration file (and
+  This is not necessary anymore, the northbound uses a similar mechanism to keep
-ensure it’s not doing anything other than that). \* Reference commit:
+  track of YANG data nodes in the candidate configuration.
-`5e57edb4 <https://github.com/opensourcerouting/frr/commit/5e57edb4b71ff03f9a22d9ec1412c3c5167f90cf>`__.
+
+* Reference commit: `4e6d63ce
+  <https://github.com/opensourcerouting/frr/commit/4e6d63cebd988af650c1c29d0f2e5a251c8d2e7a>`__.
+
+* Make the daemon SIGHUP handler re-read the configuration file (and ensure it’s
+  not doing anything other than that).
+
+* Reference commit: `5e57edb4
+  <https://github.com/opensourcerouting/frr/commit/5e57edb4b71ff03f9a22d9ec1412c3c5167f90cf>`__.
 
 Final Considerations
 --------------------

doc/developer/northbound/transactional-cli.rst

@@ -70,18 +70,21 @@ Configuration modes
 ~~~~~~~~~~~~~~~~~~~
 
 When using the transactional CLI (``--tcli``), FRR supports three
-different forms of the ``configure`` command: \* ``configure terminal``:
+different forms of the ``configure`` command:
-in this mode, a single candidate configuration is shared by all users.
+
-This means that one user might delete a configuration object that’s
+* ``configure terminal``: in this mode, a single candidate configuration is
-being edited by another user, in which case the CLI will detect and
+  shared by all users. This means that one user might delete a configuration
-report the problem. If one user issues the ``commit`` command, all
+  object that’s being edited by another user, in which case the CLI will detect
-changes done by all users are committed. \* ``configure private``: users
+  and report the problem. If one user issues the ``commit`` command, all changes
-have a private candidate configuration that is edited separately from
+  done by all users are committed.
-the other users. The ``commit`` command commits only the changes done by
+
-the user. \* ``configure exclusive``: similar to ``configure private``,
+* ``configure private``: users have a private candidate configuration that is
-but also locks the running configuration to prevent other users from
+  edited separately from the other users. The ``commit`` command commits only
-changing it. The configuration lock is released when the user exits the
+  the changes done by the user.
-configuration mode.
+
+* ``configure exclusive``: similar to ``configure private``, but also locks the
+  running configuration to prevent other users from changing it. The
+  configuration lock is released when the user exits the configuration mode.
 
 When using ``configure terminal`` or ``configure private``, the
 candidate configuration being edited might become outdated if another
@@ -112,12 +115,14 @@ Check if the candidate configuration is valid or not.
 Commit the changes done in the candidate configuration into the running
 configuration.
 
-Options: \* ``force``: commit even if the candidate configuration is
+Options:
-outdated. It’s usually a better option to use the ``update`` command
+
-instead. \* ``comment LINE...``: assign a comment to the configuration
+* ``force``: commit even if the candidate configuration is outdated. It’s
-transaction. This comment is displayed when viewing the recorded
+  usually a better option to use the ``update`` command instead.
-transactions in the output of the ``show configuration transaction``
+
-command.
+* ``comment LINE...``: assign a comment to the configuration transaction. This
+  comment is displayed when viewing the recorded transactions in the output of
+  the ``show configuration transaction`` command.
 
 ``discard``
 '''''''''''
@@ -140,10 +145,13 @@ respectively. It’s also possible to load a configuration from a previous
 transaction by specifying the desired transaction ID
 (``(1-4294967296)``).
 
-Options: \* ``translate WORD``: translate the JSON/XML configuration
+Options:
-file using the YANG module translator. \* ``replace``: replace the
+
-candidate by the loaded configuration. The default is to merge the
+* ``translate WORD``: translate the JSON/XML configuration file using the YANG
-loaded configuration into the candidate configuration.
+  module translator.
+
+* ``replace``: replace the candidate by the loaded configuration. The default is
+  to merge the loaded configuration into the candidate configuration.
 
 ``rollback configuration (1-4294967296)``
 '''''''''''''''''''''''''''''''''''''''''
@@ -156,39 +164,42 @@ identified by its transaction ID (``(1-4294967296)``).
 
 Show the candidate configuration.
 
-Options: \* ``json``: show the configuration in the JSON format. \*
+Options:
-``xml``: show the configuration in the XML format. \*
+
-``translate WORD``: translate the JSON/XML output using the YANG module
+* ``json``: show the configuration in the JSON format.
-translator. \* ``with-defaults``: show default values that are hidden by
+* ``xml``: show the configuration in the XML format.
-default. \* ``changes``: show only the changes done in the candidate
+* ``translate WORD``: translate the JSON/XML output using the YANG module translator.
-configuration.
+* ``with-defaults``: show default values that are hidden by default.
+* ``changes``: show only the changes done in the candidate configuration.
 
 ``show configuration compare <candidate|running|transaction (1-4294967296)> <candidate|running|transaction (1-4294967296)> [<json|xml> [translate WORD]]``
 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 
 Show the difference between two different configurations.
 
-Options: \* ``json``: show the configuration differences in the JSON
+Options:
-format. \* ``xml``: show the configuration differences in the XML
+
-format. \* ``translate WORD``: translate the JSON/XML output using the
+* ``json``: show the configuration differences in the JSON format.
-YANG module translator.
+* ``xml``: show the configuration differences in the XML format.
+* ``translate WORD``: translate the JSON/XML output using the YANG module translator.
 
 ``show configuration running [<json|xml> [translate WORD]] [with-defaults]``
 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
 
 Show the running configuration.
 
-Options: \* ``json``: show the configuration in the JSON format. \*
+Options:
-``xml``: show the configuration in the XML format. \*
-``translate WORD``: translate the JSON/XML output using the YANG module
-translator. \* ``with-defaults``: show default values that are hidden by
-default.
 
-   NOTE: ``show configuration running`` shows only the running
+* ``json``: show the configuration in the JSON format.
-   configuration as known by the northbound layer. Configuration
+* ``xml``: show the configuration in the XML format.
-   commands not converted to the new northbound model will not be
+* ``translate WORD``: translate the JSON/XML output using the YANG module translator.
-   displayed. To show the full running configuration, the legacy
+* ``with-defaults``: show default values that are hidden by default.
-   ``show running-config`` command must be used.
+
+NOTE: ``show configuration running`` shows only the running
+configuration as known by the northbound layer. Configuration
+commands not converted to the new northbound model will not be
+displayed. To show the full running configuration, the legacy
+``show running-config`` command must be used.
 
 ``show configuration transaction [(1-4294967296) [<json|xml> [translate WORD]] [changes]]``
 '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
@@ -199,12 +210,13 @@ configuration associated to the previously committed transaction.
 When a transaction ID is not given, show all recorded transactions in
 the rollback log.
 
-Options: \* ``json``: show the configuration in the JSON format. \*
+Options:
-``xml``: show the configuration in the XML format. \*
+
-``translate WORD``: translate the JSON/XML output using the YANG module
+* ``json``: show the configuration in the JSON format.
-translator. \* ``with-defaults``: show default values that are hidden by
+* ``xml``: show the configuration in the XML format.
-default. \* ``changes``: show changes compared to the previous
+* ``translate WORD``: translate the JSON/XML output using the YANG module translator.
-transaction.
+* ``with-defaults``: show default values that are hidden by default.
+* ``changes``: show changes compared to the previous transaction.
 
 ``show yang module [module-translator WORD] [WORD <summary|tree|yang|yin>]``
 ''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
@@ -212,11 +224,14 @@ transaction.
 When a YANG module is not given, show all loaded YANG modules.
 Otherwise, show detailed information about the given module.
 
-Options: \* ``module-translator WORD``: change the context to modules
+Options:
-loaded by the specified YANG module translator. \* ``summary``: display
+
-summary information about the module. \* ``tree``: display module in the
+* ``module-translator WORD``: change the context to modules loaded by the
-tree (RFC 8340) format. \* ``yang``: display module in the YANG format.
+  specified YANG module translator.
-\* ``yin``: display module in the YIN format.
+* ``summary``: display summary information about the module.
+* ``tree``: display module in the tree (RFC 8340) format.
+* ``yang``: display module in the YANG format.
+* ``yin``: display module in the YIN format.
 
 ``show yang module-translator``
 '''''''''''''''''''''''''''''''

doc/developer/northbound/yang-module-translator.rst

@@ -421,15 +421,20 @@ this shortcoming and make it possible to create more powerful YANG
 module translators.
 
 YANG module translators can be evaluated based on the following metrics:
-\* Translation potential: is it possible to make complex translations,
+
-taking several variables into account? \* Complexity: measure of how
+* Translation potential: is it possible to make complex translations, taking
-easy or hard it is to write a module translator. \* Speed: measure of
+  several variables into account?
-how fast the translation can be achieved. Translation speed is of
+
-fundamental importance, especially for operational data. \* Robustness:
+* Complexity: measure of how easy or hard it is to write a module translator.
-can the translator be checked for inconsistencies at load time? A module
+
-translator based on scripts wouldn’t fare well on this metric. \*
+* Speed: measure of how fast the translation can be achieved. Translation speed
-Round-trip conversions: can the translated data be translated back to
+  is of fundamental importance, especially for operational data.
-the original format without information loss?
+
+* Robustness: can the translator be checked for inconsistencies at load time? A
+  module translator based on scripts wouldn’t fare well on this metric.
+
+* Round-trip conversions: can the translated data be translated back to the
+  original format without information loss?
 
 CLI Demonstration
 -----------------

doc/developer/northbound/yang-tools.rst

@@ -83,17 +83,19 @@ Indent a YANG file:
        --keep-comments -f yang --yang-canonical \
        module.yang -o module.yang
 
-Generate skeleton instance data: \* XML:
+Generate skeleton instance data:
 
-.. code:: sh
+* XML:
+
+   .. code:: sh
 
    $ pyang -p <yang-search-path> \
        -f sample-xml-skeleton --sample-xml-skeleton-defaults \
        module.yang [augmented-module1.yang ...] -o module.xml
 
--  JSON:
+*  JSON:
 
-.. code:: sh
+   .. code:: sh
 
    $ pyang -p <yang-search-path> \
        -f jsonxsl module.yang -o module.xsl