Add man page for `vhost-device-sound`

[sandrobonazzola]

A man page for vhost-device-sound has been prepared for Fedora packaging. It would be nice to get it included in the upstream project. The patch adding the man page is here: https://src.fedoraproject.org/rpms/rust-vhost-device-sound/blob/rawhide/f/man-page.patch

[epilys]

Hello, thanks for the suggestion! The patch says "Automatically generated by Pandoc 2.19.2", do you know what it was generated from?

Also, would an mdoc manual instead of troff be usable for Fedora?

[sandrobonazzola]

Hello, thanks for the suggestion! The patch says "Automatically generated by Pandoc 2.19.2", do you know what it was generated from?

@dorindabassey can you answer this one?

Also, would an mdoc manual instead of troff be usable for Fedora?

Fedora ships man-db for consulting man pages and according to https://gitlab.com/man-db/man-db it seems mdoc is supported.

[epilys]

I wrote a quick mdoc page:

`vhost-device-sound.1`

```mdoc .Dd July 19, 2024 .Dt VHOST-DEVICE-SOUND 1 .Os .Sh NAME .Nm vhost-device-sound .Nd A virtio-sound device implementation using the vhost-user protocol .Sh SYNOPSIS .Nm .Fl socket Ar SOCKET .Fl backend Ar BACKEND .Sh DESCRIPTION The .Nm utility launches a daemon listening to .Ar SOCKET for incoming connections from .Em vhost-user front-ends. Upon successful connection and protocol negotiation, it starts a vhost-user backend instance. The functionality of a VIRTIO sound device is provided using the specified audio backend, .Ar BACKEND Ns , as the host audio implementation. .sp .Bl -tag -width Ds .It Fl -help | h Print help information. .It Fl -version | V Print version information. .It Fl -socket Pa SOCKET Path for the created vhost-user Unix domain socket. .It Fl -backend Ar BACKEND Audio backend to be used. Possible values: .Bl -enum -compact -width 0 -offset 1n .It .Li pipewire .It .Li alsa .It .Li null .El .El .Sh EXIT STATUS .Ex -std .Sh EXAMPLES Launch the backend on the host machine: .Bd -literal host# vhost-device-sound --socket /tmp/snd.sock --backend alsa .Ed .sp With QEMU, you can add a .Li virtio device that uses the backend's socket with the following flags: .Bd -literal -chardev socket,id=vsnd,path=/tmp/snd.sock \\ -device vhost-user-snd-pci,chardev=vsnd,id=snd .Ed .Sh STANDARDS .Bl -dash -compact .It .Rs .%B Virtual I/O Device (VIRTIO) .%O Version 1.2 .%A OASIS .%U https://docs.oasis-open.org/virtio/virtio/v1.2/virtio-v1.2.html .%D July 01, 2022 .Re .It .Rs .%B Vhost-user Protocol .%O Unversioned .%A QEMU Project .%U https://qemu.readthedocs.io/en/v9.0.0/interop/vhost-user.html .%D Undated .Re .El .Sh AUTHORS Copyright 2023\(en2024 .Bl -item -compact .It .An Manos Pitsidianakis Aq Mt manos.pitsidianakis@linaro.org .It .An Dorinda Bassey Aq Mt dbassey@redhat.com .It .An Matias Ezequiel Vara Larsen Aq Mt mvaralar@redhat.com .El .Pp Released under Apache-2.0 OR BSD-3-Clause. .Po See files .Pa LICENSE-APACHE Ns , .Pa LICENSE-BSD-3-Clause for full copyright and warranty notices. .Pc .Ss Links .Bl -item -compact .It .Lk https://github.com/rust-vmm/vhost-device "Main\ repository" .It .Lk https://crates.io/crates/vhost-device-sound "on\ crates.io" .El ```

rendered with `mandoc -I os=General -Tutf8 ~/vhost-device-sound.1 | col -b` as plain text

```text VHOST-DEVICE-SOUND(1) General Commands Manual VHOST-DEVICE-SOUND(1) NAME vhost-device-sound – A virtio-sound device implementation using the vhost-user protocol SYNOPSIS vhost-device-sound -socket SOCKET -backend BACKEND DESCRIPTION The vhost-device-sound utility launches a daemon listening to SOCKET for incoming connections from vhost-user front-ends. Upon successful connection and protocol negotiation, it starts a vhost-user backend instance. The functionality of a VIRTIO sound device is provided using the specified audio backend, BACKEND, as the host audio implementation. --help | -h Print help information. --version | -V Print version information. --socket SOCKET Path for the created vhost-user Unix domain socket. --backend BACKEND Audio backend to be used. Possible values: 1. pipewire 2. alsa 3. null EXIT STATUS The vhost-device-sound utility exits 0 on success, and >0 if an error occurs. EXAMPLES Launch the backend on the host machine: host# vhost-device-sound --socket /tmp/snd.sock --backend alsa With QEMU, you can add a virtio device that uses the backend's socket with the following flags: -chardev socket,id=vsnd,path=/tmp/snd.sock \ -device vhost-user-snd-pci,chardev=vsnd,id=snd STANDARDS - OASIS, Virtual I/O Device (VIRTIO), https://docs.oasis-open.org/virtio/virtio/v1.2/virtio-v1.2.html, July 01, 2022, Version 1.2. - QEMU Project, Vhost-user Protocol, https://qemu.readthedocs.io/en/v9.0.0/interop/vhost-user.html, Undated, Unversioned. AUTHORS Copyright 2023–2024 Manos Pitsidianakis Dorinda Bassey Matias Ezequiel Vara Larsen Released under Apache-2.0 OR BSD-3-Clause. (See files LICENSE-APACHE, LICENSE-BSD-3-Clause for full copyright and warranty notices.) Links Main_repository: https://github.com/rust-vmm/vhost-device on_crates.io: https://crates.io/crates/vhost-device-sound General July 19, 2024 General ```

Would we prefer something like this instead of raw roff?

[sandrobonazzola]

I have no preference on the format, whatever is easier for the project to update if command line changes would work for me.

[dorindabassey]

Hello, thanks for the suggestion! The patch says "Automatically generated by Pandoc 2.19.2", do you know what it was generated from?

I wrote the man page in markdown here and translated it with Pandoc

Also, would an mdoc manual instead of troff be usable for Fedora?

either of these tools is fine with me.