Re: [PATCH/RFCv4 1/4] Documentation: Preparation for gitweb manpages
- From
Jakub Narebski <jnareb@gmail.com>
- Date
- Sep 20, 2011, 20:11 UTC
- Message-ID
- <201109202211.06899.jnareb@gmail.com>
- In-Reply-To
- <20110919233703.GF6343@elie>
Thanks again for all language fixes. English is my secondary language...
Jonathan Nieder wrote:
> Jakub Narebski wrote:
Show 7 quoted lines
> > 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? [...]
[...]
Show 12 quoted lines
> > 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 <jnareb@gmail.com> 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 <jnareb@gmail.com> --- 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