[RFE] install-doc-quick.sh should accept a commit-ish

[RFE] install-doc-quick.sh should accept a commit-ish

[Randall S. Becker]

Other thread attached as context.

Having the git-manpages repo available is fantastic for platforms that cannot easily build documentation on demand, for example, when too many dependencies that do not build properly. 

It would be really nice to have a version of install-doc-quick.sh to either:

1. Use whatever version is checked out in git-manpages; or

2. Use the proper commit associated with the git commit being installed (0a8e923 for v2.6.0 , as an example); or

3. Allow the commit to be passed through the Documentation Makefile on demand so that any version of documentation can be installed.

Thanks,
Randall
P.S. If the idea is liked, I can try to make this happen.

-----Original Message-----
From: git-owner@vger.kernel.org [mailto:git-owner@vger.kernel.org] On Behalf Of Randall S. Becker
Sent: December 6, 2017 10:43 AM
To: 'Jeff King' <peff@peff.net>; 'Ævar Arnfjörð Bjarmason' <avarab@gmail.com>; 'Junio C Hamano' <gitster@pobox.com>
Cc: git@vger.kernel.org
Subject: RE: Documentation Breakage at 2.5.6

-----Original Message-----
On December 6, 2017 3:49 AM, Jeff King wrote:
>On Wed, Dec 06, 2017 at 09:14:57AM +0100, Ævar Arnfjörð Bjarmason wrote:
>> > I'm trying to upgrade the NonStop port from 2.3.7 upward eventually 
>> > to
>> > 2.15.1 and hit a snag on documentation. The xmlto component is a 
>> > bit new to me and I hit the following error:
>Did it work before in v2.3.7? If so, can you bisect to the breakage?
It worked fine at 2.3.7. No seeming dependency on docbook at that point - it was never on my system.

>One alternative is to try to avoid docbook entirely. The only way to get manpages with asciidoc is to generate docbook and then process it, but:
I have asciidoc installed, but using it via Make?

> - you can generate HTML directly (and "make -C Documentation html" 
> does  this). Perhaps not as nice, but you still at least have some
>   documentation.
Not an option. I need git help to work.

> - asciidoctor can generate manpages directly. I don't think our
>   Makefile supports that now, but it might not be too hard to hack in  
> (we already have some basic asciidoctor support). I'm not sure how
 > hard it would be to get Ruby running on NonStop Ruby runs fine. I'm a bit out of my configuration depth here.

>And of course one final option is to generate the manpages elsewhere and copy them in, since they're platform-independent.
>In fact, that's what quick-install-man should do (you just have to clone Junio's >git-manpages repository -- see the INSTALL file).

I've gone down this path and it works. Much cleaner in fact. Dependencies of docbook (jade) are too reliant on GCC C++ forms to port to the platform - not to mention being SVN, which is culturally uncomfortable 😉

One request to Junio: Would it be possible to tag the commits to align with the tags in the main repo? That way, I can build a nice little Jenkins job to automatically fetch the correct commit for man pages when packaging up a release.

-Peff

Re: [RFE] install-doc-quick.sh should accept a commit-ish

[Junio C Hamano]

"Randall S. Becker" <rsbecker@nexbridge.com> writes:

> Having the git-manpages repo available is fantastic for platforms
> that cannot easily build documentation on demand, for example,
> when too many dependencies that do not build properly.
>
> It would be really nice to have a version of install-doc-quick.sh to either:
>
> 1. Use whatever version is checked out in git-manpages; or
>
> 2. Use the proper commit associated with the git commit being installed (0a8e923 for v2.6.0 , as an example); or
>
> 3. Allow the commit to be passed through the Documentation Makefile on demand so that any version of documentation can be installed.

Do you mean something like this so that you can say "not the tip of
the master branch but this one?"

 Documentation/install-doc-quick.sh | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/Documentation/install-doc-quick.sh b/Documentation/install-doc-quick.sh
index 327f69bcf5..83764f7537 100755
--- a/Documentation/install-doc-quick.sh
+++ b/Documentation/install-doc-quick.sh
@@ -3,8 +3,9 @@
 
 repository=${1?repository}
 destdir=${2?destination}
+head=${3+master}
+GIT_DIR=
 
-head=master GIT_DIR=
 for d in "$repository/.git" "$repository"
 do
 	if GIT_DIR="$d" git rev-parse refs/heads/master >/dev/null 2>&1

RE: [RFE] install-doc-quick.sh should accept a commit-ish

[Randall S. Becker]

On December 6, 2017 11:40 AM, Junio C Hamano wrote:
>"Randall S. Becker" <rsbecker@nexbridge.com> writes:
>> Having the git-manpages repo available is fantastic for platforms that 
>> cannot easily build documentation on demand, for example, when too 
>> many dependencies that do not build properly.
>> It would be really nice to have a version of install-doc-quick.sh to
either:
>> 1. Use whatever version is checked out in git-manpages; or
>> 2. Use the proper commit associated with the git commit being 
>> installed (0a8e923 for v2.6.0 , as an example); or
>> 3. Allow the commit to be passed through the Documentation Makefile on
demand so that any version of documentation can be installed.

>Do you mean something like this so that you can say "not the tip of the
master branch but this one?"

> Documentation/install-doc-quick.sh | 3 ++-
> 1 file changed, 2 insertions(+), 1 deletion(-)

>diff --git a/Documentation/install-doc-quick.sh
b/Documentation/install-doc-quick.sh
>index 327f69bcf5..83764f7537 100755
>--- a/Documentation/install-doc-quick.sh
>+++ b/Documentation/install-doc-quick.sh
>@@ -3,8 +3,9 @@
 
> repository=${1?repository}
> destdir=${2?destination}
>+head=${3+master}
>+GIT_DIR=
 
>-head=master GIT_DIR=
> for d in "$repository/.git" "$repository"
> do
> 	if GIT_DIR="$d" git rev-parse refs/heads/master >/dev/null 2>&1

Providing I can pass that through make via something like quick-install-man
head=commit-ish, that's what I'm hoping.

Cheers,
Randall