Re: PG 18 relnotes and RC1

[Tom Lane]

I wrote:
> If we're okay with items not having credits, then
> add_commit_links.pl's logic for where to put the <ulink>s needs
> improvement.  I don't really understand why it's looking for
> parens in the first place -- why isn't the rule simply "put them
> before the first </para> in the item"?

I revised the script to do it that way, as attached.  The results
don't change in any of our stable branches.  In v18, it makes
this change:

diff --git a/doc/src/sgml/release-18.sgml b/doc/src/sgml/release-18.sgml
index c3e318dab00..c49eb2655eb 100644
--- a/doc/src/sgml/release-18.sgml
+++ b/doc/src/sgml/release-18.sgml
@@ -284,7 +284,7 @@ Author: Peter Eisentraut <pe...@eisentraut.org>
     database clusters using pg_upgrade, it is recommended to reindex all
     indexes related to full-text search and pg_trgm after the upgrade.
 
-    <ulink url="&commit_baseurl;fb1a18810f0">&sect;</ulink>
+<ulink url="&commit_baseurl;fb1a18810f0">&sect;</ulink>
     </para>
     </listitem>

because of the blank line before the </para>, which is not our usual
style and should be removed IMO.  (Alternatively, we could change
the $prev_leading_space updating logic to ignore blank lines.)

                        regards, tom lane


diff --git a/src/tools/add_commit_links.pl b/src/tools/add_commit_links.pl
index 710a6492032..6dda0abcd29 100755
--- a/src/tools/add_commit_links.pl
+++ b/src/tools/add_commit_links.pl
@@ -20,12 +20,13 @@
 #
 #  * File name contains the major version number preceded by a dash
 #    and followed by a period
-#  * Commit text is generated by src/tools/git_changelog
-#  * SGML comments around commit text start in the first column
-#  * The commit item title ends with an attribution that ends with
-#    a closing parentheses
-#  * previously added URL link text is unmodified
-#  * a "<para>" follows the commit item title
+#  * Commit-details text is generated by src/tools/git_changelog
+#  * SGML comment markers around commit details start in the first column
+#  * Any previously-added URL links are unmodified
+#
+# URL links will be inserted just before the first "</para>" in each
+# release note item.  They will be aligned to match the preceding line.
+# (Therefore, don't leave a blank line before that "</para>".)
 #
 # The major version number is used to select the commit hash for minor
 # releases.  An error will be generated if valid commits are found but
@@ -39,7 +40,7 @@ sub process_file
 	my $file = shift;
 
 	my $in_comment = 0;
-	my $prev_line_ended_with_paren = 0;
+	my $in_item = 0;
 	my $prev_leading_space = '';
 	my $lineno = 0;
 
@@ -50,6 +51,8 @@ sub process_file
 	# Get major version number from the file name.
 	$file =~ m/-(\d+)\./;
 	my $major_version = $1;
+	die "file name $file is not in the expected format\n"
+	  unless defined $major_version;
 
 	open(my $fh, '<', $file) || die "could not open file $file: $!\n";
 	open(my $tfh, '>', $tmpfile) || die "could not open file $tmpfile: $!\n";
@@ -58,7 +61,15 @@ sub process_file
 	{
 		$lineno++;
 
-		$in_comment = 1 if (m/^<!--/);
+		if (m/^<!--/)
+		{
+			if ($in_item)
+			{
+				print "failed to find where to add links at line $lineno\n";
+				exit(1);
+			}
+			$in_comment = 1;
+		}
 
 		# skip over commit links because we will add them below
 		next
@@ -80,36 +91,34 @@ sub process_file
 			  && push(@hashes, $hash);
 		}
 
-		if (!$in_comment && m{</para>})
+		if ($in_item && m{</para>})
 		{
-			if (@hashes)
+			for my $hash (@hashes)
 			{
-				if ($prev_line_ended_with_paren)
-				{
-					for my $hash (@hashes)
-					{
-						print $tfh
-						  "$prev_leading_space<ulink url=\"&commit_baseurl;$hash\">&sect;</ulink>\n";
-					}
-					@hashes = ();
-				}
-				else
-				{
-					print
-					  "hashes found but no matching text found for placement on line $lineno\n";
-					exit(1);
-				}
+				print $tfh
+				  "$prev_leading_space<ulink url=\"&commit_baseurl;$hash\">&sect;</ulink>\n";
 			}
+			@hashes = ();
+			$in_item = 0;
 		}
 
 		print $tfh $_;
 
-		$prev_line_ended_with_paren = m/\)\s*$/;
-
+		chomp;    # don't allow newline in $prev_leading_space
 		m/^(\s*)/;
 		$prev_leading_space = $1;
 
-		$in_comment = 0 if (m/^-->/);
+		if (m/^-->/)
+		{
+			$in_comment = 0;
+			$in_item = 1 if @hashes;
+		}
+	}
+
+	if ($in_item)
+	{
+		print "failed to find where to add links at line $lineno\n";
+		exit(1);
 	}
 
 	close($fh);