From ddeaf8f0c7bf56c12889b9425f6825a8f974b9fa Mon Sep 17 00:00:00 2001
From: Greg Price <greg@zulip.com>
Date: Thu, 25 Sep 2025 19:25:00 -0700
Subject: [PATCH] tools/format-changelog: Upgrade line-unwrapping to handle
 nested lists

The `fmt` tool from GNU coreutils is very simple, and doesn't have the
needed configuration knobs to be able to handle the nested lists that
we now routinely use in changelog entries; it ends up mangling them.

As a result, for many recent releases I've been doing the reformatting
semi-manually, in Emacs: M-q to unwrap lines (after setting the text
width to 999), and then a regexp find-and-replace to turn references
`#1234` into `#F1234`.

It seems to be somewhat annoying to get Emacs to operate within a
shell pipeline.  But it's less annoying for Vim; and Vim's `gq`
works just as well as Emacs's M-q, given the right config.
So use that.
---
 tools/format-changelog | 24 +++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/tools/format-changelog b/tools/format-changelog
index 820440b05b..a977622ff0 100755
--- a/tools/format-changelog
+++ b/tools/format-changelog
@@ -31,7 +31,29 @@ extract_highlights() {
 
 # Undo line-wrapping.
 unwrap() {
-    fmt --tagged-paragraph --width=2000
+    # Implemented by rewrapping paragraphs in Vim.
+    # (Emacs works equally well, interactively; but seems more annoying
+    # to integrate into a CLI pipeline.)
+
+    local vim_markdown_settings=/usr/share/vim/vim90/ftplugin/markdown.vim
+    if [ ! -r "${vim_markdown_settings}" ]; then
+        # On Debian, this file is installed by the package `vim-runtime`.
+        # We can generalize this as needed to find where other systems put it.
+        # Upstream is here:
+        #   https://github.com/tpope/vim-markdown/blob/f9f845f28/ftplugin/markdown.vim
+        # The parts we actually use are the variables `comments`,
+        # `formatoptions`, and `formatlistpat`.
+        echo >&2 "error: Could not find spec for rewrapping Markdown."
+        echo >&2 "  See comments in the source code in tools/format-changelog."
+        exit 1
+    fi
+
+    # The Vim command "gq" rewraps paragraphs; "G" makes it do so
+    # from the current point to the end, and "gg" first goes to the start.
+    vim -es /dev/stdin \
+      '+set textwidth=2000' \
+      "+source ${vim_markdown_settings}" \
+      '+normal gggqG' '+%print' '+:q!'
 }
 
 # Print changelog entry, with line-wrapping removed.