From ecff59d77371b21fef229c33ebb629bc49a8fad5 Mon Sep 17 00:00:00 2001
From: sternenseemann <sternenseemann@systemli.org>
Date: Wed, 23 Jul 2025 23:31:45 +0200
Subject: [PATCH] libcmd: add support for lowdown >= 1.4

lowdown 1.4.0 changed the lowdown_opts to include a new and separate
lowdown_opts_term which allows for configuring values specific to
-Tterm (which we're using). This version should have been called 2.0.0
according to semver, hence 2.0.0 was released later without any actual
breaking changes to sort of migitate the problem.

We need to support lowdown >= 1.3 && < 1.4 since the ship has sailed for
updating lowdown in NixOS 25.05 as well as lowdown >= 1.4 or we'll be
stuck in Nixpkgs forever. Support for < 1.4 can be dropped as soon as
NixOS 25.05 is EOL, assuming this change lands before NixOS 25.11
branch-off.

We detect the changed API based on the lowdown version from pkg-config
and define LOWDOWN_SEPARATE_TERM_OPTS based on that. The ifdef is named
according to the specific API change that impacts us, so that it's
hopefully a little simpler to maintain going forward. In the new API,
all newly configurable settings use what would have been the (implicit)
default before. Changing some of these values, especially hpadding,
could be interesting in future changes.

Compared to cl/3081, this change makes sure to initialize all new fields
of lowdown_opts_term explicitly.

It seems that, while making -Tterm more configurable, lowdown's word
wrapping behavior changed slightly which broke basic_repl.test. I've
chosen to work around this by using builtins.add as an example which has
a very short documentation string, so wrapping doesn't matter.

Change-Id: Id73be4c0e43d7eb4f56e10a261b4254402698ff8
(cherry picked from commit 858de5f47a1bfd33835ec97794ece339a88490f1)
---
 meson.build                                   |  5 +++++
 src/libcmd/markdown.cc                        | 19 +++++++++++++++++--
 .../data/basic_repl.test                      |  9 ++++-----
 3 files changed, 26 insertions(+), 7 deletions(-)

diff --git a/meson.build b/meson.build
index 4297703eb..ef28cfd0a 100644
--- a/meson.build
+++ b/meson.build
@@ -301,6 +301,11 @@ editline = dependency('libeditline', 'editline', version : '>=1.14', required :
 
 lowdown = dependency('lowdown', version : '>=0.9.0', required : true, include_type : 'system')
 
+# TODO(sterni): drop the corresponding #ifdef after NixOS 25.05 is EOL which still distributes lowdown < 1.4.0
+if lowdown.version().version_compare('>= 1.4.0')
+  add_project_arguments('-DLOWDOWN_SEPARATE_TERM_OPTS', language: 'cpp')
+endif
+
 # HACK(Qyriad): rapidcheck's pkg-config doesn't include the libs lol
 # Note: technically we 'check' for rapidcheck twice, for the internal-api-docs handling above,
 # but Meson will cache the result of the first one, and the required : arguments are different.
diff --git a/src/libcmd/markdown.cc b/src/libcmd/markdown.cc
index dbaab8c19..c1b32b43c 100644
--- a/src/libcmd/markdown.cc
+++ b/src/libcmd/markdown.cc
@@ -11,13 +11,28 @@ namespace nix {
 std::string renderMarkdownToTerminal(std::string_view markdown)
 {
     int windowWidth = getWindowSize().second;
+    size_t lowdown_cols = std::max(windowWidth - 5, 60);
 
-    struct lowdown_opts opts {
+    struct lowdown_opts opts{
         .type = LOWDOWN_TERM,
+#ifdef LOWDOWN_SEPARATE_TERM_OPTS
+        .term =
+            {
+                .cols = lowdown_cols,
+                .width = 0,
+                .hmargin = 0,
+                .hpadding = 4,
+                .vmargin = 0,
+                .centre = 0,
+            },
+        // maxdepth needs to be part of the ifdefs to match declaration order
         .maxdepth = 20,
-        .cols = (size_t) std::max(windowWidth - 5, 60),
+#else
+        .maxdepth = 20,
+        .cols = lowdown_cols,
         .hmargin = 0,
         .vmargin = 0,
+#endif /* LOWDOWN_SEPARATE_TERM_OPTS */
         .feat = LOWDOWN_COMMONMARK | LOWDOWN_FENCED | LOWDOWN_DEFLIST | LOWDOWN_TABLES,
         .oflags = LOWDOWN_TERM_NOLINK,
     };
diff --git a/tests/functional/repl_characterization/data/basic_repl.test b/tests/functional/repl_characterization/data/basic_repl.test
index a8dea6d7c..51cdb6fec 100644
--- a/tests/functional/repl_characterization/data/basic_repl.test
+++ b/tests/functional/repl_characterization/data/basic_repl.test
@@ -1,12 +1,11 @@
   nix-repl> 1 + 1
   2
 
-  nix-repl> :doc builtins.head
-  Synopsis: builtins.head list
+  nix-repl> :doc builtins.add
+  Synopsis: builtins.add e1 e2
+
+      Return the sum of the numbers e1 and e2.
 
-      Return the first element of a list; abort evaluation if
-      the argument isn’t a list or is an empty list. You can
-      test whether a list is empty by comparing it with [].
 
   nix-repl> f = a: "" + a