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

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

 



Am 14.09.2016 um 15:48 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>:

> Em Wed, 14 Sep 2016 14:18:55 +0200
> Markus Heiser <markus.heiser@xxxxxxxxxxx> escreveu:
> 
>> Am 14.09.2016 um 11:35 schrieb Mauro Carvalho Chehab <mchehab@xxxxxxxxxxxxxxxx>:
>> 
>>> Em Wed, 14 Sep 2016 09:45:10 +0200
>>> Jean Delvare <jdelvare@xxxxxxx> 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 <jdelvare@xxxxxxx> 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 majordomo@xxxxxxxxxxxxxxx
More majordomo info at  http://vger.kernel.org/majordomo-info.html



[Index of Archives]     [Kernel Newbies]     [Security]     [Netfilter]     [Bugtraq]     [Linux FS]     [Yosemite Forum]     [MIPS Linux]     [ARM Linux]     [Linux Security]     [Linux RAID]     [Samba]     [Video 4 Linux]     [Device Mapper]     [Linux Resources]

  Powered by Linux