From f28c32089d14303e2dd261009600478bc4ae0463 Mon Sep 17 00:00:00 2001
From: Gabriel Wicki <gabriel@erlikon.ch>
Date: Mon, 2 Dec 2024 23:36:44 +0100
Subject: [PATCH] lint: Allow texinfo markup at beginning of description.
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* guix/lint.scm(starts-with-texinfo-markup?): New function.
(check-description-style)[check-proper-start]: Add condition.
* tests/lint.scm: Add test case.

Change-Id: I674988882265d9e2041d48dba0f9627cd68bf292
Signed-off-by: Ludovic Courtès <ludo@gnu.org>
---
 guix/lint.scm  | 8 +++++++-
 tests/lint.scm | 5 +++++
 2 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/guix/lint.scm b/guix/lint.scm
index 63d101ebf98..d6d48ad27c5 100644
--- a/guix/lint.scm
+++ b/guix/lint.scm
@@ -370,6 +370,9 @@ superfluous when building natively and incorrect when cross-compiling."
 (define (properly-starts-sentence? s)
   (string-match "^[(\"'`[:upper:][:digit:]]" s))
 
+(define (starts-with-texinfo-markup? s)
+  (string-match "^@(acronym|dfn|code|command|emph|file|quotation|samp|uref|url)\\{.*?\\}" s))
+
 (define (starts-with-abbreviation? s)
   "Return #t if S starts with what looks like an abbreviation or acronym."
   (string-match "^[A-Z][A-Z0-9]+\\>" s))
@@ -447,6 +450,7 @@ trademark sign '~a' at ~d")
                                       'pre "-" 'post)))
       (if (or (string-null? description)
               (properly-starts-sentence? description)
+              (starts-with-texinfo-markup? description)
               (string-prefix-ci? first-word (package-name package))
               (string-suffix-ci? first-word (package-name package)))
           '()
@@ -513,7 +517,9 @@ by two spaces; possible infraction~p at ~{~a~^, ~}")
          (match (check-texinfo-markup description)
            ((and warning (? lint-warning?)) (list warning))
            (plain-description
-            (check-proper-start plain-description))))
+            (if (string-prefix? "@" description)
+                '()
+                (check-proper-start plain-description)))))
         (list
          (make-warning package
                        (G_ "invalid description: ~s")
diff --git a/tests/lint.scm b/tests/lint.scm
index 9297bfbaaca..df7042c4705 100644
--- a/tests/lint.scm
+++ b/tests/lint.scm
@@ -121,6 +121,11 @@
                              (description "bad description."))))
      (check-description-style pkg))))
 
+(test-equal "description: may start with texinfo markup"
+  '()
+  (check-description-style
+   (dummy-package "x" (description "@emph{Maxwell Equations of Software}"))))
+
 (test-equal "description: may start with a digit"
   '()
   (let ((pkg (dummy-package "x"