{"thread":{"id":"22905","subject":"[PATCH] Fix indentation problem in git-ls-files(1)","startedAt":"2010-03-04T14:32:10Z","lastAt":"2010-03-20T14:01:18Z","messageCount":12,"participants":["Andreas Schwab","Junio C Hamano","Mark Lodato","Johannes Sixt"],"isPatch":true,"patchVersion":1,"patchTotal":null},"messages":[{"id":"136149","messageId":"m2tyswb1jp.fsf@igel.home","threadId":"22905","inReplyTo":null,"subject":"[PATCH] Fix indentation problem in git-ls-files(1)","fromName":"Andreas Schwab","fromEmail":"schwab@linux-m68k.org","sentAt":"2010-03-04T14:32:10Z","receivedAt":"2010-03-04T14:32:10Z","isPatch":true,"sender":{"key":"schwab@linux-m68k.org","avatar":"https://avatars.githubusercontent.com/u/2175493?v=4"},"body":"The nested list in the description of the -t option wasn't properly\nindented. Additionally, make it a horizontal labeled list since the\nlabels are all short.\n\nSigned-off-by: Andreas Schwab \n---\n Documentation/git-ls-files.txt | 15 ++++++++-------\n 1 files changed, 8 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\nindex 3521637..c0dc3ec 100644\n--- a/Documentation/git-ls-files.txt\n+++ b/Documentation/git-ls-files.txt\n@@ -108,13 +108,14 @@ OPTIONS\n -t::\n \tIdentify the file status with the following tags (followed by\n \ta space) at the start of each line:\n-\tH::\tcached\n-\tS::\tskip-worktree\n-\tM::\tunmerged\n-\tR::\tremoved/deleted\n-\tC::\tmodified/changed\n-\tK::\tto be killed\n-\t?::\tother\n+[horizontal]\n+\tH:::\tcached\n+\tS:::\tskip-worktree\n+\tM:::\tunmerged\n+\tR:::\tremoved/deleted\n+\tC:::\tmodified/changed\n+\tK:::\tto be killed\n+\t?:::\tother\n \n -v::\n \tSimilar to `-t`, but use lowercase letters for files\n-- \n1.7.0.1\n\n\nAndreas.\n\n-- \nAndreas Schwab, schwab@linux-m68k.org\nGPG Key fingerprint = 58CA 54C7 6D53 942B 1756 01D3 44D5 214B 8276 4ED5\n\"And now for something completely different.\"\n"},{"id":"136173","messageId":"7v3a0fr740.fsf@alter.siamese.dyndns.org","threadId":"22905","inReplyTo":"m2tyswb1jp.fsf@igel.home","subject":"Re: [PATCH] Fix indentation problem in git-ls-files(1)","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-03-04T23:37:35Z","receivedAt":"2010-03-04T23:37:35Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Andreas Schwab writes:\n\n> The nested list in the description of the -t option wasn't properly\n> indented. Additionally, make it a horizontal labeled list since the\n> labels are all short.\n>\n> Signed-off-by: Andreas Schwab \n> ---\n\nThanks.\n\n> Documentation/git-ls-files.txt | 15 ++++++++-------\n> 1 files changed, 8 insertions(+), 7 deletions(-)\n>\n> diff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\n> index 3521637..c0dc3ec 100644\n> --- a/Documentation/git-ls-files.txt\n> +++ b/Documentation/git-ls-files.txt\n> @@ -108,13 +108,14 @@ OPTIONS\n> -t::\n> \tIdentify the file status with the following tags (followed by\n> \ta space) at the start of each line:\n> -\tH::\tcached\n> -\tS::\tskip-worktree\n> -\tM::\tunmerged\n> -\tR::\tremoved/deleted\n> -\tC::\tmodified/changed\n> -\tK::\tto be killed\n> -\t?::\tother\n> +[horizontal]\n> +\tH:::\tcached\n> +\tS:::\tskip-worktree\n> +\tM:::\tunmerged\n> +\tR:::\tremoved/deleted\n> +\tC:::\tmodified/changed\n> +\tK:::\tto be killed\n> +\t?:::\tother\n\nBoth [horizontal] and three colons are something we never have used in the\nexisting documentation set. How confident are you that various versions\nof deployed AsciiDoc people would use all support this?\n\nI am not _complaining_; I am just being cautious to see if I have to look\ninto the issue myself (if your answer is \"not at all\") or not (otherwise).\n\nCf. http://thread.gmane.org/gmane.comp.version-control.git/139014/focus=139339\n"},{"id":"136196","messageId":"m3r5nzw05p.fsf@hase.home","threadId":"22905","inReplyTo":"7v3a0fr740.fsf@alter.siamese.dyndns.org","subject":"Re: [PATCH] Fix indentation problem in git-ls-files(1)","fromName":"Andreas Schwab","fromEmail":"schwab@linux-m68k.org","sentAt":"2010-03-05T10:08:50Z","receivedAt":"2010-03-05T10:08:50Z","isPatch":true,"sender":{"key":"schwab@linux-m68k.org","avatar":"https://avatars.githubusercontent.com/u/2175493?v=4"},"body":"Junio C Hamano writes:\n\n> Both [horizontal] and three colons are something we never have used in the\n> existing documentation set. How confident are you that various versions\n> of deployed AsciiDoc people would use all support this?\n\nI'm sorry, but I have no idea. I just looked at the user guide on the\nasciidoc home page, which contais no version information.\n\nAndreas.\n\n-- \nAndreas Schwab, schwab@linux-m68k.org\nGPG Key fingerprint = 58CA 54C7 6D53 942B 1756 01D3 44D5 214B 8276 4ED5\n\"And now for something completely different.\"\n"},{"id":"136345","messageId":"ca433831003070927h4c3e24e1m75c7be88355f9663@mail.gmail.com","threadId":"22905","inReplyTo":"m3r5nzw05p.fsf@hase.home","subject":"Re: [PATCH] Fix indentation problem in git-ls-files(1)","fromName":"Mark Lodato","fromEmail":"lodatom@gmail.com","sentAt":"2010-03-07T17:27:48Z","receivedAt":"2010-03-07T17:27:48Z","isPatch":true,"sender":{"key":"lodatom@gmail.com","avatar":"https://avatars.githubusercontent.com/u/58860?v=4"},"body":"On Fri, Mar 5, 2010 at 5:08 AM, Andreas Schwab wrote:\n> Junio C Hamano writes:\n>\n>> Both [horizontal] and three colons are something we never have used in the\n>> existing documentation set.  How confident are you that various versions\n>> of deployed AsciiDoc people would use all support this?\n>\n> I'm sorry, but I have no idea.  I just looked at the user guide on the\n> asciidoc home page, which contais no version information.\n\nYes, the documentation is lacking here. I believe we official support\nAsciiDoc 8.2.7 - this is what the builds on kernel.org use. Here's a\ncheatsheet for that version:\n\n\thttp://powerman.name/doc/asciidoc-827\n\nHopefully the following will clarify things for the future:\n\nUse ';;' instead of ':::' for a nested list. The former was added in\nAsciiDoc 5.0.9; the latter in 8.3.5.\n\nFor horizontal lists, put the term and definition on the same line\n*and* prefix it with [horizontal]. Before 8.3.0, horizontal lists\nwere specified by placing the definition on the same line as the term\n(which mimics the output). After 8.3.0, this formatting does not\nmatter, and the choice of vertical vs horizontal is determined by the\npresence of [horizontal]. If you do both, I think it looks fine on\nboth.\n\nHere's an example showing a normal, vertical list, with a nested,\nhorizontal list in the second item.\n\n---- 8< ----\na::\n\tThe first letter.\nb::\n\tThe second letter.\n+\n[horizontal]\n\tB;; The capital letter.\n\tbeta;; The greek equivalent.\nc::\n\tThe third letter.\n---- >8 ----\n\nPerhaps it would be a good idea to add an Asciidoc section to\nDocumentation/CodingGuidelines? This could clear up these sorts of\nquestions, and also cover conventions used in the manual: what name to\ngive metavariables, when to use backticks, when to use single quotes,\netc.\n"},{"id":"136346","messageId":"7veijwrn8c.fsf@alter.siamese.dyndns.org","threadId":"22905","inReplyTo":"ca433831003070927h4c3e24e1m75c7be88355f9663@mail.gmail.com","subject":"Re: [PATCH] Fix indentation problem in git-ls-files(1)","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-03-07T18:38:27Z","receivedAt":"2010-03-07T18:38:27Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Mark Lodato writes:\n\n> On Fri, Mar 5, 2010 at 5:08 AM, Andreas Schwab wrote:\n>> Junio C Hamano writes:\n>>\n>>> Both [horizontal] and three colons are something we never have used in the\n>>> existing documentation set.  How confident are you that various versions\n>>> of deployed AsciiDoc people would use all support this?\n>>\n>> I'm sorry, but I have no idea.  I just looked at the user guide on the\n>> asciidoc home page, which contais no version information.\n>\n> Yes, the documentation is lacking here. I believe we official support\n> AsciiDoc 8.2.7 - this is what the builds on kernel.org use.\n\nFYI, the machine documentation set is autogenerated at k.org uses 8.2.5\nright now, not 8.2.7..\n\n> Here's a cheatsheet for that version:\n>\n> \thttp://powerman.name/doc/asciidoc-827\n\nThanks for a link.\n\n> Hopefully the following will clarify things for the future:\n> ...\n> Perhaps it would be a good idea to add an Asciidoc section to\n> Documentation/CodingGuidelines? This could clear up these sorts of\n> questions, and also cover conventions used in the manual: what name to\n> give metavariables, when to use backticks, when to use single quotes,\n> etc.\n\nThe only rule we had so far is \"try to mimic existing text around what you\nare changing\", and \"don't try to be original nor fancy by using features\nthat are not used in existing text anywhere\", I agree it would be helpful\nto have more concrete tips on what to avoid, and conventions on what\nparticular typesetting conventions we chose for various parts of speech.\n"},{"id":"136891","messageId":"m23a01yzcc.fsf@igel.home","threadId":"22905","inReplyTo":"ca433831003070927h4c3e24e1m75c7be88355f9663@mail.gmail.com","subject":"Re: [PATCH] Fix indentation problem in git-ls-files(1)","fromName":"Andreas Schwab","fromEmail":"schwab@linux-m68k.org","sentAt":"2010-03-15T22:49:55Z","receivedAt":"2010-03-15T22:49:55Z","isPatch":true,"sender":{"key":"schwab@linux-m68k.org","avatar":"https://avatars.githubusercontent.com/u/2175493?v=4"},"body":"The nested list in the description of the -t option wasn't properly\nindented. Additionally, make it a horizontal labeled list since the\nlabels are all short.\n\nSigned-off-by: Andreas Schwab \n---\n Documentation/git-ls-files.txt | 15 ++++++++-------\n 1 files changed, 8 insertions(+), 7 deletions(-)\n\ndiff --git a/Documentation/git-ls-files.txt b/Documentation/git-ls-files.txt\nindex 3521637..d39d8b8 100644\n--- a/Documentation/git-ls-files.txt\n+++ b/Documentation/git-ls-files.txt\n@@ -108,13 +108,14 @@ OPTIONS\n -t::\n \tIdentify the file status with the following tags (followed by\n \ta space) at the start of each line:\n-\tH::\tcached\n-\tS::\tskip-worktree\n-\tM::\tunmerged\n-\tR::\tremoved/deleted\n-\tC::\tmodified/changed\n-\tK::\tto be killed\n-\t?::\tother\n+[horizontal]\n+\tH;;\tcached\n+\tS;;\tskip-worktree\n+\tM;;\tunmerged\n+\tR;;\tremoved/deleted\n+\tC;;\tmodified/changed\n+\tK;;\tto be killed\n+\t?;;\tother\n \n -v::\n \tSimilar to `-t`, but use lowercase letters for files\n-- \n1.7.0.2\n\n-- \nAndreas Schwab, schwab@linux-m68k.org\nGPG Key fingerprint = 58CA 54C7 6D53 942B 1756 01D3 44D5 214B 8276 4ED5\n\"And now for something completely different.\"\n"},{"id":"136892","messageId":"7vwrxdb2nb.fsf@alter.siamese.dyndns.org","threadId":"22905","inReplyTo":"m23a01yzcc.fsf@igel.home","subject":"Re: [PATCH] Fix indentation problem in git-ls-files(1)","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-03-15T23:12:24Z","receivedAt":"2010-03-15T23:12:24Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Hmm, http://www.methods.co.nz/asciidoc/newlists.html seems to say that\n[horizontal] is new at 8.3.0, and earlier I think I said we use 8.2.5 in\norder to prepare http://www.methods.co.nz/asciidoc/newlists.html, so the\npatch looks a bit scary to me.\n\nSadly even with 8.2.7, \"git help ls-files\" shows something like this:\n\n -t\n Identify the file status with the following tags (followed by a\n space) at the start of each line: [horizontal]\n\n H cached\n S skip-worktree\n M unmerged\n"},{"id":"136945","messageId":"4B9F2DB0.30400@viscovery.net","threadId":"22905","inReplyTo":"m23a01yzcc.fsf@igel.home","subject":"Re: [PATCH] Fix indentation problem in git-ls-files(1)","fromName":"Johannes Sixt","fromEmail":"j.sixt@viscovery.net","sentAt":"2010-03-16T07:05:20Z","receivedAt":"2010-03-16T07:05:20Z","isPatch":true,"sender":{"key":"j6t@kdbg.org","avatar":"https://avatars.githubusercontent.com/u/14810926?v=4"},"body":"Andreas Schwab schrieb:\n> The nested list in the description of the -t option wasn't properly\n> indented. Additionally, make it a horizontal labeled list since the\n> labels are all short.\n\nIMHO, converting a vertical list to a horizontal list is a step in the\nwrong direction, even if the labels are short. It is far easier to scan a\nvertical list for a match than a horizontal list.\n\n-- Hannes\n"},{"id":"136972","messageId":"m2pr34kpzm.fsf@igel.home","threadId":"22905","inReplyTo":"4B9F2DB0.30400@viscovery.net","subject":"Re: [PATCH] Fix indentation problem in git-ls-files(1)","fromName":"Andreas Schwab","fromEmail":"schwab@linux-m68k.org","sentAt":"2010-03-16T19:47:57Z","receivedAt":"2010-03-16T19:47:57Z","isPatch":true,"sender":{"key":"schwab@linux-m68k.org","avatar":"https://avatars.githubusercontent.com/u/2175493?v=4"},"body":"Johannes Sixt writes:\n\n> Andreas Schwab schrieb:\n>> The nested list in the description of the -t option wasn't properly\n>> indented. Additionally, make it a horizontal labeled list since the\n>> labels are all short.\n>\n> IMHO, converting a vertical list to a horizontal list is a step in the\n> wrong direction, even if the labels are short. It is far easier to scan a\n> vertical list for a match than a horizontal list.\n\nThe linebreak after the label is useless when all labels are much\nshorter than the indentation.\n\nAndreas.\n\n-- \nAndreas Schwab, schwab@linux-m68k.org\nGPG Key fingerprint = 58CA 54C7 6D53 942B 1756 01D3 44D5 214B 8276 4ED5\n\"And now for something completely different.\"\n"},{"id":"136990","messageId":"4BA07AEE.2080100@viscovery.net","threadId":"22905","inReplyTo":"m2pr34kpzm.fsf@igel.home","subject":"Re: [PATCH] Fix indentation problem in git-ls-files(1)","fromName":"Johannes Sixt","fromEmail":"j.sixt@viscovery.net","sentAt":"2010-03-17T06:47:10Z","receivedAt":"2010-03-17T06:47:10Z","isPatch":true,"sender":{"key":"j6t@kdbg.org","avatar":"https://avatars.githubusercontent.com/u/14810926?v=4"},"body":"Andreas Schwab schrieb:\n> Johannes Sixt writes:\n> \n>> Andreas Schwab schrieb:\n>>> The nested list in the description of the -t option wasn't properly\n>>> indented. Additionally, make it a horizontal labeled list since the\n>>> labels are all short.\n>> IMHO, converting a vertical list to a horizontal list is a step in the\n>> wrong direction, even if the labels are short. It is far easier to scan a\n>> vertical list for a match than a horizontal list.\n> \n> The linebreak after the label is useless when all labels are much\n> shorter than the indentation.\n\nI use Junio's man pages, and they look like so:\n\n -t\n Identify the file status with the following tags\n (followed by a space) at the start of each line:\n\n H cached\n S skip-worktree\n M unmerged\n R removed/deleted\n C modified/changed\n K to be killed\n ? other\n\nand the HTML version at\nhttp://www.kernel.org/pub/software/scm/git/docs/git-ls-files.html looks OK\nas well. I see nothing that needs fixing in either case.\n\n-- Hannes\n"},{"id":"137255","messageId":"m2k4t8qgyh.fsf@igel.home","threadId":"22905","inReplyTo":"4BA07AEE.2080100@viscovery.net","subject":"Re: [PATCH] Fix indentation problem in git-ls-files(1)","fromName":"Andreas Schwab","fromEmail":"schwab@linux-m68k.org","sentAt":"2010-03-19T18:55:34Z","receivedAt":"2010-03-19T18:55:34Z","isPatch":true,"sender":{"key":"schwab@linux-m68k.org","avatar":"https://avatars.githubusercontent.com/u/2175493?v=4"},"body":"Johannes Sixt writes:\n\n> Andreas Schwab schrieb:\n>> Johannes Sixt writes:\n>> \n>>> Andreas Schwab schrieb:\n>>>> The nested list in the description of the -t option wasn't properly\n>>>> indented. Additionally, make it a horizontal labeled list since the\n>>>> labels are all short.\n>>> IMHO, converting a vertical list to a horizontal list is a step in the\n>>> wrong direction, even if the labels are short. It is far easier to scan a\n>>> vertical list for a match than a horizontal list.\n>> \n>> The linebreak after the label is useless when all labels are much\n>> shorter than the indentation.\n>\n> I use Junio's man pages, and they look like so:\n>\n> -t\n> Identify the file status with the following tags\n> (followed by a space) at the start of each line:\n>\n> H cached\n> S skip-worktree\n> M unmerged\n> R removed/deleted\n> C modified/changed\n> K to be killed\n> ? other\n\nThat's not what I see.\n\n -t\n Identify the file status with the following tags (followed by a\n space) at the start of each line:\n\n H\n cached\n\n S\n skip-worktree\n\n M\n unmerged\n\n R\n removed/deleted\n\n C\n modified/changed\n\n K\n to be killed\n\n ?\n other\n\n\nAndreas.\n\n-- \nAndreas Schwab, schwab@linux-m68k.org\nGPG Key fingerprint = 58CA 54C7 6D53 942B 1756 01D3 44D5 214B 8276 4ED5\n\"And now for something completely different.\"\n"},{"id":"137331","messageId":"7v634rqehd.fsf@alter.siamese.dyndns.org","threadId":"22905","inReplyTo":"m2k4t8qgyh.fsf@igel.home","subject":"Re: [PATCH] Fix indentation problem in git-ls-files(1)","fromName":"Junio C Hamano","fromEmail":"gitster@pobox.com","sentAt":"2010-03-20T14:01:18Z","receivedAt":"2010-03-20T14:01:18Z","isPatch":true,"sender":{"key":"gitster@pobox.com","avatar":"https://avatars.githubusercontent.com/u/54884?v=4"},"body":"Andreas Schwab writes:\n\n> That's not what I see.\n\nIt could be version differences of AsciiDoc-to-xmlto toolchain. I think\nI've listed the versions I use (and the ones currently used to format the\ncopies people get from k.org) elsewhere in this thread. If you are using\nanything newer, perhaps we are seeing an issue waiting to materialize and\nyou are being a useful coalmine canary.\n\nIf the output you showed is the best we could achieve without using\nconstructs that break the versions that are older than what you used but\nare still in use (e.g. \"[horizontal]\" and \"three-colons\"), I would say we\nhave to live with it. It might be suboptimal but it still is readable.\n\nOf course if you can come up with a patch that formats better without\nbreaking older tools, that is an entirely different story. It would be\nvery much appreciated.\n"}]}