lxc manpage <target>: Lots of go-md2man warnings

[ackalker]

Required information

• Distribution: Void Linux x86_64 (glibc)
• Distribution version: Rolling release
• The output of "lxc info" or if that fails:
  • Kernel version:
  • LXC version:
  • LXD version:
  • Storage backend in use:

$ lxc info
config: {}
api_extensions:
- storage_zfs_remove_snapshots
- container_host_shutdown_timeout
- container_stop_priority
- container_syscall_filtering
- auth_pki
- container_last_used_at
- etag
- patch
- usb_devices
- https_allowed_credentials
- image_compression_algorithm
- directory_manipulation
- container_cpu_time
- storage_zfs_use_refquota
- storage_lvm_mount_options
- network
- profile_usedby
- container_push
- container_exec_recording
- certificate_update
- container_exec_signal_handling
- gpu_devices
- container_image_properties
- migration_progress
- id_map
- network_firewall_filtering
- network_routes
- storage
- file_delete
- file_append
- network_dhcp_expiry
- storage_lvm_vg_rename
- storage_lvm_thinpool_rename
- network_vlan
- image_create_aliases
- container_stateless_copy
- container_only_migration
- storage_zfs_clone_copy
- unix_device_rename
- storage_lvm_use_thinpool
- storage_rsync_bwlimit
- network_vxlan_interface
- storage_btrfs_mount_options
- entity_description
- image_force_refresh
- storage_lvm_lv_resizing
- id_map_base
- file_symlinks
- container_push_target
- network_vlan_physical
- storage_images_delete
- container_edit_metadata
- container_snapshot_stateful_migration
- storage_driver_ceph
- storage_ceph_user_name
- resource_limits
- storage_volatile_initial_source
- storage_ceph_force_osd_reuse
- storage_block_filesystem_btrfs
- resources
- kernel_limits
- storage_api_volume_rename
- macaroon_authentication
- network_sriov
- console
- restrict_devlxd
- migration_pre_copy
- infiniband
- maas_network
- devlxd_events
- proxy
- network_dhcp_gateway
- file_get_symlink
- network_leases
- unix_device_hotplug
- storage_api_local_volume_handling
- operation_description
- clustering
- event_lifecycle
- storage_api_remote_volume_handling
- nvidia_runtime
- container_mount_propagation
- container_backup
- devlxd_images
- container_local_cross_pool_handling
- proxy_unix
- proxy_udp
- clustering_join
- proxy_tcp_udp_multi_port_handling
- network_state
- proxy_unix_dac_properties
- container_protection_delete
- unix_priv_drop
- pprof_http
- proxy_haproxy_protocol
- network_hwaddr
- proxy_nat
- network_nat_order
- container_full
- candid_authentication
- backup_compression
- candid_config
- nvidia_runtime_config
- storage_api_volume_snapshots
- storage_unmapped
- projects
- candid_config_key
- network_vxlan_ttl
- container_incremental_copy
- usb_optional_vendorid
- snapshot_scheduling
- container_copy_project
- clustering_server_address
- clustering_image_replication
- container_protection_shift
- snapshot_expiry
- container_backup_override_pool
- snapshot_expiry_creation
- network_leases_location
- resources_cpu_socket
- resources_gpu
- resources_numa
- kernel_features
- id_map_current
- event_location
- storage_api_remote_volume_snapshots
- network_nat_address
- container_nic_routes
- rbac
- cluster_internal_copy
- seccomp_notify
- lxc_features
- container_nic_ipvlan
- network_vlan_sriov
- storage_cephfs
- container_nic_ipfilter
- resources_v2
- container_exec_user_group_cwd
- container_syscall_intercept
- container_disk_shift
- storage_shifted
- resources_infiniband
- daemon_storage
- instances
- image_types
- resources_disk_sata
- clustering_roles
- images_expiry
- resources_network_firmware
- backup_compression_algorithm
- ceph_data_pool_name
- container_syscall_intercept_mount
- compression_squashfs
- container_raw_mount
- container_nic_routed
- container_syscall_intercept_mount_fuse
- container_disk_ceph
- virtual-machines
- image_profiles
- clustering_architecture
- resources_disk_id
- storage_lvm_stripes
- vm_boot_priority
- unix_hotplug_devices
- api_filtering
- instance_nic_network
- clustering_sizing
- firewall_driver
- projects_limits
- container_syscall_intercept_hugetlbfs
- limits_hugepages
- container_nic_routed_gateway
- projects_restrictions
- custom_volume_snapshot_expiry
- volume_snapshot_scheduling
- trust_ca_certificates
- snapshot_disk_usage
- clustering_edit_roles
- container_nic_routed_host_address
- container_nic_ipvlan_gateway
- resources_usb_pci
- resources_cpu_threads_numa
- resources_cpu_core_die
- api_os
- container_nic_routed_host_table
- container_nic_ipvlan_host_table
- container_nic_ipvlan_mode
- resources_system
- images_push_relay
- network_dns_search
- container_nic_routed_limits
- instance_nic_bridged_vlan
- network_state_bond_bridge
- usedby_consistency
- custom_block_volumes
api_status: stable
api_version: "1.0"
auth: trusted
public: false
auth_methods:
- tls
environment:
  addresses: []
  architectures:
  - x86_64
  - i686
  certificate: |
    -----BEGIN CERTIFICATE-----
    <REDACTED>
    -----END CERTIFICATE-----
  certificate_fingerprint: <REDACTED>
  driver: lxc
  driver_version: 4.0.2
  firewall: xtables
  kernel: Linux
  kernel_architecture: x86_64
  kernel_features:
    netnsid_getifaddrs: "true"
    seccomp_listener: "true"
    seccomp_listener_continue: "true"
    shiftfs: "false"
    uevent_injection: "true"
    unpriv_fscaps: "true"
  kernel_version: 5.7.14_1
  lxc_features:
    cgroup2: "true"
    mount_injection_file: "true"
    network_gateway_device_route: "true"
    network_ipvlan: "true"
    network_l2proxy: "true"
    network_phys_macvlan_mtu: "true"
    network_veth_router: "true"
    pidfd: "false"
    seccomp_notify: "true"
  os_name: void
  os_version: ""
  project: default
  server: lxd
  server_clustered: false
  server_name: <REDACTED>
  server_pid: 20651
  server_version: "4.3"
  storage: btrfs
  storage_version: "5.7"

Issue description

I wanted to test generating man pages for the various lxc commands, as my distribution doesn't supply those, so I created a temporary directory and used the lxc manpage command with that directory as target.
Although this appeared to generate man pages, I received a couple of dozen warnings of the form:

WARNING: go-md2man does not handle node type HTMLSpan

I expected the process to complete without any warnings.

Steps to reproduce

1. Create a temporary directory:
   mkdir /tmp/lxc-man
2. Ask lxc to generate man pages and store them in the temporary directory:
   lxc manpage /tmp/lxc-man
3. Check for any warnings.

Information to attach

• Any relevant kernel output (dmesg)
• Container log (lxc info NAME --show-log)
• Container configuration (lxc config show NAME --expanded)
• Main daemon log (at /var/log/lxd/lxd.log or /var/snap/lxd/common/lxd/logs/lxd.log)
• Output of the client with --debug
• Output of the daemon with --debug (alternatively output of lxc monitor while reproducing the issue)

[ackalker]

The issue looks similar to spf13/cobra#1137. That issue was closed by upstream as expected behavior, recommending a change in notation.

[stgraber]

Yeah, that's not really going to work for us as we have things like this:

lxc copy [<remote>:]<source>[/<snapshot>] [[<remote>:]<destination>] [flags]

<blah> is used for user input, [] is used to indicate an optional part of the command line, other characters listed are mandatory.

So in the example above : and / are mandatory characters.

Removing the <> within the [] blocks would look like:

lxc copy [remote:]<source>[/snapshot] [[remote:]destination] [flags]

Making it much harder to figure out what's the actual user input and what's needed, also making it inconsistent with args outside of optional blocks.

Making things consistent would then look like:

lxc copy [remote:]source[/snapshot] [[remote:]destination] [flags]

Which is even more confusing to me.

I'd certainly prefer for a fix in go-md2man to sort out escaping in such cases as manpages themselves are clearly able to store such syntax (man git for an example). As far as LXD is concerned, we care about our --help output more than we do manpages so we're not going to change syntax over this.

[ackalker]

@stgraber
I found out that cpuguy83/go-md2man (used by spf13/cobra) offers a solution to the problem by supporting HTML entities (such as < for < and > for >), see cpuguy83/go-md2man#11 (note: the issue title is a bit misleading). Required changes to lxd code should be minimal.

[stgraber]

Going through the linked issue in moby, they're using go-md2man directly rather than having spf13 spit out markdown which is then turned into a man page. LXD never directly imports go-md2man and so doesn't really have any control over that part so I'm not seeing any way for us to opt into the HTML entities support here.