Re: [PATCHv5/RFC 1/6] Documentation: Preparation for gitweb manpages

From: Junio C Hamano <gitster@pobox.com>
Date: Oct 10, 2011, 18:53 UTC
Message-ID: <7vwrcck1jm.fsf@alter.siamese.dyndns.org>
In-Reply-To: <1318098723-12813-2-git-send-email-jnareb@gmail.com>

Jakub Narebski <jnareb@gmail.com> writes:

> This patch adds infrastructure for easy generation of only
> gitweb-related manpages.  It adds a currently empty 'gitweb-doc'
> target to Documentation/Makefile, and a 'doc' proxy target to
> gitweb/Makefile.

I tend to agree with your after-three-dash comment that this separation is not necessary, it may be expedient while working on the series, but wants to be removed once the series is complete.

Show 11 quoted lines

> This way to build only gitweb documentation in both 'man' and 'html'
> formats one can use
>
>   make -C gitweb doc
>
> or
>
>   cd gitweb; make doc
>
> This somewhat follows the idea of 'full-svn-test' and 'gitweb-test' in
> t/Makefile.

It seems that this follows the idea backward in that the existing practice fo full-svn-test (and valgrind test) is to allow _excluding_ stuff that the user may not care about or the user cannot afford to run; in that sense 'gitweb-test' target is also backwards.

Show 58 quoted lines

> gitweb manpages would reside in the gitweb/ directory, "make doc"
> would invoke "make -C gitweb doc" to generate formatted docs.
>
> The gitweb.conf(5) and gitweb(1) manpages will be added in subsequent
> commits.
>
> [Commit message improved with help of Jonathan Nieder]
>
> Signed-off-by: Jakub Narebski <jnareb@gmail.com>
> ---
> This commit is not strictly necessary: it only adds "doc" target to
> gitweb/Makefile, and "gitweb-doc" target to Documentation/Makefile;
> neither is run when e.g. generating RPM.
>
> They are here because they would be here if documentation source was
> kept along with gitweb script in the 'gitweb/' subdirectory, and to
> make it easier and faster to test the changes.
>
>  Documentation/Makefile |    3 +++
>  gitweb/Makefile        |    7 ++++++-
>  2 files changed, 9 insertions(+), 1 deletions(-)
>
> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 6346a75..44be67b 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -170,6 +170,9 @@ info: git.info gitman.info
>  
>  pdf: user-manual.pdf
>  
> +GITWEB_DOC = $(filter gitweb.%,$(DOC_HTML) $(DOC_MAN1) $(DOC_MAN5) $(DOC_MAN7))
> +gitweb-doc: $(GITWEB_DOC)
> +
>  install: install-man
>  
>  install-man: man
> diff --git a/gitweb/Makefile b/gitweb/Makefile
> index 1c85b5f..3014d80 100644
> --- a/gitweb/Makefile
> +++ b/gitweb/Makefile
> @@ -174,6 +174,11 @@ test-installed:
>  	GITWEB_TEST_INSTALLED='$(DESTDIR_SQ)$(gitwebdir_SQ)' \
>  		$(MAKE) -C ../t gitweb-test
>  
> +### Documentation
> +
> +doc:
> +	$(MAKE) -C ../Documentation gitweb-doc
> +
>  ### Installation rules
>  
>  install: all
> @@ -187,5 +192,5 @@ install: all
>  clean:
>  	$(RM) gitweb.cgi static/gitweb.min.js static/gitweb.min.css GITWEB-BUILD-OPTIONS
>  
> -.PHONY: all clean install test test-installed .FORCE-GIT-VERSION-FILE FORCE
> +.PHONY: all clean install test test-installed doc .FORCE-GIT-VERSION-FILE FORCE