Re: [PATCH net-next] docs: networking: timestamping: replace tabs with spaces in code blocks

Re: [PATCH net-next] docs: networking: timestamping: replace tabs with spaces in code blocks

[Jakub Kicinski]

On Thu,  9 Jul 2020 23:22:10 +0300 Vladimir Oltean wrote:
> Reading the document in vim is currently not a pleasant experience. Its
> rst syntax highlighting is confused by the "*/" sequences which it's not
> interpreting as part of the code blocks for some reason.
> 
> Replace the tabs with spaces, so that syntax highlighters (at least the
> one in vim) have a better idea where code blocks start and where they
> end.
> 
> Signed-off-by: Vladimir Oltean <olteanv@gmail.com>

Dunno about this change, there seems to be plenty examples of using
tabs for indentation of code block :(

Jon, any guidance? It seems to me the document renders correctly [1],
so the onus is on the editor to fix the RST highlight..

[1] https://www.kernel.org/doc/html/latest/networking/timestamping.html 

> diff --git a/Documentation/networking/timestamping.rst b/Documentation/networking/timestamping.rst
> index 03f7beade470..5fa4e2274dd9 100644
> --- a/Documentation/networking/timestamping.rst
> +++ b/Documentation/networking/timestamping.rst
> @@ -257,13 +257,13 @@ setsockopt::
>  
>    struct msghdr *msg;
>    ...
> -  cmsg			       = CMSG_FIRSTHDR(msg);
> -  cmsg->cmsg_level	       = SOL_SOCKET;
> -  cmsg->cmsg_type	       = SO_TIMESTAMPING;
> -  cmsg->cmsg_len	       = CMSG_LEN(sizeof(__u32));
> +  cmsg                         = CMSG_FIRSTHDR(msg);
> +  cmsg->cmsg_level             = SOL_SOCKET;
> +  cmsg->cmsg_type              = SO_TIMESTAMPING;
> +  cmsg->cmsg_len               = CMSG_LEN(sizeof(__u32));
>    *((__u32 *) CMSG_DATA(cmsg)) = SOF_TIMESTAMPING_TX_SCHED |
> -				 SOF_TIMESTAMPING_TX_SOFTWARE |
> -				 SOF_TIMESTAMPING_TX_ACK;
> +                                 SOF_TIMESTAMPING_TX_SOFTWARE |
> +                                 SOF_TIMESTAMPING_TX_ACK;
>    err = sendmsg(fd, msg, 0);
>  
>  The SOF_TIMESTAMPING_TX_* flags set via cmsg will override
> @@ -273,7 +273,7 @@ Moreover, applications must still enable timestamp reporting via
>  setsockopt to receive timestamps::
>  
>    __u32 val = SOF_TIMESTAMPING_SOFTWARE |
> -	      SOF_TIMESTAMPING_OPT_ID /* or any other flag */;
> +              SOF_TIMESTAMPING_OPT_ID /* or any other flag */;
>    err = setsockopt(fd, SOL_SOCKET, SO_TIMESTAMPING, &val, sizeof(val));
>  
>  
> @@ -354,14 +354,14 @@ SOL_SOCKET, cmsg_type SCM_TIMESTAMPING, and payload of type
>  
>  For SO_TIMESTAMPING_OLD::
>  
> -	struct scm_timestamping {
> -		struct timespec ts[3];
> -	};
> +        struct scm_timestamping {
> +                struct timespec ts[3];
> +        };
>  
>  For SO_TIMESTAMPING_NEW::
>  
> -	struct scm_timestamping64 {
> -		struct __kernel_timespec ts[3];
> +        struct scm_timestamping64 {
> +                struct __kernel_timespec ts[3];
>  
>  Always use SO_TIMESTAMPING_NEW timestamp to always get timestamp in
>  struct scm_timestamping64 format.
> @@ -468,11 +468,11 @@ Hardware time stamping must also be initialized for each device driver
>  that is expected to do hardware time stamping. The parameter is defined in
>  include/uapi/linux/net_tstamp.h as::
>  
> -	struct hwtstamp_config {
> -		int flags;	/* no flags defined right now, must be zero */
> -		int tx_type;	/* HWTSTAMP_TX_* */
> -		int rx_filter;	/* HWTSTAMP_FILTER_* */
> -	};
> +        struct hwtstamp_config {
> +                int flags;      /* no flags defined right now, must be zero */
> +                int tx_type;    /* HWTSTAMP_TX_* */
> +                int rx_filter;  /* HWTSTAMP_FILTER_* */
> +        };
>  
>  Desired behavior is passed into the kernel and to a specific device by
>  calling ioctl(SIOCSHWTSTAMP) with a pointer to a struct ifreq whose
> @@ -505,42 +505,42 @@ not been implemented in all drivers.
>  
>  ::
>  
> -    /* possible values for hwtstamp_config->tx_type */
> -    enum {
> -	    /*
> -	    * no outgoing packet will need hardware time stamping;
> -	    * should a packet arrive which asks for it, no hardware
> -	    * time stamping will be done
> -	    */
> -	    HWTSTAMP_TX_OFF,
> -
> -	    /*
> -	    * enables hardware time stamping for outgoing packets;
> -	    * the sender of the packet decides which are to be
> -	    * time stamped by setting SOF_TIMESTAMPING_TX_SOFTWARE
> -	    * before sending the packet
> -	    */
> -	    HWTSTAMP_TX_ON,
> -    };
> -
> -    /* possible values for hwtstamp_config->rx_filter */
> -    enum {
> -	    /* time stamp no incoming packet at all */
> -	    HWTSTAMP_FILTER_NONE,
> -
> -	    /* time stamp any incoming packet */
> -	    HWTSTAMP_FILTER_ALL,
> -
> -	    /* return value: time stamp all packets requested plus some others */
> -	    HWTSTAMP_FILTER_SOME,
> -
> -	    /* PTP v1, UDP, any kind of event packet */
> -	    HWTSTAMP_FILTER_PTP_V1_L4_EVENT,
> -
> -	    /* for the complete list of values, please check
> -	    * the include file include/uapi/linux/net_tstamp.h
> -	    */
> -    };
> +   /* possible values for hwtstamp_config->tx_type */
> +   enum {
> +           /*
> +           * no outgoing packet will need hardware time stamping;
> +           * should a packet arrive which asks for it, no hardware
> +           * time stamping will be done
> +           */
> +           HWTSTAMP_TX_OFF,
> +
> +           /*
> +           * enables hardware time stamping for outgoing packets;
> +           * the sender of the packet decides which are to be
> +           * time stamped by setting SOF_TIMESTAMPING_TX_SOFTWARE
> +           * before sending the packet
> +           */
> +           HWTSTAMP_TX_ON,
> +   };
> +
> +   /* possible values for hwtstamp_config->rx_filter */
> +   enum {
> +           /* time stamp no incoming packet at all */
> +           HWTSTAMP_FILTER_NONE,
> +
> +           /* time stamp any incoming packet */
> +           HWTSTAMP_FILTER_ALL,
> +
> +           /* return value: time stamp all packets requested plus some others */
> +           HWTSTAMP_FILTER_SOME,
> +
> +           /* PTP v1, UDP, any kind of event packet */
> +           HWTSTAMP_FILTER_PTP_V1_L4_EVENT,
> +
> +           /* for the complete list of values, please check
> +           * the include file include/uapi/linux/net_tstamp.h
> +           */
> +   };
>  
>  3.1 Hardware Timestamping Implementation: Device Drivers
>  --------------------------------------------------------
> @@ -555,10 +555,10 @@ to the shared time stamp structure of the skb call skb_hwtstamps(). Then
>  set the time stamps in the structure::
>  
>      struct skb_shared_hwtstamps {
> -	    /* hardware time stamp transformed into duration
> -	    * since arbitrary point in time
> -	    */
> -	    ktime_t	hwtstamp;
> +            /* hardware time stamp transformed into duration
> +            * since arbitrary point in time
> +            */
> +            ktime_t     hwtstamp;
>      };
>  
>  Time stamps for outgoing packets are to be generated as follows:

Re: [PATCH net-next] docs: networking: timestamping: replace tabs with spaces in code blocks

[Matthew Wilcox]

On Wed, Jul 15, 2020 at 12:17:17PM -0700, Jakub Kicinski wrote:
> On Thu,  9 Jul 2020 23:22:10 +0300 Vladimir Oltean wrote:
> > Reading the document in vim is currently not a pleasant experience. Its
> > rst syntax highlighting is confused by the "*/" sequences which it's not
> > interpreting as part of the code blocks for some reason.
> > 
> > Replace the tabs with spaces, so that syntax highlighters (at least the
> > one in vim) have a better idea where code blocks start and where they
> > end.
> > 
> > Signed-off-by: Vladimir Oltean <olteanv@gmail.com>
> 
> Dunno about this change, there seems to be plenty examples of using
> tabs for indentation of code block :(
> 
> Jon, any guidance? It seems to me the document renders correctly [1],
> so the onus is on the editor to fix the RST highlight..

vim's rst mode really really really wants to use spaces instead of tabs.
It's screwed me over a bunch of times, so I eventually just disabled it.
I think we should probably stop fighting it and use spaces in rst files
instead of tabs, but that's not my call to make.