[bug#51332] [PATCH 0/2] Detect early and gracefully handle invalid Texinfo

["Ludovic Courtès" <ludo@gnu.org>]

Hello!

It’s a fact that we occasionally push invalid Texinfo markup in
package descriptions/synopses, probably even more so in external
channels, and despite the fact that ‘guix lint’ flags it.

The problem is that some of the tools were designed around the idea
that invalid Texinfo “does not happen”.  For example, if a single
package contains invalid markup, ‘guix search’ and ‘guix show’ crash
badly:

--8<---------------cut here---------------start------------->8---
$ guix search ghc citations
name: ghc-citeproc
version: 0.4.0.1
outputs: out
systems: x86_64-linux i686-linux
dependencies: ghc-aeson-pretty@0.8.8 ghc-aeson@1.5.6.0 ghc-attoparsec@0.13.2.5
+ ghc-base-compat@0.11.2 ghc-case-insensitive@1.2.1.0 ghc-data-default@0.7.1.1 ghc-diff@0.4.0
+ ghc-file-embed@0.0.15.0 ghc-pandoc-types@1.22 ghc-safe@0.3.19 ghc-scientific@0.3.7.0
+ ghc-timeit@2.0 ghc-unicode-collation@0.1.3 ghc-uniplate@1.6.13 ghc-vector@0.12.3.0
+ ghc-xml-conduit@1.9.1.1
location: gnu/packages/haskell-xyz.scm:15823:2
homepage: https://hackage.haskell.org/package/citeproc
license: FreeBSD
synopsis: Generate citations and bibliography from CSL styles  
Backtrace:
          13 (primitive-load "/home/ludo/.config/guix/current/bin/gu…")
In guix/ui.scm:
   2185:7 12 (run-guix . _)
  2148:10 11 (run-guix-command _ . _)
In ice-9/boot-9.scm:
  1752:10 10 (with-exception-handler _ _ #:unwind? _ # _)
In guix/scripts/package.scm:
    896:9  9 (_)
In ice-9/boot-9.scm:
  1747:15  8 (with-exception-handler #<procedure 7fb7f469a6c0 at ic…> …)
In guix/ui.scm:
  1677:23  7 (call-with-paginated-output-port _ #:less-options _)
  1712:11  6 (_ #<output: #{write pipe}# 15>)
  1558:14  5 (package->recutils _ #<output: #{write pipe}# 15> _ # _ …)
  1432:23  4 (texi->plain-text _)
In texinfo.scm:
  1132:22  3 (parse _)
   967:36  2 (loop #<input: string 7fb7f4a4bc40> (*fragment*) #<pro…> …)
     92:2  1 (command-spec _)
In ice-9/boot-9.scm:
  1685:16  0 (raise-exception _ #:continuable? _)

ice-9/boot-9.scm:1685:16: In procedure raise-exception:
Throw to key `parser-error' with args `(#f "Unknown command" urefhttps)'.
--8<---------------cut here---------------end--------------->8---

(This one was fixed in c3c502896b1454b345ee9f17d20063853652a35a.)

This series does two things:

  1. Emit a warning when invalid markup is encountered but keep going.

  2. Raise a syntax error, at macro-expansion time, when invalid markup
     is encountered.

Obviously #2 incurs some overhead, since it parses Texinfo strings at
expansion time, so it’s enabled only when ‘GUIX_UNINSTALLED’ is set—that
is, when working on a checkout with ./pre-inst-env.  The expanded code
is exactly the same as before though, without any overhead.  Concretely,
that means that ‘make’ fail and you just don’t see the package until
the error has been fixed:

--8<---------------cut here---------------start------------->8---
$ make
[…]
[ 78%] LOAD     gnu/packages/haskell-xyz.scm
;;; note: source file ./gnu/packages/haskell-xyz.scm
;;;       newer than compiled /home/ludo/src/guix/gnu/packages/haskell-xyz.go
;;; note: source file ./gnu/packages/haskell-xyz.scm
;;;       newer than compiled /home/ludo/src/guix/gnu/packages/haskell-xyz.go
gnu/packages/haskell-xyz.scm:15855:5: error: "@code{ghc-citeproc} parses @acronym{Citation Style Language, CSL} style files\nand uses them to generate a list of formatted citations and bibliography\nentries.  For more information about CSL, see @urefhttps://citationstyles.org/}.": invalid Texinfo markup
make[2]: *** [Makefile:7131: make-packages-go] Error 1
--8<---------------cut here---------------end--------------->8---

Feedback welcome!

Ludo’.

Ludovic Courtès (2):
  ui: Gracefully handle invalid Texinfo markup in package blurbs.
  packages: Optionally validate Texinfo markup at expansion time.

 guix/packages.scm | 52 ++++++++++++++++++++++++++++++++++++++++++++---
 guix/ui.scm       | 17 ++++++++++++++--
 2 files changed, 64 insertions(+), 5 deletions(-)


base-commit: e1261ddd38cf02a0f046f3a5360502d659b4e7d4
-- 
2.33.0