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

.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 [email protected]
.It
.An Dorinda Bassey Aq Mt [email protected]
.It
.An Matias Ezequiel Vara Larsen Aq Mt [email protected]
.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

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 <[email protected]>
     Dorinda Bassey <[email protected]>
     Matias Ezequiel Vara Larsen <[email protected]>

     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.