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

Randy Dunlap
2017-05-19T23:37:51Z

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