[Proposed] Externalize man/html ref for quick-install-man and quick-install-html

[Proposed] Externalize man/html ref for quick-install-man and quick-install-html

[Randall S. Becker]

I am proposing the following trivial change to allow the external
specification of the reference used for quick-install-man. The justification
is that I cannot have my production team modifying scripts when non-master
versions of git are installed in production (that violates so many rules
that I would have trouble enumerating). This does add any requirements for
changes to the automation for building either git-manpages or  git-htmldocs.
What it does is allow the top level make to pass GIT_MAN_REF down to the
underlying shell script with a default of master if unspecific. Where I am
uncertain is what else would be required for this change (documentation,
unit tests).

I humbly submit this for consideration.
Sincerely,
Randall

From 6acc4a4238b3e3e62674bf8a5d0b9084258a0967 Mon Sep 17 00:00:00 2001
From: "Randall S. Becker" <rsbecker@nexbridge.com>
Date: Sat, 9 Dec 2017 15:52:44 -0600
Subject: Externalize man/html ref for quick-install-man and
quick-install-html

---
 Documentation/Makefile             | 6 ++++--
 Documentation/install-doc-quick.sh | 7 ++++---
 2 files changed, 8 insertions(+), 5 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 3e39e28..4f1e6df 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -39,6 +39,8 @@ MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
 MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT))
 MAN_HTML = $(patsubst %.txt,%.html,$(MAN_TXT))

+GIT_MAN_REF = master
+
 OBSOLETE_HTML += everyday.html
 OBSOLETE_HTML += git-remote-helpers.html
 DOC_HTML = $(MAN_HTML) $(OBSOLETE_HTML)
@@ -415,14 +417,14 @@ require-manrepo::
        then echo "git-manpages repository must exist at $(MAN_REPO)"; exit
1; fi

 quick-install-man: require-manrepo
-       '$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(MAN_REPO)
$(DESTDIR)$(mandir)
+       '$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(MAN_REPO)
$(DESTDIR)$(mandir) $(GIT_MAN_REF)

 require-htmlrepo::
        @if test ! -d $(HTML_REPO); \
        then echo "git-htmldocs repository must exist at $(HTML_REPO)"; exit
1; fi

 quick-install-html: require-htmlrepo
-       '$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REPO)
$(DESTDIR)$(htmldir)
+       '$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REPO)
$(DESTDIR)$(htmldir) $(GIT_MAN_REF)

 print-man1:
        @for i in $(MAN1_TXT); do echo $$i; done
diff --git a/Documentation/install-doc-quick.sh
b/Documentation/install-doc-quick.sh
index 327f69b..a7715eb 100755
--- a/Documentation/install-doc-quick.sh
+++ b/Documentation/install-doc-quick.sh
@@ -4,7 +4,8 @@
 repository=${1?repository}
 destdir=${2?destination}

-head=master GIT_DIR=
+GIT_MAN_REF=${3?master}
+GIT_DIR=
 for d in "$repository/.git" "$repository"
 do
        if GIT_DIR="$d" git rev-parse refs/heads/master >/dev/null 2>&1
@@ -27,12 +28,12 @@ export GIT_INDEX_FILE GIT_WORK_TREE
 rm -f "$GIT_INDEX_FILE"
 trap 'rm -f "$GIT_INDEX_FILE"' 0

-git read-tree $head
+git read-tree $GIT_MAN_REF
 git checkout-index -a -f --prefix="$destdir"/

 if test -n "$GZ"
 then
-       git ls-tree -r --name-only $head |
+       git ls-tree -r --name-only $GIT_MAN_REF |
        xargs printf "$destdir/%s\n" |
        xargs gzip -f
 fi
--
2.5.6.18.ga013bef

Re: [Proposed] Externalize man/html ref for quick-install-man and quick-install-html

[Junio C Hamano]

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

> diff --git a/Documentation/Makefile b/Documentation/Makefile
> index 3e39e28..4f1e6df 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -39,6 +39,8 @@ MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
>  MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT))
>  MAN_HTML = $(patsubst %.txt,%.html,$(MAN_TXT))
>
> +GIT_MAN_REF = master
> +
>  OBSOLETE_HTML += everyday.html
>  OBSOLETE_HTML += git-remote-helpers.html
>  DOC_HTML = $(MAN_HTML) $(OBSOLETE_HTML)
> @@ -415,14 +417,14 @@ require-manrepo::
>         then echo "git-manpages repository must exist at $(MAN_REPO)"; exit
> 1; fi
>
>  quick-install-man: require-manrepo
> -       '$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(MAN_REPO)
> $(DESTDIR)$(mandir)
> +       '$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(MAN_REPO)
> $(DESTDIR)$(mandir) $(GIT_MAN_REF)

I suspect that this patch is line-wrapped and unusable for the final
application, but I think what the change wants to do makes total
sense---we are already letting the builder specify where the other
repositories for docs are, and it is not such a big stretch to let
them also say which branch or tag they want their documentation
from.

RE: [Proposed] Externalize man/html ref for quick-install-man and quick-install-html

[Randall S. Becker]

Sorry about the response positioning...

I can send you a pull request on github, if you want 😉

-----Original Message-----
From: git-owner@vger.kernel.org [mailto:git-owner@vger.kernel.org] On Behalf Of Junio C Hamano
Sent: December 11, 2017 6:27 PM
To: Randall S. Becker <rsbecker@nexbridge.com>
Cc: git@vger.kernel.org
Subject: Re: [Proposed] Externalize man/html ref for quick-install-man and quick-install-html

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

> diff --git a/Documentation/Makefile b/Documentation/Makefile index 
> 3e39e28..4f1e6df 100644
> --- a/Documentation/Makefile
> +++ b/Documentation/Makefile
> @@ -39,6 +39,8 @@ MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)  
> MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT))  MAN_HTML = $(patsubst 
> %.txt,%.html,$(MAN_TXT))
>
> +GIT_MAN_REF = master
> +
>  OBSOLETE_HTML += everyday.html
>  OBSOLETE_HTML += git-remote-helpers.html  DOC_HTML = $(MAN_HTML) 
> $(OBSOLETE_HTML) @@ -415,14 +417,14 @@ require-manrepo::
>         then echo "git-manpages repository must exist at $(MAN_REPO)"; 
> exit 1; fi
>
>  quick-install-man: require-manrepo
> -       '$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(MAN_REPO)
> $(DESTDIR)$(mandir)
> +       '$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(MAN_REPO)
> $(DESTDIR)$(mandir) $(GIT_MAN_REF)

I suspect that this patch is line-wrapped and unusable for the final application, but I think what the change wants to do makes total sense---we are already letting the builder specify where the other repositories for docs are, and it is not such a big stretch to let them also say which branch or tag they want their documentation from.

Re: [Proposed] Externalize man/html ref for quick-install-man and quick-install-html

[Jacob Keller]

On Mon, Dec 11, 2017 at 4:26 PM, Randall S. Becker
<rsbecker@nexbridge.com> wrote:
> Sorry about the response positioning...
>
> I can send you a pull request on github, if you want 😉
>

You can use https://submitgit.herokuapp.com/ to submit to the mailing
list from a pull request.

Thanks,
Jake

Re: [Proposed] Externalize man/html ref for quick-install-man and quick-install-html

[Junio C Hamano]

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

> Sorry about the response positioning...
>
> I can send you a pull request on github, if you want 😉

I don't.  It's not that I can or cannot take a pull request.  I just
do not want to queue anything that is not reviwed on list.

I however could queue this (typed to mimic what I saw in your
message), but you'd need to say what you see here is OK (and
preferably, you applied this version and it tested fine); I may have
made a typo or two, and I would really prefer extra set of eyes.

Also we need your sign-off, of course.

Thanks.

-- >8 --
From: "Randall S. Becker" <rsbecker@nexbridge.com>
Date: Sat, 9 Dec 2017 17:07:57 -0500
Subject: [PATCH] install-doc-quick: allow specifying what ref to install

We allow the builders, who want to install the preformatted manpages
and html documents, to specify where in their filesystem these two
repositories are stored.  Let them also specify which ref (or even a
revision) to grab the preformatted material from.
---
 Documentation/Makefile             | 5 +++--
 Documentation/install-doc-quick.sh | 9 +++++----
 2 files changed, 8 insertions(+), 6 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile
index 2ab65561af..4ae9ba5c86 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -39,6 +39,7 @@ MAN7_TXT += gitworkflows.txt
 MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)
 MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT))
 MAN_HTML = $(patsubst %.txt,%.html,$(MAN_TXT))
+GIT_MAN_REF = master
 
 OBSOLETE_HTML += everyday.html
 OBSOLETE_HTML += git-remote-helpers.html
@@ -437,14 +438,14 @@ require-manrepo::
 	then echo "git-manpages repository must exist at $(MAN_REPO)"; exit 1; fi
 
 quick-install-man: require-manrepo
-	'$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(MAN_REPO) $(DESTDIR)$(mandir)
+	'$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(MAN_REPO) $(DESTDIR)$(mandir) $(GIT_MAN_REF)
 
 require-htmlrepo::
 	@if test ! -d $(HTML_REPO); \
 	then echo "git-htmldocs repository must exist at $(HTML_REPO)"; exit 1; fi
 
 quick-install-html: require-htmlrepo
-	'$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REPO) $(DESTDIR)$(htmldir)
+	'$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REPO) $(DESTDIR)$(htmldir) $(GIT_MAN_REF)
 
 print-man1:
 	@for i in $(MAN1_TXT); do echo $$i; done
diff --git a/Documentation/install-doc-quick.sh b/Documentation/install-doc-quick.sh
index 327f69bcf5..17231d8e59 100755
--- a/Documentation/install-doc-quick.sh
+++ b/Documentation/install-doc-quick.sh
@@ -3,11 +3,12 @@
 
 repository=${1?repository}
 destdir=${2?destination}
+GIT_MAN_REF=${3?master}
 
-head=master GIT_DIR=
+GIT_DIR=
 for d in "$repository/.git" "$repository"
 do
-	if GIT_DIR="$d" git rev-parse refs/heads/master >/dev/null 2>&1
+	if GIT_DIR="$d" git rev-parse "$GIT_MAN_REF" >/dev/null 2>&1
 	then
 		GIT_DIR="$d"
 		export GIT_DIR
@@ -27,12 +28,12 @@ export GIT_INDEX_FILE GIT_WORK_TREE
 rm -f "$GIT_INDEX_FILE"
 trap 'rm -f "$GIT_INDEX_FILE"' 0
 
-git read-tree $head
+git read-tree "$GIT_MAN_REF"
 git checkout-index -a -f --prefix="$destdir"/
 
 if test -n "$GZ"
 then
-	git ls-tree -r --name-only $head |
+	git ls-tree -r --name-only "$GIT_MAN_REF" |
 	xargs printf "$destdir/%s\n" |
 	xargs gzip -f
 fi
-- 
2.15.1-525-g09180b8600

RE: [Proposed] Externalize man/html ref for quick-install-man and quick-install-html

[Randall S. Becker]

-----Original Message-----
On December 12, 2017 6:18 PM Junio C Hamano wrote:
Subject: Re: [Proposed] Externalize man/html ref for quick-install-man and quick-install-html
>"Randall S. Becker" <rsbecker@nexbridge.com> writes:
>> I can send you a pull request on github, if you want 😉
>I don't.  It's not that I can or cannot take a pull request.  I just do not want to queue anything that is not reviwed on list.
No worries.

>I however could queue this (typed to mimic what I saw in your message), but you'd need to say what you see here is OK (and preferably, you applied this version and it tested fine); I may have made a typo or two, and I would really prefer extra set of eyes.
Yes, needed. The lines wrapped om Documentation/Makefile - each change in quick-install-man/html should be exactly one line:

quick-install-man: require-manrepo
-	'$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(MAN_REPO) $(DESTDIR)$(mandir)
+	'$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(MAN_REPO) $(DESTDIR)$(mandir) $(GIT_MAN_REF)
 
And here

 quick-install-html: require-htmlrepo
-	'$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REPO) $(DESTDIR)$(htmldir)
+	'$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REPO) $(DESTDIR)$(htmldir) $(GIT_MAN_REF)

And otherwise please consider it signed off.

Signed-off-by: Randall S. Becker <randall.becker@nexbridge.ca>

-- >8 --
From: "Randall S. Becker" <rsbecker@nexbridge.com>
Date: Sat, 9 Dec 2017 17:07:57 -0500
Subject: [PATCH] install-doc-quick: allow specifying what ref to install

We allow the builders, who want to install the preformatted manpages and html documents, to specify where in their filesystem these two repositories are stored.  Let them also specify which ref (or even a
revision) to grab the preformatted material from.
---
 Documentation/Makefile             | 5 +++--
 Documentation/install-doc-quick.sh | 9 +++++----
 2 files changed, 8 insertions(+), 6 deletions(-)

diff --git a/Documentation/Makefile b/Documentation/Makefile index 2ab65561af..4ae9ba5c86 100644
--- a/Documentation/Makefile
+++ b/Documentation/Makefile
@@ -39,6 +39,7 @@ MAN7_TXT += gitworkflows.txt  MAN_TXT = $(MAN1_TXT) $(MAN5_TXT) $(MAN7_TXT)  MAN_XML = $(patsubst %.txt,%.xml,$(MAN_TXT))  MAN_HTML = $(patsubst %.txt,%.html,$(MAN_TXT))
+GIT_MAN_REF = master
 
 OBSOLETE_HTML += everyday.html
 OBSOLETE_HTML += git-remote-helpers.html @@ -437,14 +438,14 @@ require-manrepo::
 	then echo "git-manpages repository must exist at $(MAN_REPO)"; exit 1; fi
 
 quick-install-man: require-manrepo
-	'$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(MAN_REPO) $(DESTDIR)$(mandir)
+	'$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(MAN_REPO) 
+$(DESTDIR)$(mandir) $(GIT_MAN_REF)
 
 require-htmlrepo::
 	@if test ! -d $(HTML_REPO); \
 	then echo "git-htmldocs repository must exist at $(HTML_REPO)"; exit 1; fi
 
 quick-install-html: require-htmlrepo
-	'$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REPO) $(DESTDIR)$(htmldir)
+	'$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REPO) 
+$(DESTDIR)$(htmldir) $(GIT_MAN_REF)
 
 print-man1:
 	@for i in $(MAN1_TXT); do echo $$i; done diff --git a/Documentation/install-doc-quick.sh b/Documentation/install-doc-quick.sh
index 327f69bcf5..17231d8e59 100755
--- a/Documentation/install-doc-quick.sh
+++ b/Documentation/install-doc-quick.sh
@@ -3,11 +3,12 @@
 
 repository=${1?repository}
 destdir=${2?destination}
+GIT_MAN_REF=${3?master}
 
-head=master GIT_DIR=
+GIT_DIR=
 for d in "$repository/.git" "$repository"
 do
-	if GIT_DIR="$d" git rev-parse refs/heads/master >/dev/null 2>&1
+	if GIT_DIR="$d" git rev-parse "$GIT_MAN_REF" >/dev/null 2>&1
 	then
 		GIT_DIR="$d"
 		export GIT_DIR
@@ -27,12 +28,12 @@ export GIT_INDEX_FILE GIT_WORK_TREE  rm -f "$GIT_INDEX_FILE"
 trap 'rm -f "$GIT_INDEX_FILE"' 0
 
-git read-tree $head
+git read-tree "$GIT_MAN_REF"
 git checkout-index -a -f --prefix="$destdir"/
 
 if test -n "$GZ"
 then
-	git ls-tree -r --name-only $head |
+	git ls-tree -r --name-only "$GIT_MAN_REF" |
 	xargs printf "$destdir/%s\n" |
 	xargs gzip -f
 fi
--
2.15.1-525-g09180b8600

Re: [Proposed] Externalize man/html ref for quick-install-man and quick-install-html

[Junio C Hamano]

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

> Yes, needed. The lines wrapped om Documentation/Makefile - each
> change in quick-install-man/html should be exactly one line:
>
> quick-install-man: require-manrepo
> -	'$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(MAN_REPO) $(DESTDIR)$(mandir)
> +	'$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(MAN_REPO) $(DESTDIR)$(mandir) $(GIT_MAN_REF)
>  
> And here
>
>  quick-install-html: require-htmlrepo
> -	'$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REPO) $(DESTDIR)$(htmldir)
> +	'$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REPO) $(DESTDIR)$(htmldir) $(GIT_MAN_REF)

I somehow have a feeling that you are not even looking at the right
rendition.

To everybody else who did not complain that what I sent was
line-wrapped, the message should be showing like this:

    https://public-inbox.org/git/xmqqtvwvy1rh.fsf@gitster.mtv.corp.google.com/

Perhaps the mail program on your receiving end is mangling what you
got from the mailing list, giving you a line-wrapped version.

It also unfortunately makes me suspect that you didn't actually have
a chance to apply the patch mechanically and make sure it works for
you due to mail mangling at your end X-<.

> And otherwise please consider it signed off.

Will do, thanks.

RE: [Proposed] Externalize man/html ref for quick-install-man and quick-install-html

[Randall S. Becker]

On December 12, 2017 6:40 PM Junio C Hamano wrote to my own embarrassment:
"Randall S. Becker" <rsbecker@nexbridge.com> writes:

>> Yes, needed. The lines wrapped om Documentation/Makefile - each change 
>> in quick-install-man/html should be exactly one line:
>>
>> quick-install-man: require-manrepo
>> -	'$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(MAN_REPO) $(DESTDIR)$(mandir)
>> +	'$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(MAN_REPO) 
>> +$(DESTDIR)$(mandir) $(GIT_MAN_REF)
>>  
>> And here
>>
>>  quick-install-html: require-htmlrepo
>> -	'$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REPO) $(DESTDIR)$(htmldir)
>> +	'$(SHELL_PATH_SQ)' ./install-doc-quick.sh $(HTML_REPO) 
>> +$(DESTDIR)$(htmldir) $(GIT_MAN_REF)>

>To everybody else who did not complain that what I sent was line-wrapped, the message should be showing like this:
>    https://public-inbox.org/git/xmqqtvwvy1rh.fsf@gitster.mtv.corp.google.com/
It is correct at the above link. My mailer is Outlook 2016... so... yeah.

>Perhaps the mail program on your receiving end is mangling what you got from the mailing list, giving you a line-wrapped version.
Yes it is. It loves mangling. Nice to see it mangled it again ☹. Porting sendmail was on my list of things to do, but pretty far down.

>It also unfortunately makes me suspect that you didn't actually have a chance to apply the patch mechanically and make sure it works for you due to mail mangling at your end X-<.
I have no such capability on the system where the changes were made, nor even with Outlook on my own local Windows dev box. I've tried my mac and linux machines but can't connect up to my (bleep) mailer from those without creating more (bleep). It's either that or I'm too close to the holidays.

>> And otherwise please consider it signed off.
>Will do, thanks.

😊