From patchwork Wed Mar 6 13:04:45 2019 Content-Type: text/plain; charset="utf-8" MIME-Version: 1.0 Content-Transfer-Encoding: 7bit X-Patchwork-Submitter: Corentin BOMPARD X-Patchwork-Id: 10841091 Return-Path: Received: from mail.wl.linuxfoundation.org (pdx-wl-mail.web.codeaurora.org [172.30.200.125]) by pdx-korg-patchwork-2.web.codeaurora.org (Postfix) with ESMTP id 2237314DE for ; Wed, 6 Mar 2019 13:05:52 +0000 (UTC) Received: from mail.wl.linuxfoundation.org (localhost [127.0.0.1]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 0B84E2D859 for ; Wed, 6 Mar 2019 13:05:52 +0000 (UTC) Received: by mail.wl.linuxfoundation.org (Postfix, from userid 486) id F40142D87A; Wed, 6 Mar 2019 13:05:51 +0000 (UTC) X-Spam-Checker-Version: SpamAssassin 3.3.1 (2010-03-16) on pdx-wl-mail.web.codeaurora.org X-Spam-Level: X-Spam-Status: No, score=-7.9 required=2.0 tests=BAYES_00,MAILING_LIST_MULTI, RCVD_IN_DNSWL_HI autolearn=ham version=3.3.1 Received: from vger.kernel.org (vger.kernel.org [209.132.180.67]) by mail.wl.linuxfoundation.org (Postfix) with ESMTP id 20DCE2D859 for ; Wed, 6 Mar 2019 13:05:51 +0000 (UTC) Received: (majordomo@vger.kernel.org) by vger.kernel.org via listexpand id S1726588AbfCFNFt (ORCPT ); Wed, 6 Mar 2019 08:05:49 -0500 Received: from cisrsmtp.univ-lyon1.fr ([134.214.188.146]:60843 "EHLO cisrsmtp.univ-lyon1.fr" rhost-flags-OK-OK-OK-OK) by vger.kernel.org with ESMTP id S1726429AbfCFNFt (ORCPT ); Wed, 6 Mar 2019 08:05:49 -0500 Received: from localhost (localhost [127.0.0.1]) by cisrsmtp.univ-lyon1.fr (Postfix) with ESMTP id 9A2DBA0158 for ; Wed, 6 Mar 2019 14:05:47 +0100 (CET) X-Virus-Scanned: Debian amavisd-new at cisrsmtp.univ-lyon1.fr Received: from cisrsmtp.univ-lyon1.fr ([127.0.0.1]) by localhost (cisrsmtp.univ-lyon1.fr [127.0.0.1]) (amavisd-new, port 10024) with ESMTP id SklWutmvkCmr for ; Wed, 6 Mar 2019 14:05:46 +0100 (CET) Received: from BEMBX2013-01.univ-lyon1.fr (bembx2013-01.univ-lyon1.fr [134.214.201.247]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-SHA384 (256/256 bits)) (No client certificate requested) by cisrsmtp.univ-lyon1.fr (Postfix) with ESMTPS id 997EBA00AD for ; Wed, 6 Mar 2019 14:05:46 +0100 (CET) Received: from Corentin-Linux.lan (134.214.126.172) by BEMBX2013-01.univ-lyon1.fr (134.214.201.247) with Microsoft SMTP Server (TLS) id 15.0.1263.5; Wed, 6 Mar 2019 14:05:44 +0100 From: Corentin BOMPARD To: CC: , , , Subject: [PATCH 1/2 v3] doc/CodingGuidelines: URLs and paths as monospace. Date: Wed, 6 Mar 2019 14:04:45 +0100 Message-ID: <20190306130446.2193-1-corentin.bompard@etu.univ-lyon1.fr> X-Mailer: git-send-email 2.21.0-rc0 MIME-Version: 1.0 X-Originating-IP: [134.214.126.172] X-ClientProxiedBy: BPMBX2013-01.univ-lyon1.fr (134.214.201.243) To BEMBX2013-01.univ-lyon1.fr (134.214.201.247) Sender: git-owner@vger.kernel.org Precedence: bulk List-ID: X-Mailing-List: git@vger.kernel.org X-Virus-Scanned: ClamAV using ClamSMTP The current documentation uses both quotes (italics) and backquotes (monospace) to render URLs and pathnames, which is inconsistant. Document a best practice in CodingGuidelines to help reduce inconsistencies in the futur. We set the best practice to using backquotes, since: * It is already an established practice. For exemple: $ git grep "'[^']/*[^']'" | wc -l 206 $ git grep '`[^`]/*[^`]`' | wc -l 690 There are false on both sides, but after a cursory look at the output of both, It doesn't seem the false positive rate is really higher in the second case. At least, this shows that the existing documentation uses inconsistent formatting, and that it would be good to do something about it. * It may be debatable whether path names need to be typed in monospace but having them in italics is really unusual. Signed-off-by: Corentin BOMPARD Signed-off-by: Nathan BERBEZIER Signed-off-by: Pablo CHABANNE Signed-off-by: Matthieu MOY --- Changes: According to Matthieu MOY we added a new guideline in Documentation/CodingGuidelines.txt about monospace. Documentation/CodingGuidelines | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines index 857953071..0baff9dbe 100644 --- a/Documentation/CodingGuidelines +++ b/Documentation/CodingGuidelines @@ -580,11 +580,14 @@ Writing Documentation: or commands: Literal examples (e.g. use of command-line options, command names, - branch names, configuration and environment variables) must be - typeset in monospace (i.e. wrapped with backticks): + branch names, URLs, pathnames (files and directories), configuration and + environment variables) must be typeset in monospace (i.e. wrapped with + backticks): `--pretty=oneline` `git rev-list` `remote.pushDefault` + `http://git.example.com` + `.git/config` `GIT_DIR` `HEAD`