Fix indentation problem in git-ls-files(1)
PATCH 1/1 Fix indentation problem in git-ls-files(1)
The nested list in the description of the -t option wasn't properly indented. Additionally, make it a horizontal labeled list since the labels are all short.
--- Documentation/git-ls-files.txt | 15 ++++++++------- 1 files changed, 8 insertions(+), 7 deletions(-)
Documentation/git-ls-files.txt +8 -7
@@ -108,13 +108,14 @@ OPTIONS -t:: Identify the file status with the following tags (followed by a space) at the start of each line: - H:: cached - S:: skip-worktree - M:: unmerged - R:: removed/deleted - C:: modified/changed - K:: to be killed - ?:: other +[horizontal] + H::: cached + S::: skip-worktree + M::: unmerged + R::: removed/deleted + C::: modified/changed + K::: to be killed + ?::: other -v:: Similar to `-t`, but use lowercase letters for files
Signature · 9 lines
1.7.0.1 Andreas. -- Andreas Schwab, [email protected] GPG Key fingerprint = 58CA 54C7 6D53 942B 1756 01D3 44D5 214B 8276 4ED5 "And now for something completely different."
Quoted 6 lines · Andreas Schwab
The nested list in the description of the -t option wasn't properly indented. Additionally, make it a horizontal labeled list since the labels are all short.
Signed-off-by Andreas Schwab <[email protected]>---
Thanks.
Quoted 16 lines
Documentation/git-ls-files.txt | 15 ++++++++------- 1 files changed, 8 insertions(+), 7 deletions(-)Documentation/git-ls-files.txt +0
-5@@ -108,13 +108,14 @@ OPTIONS -t:: Identify the file status with the following tags (followed by a space) at the start of each line: - H:: cached - S:: skip-worktree - M:: unmerged - R:: removed/deleted - C:: modified/changed
Documentation/git-ls-files.txt OPTIONS · line 118
Quoted 10 lines
Documentation/git-ls-files.txt +8
-2- K:: to be killed - ?:: other +[horizontal] + H::: cached + S::: skip-worktree + M::: unmerged + R::: removed/deleted + C::: modified/changed + K::: to be killed + ?::: other
Both [horizontal] and three colons are something we never have used in the existing documentation set. How confident are you that various versions of deployed AsciiDoc people would use all support this?
I am not _complaining_; I am just being cautious to see if I have to look into the issue myself (if your answer is "not at all") or not (otherwise).
Cf. http://thread.gmane.org/gmane.comp.version-control.git/139014/focus=139339
Quoted 3 lines · Junio C Hamano
Both [horizontal] and three colons are something we never have used in the existing documentation set. How confident are you that various versions of deployed AsciiDoc people would use all support this?
I'm sorry, but I have no idea. I just looked at the user guide on the asciidoc home page, which contais no version information.
Andreas.
Signature · 3 lines
Andreas Schwab, [email protected] GPG Key fingerprint = 58CA 54C7 6D53 942B 1756 01D3 44D5 214B 8276 4ED5 "And now for something completely different."
Quoted 8 lines · Andreas Schwab
Quoted 3 lines · Junio C Hamano
Both [horizontal] and three colons are something we never have used in the existing documentation set. How confident are you that various versions of deployed AsciiDoc people would use all support this?
I'm sorry, but I have no idea. I just looked at the user guide on the asciidoc home page, which contais no version information.
Yes, the documentation is lacking here. I believe we official support AsciiDoc 8.2.7 - this is what the builds on kernel.org use. Here's a cheatsheet for that version:
http://powerman.name/doc/asciidoc-827
Hopefully the following will clarify things for the future:
Use ';;' instead of ':::' for a nested list. The former was added in AsciiDoc 5.0.9; the latter in 8.3.5.
For horizontal lists, put the term and definition on the same line *and* prefix it with [horizontal]. Before 8.3.0, horizontal lists were specified by placing the definition on the same line as the term (which mimics the output). After 8.3.0, this formatting does not matter, and the choice of vertical vs horizontal is determined by the presence of [horizontal]. If you do both, I think it looks fine on both.
Here's an example showing a normal, vertical list, with a nested, horizontal list in the second item.
---- 8< ----
a::
The first letter.
b::
The second letter.
+
[horizontal]
B;; The capital letter.
beta;; The greek equivalent.
c::
The third letter.
---- >8 ----
Perhaps it would be a good idea to add an Asciidoc section to Documentation/CodingGuidelines? This could clear up these sorts of questions, and also cover conventions used in the manual: what name to give metavariables, when to use backticks, when to use single quotes, etc.
Quoted 7 lines · Mark Lodato
Quoted 6 lines · Andreas Schwab
Quoted 3 lines · Junio C Hamano
Both [horizontal] and three colons are something we never have used in the existing documentation set. How confident are you that various versions of deployed AsciiDoc people would use all support this?
Quoted 5 lines
Quoted 2 lines
I'm sorry, but I have no idea. I just looked at the user guide on the asciidoc home page, which contais no version information.
Yes, the documentation is lacking here. I believe we official support AsciiDoc 8.2.7 - this is what the builds on kernel.org use.
FYI, the machine documentation set is autogenerated at k.org uses 8.2.5 right now, not 8.2.7..
Quoted 3 lines
Here's a cheatsheet for that version:
http://powerman.name/doc/asciidoc-827
Thanks for a link.
Quoted 7 lines
Hopefully the following will clarify things for the future:
...
Perhaps it would be a good idea to add an Asciidoc section toDocumentation/CodingGuidelines? This could clear up these sorts of questions, and also cover conventions used in the manual: what name to give metavariables, when to use backticks, when to use single quotes, etc.
The only rule we had so far is "try to mimic existing text around what you are changing", and "don't try to be original nor fancy by using features that are not used in existing text anywhere", I agree it would be helpful to have more concrete tips on what to avoid, and conventions on what particular typesetting conventions we chose for various parts of speech.
The nested list in the description of the -t option wasn't properly indented. Additionally, make it a horizontal labeled list since the labels are all short.
--- Documentation/git-ls-files.txt | 15 ++++++++------- 1 files changed, 8 insertions(+), 7 deletions(-)
Documentation/git-ls-files.txt +8 -7
@@ -108,13 +108,14 @@ OPTIONS -t:: Identify the file status with the following tags (followed by a space) at the start of each line: - H:: cached - S:: skip-worktree - M:: unmerged - R:: removed/deleted - C:: modified/changed - K:: to be killed - ?:: other +[horizontal] + H;; cached + S;; skip-worktree + M;; unmerged + R;; removed/deleted + C;; modified/changed + K;; to be killed + ?;; other -v:: Similar to `-t`, but use lowercase letters for files
Signature · 6 lines
1.7.0.2 -- Andreas Schwab, [email protected] GPG Key fingerprint = 58CA 54C7 6D53 942B 1756 01D3 44D5 214B 8276 4ED5 "And now for something completely different."
Quoted 3 lines · Andreas Schwab
The nested list in the description of the -t option wasn't properly indented. Additionally, make it a horizontal labeled list since the labels are all short.
IMHO, converting a vertical list to a horizontal list is a step in the wrong direction, even if the labels are short. It is far easier to scan a vertical list for a match than a horizontal list.
-- Hannes
Quoted 8 lines · Johannes Sixt
Quoted 3 lines · Andreas Schwab
The nested list in the description of the -t option wasn't properly indented. Additionally, make it a horizontal labeled list since the labels are all short.
IMHO, converting a vertical list to a horizontal list is a step in the wrong direction, even if the labels are short. It is far easier to scan a vertical list for a match than a horizontal list.
The linebreak after the label is useless when all labels are much shorter than the indentation.
Andreas.
Signature · 3 lines
Andreas Schwab, [email protected] GPG Key fingerprint = 58CA 54C7 6D53 942B 1756 01D3 44D5 214B 8276 4ED5 "And now for something completely different."
Quoted 6 lines · Andreas Schwab
Quoted 4 lines · Johannes Sixt
Quoted 3 lines · Andreas Schwab
The nested list in the description of the -t option wasn't properly indented. Additionally, make it a horizontal labeled list since the labels are all short.
Quoted 6 lines
Quoted 3 lines
IMHO, converting a vertical list to a horizontal list is a step in the wrong direction, even if the labels are short. It is far easier to scan a vertical list for a match than a horizontal list.
The linebreak after the label is useless when all labels are much shorter than the indentation.
I use Junio's man pages, and they look like so:
-t
Identify the file status with the following tags (followed by a space) at the start of each line:
H cached
S skip-worktree
M unmerged
R removed/deleted
C modified/changed
K to be killed
? other
and the HTML version at
http://www.kernel.org/pub/software/scm/git/docs/git-ls-files.html looks OK as well. I see nothing that needs fixing in either case.
-- Hannes
Quoted 20 lines · Johannes Sixt
Quoted 6 lines · Andreas Schwab
Quoted 4 lines · Johannes Sixt
Quoted 3 lines · Andreas Schwab
The nested list in the description of the -t option wasn't properly indented. Additionally, make it a horizontal labeled list since the labels are all short.
Quoted 6 lines
Quoted 3 lines
IMHO, converting a vertical list to a horizontal list is a step in the wrong direction, even if the labels are short. It is far easier to scan a vertical list for a match than a horizontal list.
The linebreak after the label is useless when all labels are much shorter than the indentation.
I use Junio's man pages, and they look like so:
-t
Identify the file status with the following tags (followed by a space) at the start of each line:
Quoted 7 lines
H cached
S skip-worktree
M unmerged
R removed/deleted
C modified/changed
K to be killed
? other
That's not what I see.
-t
Identify the file status with the following tags (followed by a space) at the start of each line:
H
cached
S
skip-worktree
M
unmerged
R
removed/deleted
C
modified/changed
K
to be killed
?
other
Andreas.
Signature · 3 lines
Andreas Schwab, [email protected] GPG Key fingerprint = 58CA 54C7 6D53 942B 1756 01D3 44D5 214B 8276 4ED5 "And now for something completely different."
Quoted 1 line · Andreas Schwab
That's not what I see.
It could be version differences of AsciiDoc-to-xmlto toolchain. I think I've listed the versions I use (and the ones currently used to format the copies people get from k.org) elsewhere in this thread. If you are using anything newer, perhaps we are seeing an issue waiting to materialize and you are being a useful coalmine canary.
If the output you showed is the best we could achieve without using constructs that break the versions that are older than what you used but are still in use (e.g. "[horizontal]" and "three-colons"), I would say we have to live with it. It might be suboptimal but it still is readable.
Of course if you can come up with a patch that formats better without breaking older tools, that is an entirely different story. It would be very much appreciated.
Hmm, http://www.methods.co.nz/asciidoc/newlists.html seems to say that [horizontal] is new at 8.3.0, and earlier I think I said we use 8.2.5 in order to prepare http://www.methods.co.nz/asciidoc/newlists.html, so the patch looks a bit scary to me.
Sadly even with 8.2.7, "git help ls-files" shows something like this:
-t
Identify the file status with the following tags (followed by a space) at the start of each line: [horizontal]
H cached
S skip-worktree
M unmerged