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
