Subject: Re: [PATCH/RFCv4 1/4] Documentation: Preparation for gitweb manpages

From: Jakub Narebski <[email-masked]>
Date: Tue, 20 Sep 2011 22:11:05 +0200

Thanks again for all language fixes.  English is my secondary language...

Jonathan Nieder wrote:
> Jakub Narebski wrote:

> > The goal is to move documentation out of gitweb/README to gitweb.txt and
> > gitweb.conf.txt manpages, reducing its size 10x from around 500 to
> > around 50 lines (two pages), and move information not related drectly to
> > building and installing gitweb out of gitweb/INSTALL there.
> 
> I guess you mean this patch prepares for or is part of a larger
> project or series with that goal? [...]

[...]
> > This way to build gitweb documentation one can use
> >
> >   make -C gitweb doc
> >
> > or
> >
> >   cd gitweb; make doc
> 
> Language nit: a comma after "This way" would disambiguate.
> 
> Does "make -CDocumentation man html" build the gitweb documentation,
> too (and "make install-doc" install it)?

Jonathan Nieder wrote:

>                                         Maybe its commit message could
> be clarified to mention that the new targets build a subset of the pages
> built by the ordinary "make doc" et al targets.

I hope that this version is more clear:

-- >8 --
From: Jakub Narebski <[email-masked]>
Subject: [PATCH/RFCv5 1/4] Documentation: Preparation for gitweb manpages

Gitweb documentation currently consists of gitweb/README, gitweb/INSTALL
and comments in gitweb source code.  This is harder to find, use and
browse than manpages ("man gitweb" or "git help gitweb") and HTML
documentation ("git help --web gitweb").

The goal of the next two commits is to move documentation out of
gitweb/README to gitweb.txt and gitweb.conf.txt manpages, reducing its
size 10x from around 500 to around 50 lines (two pages), and to move
information not related directly to building and installing gitweb out
of gitweb/INSTALL.

The idea is to have the gitweb manpage sources reside in AsciiDoc
format in the Documentation/ directory, like for gitk and git-gui.
This means that building git documentation (with "make doc") would
also build gitweb manpages.

An alternate solution would be to have gitweb documentation in the
gitweb/ directory, perhaps in POD format (see perlpod(1)).

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.

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.  Note also that with alternate solution, where source of
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.

Signed-off-by: Jakub Narebski <[email-masked]>
---
 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
 
-- 
1.7.6