Re: PG 18 relnotes and RC1 - Mailing list pgsql-hackers

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 <peter@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">§</ulink>
+<ulink url="&commit_baseurl;fb1a18810f0">§</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\">§</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\">§</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);