Merge branch 'jc/doc-lint'

Find common mistakes when writing gitlink: in our documentation and
drive the check from "make check-docs".

I am not entirely happy with the way the script chooses what input
file to validate, but it is not worse than not having anything, so
let's move it forward and have the logic improved later when people
care about it deeply.

* jc/doc-lint:
ci: validate "linkgit:" in documentation

diff --combined Makefile
index bc3d41ebf34ec0deec8576757491d663afe22ca6,61bd0abad5e88ceee8e5b6a1814291fa0a0b3ea4..0d59718bf72a8f033f2d2a5be7d260b52039408e
--- 1/Makefile
--- 2/Makefile
+++ b/Makefile
@@@ -355,6 -355,9 +355,6 @@@ all:
  #
  # Define HAVE_CLOCK_MONOTONIC if your platform has CLOCK_MONOTONIC in librt.
  #
 -# Define NO_HMAC_CTX_CLEANUP if your OpenSSL is version 0.9.6b or earlier to
 -# cleanup the HMAC context with the older HMAC_cleanup function.
 -#
  # Define USE_PARENS_AROUND_GETTEXT_N to "yes" if your compiler happily
  # compiles the following initialization:
  #
@@@ -440,6 -443,7 +440,6 @@@ DIFF = dif
  TAR = tar
  FIND = find
  INSTALL = install
 -RPMBUILD = rpmbuild
  TCL_PATH = tclsh
  TCLTK_PATH = wish
  XGETTEXT = xgettext
@@@ -620,7 -624,7 +620,7 @@@ TEST_PROGRAMS_NEED_X += test-svn-f
  TEST_PROGRAMS_NEED_X += test-urlmatch-normalization
  TEST_PROGRAMS_NEED_X += test-wildmatch
  
 -TEST_PROGRAMS = $(patsubst %,%$X,$(TEST_PROGRAMS_NEED_X))
 +TEST_PROGRAMS = $(patsubst %,t/helper/%$X,$(TEST_PROGRAMS_NEED_X))
  
  # List built-in command $C whose implementation cmd_$C() is not in
  # builtin/$C.o but is linked in as part of some other command.
@@@ -1134,6 -1138,9 +1134,6 @@@ ifndef NO_OPENSS
        ifdef NEEDS_CRYPTO_WITH_SSL
                OPENSSL_LIBSSL += -lcrypto
        endif
 -      ifdef NO_HMAC_CTX_CLEANUP
 -              BASIC_CFLAGS += -DNO_HMAC_CTX_CLEANUP
 -      endif
  else
        BASIC_CFLAGS += -DNO_OPENSSL
        BLK_SHA1 = 1
@@@ -1897,7 -1904,7 +1897,7 @@@ VCSSVN_OBJS += vcs-svn/fast_export.
  VCSSVN_OBJS += vcs-svn/svndiff.o
  VCSSVN_OBJS += vcs-svn/svndump.o
  
 -TEST_OBJS := $(patsubst test-%$X,test-%.o,$(TEST_PROGRAMS))
 +TEST_OBJS := $(patsubst %$X,%.o,$(TEST_PROGRAMS))
  OBJECTS := $(LIB_OBJS) $(BUILTIN_OBJS) $(PROGRAM_OBJS) $(TEST_OBJS) \
        $(XDIFF_OBJS) \
        $(VCSSVN_OBJS) \
@@@ -2062,7 -2069,7 +2062,7 @@@ XGETTEXT_FLAGS_SH = $(XGETTEXT_FLAGS) -
        --keyword=gettextln --keyword=eval_gettextln
  XGETTEXT_FLAGS_PERL = $(XGETTEXT_FLAGS) --keyword=__ --language=Perl
  LOCALIZED_C = $(C_OBJ:o=c) $(LIB_H) $(GENERATED_H)
 -LOCALIZED_SH = $(SCRIPT_SH)
 +LOCALIZED_SH = $(SCRIPT_SH) git-parse-remote.sh
  LOCALIZED_PERL = $(SCRIPT_PERL)
  
  ifdef XGETTEXT_INCLUDE_TESTS
@@@ -2204,7 -2211,7 +2204,7 @@@ bin-wrappers/%: wrap-for-bin.s
        @mkdir -p bin-wrappers
        $(QUIET_GEN)sed -e '1s|#!.*/sh|#!$(SHELL_PATH_SQ)|' \
             -e 's|@@BUILD_DIR@@|$(shell pwd)|' \
 -           -e 's|@@PROG@@|$(@F)|' < $< > $@ && \
 +           -e 's|@@PROG@@|$(patsubst test-%,t/helper/test-%,$(@F))|' < $< > $@ && \
        chmod +x $@
  
  # GNU make supports exporting all variables by "export" without parameters.
@@@ -2224,25 -2231,25 +2224,25 @@@ perf: al
  
  .PHONY: test perf
  
 -test-ctype$X: ctype.o
 +t/helper/test-ctype$X: ctype.o
  
 -test-date$X: date.o ctype.o
 +t/helper/test-date$X: date.o ctype.o
  
 -test-delta$X: diff-delta.o patch-delta.o
 +t/helper/test-delta$X: diff-delta.o patch-delta.o
  
 -test-line-buffer$X: vcs-svn/lib.a
 +t/helper/test-line-buffer$X: vcs-svn/lib.a
  
 -test-parse-options$X: parse-options.o parse-options-cb.o
 +t/helper/test-parse-options$X: parse-options.o parse-options-cb.o
  
 -test-svn-fe$X: vcs-svn/lib.a
 +t/helper/test-svn-fe$X: vcs-svn/lib.a
  
  .PRECIOUS: $(TEST_OBJS)
  
 -test-%$X: test-%.o GIT-LDFLAGS $(GITLIBS)
 +t/helper/test-%$X: t/helper/test-%.o GIT-LDFLAGS $(GITLIBS)
        $(QUIET_LINK)$(CC) $(ALL_CFLAGS) -o $@ $(ALL_LDFLAGS) $(filter %.o,$^) $(filter %.a,$^) $(LIBS)
  
 -check-sha1:: test-sha1$X
 -      ./test-sha1.sh
 +check-sha1:: t/helper/test-sha1$X
 +      t/helper/test-sha1.sh
  
  SP_OBJ = $(patsubst %.o,%.sp,$(C_OBJ))
  
@@@ -2256,10 -2263,10 +2256,10 @@@ sparse: $(SP_OBJ
  check: common-cmds.h
        @if sparse; \
        then \
 -              echo 2>&1 "Use 'make sparse' instead"; \
 +              echo >&2 "Use 'make sparse' instead"; \
                $(MAKE) --no-print-directory sparse; \
        else \
 -              echo 2>&1 "Did you mean 'make test'?"; \
 +              echo >&2 "Did you mean 'make test'?"; \
                exit 1; \
        fi
  
@@@ -2389,25 -2396,31 +2389,25 @@@ quick-install-html
  
  ### Maintainer's dist rules
  
 -git.spec: git.spec.in GIT-VERSION-FILE
 -      sed -e 's/@@VERSION@@/$(GIT_VERSION)/g' < $< > $@+
 -      mv $@+ $@
 -
  GIT_TARNAME = git-$(GIT_VERSION)
 -dist: git.spec git-archive$(X) configure
 +dist: git-archive$(X) configure
        ./git-archive --format=tar \
                --prefix=$(GIT_TARNAME)/ HEAD^{tree} > $(GIT_TARNAME).tar
        @mkdir -p $(GIT_TARNAME)
 -      @cp git.spec configure $(GIT_TARNAME)
 +      @cp configure $(GIT_TARNAME)
        @echo $(GIT_VERSION) > $(GIT_TARNAME)/version
        @$(MAKE) -C git-gui TARDIR=../$(GIT_TARNAME)/git-gui dist-version
        $(TAR) rf $(GIT_TARNAME).tar \
 -              $(GIT_TARNAME)/git.spec \
                $(GIT_TARNAME)/configure \
                $(GIT_TARNAME)/version \
                $(GIT_TARNAME)/git-gui/version
        @$(RM) -r $(GIT_TARNAME)
        gzip -f -9 $(GIT_TARNAME).tar
  
 -rpm: dist
 -      $(RPMBUILD) \
 -              --define "_source_filedigest_algorithm md5" \
 -              --define "_binary_filedigest_algorithm md5" \
 -              -ta $(GIT_TARNAME).tar.gz
 +rpm::
 +      @echo >&2 "Use distro packaged sources to run rpmbuild"
 +      @false
 +.PHONY: rpm
  
  htmldocs = git-htmldocs-$(GIT_VERSION)
  manpages = git-manpages-$(GIT_VERSION)
@@@ -2443,8 -2456,8 +2443,8 @@@ profile-clean
        $(RM) $(addsuffix *.gcno,$(addprefix $(PROFILE_DIR)/, $(object_dirs)))
  
  clean: profile-clean coverage-clean
 -      $(RM) *.o *.res refs/*.o block-sha1/*.o ppc/*.o compat/*.o compat/*/*.o
 -      $(RM) xdiff/*.o vcs-svn/*.o ewah/*.o builtin/*.o
 +      $(RM) *.res
 +      $(RM) $(OBJECTS)
        $(RM) $(LIB_FILE) $(XDIFF_LIB) $(VCSSVN_LIB)
        $(RM) $(ALL_PROGRAMS) $(SCRIPT_LIB) $(BUILT_INS) git$X
        $(RM) $(TEST_PROGRAMS) $(NO_INSTALL)
@@@ -2483,6 -2496,7 +2483,7 @@@ ALL_COMMANDS += git-gui git-citoo
  
  .PHONY: check-docs
  check-docs::
+       $(MAKE) -C Documentation lint-docs
        @(for v in $(ALL_COMMANDS); \
        do \
                case "$$v" in \