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

[Markus Heiser]

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