[PATCH 0/3] Improve autodate.sh

[PATCH 0/3] Improve autodate.sh

[Akira Yokosawa]

This patch set was inspired by your change log of commit 686915e83f79
("utilities/autodate: Convert current tag to release/edition text")
saying:

    This should really use a canned library to convert numerals to
    English-text ordinals, but none of the ones I found worked as advertised.

My guess is the ones you found are assuming bash and don't work with
dash. You know, dash doesn't handle arrays.

Patch #1 is my answer and delegates the handling of ordinals to
a LaTeX package "fmtcount".
Patch #2 is a minor update so that a repository with untracked files
is treated as clean.
Patch #3 expands the use of tag info and displays it on every page
at the bottom-right corner.

        Thanks, Akira
--
Akira Yokosawa (3):
  utilities/autodate: Use 'fmtcount' package for ordinals
  utilities/autodate: Ignore untracked files in 'git status'
  utilities/autodate: Put commit-id in footer by 'draftwatermark'

 FAQ-BUILD.txt         |  6 ++++--
 perfbook.tex          |  9 +++++++++
 utilities/autodate.sh | 35 ++++++++++++-----------------------
 3 files changed, 25 insertions(+), 25 deletions(-)

-- 
2.17.1

[PATCH 1/3] utilities/autodate: Use 'fmtcount' package for ordinals

[Akira Yokosawa]

From f688ea9f959e70e39315f0a48c843667e9e70561 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <akiyks@gmail.com>
Date: Sun, 29 Dec 2019 17:49:26 +0900
Subject: [PATCH 1/3] utilities/autodate: Use 'fmtcount' package for ordinals

LaTeX package "fmtcount" provides a macro "\Ordinalstringnum{}",
which does the conversion we need.

Also do some cosmetic tweaks:
    - Use typewriter font for commit description and non-release tag.
    - Move "(m)" indicating dirty git status to the end of release
      info.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 perfbook.tex          |  1 +
 utilities/autodate.sh | 27 +++++----------------------
 2 files changed, 6 insertions(+), 22 deletions(-)

diff --git a/perfbook.tex b/perfbook.tex
index 7dc8d95f..73b79205 100644
--- a/perfbook.tex
+++ b/perfbook.tex
@@ -59,6 +59,7 @@
 \usepackage[hyphens]{url}
 \usepackage{threeparttable}
 \usepackage{titlesec}[2016/03/21] % Suppress number in paragraph heading
+\usepackage{fmtcount}
 \usepackage[bookmarks=true,bookmarksnumbered=true,pdfborder={0 0 0},linktoc=all]{hyperref}
 \usepackage{footnotebackref} % to enable cross-ref of footnote
 \usepackage[all]{hypcap} % for going to the top of figure and table
diff --git a/utilities/autodate.sh b/utilities/autodate.sh
index 13d8bb5f..924fa6ee 100644
--- a/utilities/autodate.sh
+++ b/utilities/autodate.sh
@@ -43,7 +43,7 @@ else
 	description="`git describe --tags HEAD`"
 	case "$description" in
 	*-g*)
-		release="Commit $description"
+		release=`env printf 'Commit: \\\texttt{%s}' "$description"`
 		;;
 	v*)
 		release="Release $description"
@@ -57,25 +57,8 @@ else
 		esac
 		case "$description" in
 		Edition[.-][0-9]*)
-			ednum="`echo $description | sed -e 's/^Edition[.-]\([1-9]*\).*$/\1/'`"
-			case "$ednum" in
-			1)
-				edord=First
-				;;
-			2)
-				edord=Second
-				;;
-			3)
-				edord=Third
-				;;
-			4)
-				edord=Fourth
-				;;
-			*)
-				edord=FixMe
-				;;
-			esac
-			release="$edord $release"
+			ednum="`echo $description | sed -e 's/^Edition[.-]\([0-9]*\).*$/\1/'`"
+			release=`env printf '\\Ordinalstringnum{%s} %s' $ednum "$release"`
 			;;
 		esac
 		case "$description" in
@@ -86,7 +69,7 @@ else
 		esac
 		;;
 	*)
-		release="Commit $description"
+		release=`env printf 'Tag: \\\texttt{%s}' "$description"`
 		;;
 	esac
 fi
@@ -98,5 +81,5 @@ then
 	release=`env printf '%s %s' '\\\\' "$release"`
 fi
 
-env printf '\\date{%s %s, %s %s %s}\n' $month $day $year $modified "$release"
+env printf '\\date{%s %s, %s %s %s}\n' $month $day $year "$release" $modified
 env printf '\\newcommand{\\commityear}{%s}\n' $year
-- 
2.17.1

[PATCH 2/3] utilities/autodate: Ignore untracked files in 'git status'

[Akira Yokosawa]

From c9778ef5caf2375ce7e0d02390c97efda9e6e603 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <akiyks@gmail.com>
Date: Sun, 29 Dec 2019 17:51:13 +0900
Subject: [PATCH 2/3] utilities/autodate: Ignore untracked files in 'git status'

This is safe because untracked files won't have any effect in the
resulting .pdf unless at least one of the tracked files is modified.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 utilities/autodate.sh | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/utilities/autodate.sh b/utilities/autodate.sh
index 924fa6ee..2ebc0754 100644
--- a/utilities/autodate.sh
+++ b/utilities/autodate.sh
@@ -33,7 +33,7 @@ then
 else
 	date_str=`git show --format="%cD" | head -1`
 	# check if git status is clean
-	gitstatus=`git status --porcelain | wc -l`
+	gitstatus=`git status -uno --porcelain | wc -l`
 	if [ $gitstatus != "0" ]
 	then
 		modified="(m)"
-- 
2.17.1

[PATCH 3/3] utilities/autodate: Put commit-id in footer by 'draftwatermark'

[Akira Yokosawa]

From 8575d3513dc813b9ede20a8aa4629826b8028343 Mon Sep 17 00:00:00 2001
From: Akira Yokosawa <akiyks@gmail.com>
Date: Sun, 29 Dec 2019 17:51:53 +0900
Subject: [PATCH 3/3] utilities/autodate: Put commit-id in footer by 'draftwatermark'

A similar footer should be able to be typeset on every page by
a LaTeX package "fancyhdr", but I have not figured out a way to do
so reliably on Chapter pages.

A Release/Edition will have the release/edition tag name instead.

Also update FAQ-BUILD.txt to mention the possible version mismatch
of draftwatermark.

Signed-off-by: Akira Yokosawa <akiyks@gmail.com>
---
 FAQ-BUILD.txt         | 6 ++++--
 perfbook.tex          | 8 ++++++++
 utilities/autodate.sh | 6 ++++++
 3 files changed, 18 insertions(+), 2 deletions(-)

diff --git a/FAQ-BUILD.txt b/FAQ-BUILD.txt
index 4fb85e7a..f5066798 100644
--- a/FAQ-BUILD.txt
+++ b/FAQ-BUILD.txt
@@ -178,10 +178,11 @@
 			tlmgr install newtx
 
 10.	Building perfbook fails with a warning of buggy cleveref/listings
-	or version mismatch of titlesec. What can I do?
+	or version mismatch of titlesec/draftwatermark. What can I do?
 
 	A.	They are known issues on Ubuntu Xenial (titlesec),
-		Ubuntu Bionic (cleveref), and TeX Live 2014/2015 (listings).
+		Ubuntu Bionic (cleveref), TeX Live 2014/2015 (listings),
+		and TeX Live releases prior to 2015 (draftwatermark).
 		This answer assumes Ubuntu, but it should work on other
 		distros.
 
@@ -189,6 +190,7 @@
 		http://mirrors.ctan.org/macros/latex/contrib/titlesec.zip
 		http://mirrors.ctan.org/macros/latex/contrib/cleveref.zip
 		http://mirrors.ctan.org/macros/latex/contrib/listings.zip
+		http://mirrors.ctan.org/macros/latex/contrib/draftwatermark.zip
 
 	    2.	Install it by following instructions at:
 		https://help.ubuntu.com/community/LaTeX#Installing_packages_manually
diff --git a/perfbook.tex b/perfbook.tex
index 73b79205..0fae78fb 100644
--- a/perfbook.tex
+++ b/perfbook.tex
@@ -60,6 +60,14 @@
 \usepackage{threeparttable}
 \usepackage{titlesec}[2016/03/21] % Suppress number in paragraph heading
 \usepackage{fmtcount}
+\usepackage{draftwatermark}[2015/02/19]
+\SetWatermarkAngle{0.0}
+\SetWatermarkFontSize{8pt}
+\SetWatermarkScale{1.0}
+\SetWatermarkLightness{.6}
+\SetWatermarkHorCenter{.85\paperwidth}
+\SetWatermarkVerCenter{.95\paperheight}
+\SetWatermarkText{\texttt{\commitid}}
 \usepackage[bookmarks=true,bookmarksnumbered=true,pdfborder={0 0 0},linktoc=all]{hyperref}
 \usepackage{footnotebackref} % to enable cross-ref of footnote
 \usepackage[all]{hypcap} % for going to the top of figure and table
diff --git a/utilities/autodate.sh b/utilities/autodate.sh
index 2ebc0754..a954bbe7 100644
--- a/utilities/autodate.sh
+++ b/utilities/autodate.sh
@@ -30,6 +30,7 @@ then
 	date_str=`date -R`
 	modified=""
 	release=""
+	commitid=""
 else
 	date_str=`git show --format="%cD" | head -1`
 	# check if git status is clean
@@ -44,12 +45,15 @@ else
 	case "$description" in
 	*-g*)
 		release=`env printf 'Commit: \\\texttt{%s}' "$description"`
+		commitid=`echo $description | sed -e 's/.*-\(g.*\)/\1/'`
 		;;
 	v*)
 		release="Release $description"
+		commitid=$description
 		;;
 	Edition*)
 		release="Edition"
+		commitid=$description
 		case "$description" in
 		*P*)
 			release="Print $release"
@@ -70,6 +74,7 @@ else
 		;;
 	*)
 		release=`env printf 'Tag: \\\texttt{%s}' "$description"`
+		commitid=`echo $description | sed -e 's/.*-\(g.*\)/\1/'`
 		;;
 	esac
 fi
@@ -83,3 +88,4 @@ fi
 
 env printf '\\date{%s %s, %s %s %s}\n' $month $day $year "$release" $modified
 env printf '\\newcommand{\\commityear}{%s}\n' $year
+env printf '\\newcommand{\\commitid}{%s}\n' $commitid$modified
-- 
2.17.1

Re: [PATCH 0/3] Improve autodate.sh

[Paul E. McKenney]

On Sun, Dec 29, 2019 at 07:21:42PM +0900, Akira Yokosawa wrote:
> This patch set was inspired by your change log of commit 686915e83f79
> ("utilities/autodate: Convert current tag to release/edition text")
> saying:
> 
>     This should really use a canned library to convert numerals to
>     English-text ordinals, but none of the ones I found worked as advertised.
> 
> My guess is the ones you found are assuming bash and don't work with
> dash. You know, dash doesn't handle arrays.

It was instead that my versions of python didn't know about the
advertised library, possibly because I didn't know to tell them.

> Patch #1 is my answer and delegates the handling of ordinals to
> a LaTeX package "fmtcount".

But I like your approach better in any case, thank you!!!  ;-)

> Patch #2 is a minor update so that a repository with untracked files
> is treated as clean.

My use case for wanting the current behavior is when I add a file,
add references to it, but forget to do "git add".  The "(m)" is
a hint that I forgot something.

But what is the countervailing use case?  Maybe there is a way to
solve both problems.

> Patch #3 expands the use of tag info and displays it on every page
> at the bottom-right corner.

Nice!

I took #1 and #3, and pushed another patch that includes the most
recent tag for non-release builds.  Let's talk about #2 -- perhaps
I should take it as is, but that would require some other warning.

Thoughts?

							Thanx, Paul

>         Thanks, Akira
> --
> Akira Yokosawa (3):
>   utilities/autodate: Use 'fmtcount' package for ordinals
>   utilities/autodate: Ignore untracked files in 'git status'
>   utilities/autodate: Put commit-id in footer by 'draftwatermark'
> 
>  FAQ-BUILD.txt         |  6 ++++--
>  perfbook.tex          |  9 +++++++++
>  utilities/autodate.sh | 35 ++++++++++++-----------------------
>  3 files changed, 25 insertions(+), 25 deletions(-)
> 
> -- 
> 2.17.1
> 

Re: [PATCH 0/3] Improve autodate.sh

[Akira Yokosawa]

On Mon, 30 Dec 2019 16:06:27 -0800, Paul E. McKenney wrote:
> On Sun, Dec 29, 2019 at 07:21:42PM +0900, Akira Yokosawa wrote:
>> This patch set was inspired by your change log of commit 686915e83f79
>> ("utilities/autodate: Convert current tag to release/edition text")
>> saying:
>>
>>     This should really use a canned library to convert numerals to
>>     English-text ordinals, but none of the ones I found worked as advertised.
>>
>> My guess is the ones you found are assuming bash and don't work with
>> dash. You know, dash doesn't handle arrays.
> 
> It was instead that my versions of python didn't know about the
> advertised library, possibly because I didn't know to tell them.

Hm, installing python (or python3 nowadays?) packages can be tricky.
(system/user install, installing by pip/pip3 or apt ...)

> 
>> Patch #1 is my answer and delegates the handling of ordinals to
>> a LaTeX package "fmtcount".
> 
> But I like your approach better in any case, thank you!!!  ;-)
> 
>> Patch #2 is a minor update so that a repository with untracked files
>> is treated as clean.
> 
> My use case for wanting the current behavior is when I add a file,
> add references to it, but forget to do "git add".  The "(m)" is
> a hint that I forgot something.

Ah, current behavior does help such a situation!

> 
> But what is the countervailing use case? 

Not much of a use case, but for example, random experimental outputs
under CodeSamples/ not covered by .gitignore will generate the "(m)",
which looks irrelevant.

But my view point was of receiving side of your updates.
Now I know you've relied on the current behavior and changing it
should be regarded as a regression.

>                                           Maybe there is a way to
> solve both problems.

Let's keep the current behavior.

> 
>> Patch #3 expands the use of tag info and displays it on every page
>> at the bottom-right corner.
> 
> Nice!
> 
> I took #1 and #3, and pushed another patch that includes the most
> recent tag for non-release builds.

I thought full $description in non-release builds could be too long
for the footer area, but the position of the watermark in the preamble
specifies the center, and it looks reasonable. Thank you!

>                                           Let's talk about #2 -- perhaps
> I should take it as is, but that would require some other warning.
> 
> Thoughts?

As mentioned above, I'm OK with keeping the current behavior.
Adding some namespaces to .gitignore might be a better approach,
but it is not urgent at all.

        Thanks, Akira

> 
> 							Thanx, Paul
> 
>>         Thanks, Akira
>> --
>> Akira Yokosawa (3):
>>   utilities/autodate: Use 'fmtcount' package for ordinals
>>   utilities/autodate: Ignore untracked files in 'git status'
>>   utilities/autodate: Put commit-id in footer by 'draftwatermark'
>>
>>  FAQ-BUILD.txt         |  6 ++++--
>>  perfbook.tex          |  9 +++++++++
>>  utilities/autodate.sh | 35 ++++++++++++-----------------------
>>  3 files changed, 25 insertions(+), 25 deletions(-)
>>
>> -- 
>> 2.17.1
>>

Re: [PATCH 0/3] Improve autodate.sh

[Paul E. McKenney]

On Wed, Jan 01, 2020 at 08:36:24AM +0900, Akira Yokosawa wrote:
> On Mon, 30 Dec 2019 16:06:27 -0800, Paul E. McKenney wrote:
> > On Sun, Dec 29, 2019 at 07:21:42PM +0900, Akira Yokosawa wrote:
> >> This patch set was inspired by your change log of commit 686915e83f79
> >> ("utilities/autodate: Convert current tag to release/edition text")
> >> saying:
> >>
> >>     This should really use a canned library to convert numerals to
> >>     English-text ordinals, but none of the ones I found worked as advertised.
> >>
> >> My guess is the ones you found are assuming bash and don't work with
> >> dash. You know, dash doesn't handle arrays.
> > 
> > It was instead that my versions of python didn't know about the
> > advertised library, possibly because I didn't know to tell them.
> 
> Hm, installing python (or python3 nowadays?) packages can be tricky.
> (system/user install, installing by pip/pip3 or apt ...)

Ah, as the old saying goes, I have much to learn!

> >> Patch #1 is my answer and delegates the handling of ordinals to
> >> a LaTeX package "fmtcount".
> > 
> > But I like your approach better in any case, thank you!!!  ;-)
> > 
> >> Patch #2 is a minor update so that a repository with untracked files
> >> is treated as clean.
> > 
> > My use case for wanting the current behavior is when I add a file,
> > add references to it, but forget to do "git add".  The "(m)" is
> > a hint that I forgot something.
> 
> Ah, current behavior does help such a situation!
> 
> > But what is the countervailing use case? 
> 
> Not much of a use case, but for example, random experimental outputs
> under CodeSamples/ not covered by .gitignore will generate the "(m)",
> which looks irrelevant.

I like your suggestion below of creating directories for experiemental
not-to-be-committed results using .gitignore, and would of course welcome
a patch.

> But my view point was of receiving side of your updates.
> Now I know you've relied on the current behavior and changing it
> should be regarded as a regression.

OK, we should be good as-is, then.

> >                                           Maybe there is a way to
> > solve both problems.
> 
> Let's keep the current behavior.

Sounds good!

> >> Patch #3 expands the use of tag info and displays it on every page
> >> at the bottom-right corner.
> > 
> > Nice!
> > 
> > I took #1 and #3, and pushed another patch that includes the most
> > recent tag for non-release builds.
> 
> I thought full $description in non-release builds could be too long
> for the footer area, but the position of the watermark in the preamble
> specifies the center, and it looks reasonable. Thank you!

Very good!  And thank you for coming up with the footer trick, could
save some confusion.

> >                                           Let's talk about #2 -- perhaps
> > I should take it as is, but that would require some other warning.
> > 
> > Thoughts?
> 
> As mentioned above, I'm OK with keeping the current behavior.
> Adding some namespaces to .gitignore might be a better approach,
> but it is not urgent at all.

As noted earlier, this sounds good to me!  One approach would be to
add the experimental directory and a README within it, with the README
describing the purpose.  Then a .gitignore in that same directory could
ignore all but the README.  But maybe you have a better idea.

							Thanx, Paul

>         Thanks, Akira
> 
> > 
> > 							Thanx, Paul
> > 
> >>         Thanks, Akira
> >> --
> >> Akira Yokosawa (3):
> >>   utilities/autodate: Use 'fmtcount' package for ordinals
> >>   utilities/autodate: Ignore untracked files in 'git status'
> >>   utilities/autodate: Put commit-id in footer by 'draftwatermark'
> >>
> >>  FAQ-BUILD.txt         |  6 ++++--
> >>  perfbook.tex          |  9 +++++++++
> >>  utilities/autodate.sh | 35 ++++++++++++-----------------------
> >>  3 files changed, 25 insertions(+), 25 deletions(-)
> >>
> >> -- 
> >> 2.17.1
> >>
> 

Re: [PATCH 0/3] Improve autodate.sh

[Paul E. McKenney]

On Tue, Dec 31, 2019 at 07:06:11PM -0800, Paul E. McKenney wrote:
> On Wed, Jan 01, 2020 at 08:36:24AM +0900, Akira Yokosawa wrote:
> > On Mon, 30 Dec 2019 16:06:27 -0800, Paul E. McKenney wrote:

[ . . . ]

> > As mentioned above, I'm OK with keeping the current behavior.
> > Adding some namespaces to .gitignore might be a better approach,
> > but it is not urgent at all.
> 
> As noted earlier, this sounds good to me!  One approach would be to
> add the experimental directory and a README within it, with the README
> describing the purpose.  Then a .gitignore in that same directory could
> ignore all but the README.  But maybe you have a better idea.

Another possibility would be for your tests to direct output somewhere
outside of the perfbook source tree, if that would work reasonably.

							Thanx, Paul