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

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: Windows password security audit tool. GUI, reports in PDF.

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

Date:   Fri, 19 May 2017 16:37:34 -0700
From:   Randy Dunlap <rdunlap@...radead.org>
To:     Mauro Carvalho Chehab <mchehab@...pensource.com>,
        Joe Perches <joe@...ches.com>
Cc:     Linux Doc Mailing List <linux-doc@...r.kernel.org>,
        Mauro Carvalho Chehab <mchehab@...radead.org>,
        linux-kernel@...r.kernel.org, Jonathan Corbet <corbet@....net>,
        David Woodhouse <dwmw2@...radead.org>,
        Brian Norris <computersforpeace@...il.com>,
        Boris Brezillon <boris.brezillon@...e-electrons.com>,
        Marek Vasut <marek.vasut@...il.com>,
        Richard Weinberger <richard@....at>,
        Cyrille Pitchen <cyrille.pitchen@...el.com>,
        linux-mtd@...ts.infradead.org
Subject: Re: [PATCH 04/29] printk-formats.txt: standardize document format

On 05/19/17 13:28, Mauro Carvalho Chehab wrote:
> Em Fri, 19 May 2017 03:26:08 -0700
> Joe Perches <joe@...ches.com> 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