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

[Mauro Carvalho Chehab]

Em Fri, 19 May 2017 16:37:34 -0700
Randy Dunlap  escreveu:

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

Sorry for taking so long to return to this thread... got sidetracked by two
trips.

Changed to avoid adding that many literal escaping sequences.
The end result, in HTML format is at:

https://www.infradead.org/~mchehab/kernel_docs/unsorted/printk-formats.html

Patch enclosed.

Regards,
Mauro

-


[PATCH] printk-formats.txt: standardize document format

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.

Signed-off-by: Mauro Carvalho Chehab 

diff --git a/Documentation/printk-formats.txt b/Documentation/printk-formats.txt
index 5962949944fd..7824f8442ec4 100644
--- a/Documentation/printk-formats.txt
+++ b/Documentation/printk-formats.txt
@@ -1,5 +1,18 @@
-If variable is of Type,use printk format specifier:
--
+=
+How to get printk format specifiers right
+=
+
+:Author: Randy Dunlap 
+:Author: Andrew Murray 
+
+
+Integer types
+=
+

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

[Mauro Carvalho Chehab]

Em Fri, 19 May 2017 16:37:34 -0700
Randy Dunlap  escreveu:

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

Sorry for taking so long to return to this thread... got sidetracked by two
trips.

Changed to avoid adding that many literal escaping sequences.
The end result, in HTML format is at:

https://www.infradead.org/~mchehab/kernel_docs/unsorted/printk-formats.html

Patch enclosed.

Regards,
Mauro

-


[PATCH] printk-formats.txt: standardize document format

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.

Signed-off-by: Mauro Carvalho Chehab 

diff --git a/Documentation/printk-formats.txt b/Documentation/printk-formats.txt
index 5962949944fd..7824f8442ec4 100644
--- a/Documentation/printk-formats.txt
+++ b/Documentation/printk-formats.txt
@@ -1,5 +1,18 @@
-If variable is of Type,use printk format specifier:
--
+=
+How to get printk format specifiers right
+=
+
+:Author: Randy Dunlap 
+:Author: Andrew Murray 
+
+
+Integer types
+=
+
+::
+
+   If variable is of Type, use printk format specifier:
+   

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  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
>> 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

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  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
>> 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

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

[Mauro Carvalho Chehab]

Em Fri, 19 May 2017 03:26:08 -0700
Joe Perches  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
> 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  



Cheers,
Mauro

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

[Mauro Carvalho Chehab]

Em Fri, 19 May 2017 03:26:08 -0700
Joe Perches  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
> 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  



Cheers,
Mauro

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

[Joe Perches]

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
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``
> +=== ===

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

[Joe Perches]

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
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``
> +=== ===

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

[Mauro Carvalho Chehab]

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.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/printk-formats.txt | 416 +++
 1 file changed, 243 insertions(+), 173 deletions(-)

diff --git a/Documentation/printk-formats.txt b/Documentation/printk-formats.txt
index 5962949944fd..13cb8491731b 100644
--- 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
+How to get printk format specifiers right
+=
 
-If  is dependent on a config option for its size (e.g., sector_t,
-blkcnt_t) or is architecture-dependent for its size (e.g., tcflag_t), use a
-format specifier of its largest possible type and explicitly cast to it.
-Example:
+:Author: Randy Dunlap 
+:Author: Andrew Murray 
+
+
+Integer types
+=
+
+=== ===
+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  is dependent on a config option for its size (e.g., ``sector_t``,
+``blkcnt_t``) or is architecture-dependent for its size (e.g., ``tcflag_t``),
+use a format specifier of its largest possible type and explicitly cast to it.
+
+Example::
 
printk("test: sector number/total blocks: %llu/%llu\n",
(unsigned long long)sector, (unsigned long long)blockcount);
 
-Reminder: sizeof() result is of type size_t.
+Reminder: ``sizeof()`` result is of type ``size_t``.
 
-The kernel's printf does not support %n. For obvious reasons, floating
-point formats (%e, %f, %g, %a) are also not recognized. Use of any
+The kernel's printf does not support ``%n``. For obvious reasons, floating
+point formats (``%e, %f, %g, %a``) are also not recognized. Use of any
 unsupported specifier or length qualifier results in a WARN and early
 return from vsnprintf.
 
 Raw pointer value SHOULD be printed with %p. The kernel supports
 the following extended format specifiers for pointer types:
 
-Symbols/Function Pointers:
+Symbols/Function Pointers
+=
 
-   %pF versatile_init+0x0/0x110
-   %pf versatile_init
-   %pS versatile_init+0x0/0x110
-   %pSRversatile_init+0x9/0x110
-   (with __builtin_extract_return_addr() translation)
-   %ps versatile_init
-   %pB prev_fn_of_versatile_init+0x88/0x88
+=== ==
+If variable is of Type use printk format specifier
+=== ==
+``%pF````versatile_init+0x0/0x110``
+``%pf````versatile_init``
+``%pS````versatile_init+0x0/0x110``
+``%pSR``   ``versatile_init+0x9/0x110``
+   ``(with __builtin_extract_return_addr() translation)``
+``%ps````versatile_init``
+``%pB````prev_fn_of_versatile_init+0x88/0x88``
+=== ==
 
-   For printing symbols and function pointers. The 'S' and 's' specifiers
-   result in the symbol name with ('S') or without ('s') offsets. Where
-

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

[Mauro Carvalho Chehab]

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.

Signed-off-by: Mauro Carvalho Chehab 
---
 Documentation/printk-formats.txt | 416 +++
 1 file changed, 243 insertions(+), 173 deletions(-)

diff --git a/Documentation/printk-formats.txt b/Documentation/printk-formats.txt
index 5962949944fd..13cb8491731b 100644
--- 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
+How to get printk format specifiers right
+=
 
-If  is dependent on a config option for its size (e.g., sector_t,
-blkcnt_t) or is architecture-dependent for its size (e.g., tcflag_t), use a
-format specifier of its largest possible type and explicitly cast to it.
-Example:
+:Author: Randy Dunlap 
+:Author: Andrew Murray 
+
+
+Integer types
+=
+
+=== ===
+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  is dependent on a config option for its size (e.g., ``sector_t``,
+``blkcnt_t``) or is architecture-dependent for its size (e.g., ``tcflag_t``),
+use a format specifier of its largest possible type and explicitly cast to it.
+
+Example::
 
printk("test: sector number/total blocks: %llu/%llu\n",
(unsigned long long)sector, (unsigned long long)blockcount);
 
-Reminder: sizeof() result is of type size_t.
+Reminder: ``sizeof()`` result is of type ``size_t``.
 
-The kernel's printf does not support %n. For obvious reasons, floating
-point formats (%e, %f, %g, %a) are also not recognized. Use of any
+The kernel's printf does not support ``%n``. For obvious reasons, floating
+point formats (``%e, %f, %g, %a``) are also not recognized. Use of any
 unsupported specifier or length qualifier results in a WARN and early
 return from vsnprintf.
 
 Raw pointer value SHOULD be printed with %p. The kernel supports
 the following extended format specifiers for pointer types:
 
-Symbols/Function Pointers:
+Symbols/Function Pointers
+=
 
-   %pF versatile_init+0x0/0x110
-   %pf versatile_init
-   %pS versatile_init+0x0/0x110
-   %pSRversatile_init+0x9/0x110
-   (with __builtin_extract_return_addr() translation)
-   %ps versatile_init
-   %pB prev_fn_of_versatile_init+0x88/0x88
+=== ==
+If variable is of Type use printk format specifier
+=== ==
+``%pF````versatile_init+0x0/0x110``
+``%pf````versatile_init``
+``%pS````versatile_init+0x0/0x110``
+``%pSR``   ``versatile_init+0x9/0x110``
+   ``(with __builtin_extract_return_addr() translation)``
+``%ps````versatile_init``
+``%pB````prev_fn_of_versatile_init+0x88/0x88``
+=== ==
 
-   For printing symbols and function pointers. The 'S' and 's' specifiers
-   result in the symbol name with ('S') or without ('s') offsets. Where
-   this is used on a kernel without KALLSYMS - the symbol address is
-