From: Jonathan Nieder <jrnieder@gmail.com>
To: Jakub Narebski <jnareb@gmail.com>
Cc: git@vger.kernel.org, Drew Northup <drew.northup@maine.edu>,
John 'Warthog9' Hawley <warthog9@kernel.org>,
admin@repo.or.cz
Subject: Re: [PATCH/RFCv4 1/4] Documentation: Preparation for gitweb manpages
Date: Mon, 19 Sep 2011 18:37:03 -0500 [thread overview]
Message-ID: <20110919233703.GF6343@elie> (raw)
In-Reply-To: <1316352884-26193-2-git-send-email-jnareb@gmail.com>
Jakub Narebski wrote:
> Gitweb documentation currently consist of gitweb/README, gitweb/INSTALL
> and comments in gitweb source code. This is harder to find, use and
> browse that manpages ("man gitweb" or "git help gitweb") and HTML
> documentation ("git help --web gitweb").
Language nits: s/consist/consists/; s/that manpages/than manpages/. I
completely agree.
> 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? Wording nits: s/and move
information/and to move information/; s/drectly/directly/; s/ there//.
> The idea is to have gitweb manpage sources reside in AsciiDoc format
> in Documentation/ directory, like for gitk and git-gui. Alternate
> solution would be to have gitweb documentation in gitweb/ directory,
> perhaps in POD format (see perlpod(1)).
Language nits: missing "the" before "Documentation/ directory" and
"gitweb manpage sources"; missing "An" before "Alternate solution".
I guess this is the most controversial aspect of the patch; your idea
seems sane enough to me.
> This patch adds infrastructure for easy generating gitweb-related
> manpages. It adds currently empty 'gitweb-doc' target to
> Documentation/Makefile, and 'doc' proxy target to gitweb's Makefile.
Language nits: s/easy/easily/; missing "a" before "currently empty
'gitweb-doc' target" and "'doc' proxy target".
> 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)?
[...]
> --- 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)
Looks like no, alas.
Except for that detail, this looks good.
Thanks,
Jonathan
next prev parent reply other threads:[~2011-09-19 23:37 UTC|newest]
Thread overview: 12+ messages / expand[flat|nested] mbox.gz Atom feed top
2011-09-18 13:34 [PATCH/RFCv4 0/4] Moving gitweb documentation to manpages Jakub Narebski
2011-09-18 13:34 ` [PATCH/RFCv4 1/4] Documentation: Preparation for gitweb manpages Jakub Narebski
2011-09-19 23:37 ` Jonathan Nieder [this message]
2011-09-20 0:10 ` Jakub Narebski
2011-09-20 20:11 ` Jakub Narebski
2011-09-20 20:19 ` Jonathan Nieder
2011-09-20 20:33 ` Jakub Narebski
2011-09-18 13:34 ` [PATCH/RFCv4 2/4] gitweb: Add manpage for /etc/gitweb.conf (for gitweb documentation) Jakub Narebski
2011-09-20 4:41 ` Jonathan Nieder
2011-09-22 13:41 ` Jakub Narebski
2011-09-18 13:34 ` [PATCH/RFCv4 3/4] gitweb: Add manpage for gitweb Jakub Narebski
2011-09-18 13:34 ` [PATCH/RFCv4 4/4] gitweb: Add gitweb manpages to 'gitweb' package in git.spec Jakub Narebski
Reply instructions:
You may reply publicly to this message via plain-text email
using any one of the following methods:
* Save the following mbox file, import it into your mail client,
and reply-to-all from there: mbox
Avoid top-posting and favor interleaved quoting:
https://en.wikipedia.org/wiki/Posting_style#Interleaved_style
* Reply using the --to, --cc, and --in-reply-to
switches of git-send-email(1):
git send-email \
--in-reply-to=20110919233703.GF6343@elie \
--to=jrnieder@gmail.com \
--cc=admin@repo.or.cz \
--cc=drew.northup@maine.edu \
--cc=git@vger.kernel.org \
--cc=jnareb@gmail.com \
--cc=warthog9@kernel.org \
/path/to/YOUR_REPLY
https://kernel.org/pub/software/scm/git/docs/git-send-email.html
* If your mail client supports setting the In-Reply-To header
via mailto: links, try the mailto: link
Be sure your reply has a Subject: header at the top and a blank line
before the message body.
This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox;
as well as URLs for NNTP newsgroup(s).