Add more information about Bluetooth usage.

The patch shows how to create a remote device connection and
how to manage devices in /etc/bluetooth/hosts.  The multimedia
chapter was extended with a description on how to set up and
connect a Bluetooth audio device as a sound sink.
It also adds man page references to man-refs.ent for hcsecd(8)
and virtual_oss(8), respectively.

I cleaned up the patch a bit for consistency and proper markup.

PR:			    228879
Submitted by:		    nekoxmachina@gmail.com
Take a look at this PR by:  lme

en_US.ISO8859-1/books/handbook/advanced-networking/chapter.xml

@@ -55,6 +55,10 @@
 	<para>How to configure multiple <acronym>VLANs</acronym> on
 	  &os;.</para>
       </listitem>
+
+      <listitem>
+	<para>Configure bluetooth headset.</para>
+      </listitem>
     </itemizedlist>
 
     <para>Before reading this chapter, you should:</para>
@@ -2365,8 +2369,9 @@ ubt0: Interface 1 (alt.config 5) endpoints: isoc-in=0x83, isoc-out=0x3,
 
       <para>To start and stop the Bluetooth stack, use its startup
 	script.  It is a good idea to stop the stack before unplugging
-	the device.  When starting the stack, the output should be
+	the device.  Starting the bluetooth stack might require
-	similar to the following:</para>
+	&man.hcsecd.8; to be started.  When starting the stack, the
+	output should be similar to the following:</para>
 
       <screen>&prompt.root; <userinput>service bluetooth start ubt0</userinput>
 BD_ADDR: 00:02:72:00:d4:1a
@@ -2420,9 +2425,9 @@ Inquiry complete. Status: No error [00]</screen>
 	Bluetooth device, similar to the <acronym>MAC</acronym>
 	address of a network card.  This address is needed for further
 	communication with a device and it is possible to assign a
-	human readable name to a BD_ADDR.  Information regarding the
+	human readable name to a <literal>BD_ADDR</literal>.
-	known Bluetooth hosts is contained in
+	Information regarding the known Bluetooth hosts is contained
-	<filename>/etc/bluetooth/hosts</filename>.  The following
+	in <filename>/etc/bluetooth/hosts</filename>.  The following
 	example shows how to obtain the human readable name that was
 	assigned to the remote device:</para>
 
@@ -2435,11 +2440,25 @@ Name: Pav's T39</screen>
 	<quote>your.host.name (ubt0)</quote>.  The name assigned to
 	the local device can be changed at any time.</para>
 
+      <para>Remote devices can be assigned aliases in
+	<filename>/etc/bluetooth/hosts</filename>.  More information
+	about <filename>/etc/bluetooth/hosts</filename> file might be
+	found in &man.bluetooth.hosts.5;.</para>
+
       <para>The Bluetooth system provides a point-to-point connection
 	between two Bluetooth units, or a point-to-multipoint
 	connection which is shared among several Bluetooth devices.
-	The following example shows how to obtain the list of active
+	The following example shows how to create a connection to a
-	baseband connections for the local device:</para>
+	remote device:</para>
+
+      <screen>&prompt.user; <userinput>hccontrol -n ubt0hci create_connection <replaceable>BT_ADDR</replaceable></userinput></screen>
+
+      <para><literal>create_connection</literal> accepts
+	<literal>BT_ADDR</literal> as well as host aliases in
+	<filename>/etc/bluetooth/hosts</filename>.</para>
+
+      <para>The following example shows how to obtain the list of
+	active baseband connections for the local device:</para>
 
       <screen>&prompt.user; <userinput>hccontrol -n ubt0hci read_connection_list</userinput>
 Remote BD_ADDR    Handle Type Mode Role Encrypt Pending Queue State

en_US.ISO8859-1/books/handbook/multimedia/chapter.xml

@@ -84,6 +84,10 @@
       <listitem>
 	<para>Configure an image scanner.</para>
       </listitem>
+
+      <listitem>
+	<para>Configure a Bluetooth headset.</para>
+      </listitem>
     </itemizedlist>
 
     <para>Before reading this chapter, you should:</para>
@@ -286,6 +290,49 @@ pcm2: &lt;Conexant CX20590 (Analog 2.0+HP/2.0)&gt; (play/rec) default</screen>
       </note>
     </sect2>
 
+    <sect2 xml:id="bluetooth-headset">
+      <title>Setting up Bluetooth Sound Devices</title>
+
+      <indexterm>
+	<primary>Bluetooth audio</primary>
+      </indexterm>
+
+      <para>Connecting to a Bluetooth device is out of scope for this
+	chapter.  Refer to <xref
+	  linkend="network-bluetooth"/> for more information.</para>
+
+      <para>To get Bluetooth sound sink working with FreeBSD's sound
+	system, users have to install
+	<package>audio/virtual_oss</package> first:</para>
+
+      <screen>&prompt.root; <userinput>pkg install virtual_oss</userinput></screen>
+
+      <para><package>audio/virtual_oss</package> requires
+	<literal>cuse</literal> to be loaded into the kernel:</para>
+
+      <screen>&prompt.root; <userinput>kldload cuse</userinput></screen>
+
+      <para>To load <literal>cuse</literal> during system startup, run
+	this command:</para>
+
+      <screen>&prompt.root; <userinput>sysrc -f /boot/loader.conf cuse_load=yes</userinput></screen>
+
+      <para>To use headphones as a sound sink with
+	<package>audio/virtual_oss</package>, users need to create a
+	virtual device after connecting to a Bluetooth audio
+	device:</para>
+
+      <screen>&prompt.root; <userinput>virtual_oss -C 2 -c 2 -r 48000 -b 16 -s 768 -R /dev/null -P /dev/bluetooth/<replaceable>headphones</replaceable> -d dsp</userinput></screen>
+
+      <note>
+	<para><replaceable>headphones</replaceable> in this example is
+	  a hostname from <filename>/etc/bluetooth/hosts</filename>.
+	  <literal>BT_ADDR</literal> could be used instead.</para>
+      </note>
+
+      <para>Refer to &man.virtual_oss.8; for more information.</para>
+    </sect2>
+
     <sect2 xml:id="troubleshooting">
       <title>Troubleshooting Sound</title>
 

share/xml/man-refs.ent

@@ -303,6 +303,7 @@
 <!ENTITY man.h2xs.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>h2xs</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
 <!ENTITY man.hash.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>hash</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
 <!ENTITY man.hashstat.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>hashstat</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
+<!ENTITY man.hcsecd.8 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>hcsecd</refentrytitle><manvolnum>8</manvolnum></citerefentry>">
 <!ENTITY man.hd.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>hd</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
 <!ENTITY man.head.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>head</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
 <!ENTITY man.hesinfo.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>hesinfo</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
@@ -812,6 +813,7 @@
 <!ENTITY man.vidfont.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>vidfont</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
 <!ENTITY man.view.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>view</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
 <!ENTITY man.vim.1 "<citerefentry xmlns='http://docbook.org/ns/docbook' vendor='ports'><refentrytitle>vim</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
+<!ENTITY man.virtual_oss.8 "<citerefentry xmlns='http://docbook.org/ns/docbook' vendor='ports'><refentrytitle>virtual_oss</refentrytitle><manvolnum>8</manvolnum></citerefentry>">
 <!ENTITY man.vis.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>vis</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
 <!ENTITY man.vt220keys.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>vt220keys</refentrytitle><manvolnum>1</manvolnum></citerefentry>">
 <!ENTITY man.vttest.1 "<citerefentry xmlns='http://docbook.org/ns/docbook'><refentrytitle>vttest</refentrytitle><manvolnum>1</manvolnum></citerefentry>">