#1053885 manpages generation for many commands is flawed

Package:
src:lxd
Source:
src:lxd
Submitter:
Osamu Aoki
Date:
2023-10-30 05:09:03 UTC
Severity:
normal
Tags:
#1053885#5
Date:
2023-10-13 14:47:35 UTC
From:
To:
Problem:

Manpages of lxd-client are sometimes unintelligible.  For example:

```
$ man lxc launch
LXD - Command line client(1)                       LXD - Command line client(1)

NAME
       lxc-launch - Create and start instances from images

SYNOPSIS
       lxc launch [:] [:][] [flags]
...
Auto generated by spf13/cobra  May 2023  LXD - Command line client(1)
```

Please compare odd SYNOPSIS in the above manpage with `-h` option result
of the command as below..

```
$ lxc launch -h
Description:
  Create and start instances from images

Usage:
  lxc launch [<remote>:]<image> [<remote>:][<name>] [flags]
...
```

Proposed interim fix:

Add README.Debian for affected binary packages mentioning manpaage
problem and guide people to use `-h` option with command to get
intelligible help.

Speculated root cause and fix path:

As noted at the bottom of manpage, this is generated from help message
of the corresponding command.  I don't know how exacly it process help
message but it processing seems to drop words between "<" and ">".

If plain text markup is converted to XML and then passed to xml2man or
xmlto type processor, this kind of problem may happen unless "<" and ">"
are escaped properly before their processing.

I understand this is upstream problem but I don't know where to send
this bug report due to lxd and incus situation.  This is probably needs
fix to the manpage generation script or rewrite all manpage without
problematic "<" and ">".

Osamu
#1053885#10
Date:
2023-10-30 03:12:06 UTC
From:
To:
Hi Osamu,

  Thanks for noticing and reporting this. I've looked into it a bit,
and I think it would be appropriate to report this to the spf13/cobra
project[0]. From my reading of the LXD/Incus use of the library, I
don't think they're doing anything "special" that would affect the
behavior generating the manpages. If you do report it there, we can re-
assign this bug to src:golang-github-spf13-cobra.

Mathias

[0] -- https://github.com/spf13/cobra
#1053885#15
Date:
2023-10-30 05:07:14 UTC
From:
To:
control: reassign -1 src:golang-github-spf13-cobra
thanks

Hi,

Thanks for your assessment.  I had the same feeling but wasn't sure on build
process.  Let's reassign this.