linux-kernel - Re: [PATCH] doc: convert printk-formats.txt to rst

lists.openwall.net		lists / announce owl-users owl-dev john-users john-dev passwdqc-users yescrypt popa3d-users / oss-security kernel-hardening musl sabotage tlsify passwords / crypt-dev xvendor / Bugtraq Full-Disclosure linux-kernel linux-netdev linux-ext4 linux-hardening linux-cve-announce PHC
Open Source and information security mailing list archives

Hash Suite for Android: free password hash cracker in your pocket

[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]

Date:   Wed, 6 Dec 2017 08:11:23 +0100
From:   Markus Heiser <markus.heiser@...marit.de>
To:     "Tobin C. Harding" <me@...in.cc>
Cc:     Jonathan Corbet <corbet@....net>,
        Randy Dunlap <rdunlap@...radead.org>,
        Andrew Murray <amurray@...-data.co.uk>,
        Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        linux-kernel@...r.kernel.org
Subject: Re: [PATCH] doc: convert printk-formats.txt to rst


> Am 06.12.2017 um 02:45 schrieb Tobin C. Harding <me@...in.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@...radead.org>
> :Author: Andrew Murray <amurray@...-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 --