{"thread":{"id":"50633","subject":"Re: [PATCH v2] doc: format pathnames and URLs as monospace","startedAt":"2019-03-03T19:20:51Z","lastAt":"2019-03-03T19:20:51Z","messageCount":1,"participants":["Matthieu Moy"],"isPatch":true,"patchVersion":2,"patchTotal":null},"messages":[{"id":"370555","messageId":"1990905128.10960364.1551640846345.JavaMail.zimbra@inria.fr","threadId":"50633","inReplyTo":"ddf8692759de4bc28f8d49dfec939805@BPMBX2013-01.univ-lyon1.fr","subject":"Re: [PATCH v2] doc: format pathnames and URLs as monospace","fromName":"Matthieu Moy","fromEmail":"matthieu.moy@univ-lyon1.fr","sentAt":"2019-03-03T19:20:46Z","receivedAt":"2019-03-03T19:20:51Z","isPatch":true,"sender":{"key":"matthieu.moy@univ-lyon1.fr","avatar":"https://gravatar.com/avatar/8ab83b763226bd297b59ddd1463a8bfc852924577191233f73a953b86888fe0c?d=mp&s=160"},"body":"\"corentin bompard\" <corentin.bompard@etu.univ-lyon1.fr> wrote:\n\n> Updating the documentation to use monospace on URLs and pathnames because it\n> makes more sense\n\nWe usually write commit message with an imperative tone, eg. \"Update\ndocumentation\", not \"Updating documentation\". Also, the period (.) is\nmissing at the end of the sentence and the message is not wrapped at\n72 characters (your text editor probably can do that for you; with\nEmacs it's M-q or M-x auto-fill-mode RET).\n\nBut more importantly, \"makes more sense\" is the question here, not an\nanswer. The commit message is precisely here to justify why the code\nafter the patch makes more sense than before, and you can't argue \"it\nmakes more sense because it makes more sense\".\n\nAmong the arguments:\n\n* It is already an established practice. For example:\n\n  $ git grep \"'[^' ]*/[^' ]*'\" | wc -l\n  204\n  $ git grep '`[^` ]*/[^` ]*`' | wc -l\n  576\n  \n  There are false on both sides, but after a cursory look at the\n  output of both, I don't think the false positive rate is really\n  higher in the second case.\n\n  At least, this shows that the existing documentation uses inconsistent\n  formatting, and that it would be good to do something about it.\n\n* It may be debatable whether path names need to be typed in\n  monospace (I wouldn't be shocked if they were using the normal\n  font), but having them in italics is really unusual.\n\nIn addition to doing the actual change, you probably want to add a\nmention of the rule followed in Documentation/CodingGuideline.\n\nThe patch itself looks good, except the error noted by Eric Sunshine\nand:\n\n> --- a/Documentation/git-filter-branch.txt\n> +++ b/Documentation/git-filter-branch.txt\n> @@ -48,7 +48,7 @@ rewriting published history.)\n> \n> Always verify that the rewritten version is correct: The original refs,\n> if different from the rewritten ones, will be stored in the namespace\n> -'refs/original/'.\n> +`refs/original/`.\n> \n> Note that since this operation is very I/O expensive, it might\n> be a good idea to redirect the temporary directory off-disk with the\n[...]\n> diff --git a/Documentation/glossary-content.txt b/Documentation/glossary-content.txt\n> index 023ca95e7..9848d0d84 100644\n> --- a/Documentation/glossary-content.txt\n> +++ b/Documentation/glossary-content.txt\n> @@ -524,7 +524,7 @@ The most notable example is `HEAD`.\n> [[def_remote_tracking_branch]]remote-tracking branch::\n> \tA <<def_ref,ref>> that is used to follow changes from another\n> \t<<def_repository,repository>>. It typically looks like\n> -\t'refs/remotes/foo/bar' (indicating that it tracks a branch named\n> +\t`refs/remotes/foo/bar` (indicating that it tracks a branch named\n> \t'bar' in a remote named 'foo'), and matches the right-hand-side of\n> \ta configured fetch <<def_refspec,refspec>>. A remote-tracking\n> \tbranch should not contain direct modifications or have local\n> @@ -654,7 +654,7 @@ The most notable example is `HEAD`.\n> \tThe default <<def_branch,branch>> that is merged into the branch in\n> \tquestion (or the branch in question is rebased onto). It is configured\n> \tvia branch.<name>.remote and branch.<name>.merge. If the upstream branch\n> -\tof 'A' is 'origin/B' sometimes we say \"'A' is tracking 'origin/B'\".\n> +\tof 'A' is `origin/B` sometimes we say \"'A' is tracking `origin/B`\".\n> \n> [[def_working_tree]]working tree::\n> \tThe tree of actual checked out files.  The working tree normally\n[...]\n> diff --git a/Documentation/revisions.txt b/Documentation/revisions.txt\n> index 72daa20e7..92b1d5638 100644\n> --- a/Documentation/revisions.txt\n> +++ b/Documentation/revisions.txt\n> @@ -23,27 +23,27 @@ characters and to avoid word splitting.\n>   followed by a dash and a number of commits, followed by a dash, a\n>   'g', and an abbreviated object name.\n> \n> -'<refname>', e.g. 'master', 'heads/master', 'refs/heads/master'::\n> +'<refname>', e.g. 'master', `heads/master`, `refs/heads/master`::\n\nThese are refnames, and you said you excluded them from the patch.\n\n-- \nMatthieu Moy\nhttps://matthieu-moy.fr/\n"}]}