Re: [PATCH 04/29] printk-formats.txt: standardize document format

[Randy Dunlap]

On 05/19/17 13:28, Mauro Carvalho Chehab wrote:
> Em Fri, 19 May 2017 03:26:08 -0700
> Joe Perches <joe@xxxxxxxxxxx> escreveu:
> 
>> On Thu, 2017-05-18 at 22:25 -0300, Mauro Carvalho Chehab wrote:
>>> Each text file under Documentation follows a different
>>> format. Some doesn't even have titles!
>>>
>>> Change its representation to follow the adopted standard,
>>> using ReST markups for it to be parseable by Sphinx:
>>>
>>> - add a title for the document;
>>> - add markups for section titles;
>>> - move authorship to the beginning and use :Author:;
>>> - use right markup for tables;
>>> - mark literals and literal blocks.  
>>
>> I think the .rst markup is far uglier to read as text
>> and harder to modify for new additions to %p<foo>
>> given column alignments.
>>
>> For instance below, but other than that, the .rst
>> is easier to read.
>>
>>> diff --git a/Documentation/printk-formats.txt b/Documentation/printk-formats.txt  
>> []
>>> @@ -1,139 +1,180 @@
>>> -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 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``
>>> +======================= ===========================  
> 
> Well, we could,instead, use literal blocks, e. g. something like:
> 
> ::
> 
>  -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  
> 

I like that latter option.

thanks.
-- 
~Randy