pg_backupcluster/trixie is old

[crpb]

Hi, the documentation was fixed in trixie but sadly it isn't on the website.

Could you please recreate it?

https://manpages.debian.org/testing/postgresql-common/pg_backupcluster.1.en.html#FILES
https://manpages.debian.org/unstable/postgresql-common/pg_backupcluster.1.en.html#FILES

It is also still wrong in bookworm but for that we might need to poke @df7cb

[stapelberg]

I have started a full re-render run. It will be some hours until the updated files are available…

[stapelberg]

For some reason, the mandoc process exits (“signal: aborted (core dumped)”), but despite the message saying “core dumped”, I cannot locate a core file (kernel.core_pattern = core, the working directory is /tmp) :(

Not 100% sure how to best debug this further (I would love to have systemd-coredump on manziarly.debian.org, and enough access to use it), so there will be some delay in getting these files updated.

[stapelberg]

Luckily, the crash is reproducible on my other deployment. There, I get the following stack trace:

gdb $ backtrace
#0  0x000000000047535c in __pthread_kill_implementation.constprop.0 ()
#1  0x0000000000458398 in raise ()
#2  0x00000000004011ee in abort ()
#3  0x0000000000401116 in __assert_fail_base.cold ()
#4  0x0000000000453946 in __assert_fail ()
#5  0x00000000004037ae in print_otag (h=0xfc880c0, tag=TAG_TABLE, fmt=0x505784 "c") at html.c:644
#6  0x0000000000407680 in mdoc_nm_pre (meta=0xfc87e10, n=0xfc8d0f0, h=0xfc880c0) at mdoc_html.c:659
#7  0x0000000000406aee in print_mdoc_node (meta=0xfc87e10, n=0xfc8d0f0, h=0xfc880c0) at mdoc_html.c:421
#8  0x00000000004066f2 in print_mdoc_nodelist (meta=0xfc87e10, n=0xfc8d0f0, h=0xfc880c0) at mdoc_html.c:338
#9  0x0000000000406b62 in print_mdoc_node (meta=0xfc87e10, n=0xfe19500, h=0xfc880c0) at mdoc_html.c:432
#10 0x00000000004066f2 in print_mdoc_nodelist (meta=0xfc87e10, n=0xfe19500, h=0xfc880c0) at mdoc_html.c:338
#11 0x0000000000406b62 in print_mdoc_node (meta=0xfc87e10, n=0xfe19320, h=0xfc880c0) at mdoc_html.c:432
#12 0x00000000004066f2 in print_mdoc_nodelist (meta=0xfc87e10, n=0xfe19320, h=0xfc880c0) at mdoc_html.c:338
#13 0x0000000000406539 in html_mdoc (arg=0xfc880c0, mdoc=0xfc87e10) at mdoc_html.c:305
#14 0x000000000041d4fc in process (parser=0xfc876c0, outtype=OUTT_HTML, formatter=0xfc880c0) at mandocd.c:260
#15 0x000000000041d32c in main (argc=1, argv=0x7ffd68b54298) at mandocd.c:214

The manpage in question seems to be:

gdb $ frame 13
#13 0x0000000000406539 in html_mdoc (arg=0xfc880c0, mdoc=0xfc87e10) at mdoc_html.c:305
305     mdoc_html.c: No such file or directory.
gdb $ p *mdoc
$4 = {
  first = 0xfdf5410,
  msec = 0x10081e50 "3ossp",
  vol = 0x10081e70 "3ossp",
  os = 0xfd260f0 "ossp-uuid 1.6.4",
  arch = 0x0,
  title = 0x10081e30 "UUID",
  name = 0xfd260d0 "uuid",
  date = 0x10081e10 "December 9, 2024",
  sodest = 0x0,
  hasbody = 0,
  rcsids = 0,
  os_e = MANDOC_OS_OTHER,
  macroset = MACROSET_MDOC
}

Unfortunately, merely running mandoc(1) on that page seems to work fine, but running it through mandocd as debiman does doesn’t seem to work. More investigation needed…

[stapelberg]

At first, I thought this issue only reproduced with mandocd, but that turned out to be incorrect.

Nevertheless, I will leave the description of my earlier debugging attempt here just in case it helps with other debugging:

Extracting the (ordered) list of processed manpages per mandocd subprocess

I added a debug printf to debiman:

--- i/internal/convert/convert.go
+++ w/internal/convert/convert.go
@@ -4,6 +4,7 @@ import (
        "bytes"
        "fmt"
        "io"
+       "log"
        "net/url"
        "sort"
        "strings"
@@ -404,7 +405,8 @@ func postprocess(resolve func(ref string) string, n *html.Node, toc *[]string) e
 //
 // resolve, if non-nil, will be called to resolve a reference (like
 // “rm(1)”) into a URL.
-func (p *Process) ToHTML(r io.Reader, resolve func(ref string) string) (doc string, toc []string, err error) {
+func (p *Process) ToHTML(r io.Reader, fn string, resolve func(ref string) string) (doc string, toc []string, err error) {
+       log.Printf("DEBUG: p=%p ToHTML %s", p, fn)
        stdout, stderr, err := p.mandoc(r)
        if stderr != "" {
                return "", nil, fmt.Errorf("mandoc failed: %v", stderr)

Searching for 3ossp in the output yields all man pages and the addresses of the Process that handled the man page:

ex622 % grep DEBUG /tmp/full-rerender2.log | grep 3ossp
2025/05/06 18:13:03 convert.go:409: DEBUG: p=0xc001fc5f68 ToHTML /srv/man/www/bookworm/libossp-uuid-dev/uuid.3ossp.en.gz
2025/05/06 18:13:03 convert.go:409: DEBUG: p=0xc001fc5f68 ToHTML /srv/man/www/bookworm/libossp-uuid-dev/uuid++.3ossp.en.gz
2025/05/06 18:16:03 convert.go:409: DEBUG: p=0xc0061bb6c8 ToHTML /srv/man/www/testing/libossp-uuid-dev/uuid.3ossp.en.gz
2025/05/06 18:16:03 convert.go:409: DEBUG: p=0xc001fc5f68 ToHTML /srv/man/www/testing/libossp-uuid-dev/uuid++.3ossp.en.gz

So there’s two choices to try, 0xc001fc5f68 and 0xc0061bb6c8.

By grepping the log for these addresses, I get a list of manpages that were sent to mandocd(8) (in the exact order), which I then fed to this isolated reproducer program:

package main

import (
	"compress/gzip"
	"fmt"
	"io"
	"log"
	"os"
	"strings"

	"github.com/Debian/debiman/internal/convert"
)

func convertFile(converter *convert.Process, src string, resolve func(ref string) string) (doc string, toc []string, err error) {
	f, err := os.Open(src)
	if err != nil {
		return "", nil, err
	}
	defer f.Close()
	r, err := gzip.NewReader(f)
	if err != nil {
		if err == io.EOF {
			// TODO: better representation of an empty manpage
			return "This space intentionally left blank.", nil, nil
		}
		return "", nil, err
	}
	defer r.Close()
	out, toc, err := converter.ToHTML(r, resolve)
	if err != nil {
		return "", nil, fmt.Errorf("convert(%q): %v", src, err)
	}
	return out, toc, nil
}

func repro() error {
	b, err := io.ReadAll(os.Stdin)
	if err != nil {
		return err
	}
	filenames := strings.Split(strings.TrimSpace(string(b)), "\n")
	log.Printf("rendering %d man pages", len(filenames))

	converter, err := convert.NewProcess()
	if err != nil {
		return err
	}
	defer converter.Kill()

	for _, fn := range filenames {
		_, _, err := convertFile(converter, fn, func(ref string) string {
			return ""
		})
		if err != nil {
			return fmt.Errorf("rendering %s failed: %v", fn, err)
		}
	}

	return nil
}

func main() {
	if err := repro(); err != nil {
		log.Fatal(err)
	}
}

And indeed, this reproduces the crash!

ex622 % grep p=0xc0061bb6c8 full-rerender2.log | gre 'ToHTML (.*)' | PATH=/srv/man/bin:$PATH /tmp/repro
2025/05/06 18:18:47 rendering 50454 man pages
2025/05/06 18:19:46 mandoc unexpectedly exited: signal: aborted (core dumped)

(end of old debugging description)

While running mandoc on the offending man page seems to work:

ex622 % /srv/man/bin/mandoc /srv/man/www/testing/libossp-uuid-dev/uuid.3ossp.en.gz
UUID(3ossp)                          3ossp                         UUID(3ossp)

NAME
     uuid – Universally Unique IDentifier

SYNOPSIS
     #include <uuid.h>

     cc $(pkg-config --libs --cflags ossp-uuid) ...

DESCRIPTION
[…]

…printing the page to HTML does not work:

ex622 % /srv/man/bin/mandoc -Thtml /srv/man/www/testing/libossp-uuid-dev/uuid.3ossp.en.gz
<!DOCTYPE html>
<html>
<!-- This is an automatically generated file.  Do not edit.
   e
    OSSP uuid - Universally Unique Identifier
    Copyright (c) 2004-2008 Ralf S. Engelschall <rse@engelschall.com>
    Copyright (c) 2004-2008 The OSSP Project <http://www.ossp.org/>
  
    This file is part of OSSP uuid, a library for the generation
    of UUIDs which can found at http://www.ossp.org/pkg/lib/uuid/
  
    Permission to use, copy, modify, and distribute this software for
    any purpose with or without fee is hereby granted, provided that
    the above copyright notice and this permission notice appear in all
    copies.
  
    THIS SOFTWARE IS PROVIDED ``AS IS'' AND ANY EXPRESSED OR IMPLIED
    WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
    MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
    IN NO EVENT SHALL THE AUTHORS AND COPYRIGHT HOLDERS AND THEIR
    CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
    SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
    LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF
    USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND
    ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
    OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT
    OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
    SUCH DAMAGE.
   -->
<head>
  <meta charset="utf-8"/>
  <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
  <style>
    table.head, table.foot { width: 100%; }
    td.head-rtitle, td.foot-os { text-align: right; }
    td.head-vol { text-align: center; }
    .Nd, .Bf, .Op { display: inline; }
    .Pa, .Ad { font-style: italic; }
    .Ms { font-weight: bold; }
    .Bl-diag > dt { font-weight: bold; }
    code.Nm, .Fl, .Cm, .Ic, code.In, .Fd, .Fn, .Cd { font-weight: bold;
      font-family: inherit; }
  </style>
  <title>UUID(3ossp)</title>
</head>
<body>
<table class="head">
  <tr>
    <td class="head-ltitle">UUID(3ossp)</td>
    <td class="head-vol">3ossp</td>
    <td class="head-rtitle">UUID(3ossp)</td>
  </tr>
</table>
<div class="manual-text">
<section class="Sh">
<h1 class="Sh" id="NAME"><a class="permalink" href="#NAME">NAME</a></h1>
<p class="Pp"><code class="Nm">uuid</code> &#x2014; <span class="Nd">Universally
    Unique IDentifier</span></p>
</section>
<section class="Sh">
<h1 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h1>
<p class="Pp"><code class="In">#include
  &lt;<a class="In">uuid.h</a>&gt;</code></p>
mandoc: html.c:644: print_otag: Assertion `(htmltags[t->tag].flags & HTML_TOPHRASE) == 0' failed.
zsh: IOT instruction (core dumped)  /srv/man/bin/mandoc -Thtml 

Let’s see if we can minimize the man page! This seems to be the minimal contents I need to make mandoc crash:

.Dd December  9, 2024
.ds doc-volume-operating-system OSSP
.Dt UUID 3ossp
.Os ossp-uuid 1.6.4
.
.Sh SYNOPSIS
.In uuid.h
.Nm foobar
.

Dumping the structure with mandoc -Ttree, I see:

midna % mandoc -Ttree minimal.gz 
title = "UUID"
name  = "foobar"
sec   = "3ossp"
vol   = "3ossp"
os    = "ossp-uuid 1.6.4"
date  = "December 9, 2024"

Dd (elem) *1:2 NOPRT
    December 9, 2024 (text) 1:5
Dt (elem) *3:2 NOPRT
    UUID (text) 3:5
    3ossp (text) 3:10
Os (elem) *4:2 NOPRT
    ossp-uuid (text) 4:5
    1.6.4 (text) 4:15
Sh (block) *6:2
  Sh (head) 6:2 ID=HREF
      SYNOPSIS (text) 6:5
  Sh (body) 6:2
      In (elem) *7:2
          uuid.h (text) 7:5
      Nm (block) *8:2
        Nm (head) 8:2
            foobar (text) 8:5
        Nm (body) 8:2

…and when printing to HTML, processing stops right after the .In line:

midna ~ % mandoc -Thtml minimal.gz     
<!DOCTYPE html>
<html>
<head>
  <meta charset="utf-8"/>
  <meta name="viewport" content="width=device-width, initial-scale=1.0"/>
  <style>
    table.head, table.foot { width: 100%; }
    td.head-rtitle, td.foot-os { text-align: right; }
    td.head-vol { text-align: center; }
    .Nd, .Bf, .Op { display: inline; }
    .Pa, .Ad { font-style: italic; }
    .Ms { font-weight: bold; }
    .Bl-diag > dt { font-weight: bold; }
    code.Nm, .Fl, .Cm, .Ic, code.In, .Fd, .Fn, .Cd { font-weight: bold;
      font-family: inherit; }
  </style>
  <title>UUID(3ossp)</title>
</head>
<body>
<div class="head" role="doc-pageheader" aria-label="Manual header
  line"><span class="head-ltitle">UUID(3ossp)</span>
  <span class="head-vol">3ossp</span>
  <span class="head-rtitle">UUID(3ossp)</span></div>
<main class="manual-text">
<section class="Sh">
<h2 class="Sh" id="SYNOPSIS"><a class="permalink" href="#SYNOPSIS">SYNOPSIS</a></h2>
<p class="Pp"><code class="In">#include
  &lt;<a class="In">uuid.h</a>&gt;</code></p>
mandoc: html.c:650: print_otag: Assertion `(htmltags[t->tag].flags & HTML_TOPHRASE) == 0' failed.
zsh: IOT instruction (core dumped)  /home/michael/src/mandoc-cvs-2025-05-06/mandoc/mandoc -Thtml minimal.gz

At this point, I think I have enough to send a report to the mandoc developers.

Update: I reported this issue to the mandoc folks over at https://inbox.vuxu.org/mandoc-discuss/CANnVG6mGKTxTpwygzT0vN2PmswjiELuH5=A+6WkADzt3ByfNww@mail.gmail.com/T/#u