On Fri, Sep 13, 2024 at 12:39:28PM -0400, Bruce Momjian wrote:
> I applied this patch to PG 17. You can see the results at:
>
> https://momjian.us/pgsql_docs/release-17.html
>
> The community doc build only shows the master branch, which is PG 18,
> and the PG 17 docs are only built before the release.
>
> I changed the patch to use the section symbol "ยง" instead of showing
> the hashes. The hashes seemed too detailed. Does anyone see a better
> symbol to use from here?
>
> http://www.zipcon.net/~swhite/docs/computers/browsers/entities_page.html
>
> I think we are limited to the HTML entities listed on that page. I also
> removed the brackets and the period you added at the end of the text.
I wrote the attached Perl script that automatically adds commit links.
I tested it against PG 12-17 and the results were good. I plan to add
this script to all branches and run it on all branch release notes in a
few days.
--
Bruce Momjian <[email protected]> https://momjian.us
EDB https://enterprisedb.com
When a patient asks the doctor, "Am I going to die?", he means
"Am I going to die soon?"
#! /usr/bin/perl
#################################################################
# add_commit_links.pl -- add commit links to the release notes
#
# Copyright (c) 2024, PostgreSQL Global Development Group
#
# src/tools/add_commit_links.pl
#################################################################
#
# This script adds commit links to the release notes.
#
# Usage: cd to top of source tree and issue
# src/tools/add_commit_links.pl release_notes_file
#
# The script can add links for release note items that lack them, and update
# those that have them. The script is sensitive to the release note file being
# in a specific format:
#
# * 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
#
# 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
# no proper location for the commit links is found.
use strict;
use warnings FATAL => 'all';
if (@ARGV != 1)
{
printf(STDERR "Usage: %s release_notes_file\n", $0);
exit(1);
}
my $in_comment = 0;
my $prev_line_ended_with_paren = 0;
my $prev_leading_space = '';
my $lineno = 0;
my @hashes = ();
my $file = shift @ARGV;
my $tmpfile = $file . ".tmp";
# Get major version number from the file name.
$file =~ m/-([0-9]+)\./;
my $major_version = $1;
open(my $fh, '<', $file) || die "could not open file %s: $!\n", $file;
open(my $tfh, '>', $tmpfile) || die "could not open file %s: $!\n", $tmpfile;
while (<$fh>)
{
$lineno++;
$in_comment = 1 if (m/^<!--/);
# skip over commit links because we will add them below
next
if (!$in_comment &&
m{^\s*<ulink url="&commit_baseurl;[0-9a-f]+">§</ulink>\s*$});
if ($in_comment && m/\[([0-9a-f]+)\]/)
{
my $hash = $1;
# major release item
(!m/^Branch:/) && push(@hashes, $hash);
# minor release item
m/^Branch:/ &&
defined($major_version) &&
m/_${major_version}_/ &&
push(@hashes, $hash);
}
if (!$in_comment && m{</para>})
{
if (@hashes && $prev_line_ended_with_paren)
{
for my $hash (@hashes)
{
print({$tfh}
"$prev_leading_space<ulink url=\"&commit_baseurl;$hash\">§</ulink>\n"
);
}
}
# clear if we had links or already output links
if ($prev_line_ended_with_paren)
{
@hashes = ();
}
elsif (@hashes)
{
printf(
"hashes found but no previous links or matching text found for placement on line %s\n",
$lineno);
exit(1);
}
}
print({$tfh} $_);
$prev_line_ended_with_paren = m/\)\s*$/;
m/^(\s*)/;
$prev_leading_space = $1;
$in_comment = 0 if (m/^-->/);
}
close($fh);
close($tfh);
rename($tmpfile, $file) || die "could not rename %s to %s: $!\n", $tmpfile,
$file;
