[PATCH 4/4] Documentation: networking: improve docs

[Steffen Trumtrar]

On Wed, Feb 10, 2016 at 11:07:37AM +0100, Robert Schwebel wrote:
> Add the following improvements:
> 
> - clarify commands vs. filesystems for network file transport protocols
> - Beautify links with prosa text instead of standard headlines
> - adapt 'devinfo eth0' parameter output to current code
> - improve console texts
> - add docs for netconsole.active
> 
> Signed-off-by: Robert Schwebel <r.schwebel at pengutronix.de>
> ---
>  Documentation/user/networking.rst | 44 ++++++++++++++++++++++++---------------
>  1 file changed, 27 insertions(+), 17 deletions(-)
> 
> diff --git a/Documentation/user/networking.rst b/Documentation/user/networking.rst
> index 6eeb93d..c1b1857 100644
> --- a/Documentation/user/networking.rst
> +++ b/Documentation/user/networking.rst
> @@ -1,26 +1,25 @@
>  Networking
>  ==========
>  
> -barebox has IPv4 networking support. Several protocols such as
> -:ref:`command_dhcp`, :ref:`filesystems_nfs`, :ref:`command_tftp` are
> -supported.
> +barebox has IPv4 networking support. Several protocols such as :ref:`DHCP
> +<command_dhcp>`, NFS and TFTP are supported.
>  
>  Network configuration
>  ---------------------
>  
>  The first step for networking is configuring the network device. The network
>  device is usually ``eth0``. The current configuration can be viewed with the
> -:ref:`command_devinfo` command:
> +:ref:`devinfo <command_devinfo>` command:
>  
>  .. code-block:: sh
>  
>    barebox:/ devinfo eth0
>    Parameters:
> -    ipaddr: 192.168.23.197
> -    serverip: 192.168.23.1
> +    ethaddr: 00:1c:49:01:03:4b
>      gateway: 192.168.23.1
> +    ipaddr: 192.168.23.197
>      netmask: 255.255.0.0
> -    ethaddr: 00:1c:49:01:03:4b
> +    serverip: 192.168.23.1
>  
>  The configuration can be changed on the command line with:
>  
> @@ -28,19 +27,21 @@ The configuration can be changed on the command line with:
>  
>    eth0.ipaddr=172.0.0.10
>  
> -The :ref:`command_dhcp` command will change the settings based on the answer
> +The :ref:`dhcp command <command_dhcp>` will change the settings based on the answer
>  from the DHCP server.
>  
>  This low-level configuration of the network interface is often not necessary. Normally
>  the network settings should be edited in ``/env/network/eth0``, then the network interface
> -can be brought up using the :ref:`command_ifup` command.
> +can be brought up using the :ref:`ifup command <command_ifup>`.
>  
>  Network filesystems
>  -------------------
>  
> -barebox supports NFS and TFTP as filesystem implementations. See :ref:`filesystems_nfs`
> -and :ref:`filesystems_tftp` for more information. After the network device has been
> -brought up a network filesystem can be mounted with:
> +barebox supports NFS and TFTP both with commands (:ref:`nfs <command_nfs>` and
> +:ref:`tftp <command_tftp>`) and as filesystem implementations; see
> +:ref:`filesystems_nfs` and :ref:`filesystems_tftp` for more information. After
> +the network device has been brought up, a network filesystem can be mounted
> +with:
>  
>  .. code-block:: sh
>  
> @@ -52,8 +53,9 @@ or
>  
>    mount -t nfs 192.168.2.1:/export none /mnt
>  
> -**NOTE:** this can often be hidden behind the :ref:`command_automount` command to make
> -mounting transparent to the user.
> +**NOTE:** The execution of the mount command can often be hidden behind the
> +:ref:`automount command <command_automount>`, to make mounting transparent to
> +the user.
>  
>  Network console
>  ---------------
> @@ -71,11 +73,19 @@ risks. It can be enabled using:
>    netconsole.ip=192.168.23.2
>    netconsole.active=ioe
>  
> -This will send UDP packets to 192.168.23.2 on port 6666. On 192.168.23.2 the
> -scripts/netconsole script can be used to control barebox:
> +This will send UDP packets to a PC with IP address 192.168.23.2 and port 6666.
> +
> +The ``netconsole.active`` parameter consists of the fields "input" (i),
> +"output" (o) and "error" (e); if the fields are set, the respective channel is
> +activated on the network console.
> +
> +On the PC side, the ``scripts/netconsole`` script can be used to remote control
> +barebox:
>  
>  .. code-block:: sh
>  
>    scripts/netconsole <board IP> 6666
>  
> -The netconsole can be used just like any other console.
> +The netconsole can be used just like any other console. Note, however, that the
> +simple console protocol is is UDP based, so there is no guarantee about packet
			   ^^^^^

Regards,
Steffen Trumtrar

-- 
Pengutronix e.K.                           |                             |
Industrial Linux Solutions                 | http://www.pengutronix.de/  |
Peiner Str. 6-8, 31137 Hildesheim, Germany | Phone: +49-5121-206917-0    |
Amtsgericht Hildesheim, HRA 2686           | Fax:   +49-5121-206917-5555 |