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. - Thanks, Mauro -- 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
