Skip to content

Commit df8baa4

Browse files
jonasJunio C Hamano
jonas
authored and
Junio C Hamano
committed
[PATCH] Random documentation fixes
The fixes focuses on improving the HTML output. Most noteworthy: - Fix the Makefile to also make various *.html files depend on included files. - Consistently use 'NOTE: ...' instead of '[ ... ]' for additional info. - Fix ending '::' for description lists in OPTION section etc. - Fix paragraphs in description lists ending up as preformated text. - Always use listingblocks (preformatted text wrapped in lines with -----) for examples that span empty lines, so they are put in only one HTML block. - Use '1.' instead of '(1)' for numbered lists. - Fix linking to other GIT docs. - git-rev-list.txt: put option descriptions in an OPTION section. Signed-off-by: Jonas Fonseca <fonseca@diku.dk> Signed-off-by: Junio C Hamano <junkio@cox.net>
1 parent 5a82b4f commit df8baa4

26 files changed

+209
-192
lines changed

‎Documentation/Makefile‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,9 @@ install: man
5353
$(patsubst %.txt,%.1,$(wildcard git-diff-*.txt)): \
5454
diff-format.txt diff-options.txt
5555
$(patsubst %,%.1,git-fetch git-pull git-push): pull-fetch-param.txt
56+
$(patsubst %.txt,%.html,$(wildcard git-diff-*.txt)): \
57+
diff-format.txt diff-options.txt
58+
$(patsubst %,%.html,git-fetch git-pull git-push): pull-fetch-param.txt
5659
git.7: ../README
5760

5861
clean:

‎Documentation/cvs-migration.txt‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -229,10 +229,10 @@ does rename or copy would not show in the output, and if the
229229
"o-file.c", it would find the commit that changed the statement
230230
when it was in "o-file.c".
231231

232-
[ BTW, the current versions of "git-diff-tree -C" is not eager
232+
NOTE: The current versions of "git-diff-tree -C" is not eager
233233
enough to find copies, and it will miss the fact that a-file.c
234234
was created by copying o-file.c unless o-file.c was somehow
235-
changed in the same commit.]
235+
changed in the same commit.
236236

237237
You can use the --pickaxe-all flag in addition to the -S flag.
238238
This causes the differences from all the files contained in
@@ -243,6 +243,6 @@ that contain this changed "if" statement:
243243
nitfol();
244244
}' --pickaxe-all
245245

246-
[ Side note. This option is called "--pickaxe-all" because -S
246+
NOTE: This option is called "--pickaxe-all" because -S
247247
option is internally called "pickaxe", a tool for software
248-
archaeologists.]
248+
archaeologists.

‎Documentation/diffcore.txt‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -254,11 +254,11 @@ As an example, typical orderfile for the core GIT probably
254254
would look like this:
255255

256256
------------------------------------------------
257-
README
258-
Makefile
259-
Documentation
260-
*.h
261-
*.c
262-
t
257+
README
258+
Makefile
259+
Documentation
260+
*.h
261+
*.c
262+
t
263263
------------------------------------------------
264264

‎Documentation/git-applypatch.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -30,7 +30,7 @@ OPTIONS
3030
<patch>::
3131
The patch to apply.
3232

33-
<info>:
33+
<info>::
3434
Author and subject information extracted from e-mail,
3535
used on "author" line and as the first line of the
3636
commit log message.

‎Documentation/git-bisect.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -91,7 +91,7 @@ Author
9191
Written by Linus Torvalds <torvalds@osdl.org>
9292

9393
Documentation
94-
--------------
94+
-------------
9595
Documentation by Junio C Hamano and the git-list <git@vger.kernel.org>.
9696

9797
GIT

‎Documentation/git-cherry-pick.txt‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -38,9 +38,9 @@ OPTIONS
3838
option is used, your working tree does not have to match
3939
the HEAD commit. The cherry-pick is done against the
4040
beginning state of your working tree.
41-
42-
This is useful when cherry-picking more than one commits'
43-
effect to your working tree in a row.
41+
+
42+
This is useful when cherry-picking more than one commits'
43+
effect to your working tree in a row.
4444

4545

4646
Author

‎Documentation/git-commit-tree.txt‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -58,11 +58,11 @@ following environment variables.
5858
GIT_COMMITTER_NAME
5959
GIT_COMMITTER_EMAIL
6060

61-
(nb <,> and '\n's are stripped)
61+
(nb "<", ">" and "\n"s are stripped)
6262

6363
A commit comment is read from stdin (max 999 chars). If a changelog
64-
entry is not provided via '<' redirection, "git-commit-tree" will just wait
65-
for one to be entered and terminated with ^D
64+
entry is not provided via "<" redirection, "git-commit-tree" will just wait
65+
for one to be entered and terminated with ^D.
6666

6767
Diagnostics
6868
-----------

‎Documentation/git-cvsimport.txt‎

Lines changed: 5 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -51,15 +51,15 @@ OPTIONS
5151
The 'HEAD' branch from CVS is imported to the 'origin' branch within
5252
the git repository, as 'HEAD' already has a special meaning for git.
5353
Use this option if you want to import into a different branch.
54-
55-
Use '-o master' for continuing an import that was initially done by
56-
the old cvs2git tool.
54+
+
55+
Use '-o master' for continuing an import that was initially done by
56+
the old cvs2git tool.
5757

5858
-p <options-for-cvsps>::
5959
Additional options for cvsps.
6060
The options '-u' and '-A' are implicit and should not be used here.
61-
62-
If you need to pass multiple options, separate them with a comma.
61+
+
62+
If you need to pass multiple options, separate them with a comma.
6363

6464
-m::
6565
Attempt to detect merges based on the commit message. This option

‎Documentation/git-diff-index.txt‎

Lines changed: 4 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -86,8 +86,8 @@ the more useful of the two in that what it does can't be emulated with
8686
a "git-write-tree" + "git-diff-tree". Thus that's the default mode.
8787
The non-cached version asks the question:
8888

89-
show me the differences between HEAD and the currently checked out
90-
tree - index contents _and_ files that aren't up-to-date
89+
show me the differences between HEAD and the currently checked out
90+
tree - index contents _and_ files that aren't up-to-date
9191

9292
which is obviously a very useful question too, since that tells you what
9393
you *could* commit. Again, the output matches the "git-diff-tree -r"
@@ -107,13 +107,13 @@ not up-to-date and may contain new stuff. The all-zero sha1 means that to
107107
get the real diff, you need to look at the object in the working directory
108108
directly rather than do an object-to-object diff.
109109

110-
NOTE! As with other commands of this type, "git-diff-index" does not
110+
NOTE: As with other commands of this type, "git-diff-index" does not
111111
actually look at the contents of the file at all. So maybe
112112
`kernel/sched.c` hasn't actually changed, and it's just that you
113113
touched it. In either case, it's a note that you need to
114114
"git-upate-cache" it to make the cache be in sync.
115115

116-
NOTE 2! You can have a mixture of files show up as "has been updated"
116+
NOTE: You can have a mixture of files show up as "has been updated"
117117
and "is still dirty in the working directory" together. You can always
118118
tell which file is in which state, since the "has been updated" ones
119119
show a valid sha1, and the "not in sync with the index" ones will

‎Documentation/git-diff-tree.txt‎

Lines changed: 12 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -101,16 +101,18 @@ An example of normal usage is:
101101
which tells you that the last commit changed just one file (it's from
102102
this one:
103103

104-
commit 3c6f7ca19ad4043e9e72fa94106f352897e651a8
105-
tree 5319e4d609cdd282069cc4dce33c1db559539b03
106-
parent b4e628ea30d5ab3606119d2ea5caeab141d38df7
107-
author Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005
108-
committer Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005
109-
110-
Make "git-fsck-objects" print out all the root commits it finds.
111-
112-
Once I do the reference tracking, I'll also make it print out all the
113-
HEAD commits it finds, which is even more interesting.
104+
-----------------------------------------------------------------------------
105+
commit 3c6f7ca19ad4043e9e72fa94106f352897e651a8
106+
tree 5319e4d609cdd282069cc4dce33c1db559539b03
107+
parent b4e628ea30d5ab3606119d2ea5caeab141d38df7
108+
author Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005
109+
committer Linus Torvalds <torvalds@ppc970.osdl.org> Sat Apr 9 12:02:30 2005
110+
111+
Make "git-fsck-objects" print out all the root commits it finds.
112+
113+
Once I do the reference tracking, I'll also make it print out all the
114+
HEAD commits it finds, which is even more interesting.
115+
-----------------------------------------------------------------------------
114116

115117
in case you care).
116118

0 commit comments

Comments
 (0)