Skip to content

Commit 98509d0

Browse files
committed
Merge branch 'jk/diff-rendered-docs'
Dev doc update. * jk/diff-rendered-docs: Revert "doc/Makefile: drop doc-diff worktree and temporary files on "make clean"" doc/Makefile: drop doc-diff worktree and temporary files on "make clean" doc-diff: add --clean mode to remove temporary working gunk doc-diff: fix non-portable 'man' invocation doc-diff: always use oids inside worktree SubmittingPatches: mention doc-diff
2 parents 07703ae + 6b6547b commit 98509d0

File tree

2 files changed

+32
-9
lines changed

2 files changed

+32
-9
lines changed

Documentation/SubmittingPatches

Lines changed: 3 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,9 @@ GitHub-Travis CI hints section for details.
8080

8181
Do not forget to update the documentation to describe the updated
8282
behavior and make sure that the resulting documentation set formats
83-
well. It is currently a liberal mixture of US and UK English norms for
83+
well (try the Documentation/doc-diff script).
84+
85+
We currently have a liberal mixture of US and UK English norms for
8486
spelling and grammar, which is somewhat unfortunate. A huge patch that
8587
touches the files all over the place only to correct the inconsistency
8688
is not welcome, though. Potential clashes with other changes that can

Documentation/doc-diff

Lines changed: 29 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,21 +1,34 @@
11
#!/bin/sh
2+
#
3+
# Build two documentation trees and diff the resulting formatted output.
4+
# Compared to a source diff, this can reveal mistakes in the formatting.
5+
# For example:
6+
#
7+
# ./doc-diff origin/master HEAD
8+
#
9+
# would show the differences introduced by a branch based on master.
210

311
OPTIONS_SPEC="\
412
doc-diff [options] <from> <to> [-- <diff-options>]
13+
doc-diff (-c|--clean)
514
--
615
j=n parallel argument to pass to make
716
f force rebuild; do not rely on cached results
17+
c,clean cleanup temporary working files
818
"
919
SUBDIRECTORY_OK=1
1020
. "$(git --exec-path)/git-sh-setup"
1121

1222
parallel=
1323
force=
24+
clean=
1425
while test $# -gt 0
1526
do
1627
case "$1" in
1728
-j)
1829
parallel=$2; shift ;;
30+
-c|--clean)
31+
clean=t ;;
1932
-f)
2033
force=t ;;
2134
--)
@@ -26,6 +39,17 @@ do
2639
shift
2740
done
2841

42+
cd_to_toplevel
43+
tmp=Documentation/tmp-doc-diff
44+
45+
if test -n "$clean"
46+
then
47+
test $# -eq 0 || usage
48+
git worktree remove --force "$tmp/worktree" 2>/dev/null
49+
rm -rf "$tmp"
50+
exit 0
51+
fi
52+
2953
if test -z "$parallel"
3054
then
3155
parallel=$(getconf _NPROCESSORS_ONLN 2>/dev/null)
@@ -42,9 +66,6 @@ to=$1; shift
4266
from_oid=$(git rev-parse --verify "$from") || exit 1
4367
to_oid=$(git rev-parse --verify "$to") || exit 1
4468

45-
cd_to_toplevel
46-
tmp=Documentation/tmp-doc-diff
47-
4869
if test -n "$force"
4970
then
5071
rm -rf "$tmp"
@@ -69,12 +90,12 @@ generate_render_makefile () {
6990
printf '%s: %s\n' "$dst" "$src"
7091
printf '\t@echo >&2 " RENDER $(notdir $@)" && \\\n'
7192
printf '\tmkdir -p $(dir $@) && \\\n'
72-
printf '\tMANWIDTH=80 man -l $< >$@+ && \\\n'
93+
printf '\tMANWIDTH=80 man $< >$@+ && \\\n'
7394
printf '\tmv $@+ $@\n'
7495
done
7596
}
7697

77-
# render_tree <dirname> <committish>
98+
# render_tree <committish_oid>
7899
render_tree () {
79100
# Skip install-man entirely if we already have an installed directory.
80101
# We can't rely on make here, since "install-man" unconditionally
@@ -84,7 +105,7 @@ render_tree () {
84105
# through.
85106
if ! test -d "$tmp/installed/$1"
86107
then
87-
git -C "$tmp/worktree" checkout "$2" &&
108+
git -C "$tmp/worktree" checkout --detach "$1" &&
88109
make -j$parallel -C "$tmp/worktree" \
89110
GIT_VERSION=omitted \
90111
SOURCE_DATE_EPOCH=0 \
@@ -104,6 +125,6 @@ render_tree () {
104125
fi
105126
}
106127

107-
render_tree $from_oid "$from" &&
108-
render_tree $to_oid "$to" &&
128+
render_tree $from_oid &&
129+
render_tree $to_oid &&
109130
git -C $tmp/rendered diff --no-index "$@" $from_oid $to_oid

0 commit comments

Comments
 (0)