[<prev] [next>] [<thread-prev] [thread-next>] [day] [month] [year] [list]
Message-ID: <0eb65f46-f1cc-2d79-7083-235e608882a9@infradead.org>
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
Powered by blists - more mailing lists