[PATCH] net: fix e100.rst Documentation build errors

[PATCH] net: fix e100.rst Documentation build errors

[Randy Dunlap]

From: Randy Dunlap <rdunlap@infradead.org>

Fix Documentation build errors in e100.rst.  Several section titles
and the corresponding underlines should not be indented.

Documentation/networking/e100.rst:90: (SEVERE/4) Unexpected section title.
Documentation/networking/e100.rst:109: (SEVERE/4) Unexpected section title.

Fixes: 85d63445f411 ("Documentation: e100: Update the Intel 10/100 driver doc")

Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
Cc: Jeff Kirsher <jeffrey.t.kirsher@intel.com>
Cc: Aaron Brown <aaron.f.brown@intel.com>
---
Is there a Sphinx version problem here?  Tested-by: should indicate
that there was no error like I am seeing.

 Documentation/networking/e100.rst |   24 ++++++++++++------------
 1 file changed, 12 insertions(+), 12 deletions(-)

--- lnx-418-rc1.orig/Documentation/networking/e100.rst
+++ lnx-418-rc1/Documentation/networking/e100.rst
@@ -86,8 +86,8 @@ Event Log Message Level:  The driver use
 Additional Configurations
 =========================
 
-  Configuring the Driver on Different Distributions
-  -------------------------------------------------
+Configuring the Driver on Different Distributions
+-------------------------------------------------
 
   Configuring a network driver to load properly when the system is started is
   distribution dependent. Typically, the configuration process involves adding
@@ -105,8 +105,8 @@ Additional Configurations
        alias eth0 e100
        alias eth1 e100
 
-  Viewing Link Messages
-  ---------------------
+Viewing Link Messages
+---------------------
   In order to see link messages and other Intel driver information on your
   console, you must set the dmesg level up to six. This can be done by
   entering the following on the command line before loading the e100 driver::
@@ -119,8 +119,8 @@ Additional Configurations
   NOTE: This setting is not saved across reboots.
 
 
-  ethtool
-  -------
+ethtool
+-------
 
   The driver utilizes the ethtool interface for driver configuration and
   diagnostics, as well as displaying statistical information.  The ethtool
@@ -129,8 +129,8 @@ Additional Configurations
   The latest release of ethtool can be found from
   https://www.kernel.org/pub/software/network/ethtool/
 
-  Enabling Wake on LAN* (WoL)
-  ---------------------------
+Enabling Wake on LAN* (WoL)
+---------------------------
   WoL is provided through the ethtool* utility.  For instructions on enabling
   WoL with ethtool, refer to the ethtool man page.
 
@@ -138,16 +138,16 @@ Additional Configurations
   this driver version, in order to enable WoL, the e100 driver must be
   loaded when shutting down or rebooting the system.
 
-  NAPI
-  ----
+NAPI
+----
 
   NAPI (Rx polling mode) is supported in the e100 driver.
 
   See https://wiki.linuxfoundation.org/networking/napi for more information
   on NAPI.
 
-  Multiple Interfaces on Same Ethernet Broadcast Network
-  ------------------------------------------------------
+Multiple Interfaces on Same Ethernet Broadcast Network
+------------------------------------------------------
 
   Due to the default ARP behavior on Linux, it is not possible to have
   one system on two IP networks in the same Ethernet broadcast domain

Re: [PATCH] net: fix e100.rst Documentation build errors

[Jani Nikula]

On Sat, 16 Jun 2018, Randy Dunlap <rdunlap@infradead.org> wrote:
> From: Randy Dunlap <rdunlap@infradead.org>
>
> Fix Documentation build errors in e100.rst.  Several section titles
> and the corresponding underlines should not be indented.

Really the content blocks below the titles should not be indented
either. It's not an error, but the end result is probably not what you
want.

BR,
Jani.


>
> Documentation/networking/e100.rst:90: (SEVERE/4) Unexpected section title.
> Documentation/networking/e100.rst:109: (SEVERE/4) Unexpected section title.
>
> Fixes: 85d63445f411 ("Documentation: e100: Update the Intel 10/100 driver doc")
>
> Signed-off-by: Randy Dunlap <rdunlap@infradead.org>
> Cc: Jeff Kirsher <jeffrey.t.kirsher@intel.com>
> Cc: Aaron Brown <aaron.f.brown@intel.com>
> ---
> Is there a Sphinx version problem here?  Tested-by: should indicate
> that there was no error like I am seeing.
>
>  Documentation/networking/e100.rst |   24 ++++++++++++------------
>  1 file changed, 12 insertions(+), 12 deletions(-)
>
> --- lnx-418-rc1.orig/Documentation/networking/e100.rst
> +++ lnx-418-rc1/Documentation/networking/e100.rst
> @@ -86,8 +86,8 @@ Event Log Message Level:  The driver use
>  Additional Configurations
>  =========================
>  
> -  Configuring the Driver on Different Distributions
> -  -------------------------------------------------
> +Configuring the Driver on Different Distributions
> +-------------------------------------------------
>  
>    Configuring a network driver to load properly when the system is started is
>    distribution dependent. Typically, the configuration process involves adding
> @@ -105,8 +105,8 @@ Additional Configurations
>         alias eth0 e100
>         alias eth1 e100
>  
> -  Viewing Link Messages
> -  ---------------------
> +Viewing Link Messages
> +---------------------
>    In order to see link messages and other Intel driver information on your
>    console, you must set the dmesg level up to six. This can be done by
>    entering the following on the command line before loading the e100 driver::
> @@ -119,8 +119,8 @@ Additional Configurations
>    NOTE: This setting is not saved across reboots.
>  
>  
> -  ethtool
> -  -------
> +ethtool
> +-------
>  
>    The driver utilizes the ethtool interface for driver configuration and
>    diagnostics, as well as displaying statistical information.  The ethtool
> @@ -129,8 +129,8 @@ Additional Configurations
>    The latest release of ethtool can be found from
>    https://www.kernel.org/pub/software/network/ethtool/
>  
> -  Enabling Wake on LAN* (WoL)
> -  ---------------------------
> +Enabling Wake on LAN* (WoL)
> +---------------------------
>    WoL is provided through the ethtool* utility.  For instructions on enabling
>    WoL with ethtool, refer to the ethtool man page.
>  
> @@ -138,16 +138,16 @@ Additional Configurations
>    this driver version, in order to enable WoL, the e100 driver must be
>    loaded when shutting down or rebooting the system.
>  
> -  NAPI
> -  ----
> +NAPI
> +----
>  
>    NAPI (Rx polling mode) is supported in the e100 driver.
>  
>    See https://wiki.linuxfoundation.org/networking/napi for more information
>    on NAPI.
>  
> -  Multiple Interfaces on Same Ethernet Broadcast Network
> -  ------------------------------------------------------
> +Multiple Interfaces on Same Ethernet Broadcast Network
> +------------------------------------------------------
>  
>    Due to the default ARP behavior on Linux, it is not possible to have
>    one system on two IP networks in the same Ethernet broadcast domain
>
>
> --
> To unsubscribe from this list: send the line "unsubscribe linux-doc" in
> the body of a message to majordomo@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

-- 
Jani Nikula, Intel Open Source Graphics Center

Re: [PATCH] net: fix e100.rst Documentation build errors

[Michal Kubecek]

On Mon, Jun 18, 2018 at 11:04:51AM +0300, Jani Nikula wrote:
> On Sat, 16 Jun 2018, Randy Dunlap <rdunlap@infradead.org> wrote:
> > From: Randy Dunlap <rdunlap@infradead.org>
> >
> > Fix Documentation build errors in e100.rst.  Several section titles
> > and the corresponding underlines should not be indented.
> 
> Really the content blocks below the titles should not be indented
> either. It's not an error, but the end result is probably not what you
> want.

Also the indentation of this part:

> Rx Descriptors: Number of receive descriptors. A receive descriptor is a data
>    structure that describes a receive buffer and its attributes to the network
>    controller. The data in the descriptor is used by the controller to write
>    data from the controller to host memory. In the 3.x.x driver the valid range
>    for this parameter is 64-256. The default value is 256. This parameter can be
>    changed using the command::
> 
>    ethtool -G eth? rx n
> 
>    Where n is the number of desired Rx descriptors.
> 
> Tx Descriptors: Number of transmit descriptors. A transmit descriptor is a data
>    structure that describes a transmit buffer and its attributes to the network
>    controller. The data in the descriptor is used by the controller to read
>    data from the host memory to the controller. In the 3.x.x driver the valid
>    range for this parameter is 64-256. The default value is 128. This parameter
>    can be changed using the command::
> 
>    ethtool -G eth? tx n
> 
>    Where n is the number of desired Tx descriptors.
> 
> Speed/Duplex: The driver auto-negotiates the link speed and duplex settings by
>    default. The ethtool utility can be used as follows to force speed/duplex.::
> 
>    ethtool -s eth?  autoneg off speed {10|100} duplex {full|half}
> 
>    NOTE: setting the speed/duplex to incorrect values will cause the link to
>    fail.
> 
> Event Log Message Level:  The driver uses the message level flag to log events
>    to syslog. The message level can be set at driver load time. It can also be
>    set using the command::
> 
>    ethtool -s eth? msglvl n

causes

.../Documentation/networking/e100.rst:56: WARNING: Literal block expected; none found.
.../Documentation/networking/e100.rst:67: WARNING: Literal block expected; none found.
.../Documentation/networking/e100.rst:74: WARNING: Literal block expected; none found.
.../Documentation/networking/e100.rst:83: WARNING: Literal block expected; none found.

as the literal block has the same indentation as preceding paragraph
(except for the first line).

Michal Kubecek