Return-Path: <linux-kernel-owner@vger.kernel.org>
Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand
        id S1753217AbdLFHSz convert rfc822-to-8bit (ORCPT <rfc822;w@1wt.eu>);
        Wed, 6 Dec 2017 02:18:55 -0500
Received: from smtp2-2.goneo.de ([85.220.129.34]:53565 "EHLO smtp2-2.goneo.de"
        rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP
        id S1752673AbdLFHSu (ORCPT <rfc822;linux-kernel@vger.kernel.org>);
        Wed, 6 Dec 2017 02:18:50 -0500
X-Greylist: delayed 423 seconds by postgrey-1.27 at vger.kernel.org; Wed, 06 Dec 2017 02:18:49 EST
X-Spam-Flag: NO
X-Spam-Score: -2.789
Content-Type: text/plain; charset=us-ascii
Mime-Version: 1.0 (Mac OS X Mail 10.3 \(3273\))
Subject: Re: [PATCH] doc: convert printk-formats.txt to rst
From: Markus Heiser <markus.heiser@darmarit.de>
In-Reply-To: <1512524729-16051-1-git-send-email-me@tobin.cc>
Date: Wed, 6 Dec 2017 08:11:23 +0100
Cc: Jonathan Corbet <corbet@lwn.net>, Randy Dunlap <rdunlap@infradead.org>,
        Andrew Murray <amurray@mpc-data.co.uk>,
        Linux Doc Mailing List <linux-doc@vger.kernel.org>,
        linux-kernel@vger.kernel.org
Content-Transfer-Encoding: 8BIT
Message-Id: <0549146F-4B62-4AFB-A29D-E4B7622455A0@darmarit.de>
References: <1512524729-16051-1-git-send-email-me@tobin.cc>
To: "Tobin C. Harding" <me@tobin.cc>
X-Mailer: Apple Mail (2.3273)
Sender: linux-kernel-owner@vger.kernel.org
List-ID: <linux-kernel.vger.kernel.org>
X-Mailing-List: linux-kernel@vger.kernel.org
Content-Length: 2530
Lines: 98


> Am 06.12.2017 um 02:45 schrieb Tobin C. Harding <me@tobin.cc>:
> 
> Documentation/printk-formats.txt is a candidate for conversion to
> ReStructuredText format. Some effort has already been made to do this
> conversion even thought the suffix is currently .txt
> 
> Changes required to complete conversion
> 
> - Add double backticks where needed.
> - Add entry to Documentation/index.rst
> - Use flat-table instead of ASCII table.

[...]

> +=============================================
> +How to Get ``printk`` Format Specifiers Right
> +=============================================
> 
> :Author: Randy Dunlap <rdunlap@infradead.org>
> :Author: Andrew Murray <amurray@mpc-data.co.uk>
> @@ -8,56 +8,91 @@ How to get printk format specifiers right
> Integer types
> =============
> 
> -::
> +For printing integer types, we have the following format specifiers:
> +		
> +   .. flat-table:: 
> +      :widths: 2 2
> +
> +      * - **Type**
> +	- **Specifier**
> +
> +      * - ``int``
> +        - ``%d`` or ``%x``
> +
> +      * - ``unsigned int``
> +	- ``%u`` or ``%x``
> +
> +      * - ``long``
> +	- ``%ld`` or ``%lx``
> +
> +      * - ``unsigned long``
> +	- ``%lu`` or ``%lx``
> +
> +      * - ``long long``
> +	- ``%lld`` or ``%llx``
> 
> -	If variable is of Type,		use printk format specifier:
> -	------------------------------------------------------------
> -		int			%d or %x
> -		unsigned int		%u or %x
> -		long			%ld or %lx
> -		unsigned long		%lu or %lx
> -		long long		%lld or %llx
> -		unsigned long long	%llu or %llx
> -		size_t			%zu or %zx
> -		ssize_t			%zd or %zx
> -		s32			%d or %x
> -		u32			%u or %x
> -		s64			%lld or %llx
> -		u64			%llu or %llx
> -
> -If <type> is dependent on a config option for its size (e.g., ``sector_t``,
> +      * - ``unsigned long long``
> +	- ``%llu`` or ``%llx``
> +
> +      * - ``size_t``
> +	- ``%zu`` or ``%zx``
> +
> +      * - ``ssize_t``
> +	- ``%zd`` or ``%zx``
> +
> +      * - ``s32``
> +	- ``%d`` or ``%x``
> +
> +      * - ``u32``
> +	- ``%u`` or ``%x``
> +
> +      * - ``s64``
> +	- ``%lld`` or ``%llx``
> +
> +      * - ``u64``
> +	- ``%llu`` or ``%llx``
> +
> +

Thanks!

just a question .. might it be better we stay with ASCII table
in cases like this. I guess this table won't changed often.
The flat-table directive is good for big and therefore frequently 
changed tables where a small precise diff reduce the patch.
But flat-table is also hard to read in plain text. Its a balancing
and thats my opinion, lets hear what other say ...

-- Markus --