Re: [PATCH 06/17] CodingStyle.rst: use the proper tag for verbatim font

[Markus Heiser]

Am 14.09.2016 um 15:48 schrieb Mauro Carvalho Chehab :

> Em Wed, 14 Sep 2016 14:18:55 +0200
> Markus Heiser  escreveu:
> 
>> Am 14.09.2016 um 11:35 schrieb Mauro Carvalho Chehab 
>> :
>> 
>>> Em Wed, 14 Sep 2016 09:45:10 +0200
>>> Jean Delvare  escreveu:
>>> 
 On Tue, 13 Sep 2016 16:24:48 -0300, Mauro Carvalho Chehab wrote:  
> Em Tue, 13 Sep 2016 19:45:23 +0200
> Jean Delvare  escreveu:
> 
>> Hi Mauro,
>> 
>> On Mon, 12 Sep 2016 11:47:57 -0300, Mauro Carvalho Chehab wrote:
>>> Instead of using "foo", use ``foo`` for the names that are
>>> literal.  
>> 
>> Because...?
> 
> Because it is an usual typographic convention to use monospaced
> fonts for functions and language commands on documents.
> 
> On Sphinx/ReST, ``foo`` means that foo will be displayed using a
> monospaced font.
 
 My point was that such an explanation should be part of your patch
 description, so that the change can be accepted (is the reviewer agrees
 with your reason) or discussed (if he/she doesn't.)  
>>> 
>>> Yeah, I understood. I actually folded it on the patch.
>>> 
>>> See below. I'll be sending a new version of this series soon.
>>> 
 And I do agree with the change, for what it's worth :-)  
>>> 
>>> Good! feel free to send an ack if want ;)
>>> 
>>> Thanks!
>>> Mauro
>>> 
>>> CodingStyle.rst: use the proper tag for verbatim font
>>> 
>>> Instead of using "foo", use ``foo`` for the names that are
>>> literal, because it is an usual typographic convention to use
>>> monospaced fonts for functions and language commands on documents,
>>> and we're following such convention on the other ReST books.
>>> 
>>> On Sphinx/ReST, ``foo`` means that foo will be displayed using a
>>> monospaced font.  
>> 
>> sorry if I'm pedantic ... more correct might be:
>> 
>>   On Sphinx/ReST, ``foo`` means that foo will be marked as inline literal ...
>> 
>> ... it is not the markup which displays (presentation) something verbatim,
>> it is always the (e.g. HTML) stylesheet which implements, how content 
>> e.g. a "inline literal" [1] is displayed with verbatim. 
>> 
>> There is a "separation of content and presentation" [2]
>> 
>> Thats why I think, Mauro's first commit message was 'enough'.
>> 
>> Anyway, both commit messages are 'enough' :-)
> 
> Ok, what about using this comment for the patch?
> 
> Documentation/CodingStyle: use the proper tag for verbatim font
> 
> On Sphinx/ReST notation, ``foo`` means that foo will be will be 
> marked as inline literal, effectively making it   to be presented
> as a monospaced font.
> 
> As we want this document to be parsed by Sphinx, instead of using
> "foo", use ``foo`` for the names that are literal, because it is an
> usual typographic convention to use monospaced fonts for functions
> and language commands on documents, and we're following such
> convention on the other ReST books.
> 

Its all OK ;-)  ... again sorry, I don't wanted to impede you ... I 
only wanted that we all realize, that there is a separation of content
and presentation and that the markup is abstract and not directly bonded
to a concrete presentation.


-- Markus 
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 06/17] CodingStyle.rst: use the proper tag for verbatim font

[Mauro Carvalho Chehab]

Em Wed, 14 Sep 2016 14:18:55 +0200
Markus Heiser  escreveu:

> Am 14.09.2016 um 11:35 schrieb Mauro Carvalho Chehab 
> :
> 
> > Em Wed, 14 Sep 2016 09:45:10 +0200
> > Jean Delvare  escreveu:
> >   
> >> On Tue, 13 Sep 2016 16:24:48 -0300, Mauro Carvalho Chehab wrote:  
> >>> Em Tue, 13 Sep 2016 19:45:23 +0200
> >>> Jean Delvare  escreveu:
> >>>   
>  Hi Mauro,
>  
>  On Mon, 12 Sep 2016 11:47:57 -0300, Mauro Carvalho Chehab wrote:
> > Instead of using "foo", use ``foo`` for the names that are
> > literal.  
>  
>  Because...?
> >>> 
> >>> Because it is an usual typographic convention to use monospaced
> >>> fonts for functions and language commands on documents.
> >>> 
> >>> On Sphinx/ReST, ``foo`` means that foo will be displayed using a
> >>> monospaced font.
> >> 
> >> My point was that such an explanation should be part of your patch
> >> description, so that the change can be accepted (is the reviewer agrees
> >> with your reason) or discussed (if he/she doesn't.)  
> > 
> > Yeah, I understood. I actually folded it on the patch.
> > 
> > See below. I'll be sending a new version of this series soon.
> >   
> >> And I do agree with the change, for what it's worth :-)  
> > 
> > Good! feel free to send an ack if want ;)
> > 
> > Thanks!
> > Mauro
> > 
> > CodingStyle.rst: use the proper tag for verbatim font
> > 
> > Instead of using "foo", use ``foo`` for the names that are
> > literal, because it is an usual typographic convention to use
> > monospaced fonts for functions and language commands on documents,
> > and we're following such convention on the other ReST books.
> > 
> > On Sphinx/ReST, ``foo`` means that foo will be displayed using a
> > monospaced font.  
> 
> sorry if I'm pedantic ... more correct might be:
> 
>On Sphinx/ReST, ``foo`` means that foo will be marked as inline literal ...
> 
> ... it is not the markup which displays (presentation) something verbatim,
> it is always the (e.g. HTML) stylesheet which implements, how content 
> e.g. a "inline literal" [1] is displayed with verbatim. 
> 
> There is a "separation of content and presentation" [2]
> 
> Thats why I think, Mauro's first commit message was 'enough'.
> 
> Anyway, both commit messages are 'enough' :-)

Ok, what about using this comment for the patch?

Documentation/CodingStyle: use the proper tag for verbatim font

On Sphinx/ReST notation, ``foo`` means that foo will be will be 
marked as inline literal, effectively making it to be presented
as a monospaced font.

As we want this document to be parsed by Sphinx, instead of using
"foo", use ``foo`` for the names that are literal, because it is an
usual typographic convention to use monospaced fonts for functions
and language commands on documents, and we're following such
convention on the other ReST books.


-

Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 06/17] CodingStyle.rst: use the proper tag for verbatim font

[Markus Heiser]

Am 14.09.2016 um 11:35 schrieb Mauro Carvalho Chehab :

> Em Wed, 14 Sep 2016 09:45:10 +0200
> Jean Delvare  escreveu:
> 
>> On Tue, 13 Sep 2016 16:24:48 -0300, Mauro Carvalho Chehab wrote:
>>> Em Tue, 13 Sep 2016 19:45:23 +0200
>>> Jean Delvare  escreveu:
>>> 
 Hi Mauro,
 
 On Mon, 12 Sep 2016 11:47:57 -0300, Mauro Carvalho Chehab wrote:  
> Instead of using "foo", use ``foo`` for the names that are
> literal.
 
 Because...?  
>>> 
>>> Because it is an usual typographic convention to use monospaced
>>> fonts for functions and language commands on documents.
>>> 
>>> On Sphinx/ReST, ``foo`` means that foo will be displayed using a
>>> monospaced font.  
>> 
>> My point was that such an explanation should be part of your patch
>> description, so that the change can be accepted (is the reviewer agrees
>> with your reason) or discussed (if he/she doesn't.)
> 
> Yeah, I understood. I actually folded it on the patch.
> 
> See below. I'll be sending a new version of this series soon.
> 
>> And I do agree with the change, for what it's worth :-)
> 
> Good! feel free to send an ack if want ;)
> 
> Thanks!
> Mauro
> 
> CodingStyle.rst: use the proper tag for verbatim font
> 
> Instead of using "foo", use ``foo`` for the names that are
> literal, because it is an usual typographic convention to use
> monospaced fonts for functions and language commands on documents,
> and we're following such convention on the other ReST books.
> 
> On Sphinx/ReST, ``foo`` means that foo will be displayed using a
> monospaced font.

sorry if I'm pedantic ... more correct might be:

   On Sphinx/ReST, ``foo`` means that foo will be marked as inline literal ...

... it is not the markup which displays (presentation) something verbatim,
it is always the (e.g. HTML) stylesheet which implements, how content 
e.g. a "inline literal" [1] is displayed with verbatim. 

There is a "separation of content and presentation" [2]

Thats why I think, Mauro's first commit message was 'enough'.

Anyway, both commit messages are 'enough' :-)

--Markus--

[1] 
http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html#inline-literals
[2] https://en.wikipedia.org/wiki/Separation_of_presentation_and_content


--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 06/17] CodingStyle.rst: use the proper tag for verbatim font

[Mauro Carvalho Chehab]

Em Wed, 14 Sep 2016 09:45:10 +0200
Jean Delvare  escreveu:

> On Tue, 13 Sep 2016 16:24:48 -0300, Mauro Carvalho Chehab wrote:
> > Em Tue, 13 Sep 2016 19:45:23 +0200
> > Jean Delvare  escreveu:
> >   
> > > Hi Mauro,
> > > 
> > > On Mon, 12 Sep 2016 11:47:57 -0300, Mauro Carvalho Chehab wrote:  
> > > > Instead of using "foo", use ``foo`` for the names that are
> > > > literal.
> > > 
> > > Because...?  
> > 
> > Because it is an usual typographic convention to use monospaced
> > fonts for functions and language commands on documents.
> > 
> > On Sphinx/ReST, ``foo`` means that foo will be displayed using a
> > monospaced font.  
> 
> My point was that such an explanation should be part of your patch
> description, so that the change can be accepted (is the reviewer agrees
> with your reason) or discussed (if he/she doesn't.)

Yeah, I understood. I actually folded it on the patch.

See below. I'll be sending a new version of this series soon.

> And I do agree with the change, for what it's worth :-)

Good! feel free to send an ack if want ;)

Thanks!
Mauro

CodingStyle.rst: use the proper tag for verbatim font

Instead of using "foo", use ``foo`` for the names that are
literal, because it is an usual typographic convention to use
monospaced fonts for functions and language commands on documents,
and we're following such convention on the other ReST books.

On Sphinx/ReST, ``foo`` means that foo will be displayed using a
monospaced font.

Signed-off-by: Mauro Carvalho Chehab 

diff --git a/Documentation/development-process/CodingStyle.rst 
b/Documentation/development-process/CodingStyle.rst
index 4e65f1eaedca..d23a91d0c073 100644
--- a/Documentation/development-process/CodingStyle.rst
+++ b/Documentation/development-process/CodingStyle.rst
@@ -38,8 +38,8 @@ benefit of warning you when you're nesting your functions too 
deep.
 Heed that warning.
 
 The preferred way to ease multiple indentation levels in a switch statement is
-to align the "switch" and its subordinate "case" labels in the same column
-instead of "double-indenting" the "case" labels.  E.g.:
+to align the ``switch`` and its subordinate ``case`` labels in the same column
+instead of ``double-indenting`` the ``case`` labels.  E.g.:
 
 .. code-block:: c
 
@@ -142,7 +142,7 @@ special anyway (you can't nest them in C).
 
 Note that the closing brace is empty on a line of its own, _except_ in
 the cases where it is followed by a continuation of the same statement,
-ie a "while" in a do-statement or an "else" in an if-statement, like
+ie a ``while`` in a do-statement or an ``else`` in an if-statement, like
 this:
 
 .. code-block:: c
@@ -231,7 +231,7 @@ Do not add spaces around (inside) parenthesized 
expressions.  This example is
s = sizeof( struct file );
 
 When declaring pointer data or a function that returns a pointer type, the
-preferred use of '\*' is adjacent to the data name or function name and not
+preferred use of ``*`` is adjacent to the data name or function name and not
 adjacent to the type name.  Examples:
 
 .. code-block:: c
@@ -266,10 +266,10 @@ no space after the prefix increment & decrement unary 
operators:
 
++  --
 
-and no space around the '.' and "->" structure member operators.
+and no space around the ``.`` and ``->`` structure member operators.
 
 Do not leave trailing whitespace at the ends of lines.  Some editors with
-"smart" indentation will insert whitespace at the beginning of new lines as
+``smart`` indentation will insert whitespace at the beginning of new lines as
 appropriate, so you can start typing the next line of code right away.
 However, some such editors do not remove the whitespace if you end up not
 putting a line of code there, such as if you leave a blank line.  As a result,
@@ -287,17 +287,17 @@ Naming
 C is a Spartan language, and so should your naming be.  Unlike Modula-2
 and Pascal programmers, C programmers do not use cute names like
 ThisVariableIsATemporaryCounter.  A C programmer would call that
-variable "tmp", which is much easier to write, and not the least more
+variable ``tmp``, which is much easier to write, and not the least more
 difficult to understand.
 
 HOWEVER, while mixed-case names are frowned upon, descriptive names for
-global variables are a must.  To call a global function "foo" is a
+global variables are a must.  To call a global function ``foo`` is a
 shooting offense.
 
 GLOBAL variables (to be used only if you _really_ need them) need to
 have descriptive names, as do global functions.  If you have a function
 that counts the number of active users, you should call that
-"count_active_users()" or similar, you should _not_ call it "cntusr()".
+``count_active_users()`` or similar, you should _not_ call it ``cntusr()``.
 
 Encoding the type of a function into the name (so-called Hungarian
 notation) is brain damaged - the compiler knows the types anyway and can
@@ -305,9 +305,9 @@ check 

Re: [PATCH 06/17] CodingStyle.rst: use the proper tag for verbatim font

[Markus Heiser]

Am 14.09.2016 um 09:45 schrieb Jean Delvare :

> On Tue, 13 Sep 2016 16:24:48 -0300, Mauro Carvalho Chehab wrote:
>> Em Tue, 13 Sep 2016 19:45:23 +0200
>> Jean Delvare  escreveu:
>> 
>>> Hi Mauro,
>>> 
>>> On Mon, 12 Sep 2016 11:47:57 -0300, Mauro Carvalho Chehab wrote:
 Instead of using "foo", use ``foo`` for the names that are
 literal.  
>>> 
>>> Because...?
>> 
>> Because it is an usual typographic convention to use monospaced
>> fonts for functions and language commands on documents.
>> 
>> On Sphinx/ReST, ``foo`` means that foo will be displayed using a
>> monospaced font.
> 
> My point was that such an explanation should be part of your patch
> description,

IMHO """use ``foo`` for the names that are **literal**""" is enough.

-- Markus --

> so that the change can be accepted (is the reviewer agrees
> with your reason) or discussed (if he/she doesn't.)
> 
> And I do agree with the change, for what it's worth :-)
> 
> Thanks,
> -- 
> Jean Delvare
> SUSE L3 Support
> --
> To unsubscribe from this list: send the line "unsubscribe linux-doc" in
> the body of a message to majord...@vger.kernel.org
> More majordomo info at  http://vger.kernel.org/majordomo-info.html

--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 06/17] CodingStyle.rst: use the proper tag for verbatim font

[Jean Delvare]

On Tue, 13 Sep 2016 16:24:48 -0300, Mauro Carvalho Chehab wrote:
> Em Tue, 13 Sep 2016 19:45:23 +0200
> Jean Delvare  escreveu:
> 
> > Hi Mauro,
> > 
> > On Mon, 12 Sep 2016 11:47:57 -0300, Mauro Carvalho Chehab wrote:
> > > Instead of using "foo", use ``foo`` for the names that are
> > > literal.  
> > 
> > Because...?
> 
> Because it is an usual typographic convention to use monospaced
> fonts for functions and language commands on documents.
> 
> On Sphinx/ReST, ``foo`` means that foo will be displayed using a
> monospaced font.

My point was that such an explanation should be part of your patch
description, so that the change can be accepted (is the reviewer agrees
with your reason) or discussed (if he/she doesn't.)

And I do agree with the change, for what it's worth :-)

Thanks,
-- 
Jean Delvare
SUSE L3 Support
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 06/17] CodingStyle.rst: use the proper tag for verbatim font

[Mauro Carvalho Chehab]

Em Tue, 13 Sep 2016 19:45:23 +0200
Jean Delvare  escreveu:

> Hi Mauro,
> 
> On Mon, 12 Sep 2016 11:47:57 -0300, Mauro Carvalho Chehab wrote:
> > Instead of using "foo", use ``foo`` for the names that are
> > literal.  
> 
> Because...?

Because it is an usual typographic convention to use monospaced
fonts for functions and language commands on documents.

On Sphinx/ReST, ``foo`` means that foo will be displayed using a
monospaced font.

Regards,
Mauro.

> 
> > Signed-off-by: Mauro Carvalho Chehab 
> > ---
> >  Documentation/kernel-development/CodingStyle.rst | 98 
> > 
> >  1 file changed, 49 insertions(+), 49 deletions(-)
> > 
> > diff --git a/Documentation/kernel-development/CodingStyle.rst 
> > b/Documentation/kernel-development/CodingStyle.rst
> > index 3bc022b43ed8..4b2ba1008b11 100644
> > --- a/Documentation/kernel-development/CodingStyle.rst
> > +++ b/Documentation/kernel-development/CodingStyle.rst
> > @@ -38,8 +38,8 @@ benefit of warning you when you're nesting your functions 
> > too deep.
> >  Heed that warning.
> >  
> >  The preferred way to ease multiple indentation levels in a switch 
> > statement is
> > -to align the "switch" and its subordinate "case" labels in the same column
> > -instead of "double-indenting" the "case" labels.  E.g.:
> > +to align the ``switch`` and its subordinate ``case`` labels in the same 
> > column
> > +instead of ``double-indenting`` the ``case`` labels.  E.g.:
> >  
> >  .. code-block:: c
> >  (...)  
> 



Thanks,
Mauro
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html

Re: [PATCH 06/17] CodingStyle.rst: use the proper tag for verbatim font

[Jean Delvare]

Hi Mauro,

On Mon, 12 Sep 2016 11:47:57 -0300, Mauro Carvalho Chehab wrote:
> Instead of using "foo", use ``foo`` for the names that are
> literal.

Because...?

> Signed-off-by: Mauro Carvalho Chehab 
> ---
>  Documentation/kernel-development/CodingStyle.rst | 98 
> 
>  1 file changed, 49 insertions(+), 49 deletions(-)
> 
> diff --git a/Documentation/kernel-development/CodingStyle.rst 
> b/Documentation/kernel-development/CodingStyle.rst
> index 3bc022b43ed8..4b2ba1008b11 100644
> --- a/Documentation/kernel-development/CodingStyle.rst
> +++ b/Documentation/kernel-development/CodingStyle.rst
> @@ -38,8 +38,8 @@ benefit of warning you when you're nesting your functions 
> too deep.
>  Heed that warning.
>  
>  The preferred way to ease multiple indentation levels in a switch statement 
> is
> -to align the "switch" and its subordinate "case" labels in the same column
> -instead of "double-indenting" the "case" labels.  E.g.:
> +to align the ``switch`` and its subordinate ``case`` labels in the same 
> column
> +instead of ``double-indenting`` the ``case`` labels.  E.g.:
>  
>  .. code-block:: c
>  (...)

-- 
Jean Delvare
SUSE L3 Support
--
To unsubscribe from this list: send the line "unsubscribe linux-doc" in
the body of a message to majord...@vger.kernel.org
More majordomo info at  http://vger.kernel.org/majordomo-info.html