doc: clarify sections and use "home styled" admonitions

Files in doc/cli/*.md are used in and displayed as help text in the CLI
admin-exec level.  So we cannot use standard admonitions (yet) since the
terminal markdown converter (lowdown) doesn't support the syntax.

Signed-off-by: Joachim Wiberg <[email protected]>

Author: troglobit

doc/cli/configure.md

@@ -40,12 +40,15 @@ admin@host:/config/interface/eth0/> up
 admin@host:/config/>
 ```
 
-> **Note:** the tree structure in the configure context is automatically
-> generated from the system's supported NETCONF YANG models, which may
-> vary between products.  However, the `ietf-interfaces.yang` and
-> `ietf-ip.yang` models, for instance, that provide basic networking
+----
+
+> **Note:** commands in configure context are automatically generated
+> from the system's YANG models, hence different products likely have a
+> different set of commands.  However, both the `ietf-interfaces.yang`
+> and `ietf-ip.yang` models, for instance, that provide the networking
 > support are common to all systems.
 
+----
 
 ## Set IP Address on an Interface
 
@@ -103,9 +106,12 @@ admin@host:/> copy running-config startup-config
 The `startup-config` can also be inspected with the `show` command to
 verify the changes are saved.
 
-> **Note:** most (all) commands need to be spelled out, no short forms
-> are allowed at the moment.  Use the `TAB` key to make this easier.
+----
+
+> **Note:** all commands need to be spelled out, no short forms are
+> allowed in the CLI.  Use the `TAB` key to make your life easier.
 
+----
 
 ## Changing Hostname
 
@@ -122,9 +128,12 @@ admin@example:/>
 Notice how the hostname in the prompt does not change until the change
 is committed.
 
+----
+
 > **Note:** critical services like syslog, mDNS, LLDP, and similar that
 > advertise the hostname, are restarted when the hostname is changed.
 
+----
 
 ## Changing Password
 
@@ -148,10 +157,13 @@ the `do password encrypt` command.  This launches the admin-exec command
 to hash, and optionally salt, your password.  This encrypted string can
 then be used with `set password ...`.
 
+----
+
 > **Tip:** if you are having trouble thinking of a password, there is
 > also `do password generate`, which generates random but readable
 > strings using the UNIX command `pwgen`.
 
+----
 
 ## SSH Authorized Key
 
@@ -173,10 +185,14 @@ key-data AAAAB3NzaC1yc2EAAAADAQABAAABgQC8iBL42yeMBioFay7lty1C4ZDTHcHyo739gc91rTT
 admin@host:/config/system/authentication/user/admin/authorized-key/example@host/> leave
 ```
 
+----
+
 > **Note:** the `ssh-keygen` program already base64 encodes the public
 > key data, so there is no need to use the `text-editor` command, `set`
 > does the job.
 
+----
+
 ## Creating a VETH Pair
 
 The following example creates a `veth0a <--> veth0b` virtual Ethernet
@@ -213,10 +229,13 @@ admin@host:/config/> leave
 
 See the bridging example below for more.
 
+----
+
 > **Note:** in the CLI you do not have to create the `veth0b` interface.
 > The system _infers_ this for you.  When setting up a VETH pair using
 > NETCONF, however, you must include the `veth0b` interface.
 
+----
 
 ## Creating a Bridge
 
@@ -272,6 +291,10 @@ the VETH pair from the previous example) are now bridged.  Any traffic
 ingressing one port will egress the other.  Only reserved IEEE multicast
 is filtered, except LLDP frames as shown above.
 
+----
+
 > **Note:** the bridge can be named anything, provided the interface
 > name is not already taken.  However, for any name outside the pattern
 > `br[0-9]+`, you have to set the interface type manually to `bridge`.
+
+----

doc/cli/introduction.md

@@ -1,4 +1,4 @@
-# Introduction
+# CLI Introduction
 
 The command line interface (CLI, see-ell-aye) implements a CISCO-like,
 or Juniper Networks JunOS-like, CLI.  It is the traditional way of
@@ -10,8 +10,7 @@ Nevertheless, when it comes to initial deployment and debugging, it
 is very useful to know how to navigate and use the CLI.  This very
 short guide intends to help you with that.
 
-
-## About
+----
 
 New users usually get the CLI as the default "shell" when logging in,
 but the default `admin` user logs in to `bash`.  To access the CLI,
@@ -35,9 +34,12 @@ admin@host-12-34-56:/> show                   # Try: Tab or ?
 admin@host-12-34-56:/>                        # Try: Tab or ?
 ```
 
-> **Tip:** Even on an empty command line you can tap the Tab or ? keys.
-> See `help keybindings` for more tips!
+----
+
+> **Note:** even on an empty command line, you can tap the `Tab` or `?` keys.  
+> See [`help keybindings`](keybindings.md) for more tips!
 
+----
 
 ## Key Concepts
 
@@ -132,8 +134,12 @@ In *configure context* the following commands are available:
 
 ## Example Session
 
-> Remember to use the `TAB` and `?` keys to speed up your navigation.
-> See `help keybindings` for more tips!
+----
+
+> Remember to use the `TAB` and `?` keys to speed up your navigation.  
+> See [`help keybindings`](keybindings.md) for more tips!
+
+----
 
 In this example we enter configure context to add an IPv4 address to
 interface `eth0`, then we apply the changes using the `leave` command.
@@ -181,4 +187,3 @@ admin@host-12-34-56:/> copy startup-config running-config
 ```
 
 Or restarting the device.
-

doc/cli/keybindings.md

@@ -1,4 +1,4 @@
-# Keybindings
+# CLI Keybindings
 
 Writing CLI commands by hand is very tedious.  To make things easier the
 CLI has several keybindings, most significant first:
@@ -27,10 +27,12 @@ CLI has several keybindings, most significant first:
 | Ctrl-n  | Down arrow     | History, next command                            |
 | Ctrl-r  |                | History, reversed interactive search (i-search)  |
 
-> **Note:** the Meta key is called Alt on most modern keyboards.  If you
-> have neither, first tap the Esc key instead of holding down Alt/Meta.
+## What is Meta?
 
-## Examples
+The Meta key is called Alt on most modern keyboards.  If you have
+neither, first tap the Esc key instead of holding down Alt/Meta.
+
+## Usage
 
 Complete a word.  Start by typing a few characters, then tap the TAB key
 on your keyboard:

doc/cli/quick.md

@@ -1,4 +1,4 @@
-# Quick Overview
+# CLI Quickstart Guide
 
 The question mark `?` key along with the `Tab` key are your best friends
 in the command line interface.  They provide context help and completion
@@ -16,14 +16,17 @@ of commands you input.  See the table below for a handful of examples.
 Explore the following topics for more information.  Note, the
 keybindings are really useful to learn!
 
-| **Command**         | **Description**                            |
-|---------------------|--------------------------------------------|
-| `help introduction` | An introduction to the CLI                 |
-| `help configure`    | How to use configure context               |
-| `help text-editor`  | Help with the built-in text-editor command |
-| `help keybindings`  | Lists keybindings and other helpful tricks |
+| **Command**         | **Description**                                    |
+|---------------------|----------------------------------------------------|
+| `help introduction` | An introduction to the CLI                         |
+| `help configure`    | How to use configure context                       |
+| `help text-editor`  | Help with the built-in text-editor command         |
+| `help keybindings`  | Lists available keybindings & other helpful tricks |
+
+----
 
 > In `configure` context the `help setting` command shows the YANG
 > description text for each node and container.  To reach the admin
 > exec help from configure context, e.g., `do help text-editor`
 
+----

doc/cli/tcpdump.md

@@ -57,11 +57,15 @@ up the switch core to mirror traffic ingressing and/or egressing a set
 of ports to another port.  On this *monitor port* you can then run your
 tcpdump, which means you need an external device (laptop).
 
+----
+
 > A planned feature is to support mirroring traffic to the CPU port,
 > which would be an effective way to log and monitor traffic over a
 > longer period of time.  Highly effective for diagnosing intermittent
 > and other rare network issues.
 
+----
+
 If only "proof of life" is required, then sometimes port counters, also
 called *RMON counters*, can be very useful too.  Seeing counters of a
 particular type increment means traffic is ingressing or egressing.

doc/cli/text-editor.md

@@ -44,10 +44,13 @@ C-x i   insert    C-x g   goto-ln  C-x o other win   C-x C-x swap     M-q reform
   - tap `c`
   - release `Ctrl`
 
+----
+
 > The status field at the bottom asks if you are really sure, and/or if
 > you want to add a final Enter/newline to the file.  For binary content
 > that final newline may be important.
 
+----
 
 ## Changing the Editor