howto: Use all-space indentation in ASCII art
PATCH 1/1 howto: Use all-space indentation in ASCII art
Keep the sketch aligned independent of the tabstop width used.
--- Documentation/howto/revert-a-faulty-merge.txt | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 deletions(-)
Documentation/howto/revert-a-faulty-merge.txt +8 -8
@@ -30,7 +30,7 @@ The history immediately after the "revert of the merge" would look like this: ---o---o---o---M---x---x---W - / + / ---A---B where A and B are on the side development that was not so good, M is the
@@ -47,7 +47,7 @@ After the developers of the side branch fix their mistakes, the history may look like this: ---o---o---o---M---x---x---W---x - / + / ---A---B-------------------C---D where C and D are to fix what was broken in A and B, and you may already
@@ -81,7 +81,7 @@ In such a situation, you would want to first revert the previous revert, which would make the history look like this: ---o---o---o---M---x---x---W---x---Y - / + / ---A---B-------------------C---D where Y is the revert of W. Such a "revert of the revert" can be done
@@ -93,14 +93,14 @@ This history would (ignoring possible conflicts between what W and W..Y changed) be equivalent to not having W nor Y at all in the history: ---o---o---o---M---x---x-------x---- - / + / ---A---B-------------------C---D and merging the side branch again will not have conflict arising from an earlier revert and revert of the revert. ---o---o---o---M---x---x-------x-------* - / / + / / ---A---B-------------------C---D Of course the changes made in C and D still can conflict with what was
@@ -111,13 +111,13 @@ faulty A and B, and redone the changes on top of the updated mainline after the revert, the history would have looked like this: ---o---o---o---M---x---x---W---x---x - / \ + / \ ---A---B A'--B'--C' If you reverted the revert in such a case as in the previous example: ---o---o---o---M---x---x---W---x---x---Y---* - / \ / + / \ / ---A---B A'--B'--C' where Y is the revert of W, A' and B' are rerolled A and B, and there may
@@ -129,7 +129,7 @@ lot of overlapping changes that result in conflicts. So do not do "revert of revert" blindly without thinking.. ---o---o---o---M---x---x---W---x---x - / \ + / \ ---A---B A'--B'--C' In the history with rebased side branch, W (and M) are behind the merge
Signature · 1 line
1.8.3.2.50.g531c8dd
Quoted 1 line · Dirk Wallenstein
Keep the sketch aligned independent of the tabstop width used.
Thanks.
This is a source text to be formatted into HTML, isn't it?
In our sources, a HT indents to multiple of 8 columns. As long as the output HTML produced from the source can be seen on a terminal with any tab-width correctly, I do not see any reason to apply this patch.
Am I missing something???
Quoted 6 lines · Junio C Hamano
Quoted 1 line · Dirk Wallenstein
Keep the sketch aligned independent of the tabstop width used.
Thanks.
Quoted 9 lines
This is a source text to be formatted into HTML, isn't it?
In our sources, a HT indents to multiple of 8 columns. As long as the output HTML produced from the source can be seen on a terminal with any tab-width correctly, I do not see any reason to apply this patch.
Am I missing something???
Those text files are installed as documentation (at least on my distribution). They have a *.txt suffix, which tells me that they are meant to be read. If those would ever be opened with a text editor where the user has set the default tabstop width to something other than 8 it would teach something nonsensical. Not to mention if those files would have been printed with the wrong setting.
Why would you want to limit those files to be source for HTML only?
The HTML after this patch is still fine.
Signature · 2 lines
Cheers, Dirk
Quoted 1 line · Dirk Wallenstein
Those text files are installed as documentation (at least on my distribution).
That's probably a distribution bug (or a git makefile bug, depending on how you look at it). It would be better to ship the HTML documentation, converted to text, instead of keeping the version with markup including occasional random \ signs, linkgit:, ``, etc.
What distribution do you use? (As maintainer of packaging for a Linux distro, I know at least one that is guilty of this.)
Thanks,
Jonathan
Quoted 8 lines · Jonathan Nieder
Quoted 1 line · Dirk Wallenstein
Those text files are installed as documentation (at least on my distribution).
That's probably a distribution bug (or a git makefile bug, depending on how you look at it). It would be better to ship the HTML documentation, converted to text, instead of keeping the version with markup including occasional random \ signs, linkgit:, ``, etc.
They are also installed if I only use Git's makefile.
Quoted 3 lines
What distribution do you use? (As maintainer of packaging for a Linux distro, I know at least one that is guilty of this.)
Ubuntu.
As an aside, I had to run manual creation as root. Otherwise it did hang (XMLTO). Is that an Ubuntu bug? Sorry, just because you seem to know about this.
Signature · 2 lines
Cheers, Dirk
Quoted 11 lines
Quoted 2 lines
Those text files are installed as documentation (at least on my distribution).
That's probably a distribution bug (or a git makefile bug, depending on how you look at it). It would be better to ship the HTML documentation, converted to text, instead of keeping the version with markup including occasional random \ signs, linkgit:, ``, etc.
What distribution do you use? (As maintainer of packaging for a Linux distro, I know at least one that is guilty of this.)
From the AcsiiDoc Home Page:
=begin quote=
You write an AsciiDoc document the same way you would write a normal text document, there are no markup tags or weird format notations. AsciiDoc files are designed to be viewed, edited and printed directly or translated to other presentation formats using the asciidoc(1) command. =end quote=
So, the asciidoc "source" files should be readable in their unprocessed form. And, not using tabs in ASCII art doesn't appear to have any downside.
Quoted 3 lines
Why would you want to limit those files to be source for HTML only?
The HTML after this patch is still fine.
Have you thought the reason why the formatted result _before_ the patch is good?
These *.txt files are asciidoc formatted source files. They are meant to be easy to read and edit without distracting mark-ups (unlike roff and html), but with one big precondition: your tab-width ought to be
8. That is how asciidoc expands the tab when producing the formatted output, and that is why the formatted result _before_ the patch is good.
Expanding these tabs to all spaces do not buy us anything, other than source code bloat, and with one downside.
It would give a false impression that it somehow is OK to open these *.txt files with a wrong tab-width setting, and even worse, edit them. You may even type a new tab yourself to indent by 4 places, and formatted result will be broken by such a person.
It would signal that your tab-width setting is not suitable to view/edit these files if the elements in the illustration do not line up. View it as a bonus safety feature ;-)
Quoted 5 lines · Junio C Hamano
Quoted 3 lines
Why would you want to limit those files to be source for HTML only?
The HTML after this patch is still fine.
Have you thought the reason why the formatted result _before_ the patch is good?
No, as I said, *.txt suffixes tell me there is text in there and not source code. But what is more important is that they are installed (by Git) as is (obviously) into share/doc. I'm happy to learn about the conversion through these posts, but the installation is flawed.
Quoted 6 lines
These *.txt files are asciidoc formatted source files. They are meant to be easy to read and edit without distracting mark-ups (unlike roff and html), but with one big precondition: your tab-width ought to be
8. That is how asciidoc expands the tab when producing the formatted output, and that is why the formatted result _before_ the patch is good.
asciidoc replaces the other spaces in the sketch with spaces in the result. Hard to believe it stops doing that if it is accidentally a sequence of 8 spaces. And spaces are invisible by design. Whitespace only distracts if it leads to a wrong result.
Quoted 3 lines
Expanding these tabs to all spaces do not buy us anything, other than source code bloat, and with one downside.
Correctness maybe, if you open them in an editor to read them. Imagine the code bloat when the installation procedure expands the tabs so that the final installation is correct.
Quoted 4 lines
It would give a false impression that it somehow is OK to open these *.txt files with a wrong tab-width setting, and even worse, edit them. You may even type a new tab yourself to indent by 4 places, and formatted result will be broken by such a person.
Luckily there are whitespace checks for mixed space and/or tab-indent. The right approach would probably be to have no tabs indent in any of these files. I'm happy to assist ;)
Quoted 4 lines
It would signal that your tab-width setting is not suitable to view/edit these files if the elements in the illustration do not line up. View it as a bonus safety feature ;-)
gitattributes could solve that much more reliable if there wasn't any tab indentation allowed.
In the end, this is installed as documentation with a requirement on the tab-width of any reader application used. The easiest and most foolproof solution without introducing errors is to simply expand these tabs. Again, the current installation is flawed.
Signature · 2 lines
Cheers, Dirk
cover Remove tabs from howto documents
I really think that tabs are generally bad here. So, this will remove all tabs from the howto folder and prevent indenting with tabs through gitattributes.
Dirk Wallenstein (2):
howto: Suppress indentation with tabs
howto: Eliminate all tabs
Documentation/howto/.gitattributes | 1 + .../howto/rebase-from-internal-branch.txt | 8 ++-- Documentation/howto/rebuild-from-update-hook.txt | 4 +- .../howto/recover-corrupted-blob-object.txt | 50 +++++++++++----------- Documentation/howto/revert-a-faulty-merge.txt | 16 +++---- Documentation/howto/revert-branch-rebase.txt | 2 +- Documentation/howto/update-hook-example.txt | 8 ++-- Documentation/howto/use-git-daemon.txt | 10 ++--- 8 files changed, 50 insertions(+), 49 deletions(-) create mode 100644 Documentation/howto/.gitattributes
Signature · 1 line
1.8.3.3.2.g85103ba
Re: [PATCH 0/2] Remove tabs from howto documents
Quoted 8 lines · Dirk Wallenstein
I really think that tabs are generally bad here. So, this will remove all tabs from the howto folder and prevent indenting with tabs through gitattributes.
Dirk Wallenstein (2):
howto: Suppress indentation with tabs
howto: Eliminate all tabs
Quoted 11 lines
Documentation/howto/.gitattributes | 1 + .../howto/rebase-from-internal-branch.txt | 8 ++-- Documentation/howto/rebuild-from-update-hook.txt | 4 +- .../howto/recover-corrupted-blob-object.txt | 50 +++++++++++----------- Documentation/howto/revert-a-faulty-merge.txt | 16 +++---- Documentation/howto/revert-branch-rebase.txt | 2 +- Documentation/howto/update-hook-example.txt | 8 ++-- Documentation/howto/use-git-daemon.txt | 10 ++--- 8 files changed, 50 insertions(+), 49 deletions(-) create mode 100644 Documentation/howto/.gitattributes
How about adding a line about this in Documentation/CodingGuidelines?
Signature · 5 lines
Med vänliga hälsningar Fredrik Gustafsson tel: 0733-608274 e-post: [email protected]
A message that is not in the archive (sent off-list or not yet received): [email protected]
PATCH 1/2 howto: Suppress indentation with tabs
The AsciiDoc files in the 'howto' folder are installed as documentation and AsciiDoc files are meant to be read and printed as is. To quote the AsciiDoc Home Page:
AsciiDoc files are designed to be viewed, edited and printed directly or translated to other presentation formats using the asciidoc(1) command.
Tabs have the property of a configurable width and can thereby skew the layout of a page and distort the meaning. This is particularly a problem when mixing lines with different indentation (space vs tab) in code examples and ASCII art.
Prevent such a mix-up by prohibiting tab indentation entirely.
--- Documentation/howto/.gitattributes | 1 + 1 file changed, 1 insertion(+) create mode 100644 Documentation/howto/.gitattributes
Documentation/howto/.gitattributes new file +1 -0
@@ -0,0 +1 @@ +* whitespace=tab
Signature · 1 line
1.8.3.3.2.g85103ba
A message that is not in the archive (sent off-list or not yet received): 4d37bfa3326469ab5b7cdbf0018f7aa671c2d74a.1375288760.git.halsmit@t-online.de
PATCH 2/2 howto: Eliminate all tabs
Because tabs have a variable width, the layout can diverge from what the author intended. Replace all tabs with spaces to the next column that is a multiple of 8.
This fixes several ascii art sketches and a code example where viewing it with a tab-width other than 8 lead to wrong indentation.
--- .../howto/rebase-from-internal-branch.txt | 8 ++-- Documentation/howto/rebuild-from-update-hook.txt | 4 +- .../howto/recover-corrupted-blob-object.txt | 50 +++++++++++----------- Documentation/howto/revert-a-faulty-merge.txt | 16 +++---- Documentation/howto/revert-branch-rebase.txt | 2 +- Documentation/howto/update-hook-example.txt | 8 ++-- Documentation/howto/use-git-daemon.txt | 10 ++--- 7 files changed, 49 insertions(+), 49 deletions(-)
Documentation/howto/rebase-from-internal-branch.txt +4 -4
@@ -1,8 +1,8 @@ -From: Junio C Hamano <[email protected]> -To: [email protected] -Cc: Petr Baudis <[email protected]>, Linus Torvalds <[email protected]> +From:Junio C Hamano <[email protected]> +To: [email protected] +Cc: Petr Baudis <[email protected]>, Linus Torvalds <[email protected]> Subject: Re: sending changesets from the middle of a git tree -Date: Sun, 14 Aug 2005 18:37:39 -0700 +Date: Sun, 14 Aug 2005 18:37:39 -0700 Abstract: In this article, JC talks about how he rebases the public "pu" branch using the core Git tools when he updates the "master" branch, and how "rebase" works. Also discussed
Documentation/howto/rebuild-from-update-hook.txt +2 -2
@@ -19,8 +19,8 @@ when I took over Git maintainership from Linus. The directories relevant to this how-to are these two: - /pub/scm/git/git.git/ The public Git repository. - /pub/software/scm/git/docs/ The HTML documentation page. + /pub/scm/git/git.git/ The public Git repository. + /pub/software/scm/git/docs/ The HTML documentation page. So I made a repository to generate the documentation under my home directory over there.
Documentation/howto/recover-corrupted-blob-object.txt +25 -25
97 lines not on this page · raw message
Documentation/howto/revert-a-faulty-merge.txt +8 -8
@@ -30,7 +30,7 @@ The history immediately after the "revert of the merge" would look like this: ---o---o---o---M---x---x---W - / + / ---A---B where A and B are on the side development that was not so good, M is the
@@ -47,7 +47,7 @@ After the developers of the side branch fix their mistakes, the history may look like this: ---o---o---o---M---x---x---W---x - / + / ---A---B-------------------C---D where C and D are to fix what was broken in A and B, and you may already
@@ -81,7 +81,7 @@ In such a situation, you would want to first revert the previous revert, which would make the history look like this: ---o---o---o---M---x---x---W---x---Y - / + / ---A---B-------------------C---D where Y is the revert of W. Such a "revert of the revert" can be done
@@ -93,14 +93,14 @@ This history would (ignoring possible conflicts between what W and W..Y changed) be equivalent to not having W nor Y at all in the history: ---o---o---o---M---x---x-------x---- - / + / ---A---B-------------------C---D and merging the side branch again will not have conflict arising from an earlier revert and revert of the revert. ---o---o---o---M---x---x-------x-------* - / / + / / ---A---B-------------------C---D Of course the changes made in C and D still can conflict with what was
@@ -111,13 +111,13 @@ faulty A and B, and redone the changes on top of the updated mainline after the revert, the history would have looked like this: ---o---o---o---M---x---x---W---x---x - / \ + / \ ---A---B A'--B'--C' If you reverted the revert in such a case as in the previous example: ---o---o---o---M---x---x---W---x---x---Y---* - / \ / + / \ / ---A---B A'--B'--C' where Y is the revert of W, A' and B' are rerolled A and B, and there may
@@ -129,7 +129,7 @@ lot of overlapping changes that result in conflicts. So do not do "revert of revert" blindly without thinking.. ---o---o---o---M---x---x---W---x---x - / \ + / \ ---A---B A'--B'--C' In the history with rebased side branch, W (and M) are behind the merge
Documentation/howto/revert-branch-rebase.txt +1 -1
@@ -154,7 +154,7 @@ $ git pull . master Packing 0 objects Unpacking 0 objects -* committish: e3a693c... refs/heads/master from . +* committish: e3a693c... refs/heads/master from . Trying to merge e3a693c... into 8c1f5f0... using 10d781b... Committed merge 7fb9b7262a1d1e0a47bbfdcbbcf50ce0635d3f8f cache.h | 8 ++++----
Documentation/howto/update-hook-example.txt +4 -4
@@ -51,19 +51,19 @@ verbose=false GLOBIGNORE=* function grant { - $verbose && echo >&2 "-Grant- $1" + $verbose && echo >&2 "-Grant- $1" echo grant exit 0 } function deny { - $verbose && echo >&2 "-Deny- $1" + $verbose && echo >&2 "-Deny- $1" echo deny exit 1 } function info { - $verbose && echo >&2 "-Info- $1" + $verbose && echo >&2 "-Info- $1" } # Implement generic branch and tag policies.
@@ -83,7 +83,7 @@ case "$1" in mb=$(git-merge-base "$2" "$3") case "$mb,$2" in "$2,$mb") info "Update is fast-forward" ;; - *) noff=y; info "This is not a fast-forward update.";; + *) noff=y; info "This is not a fast-forward update.";; esac fi ;;
Documentation/howto/use-git-daemon.txt +5 -5
@@ -12,11 +12,11 @@ things do not go according to plan (e.g. a socket could not be bound). Another word of warning: if you run - $ git ls-remote git://127.0.0.1/rule-the-world.git + $ git ls-remote git://127.0.0.1/rule-the-world.git and you see a message like - fatal: The remote end hung up unexpectedly + fatal: The remote end hung up unexpectedly it only means that _something_ went wrong. To find out _what_ went wrong, you have to ask the server. (Git refuses to be more precise for your
@@ -25,8 +25,8 @@ Sorry, not allowed -- who knows what you planned to do with them?) With these two caveats, let's see an example: - $ git daemon --reuseaddr --verbose --base-path=/home/gitte/git \ - --export-all -- /home/gitte/git/rule-the-world.git + $ git daemon --reuseaddr --verbose --base-path=/home/gitte/git \ + --export-all -- /home/gitte/git/rule-the-world.git (Of course, unless your user name is `gitte` _and_ your repository is in ~/rule-the-world.git, you have to adjust the paths. If your repository is
@@ -49,6 +49,6 @@ a good practice to put the paths after a "--" separator. Now, test your daemon with - $ git ls-remote git://127.0.0.1/rule-the-world.git + $ git ls-remote git://127.0.0.1/rule-the-world.git If this does not work, find out why, and submit a patch to this document.
Signature · 1 line
1.8.3.3.2.g85103ba
Re: [PATCH 2/2] howto: Eliminate all tabs
Documentation/howto/rebase-from-internal-branch.txt line 1
Quoted 9 lines · Dirk Wallenstein
Documentation/howto/rebase-from-internal-branch.txt +1
-3@@ -1,8 +1,8 @@ -From: Junio C Hamano <[email protected]> -To: [email protected] -Cc: Petr Baudis <[email protected]>, Linus Torvalds <[email protected]> +From:Junio C Hamano <[email protected]>
Why does this patch have to break the e-mail headers like this?
These are copies of old e-mails; keep them as close to the original as they were.
Besides, the tab width of our source is 8, period. Get over it.
Re: [PATCH 2/2] howto: Eliminate all tabs
Junio C Hamano <[email protected]> wrote (Wed, Jul 31, 2013 at 10:03:15AM -0700):
Quoted 14 lines
Documentation/howto/rebase-from-internal-branch.txt line 1
Quoted 9 lines · Dirk Wallenstein
Documentation/howto/rebase-from-internal-branch.txt +1
-3@@ -1,8 +1,8 @@ -From: Junio C Hamano <[email protected]> -To: [email protected] -Cc: Petr Baudis <[email protected]>, Linus Torvalds <[email protected]> +From:Junio C Hamano <[email protected]>Why does this patch have to break the e-mail headers like this?
Quoted 5 lines
These are copies of old e-mails; keep them as close to the original as they were.
Besides, the tab width of our source is 8, period. Get over it.
I will try. It just doesn't make sense to me at all.
Signature · 1 line
Dirk
Re: [PATCH 2/2] howto: Eliminate all tabs
In reply to Junio C HamanoQuoted 1 line · Junio C Hamano
Besides, the tab width of our source is 8, period. Get over it.
Isn't the howto documentation intended (mainly/also) for the users of git, not the developers?
Signature · 1 line
Piotr Krukowiecki
A message that is not in the archive (sent off-list or not yet received): CAA01CsqW1FWm8ExK7hypHp1_Jm0-kc1REQeuPYjbzU=aUQ+L9g@mail.gmail.com
Re: [PATCH 2/2] howto: Eliminate all tabs
Quoted 2 lines · Piotr Krukowiecki
Isn't the howto documentation intended (mainly/also) for the users of git, not the developers?
And they have *.html version for that exact version, no?
We used not to bother running asciidoc to Documentation/howto, so the *.txt versions had to be exposed to the end users because there was no other variant. That is no longer true, and *.txt versions are sources.