doc: in user-facing config examples, indicate which file it goes into

Add suggestions for config fragments in config file examples, as
applicable.

doc/dox/config/pipewire-client.conf.5.md

@@ -66,7 +66,9 @@ may also be specified, see \ref page_man_pipewire_conf_5 "pipewire.conf(5)".
 # STREAM PROPERTIES  @IDX@ client.conf
 
 The client configuration files contain a stream.properties section that configures the options for client streams:
-```
+```css
+# ~/.config/pipewire/client.conf.d/custom.conf
+
 stream.properties = {
     #node.latency = 1024/48000
     #node.autoconnect = true
@@ -118,7 +120,9 @@ object of the stream and filter.
 Add a `stream.rules` or `filter.rules` section in the config file like
 this:
 
-```
+```css
+# ~/.config/pipewire/client.conf.d/custom.conf
+
 stream.rules = [
     {
         matches = [
@@ -144,6 +148,8 @@ An `alsa.properties` section can be added to configure client applications
 that connect via the PipeWire ALSA plugin.
 
 ```css
+# ~/.config/pipewire/client-rt.conf.d/custom.conf
+
 alsa.properties = {
     #alsa.deny = false
     #alsa.format = 0
@@ -185,7 +191,10 @@ It is possible to set ALSA client specific properties by using
 set any of the above ALSA properties or any of the `stream.properties`.
 
 ### Example
-```
+
+```css
+# ~/.config/pipewire/client-rt.conf.d/custom.conf
+
 alsa.rules = [
     {   matches = [ { application.process.binary = "resolve" } ]
         actions = {

doc/dox/config/pipewire-jack.conf.5.md

@@ -41,8 +41,9 @@ may also be specified, see \ref page_man_pipewire_conf_5 "pipewire.conf(5)".
 # JACK PROPERTIES  @IDX@ jack.conf
 
 The configuration file can contain an extra JACK specific section called `jack.properties` like this:
-```
+```css
-...
+# ~/.config/pipewire/jack.conf.d/custom.conf
+
 jack.properties = {
     #rt.prio             = 88
     #node.latency        = 1024/48000
@@ -204,7 +205,9 @@ on the client and node object of the jack client.
 
 Add a `jack.rules` section in the config file like this:
 
-```
+```css
+# ~/.config/pipewire/jack.conf.d/custom.conf
+
 jack.rules = [
     {
         matches = [

doc/dox/config/pipewire-pulse.conf.5.md

@@ -74,6 +74,8 @@ Some of these properties map to the PulseAudio `/etc/pulse/default.pa` config en
 ## Example
 
 ```css
+# ~/.config/pipewire/pipewire-pulse.conf.d/custom.conf
+
 stream.properties = {
     #node.latency = 1024/48000
     #node.autoconnect = true
@@ -124,6 +126,8 @@ for available options.
 ## Example
 
 ```css
+# ~/.config/pipewire/pipewire-pulse.conf.d/custom.conf
+
 pulse.rules = [
     {
         # skype does not want to use devices that don't have an S16 sample format.
@@ -154,7 +158,8 @@ additional commands with the `pulse.cmd` section in
 `pipewire-pulse.conf`.
 
 ```css
-...
+# ~/.config/pipewire/pipewire-pulse.conf.d/custom.conf
+
 pulse.cmd = [
     { cmd = "load-module" args = "module-always-sink" flags = [ ] }
     { cmd = "load-module" args = "module-switch-on-connect" }

doc/dox/config/pipewire.conf.5.md

@@ -53,7 +53,9 @@ for configuration is recommended.
 A configuration file `~/.config/pipewire/pipewire.conf.d/custom.conf`
 to change the value of the `default.clock.min-quantum` setting in `pipewire.conf`:
 
-```css
+```
+# ~/.config/pipewire/pipewire.conf.d/custom.conf
+
 context.properties = {
     default.clock.min-quantum = 128
 }
@@ -172,7 +174,9 @@ cpu cores.
 @PAR@ pipewire.conf  context.data-loops = [ ... ]
 This controls the data loops that will be created for the context. Is is an array of
 data loop specifications, one entry for each data loop to start:
-```json
+```
+# ~/.config/pipewire/pipewire.conf.d/custom.conf
+
 context.data-loops = [
     {
          #library.name.system = support/libspa-support
@@ -310,7 +314,9 @@ plugin. The plugin is loaded from the first matching factory-name.
 
 ## Example
 
-```json
+```
+# ~/.config/pipewire/pipewire.conf.d/custom.conf
+
 context.spa-libs = {
     audio.convert.* = audioconvert/libspa-audioconvert
     avb.*           = avb/libspa-avb
@@ -330,7 +336,9 @@ context.spa-libs = {
 PipeWire modules to be loaded. See
 \ref page_man_libpipewire-modules_7 "libpipewire-modules(7)".
 
-```json
+```
+# ~/.config/pipewire/pipewire.conf.d/custom.conf
+
 context.modules = [
     #{ name = MODULENAME
     #    ( args  = { KEY = VALUE ... } )
@@ -361,7 +369,9 @@ to a context property.
 The `context.objects` section allows you to make some objects from factories (usually created
 by loading modules in `context.modules`).
 
-```json
+```
+# ~/.config/pipewire/pipewire.conf.d/custom.conf
+
 context.objects = [
     #{ factory = <factory-name>
     #    ( args  = { <key> = <value> ... } )
@@ -391,7 +401,9 @@ to a context property.
 This fragment creates a new dummy driver node, but only if
 `core.daemon` property is true:
 
-```json
+```
+# ~/.config/pipewire/pipewire.conf.d/custom.conf
+
 context.objects = [
     { factory = spa-node-factory
       args = {
@@ -410,7 +422,9 @@ context.objects = [
 The `context.exec` section can be used to start arbitrary commands as
 part of the initialization of the PipeWire program.
 
-```json
+```
+# ~/.config/pipewire/pipewire.conf.d/custom.conf
+
 context.exec = [
     #{   path = <program-name>
     #    ( args = "<arguments>" | [ <arg1> <arg2> ... ] )
@@ -434,7 +448,9 @@ to a context property.
 
 The following fragment executes a pactl command with the given arguments:
 
-```json
+```
+# ~/.config/pipewire/pipewire.conf.d/custom.conf
+
 context.exec = [
     { path = "pactl" args = "load-module module-always-sink" }
 ]
@@ -447,7 +463,7 @@ possible to perform some action when an object (usually a node or
 stream) is created/updated that matches certain properties.
 
 The general rules object follows the following pattern:
-```json
+```css
 <rules> = [
     {
         matches = [
@@ -494,7 +510,7 @@ which is used to update the properties of the matched object.
 In the matches array, it is also possible to use regular expressions to match property values.
 For example, to match all nodes with a name that starts with my_, you can use the following condition:
 
-```
+```css
 matches = [
   {
     node.name = "~my_.*"
@@ -508,7 +524,7 @@ expressions is the POSIX extended regex syntax, as described in the regex (7) ma
 In addition to regular expressions, you may also use the ! character to negate a condition. For
 example, to match all nodes with a name that does not start with my_, you can use the following condition:
 
-```
+```css
 matches = [
   {
     node.name = "!~my_.*"
@@ -519,7 +535,7 @@ matches = [
 The ! character can be used with or without a regular expression. For example, to match all
 nodes with a name that is not equal to my_node, you can use the following condition:
 
-```
+```css
 matches = [
   {
     node.name = "!my_node"
@@ -530,7 +546,7 @@ matches = [
 The null value has a special meaning; it checks if the property is not available
 (or unset). To check if a property is not set:
 
-```
+```css
 matches = [
   {
     node.name = null
@@ -540,7 +556,7 @@ matches = [
 
 To check the existence of a property, one can use the !null condition, for example:
 
-```
+```css
 matches = [
   {
     node.name = "!null"
@@ -553,7 +569,7 @@ matches = [
 To handle the "null" string, one needs to escape the string. For example, to check
 if a property has the string value "null", use:
 
-```
+```css
 matches = [
   {
     node.name = "null"
@@ -562,7 +578,7 @@ matches = [
 ```
 To handle anything but the "null" string, use:
 
-```
+```css
 matches = [
   {
     node.name = "!\"null\""
@@ -583,7 +599,9 @@ A typical case is to update custom settings when running inside a VM.
 The `cpu.vm.name` is automatically set when running in a VM with the name of
 the VM. A match rule can be written to set custom properties like this:
 
-```
+```css
+# ~/.config/pipewire/pipewire.conf.d/custom.conf
+
 context.properties.rules = [
     {   matches = [ { cpu.vm.name = !null } ]
         actions = {
@@ -607,7 +625,9 @@ properties that are updated on the node object.
 
 Add a `node.rules` section in the config file like this:
 
-```
+```css
+# ~/.config/pipewire/pipewire.conf.d/custom.conf
+
 node.rules = [
     {
         matches = [
@@ -638,7 +658,9 @@ properties that are updated on the device object.
 
 Add a `device.rules` section in the config file like this:
 
-```
+```css
+# ~/.config/pipewire/pipewire.conf.d/custom.conf
+
 device.rules = [
     {
         matches = [

doc/dox/pulse-modules.inc

@@ -10,6 +10,8 @@ can also added to `pipewire-pulse.conf`, typically by a drop-in file
 in `~/.config/pipewire/pipewire-pulse.conf.d/` containing the module
 name and its arguments
 ```
+# ~/.config/pipewire/pipewire-pulse.conf.d/custom.conf
+
 pulse.cmd = [
     { cmd = "load-module" args = "module-null-sink sink_name=foo" flags = [ ] }
 ]

src/modules/module-combine-stream.c

@@ -82,6 +82,8 @@
  * ## Example configuration
  *
  *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire.conf.d/my-combine-stream-1.conf
+ *
  * context.modules = [
  * {   name = libpipewire-module-combine-stream
  *     args = {
@@ -122,6 +124,8 @@
  * from 3 separate stereo sinks.
  *
  *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire.conf.d/my-combine-stream-2.conf
+ *
  * context.modules = [
  * {   name = libpipewire-module-combine-stream
  *     args = {
@@ -170,6 +174,8 @@
  * from 2 separate stereo sources.
  *
  *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire.conf.d/my-combine-stream-3.conf
+ *
  * context.modules = [
  * {   name = libpipewire-module-combine-stream
  *     args = {

src/modules/module-echo-cancel.c

@@ -117,6 +117,8 @@
  *
  * ## Example configuration
  *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire.conf.d/my-echo-cancel.conf
+ *
  * context.modules = [
  *  {   name = libpipewire-module-echo-cancel
  *      args = {

src/modules/module-example-filter.c

@@ -65,6 +65,8 @@
  * ## Example configuration of a virtual source
  *
  *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire.conf.d/my-example-filter.conf
+ *
  * context.modules = [
  * {   name = libpipewire-module-example-filter
  *     args = {

src/modules/module-example-sink.c

@@ -63,6 +63,8 @@
  * ## Example configuration
  *
  *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire.conf.d/my-example-sink.conf
+ *
  * context.modules = [
  * {   name = libpipewire-module-example-sink
  *     args = {

src/modules/module-example-source.c

@@ -63,6 +63,8 @@
  * ## Example configuration
  *
  *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire.conf.d/my-example-source.conf
+ *
  * context.modules = [
  * {   name = libpipewire-module-example-source
  *     args = {

src/modules/module-ffado-driver.c

@@ -76,6 +76,8 @@
  * ## Example configuration of a duplex sink/source
  *
  *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire.conf.d/my-ffado-driver.conf
+ *
  * context.modules = [
  * {   name = libpipewire-module-ffado-driver
  *     args = {

src/modules/module-filter-chain.c

@@ -477,7 +477,12 @@ PW_LOG_TOPIC_STATIC(mod_topic, "mod." NAME);
  * This example uses the rnnoise LADSPA plugin to create a new
  * virtual source.
  *
+ * Run with `pipewire -c filter-chain.conf`. The configuration can also
+ * be put under `pipewire.conf.d/` to run it inside the PipeWire server.
+ *
  *\code{.unparsed}
+ * # ~/.config/pipewire/filter-chain.conf.d/my-filter-chain-1.conf
+ *
  * context.modules = [
  * {   name = libpipewire-module-filter-chain
  *     args = {
@@ -515,6 +520,8 @@ PW_LOG_TOPIC_STATIC(mod_topic, "mod." NAME);
  * to a stereo Dolby Surround signal.
  *
  *\code{.unparsed}
+ * # ~/.config/pipewire/filter-chain.conf.d/my-filter-chain-2.conf
+ *
  * context.modules = [
  * {   name = libpipewire-module-filter-chain
  *     args = {

src/modules/module-jack-tunnel.c

@@ -75,6 +75,8 @@
  * ## Example configuration of a duplex sink/source
  *
  *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire.conf.d/my-jack-tunnel.conf
+ *
  * context.modules = [
  * {   name = libpipewire-module-jack-tunnel
  *     args = {

src/modules/module-jackdbus-detect.c

@@ -42,6 +42,8 @@
  *
  * ## Example configuration
  *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire.conf.d/my-jack-dbus-detect.conf
+ *
  * context.modules = [
  *  {   name = libpipewire-module-jackdbus-detect
  *      args {

src/modules/module-loopback.c

@@ -82,6 +82,8 @@
  * This Virtual sink routes stereo input to the rear channels of a 7.1 sink.
  *
  *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire.conf.d/my-loopback-1.conf
+ *
  * context.modules = [
  * {   name = libpipewire-module-loopback
  *     args = {
@@ -111,6 +113,8 @@
  * This is useful for splitting up multi-channel inputs from USB audio interfaces that are not yet fully supported by alsa.
  *
  *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire.conf.d/my-loopback-2.conf
+ *
  * context.modules = [
  * {   name = libpipewire-module-loopback
  *     args = {
@@ -137,6 +141,8 @@
  * using the PSD algorithm on the playback stream.
  *
  *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire.conf.d/my-loopback-3.conf
+ *
  * context.modules = [
  * {   name = libpipewire-module-loopback
  *     args = {
@@ -168,6 +174,8 @@
  * downmixing from the two first AUX channels of a pro-audio device.
  *
  *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire.conf.d/my-loopback-4.conf
+ *
  * context.modules = [
  * {   name = libpipewire-module-loopback
  *     args = {

src/modules/module-netjack2-driver.c

@@ -87,6 +87,8 @@
  * ## Example configuration of a duplex sink/source
  *
  *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire.conf.d/my-netjack2-driver.conf
+ *
  * context.modules = [
  * {   name = libpipewire-module-netjack2-driver
  *     args = {

src/modules/module-netjack2-manager.c

@@ -92,6 +92,8 @@
  * ## Example configuration of a duplex sink/source
  *
  *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire.conf.d/my-netjack2-manager.conf
+ *
  * context.modules = [
  * {   name = libpipewire-module-netjack2-manager
  *     args = {

src/modules/module-parametric-equalizer.c

@@ -69,6 +69,8 @@
  *
  * ## Example configuration
  *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire.conf.d/my-parametric-equalizer.conf
+ *
  * context.modules = [
  * {   name = libpipewire-module-parametric-equalizer
  *     args = {

src/modules/module-pipe-tunnel.c

@@ -93,6 +93,8 @@
  * ## Example configuration of a pipe playback stream
  *
  *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire.conf.d/my-pipe-tunnel.conf
+ *
  * context.modules = [
  * {   name = libpipewire-module-pipe-tunnel
  *     args = {

src/modules/module-protocol-pulse.c

@@ -48,6 +48,8 @@
  * A config section with server properties can be given.
  *
  *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire-pulse.conf.d/custom.conf
+ *
  * pulse.properties = {
  *     # the addresses this server listens on
  *     server.address = [
@@ -297,6 +299,8 @@
  * section with a `quirks` and an `update-props` action.
  *
  *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire-pulse.conf.d/custom.conf
+ *
  * pulse.rules = [
  *     {
  *         # skype does not want to use devices that don't have an S16 sample format.
@@ -343,6 +347,8 @@
  * ## Example configuration
  *
  *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire-pulse.conf.d/custom.conf
+ *
  * context.modules = [
  * {   name = libpipewire-module-protocol-pulse
  *     args = { }

src/modules/module-protocol-simple.c

@@ -83,6 +83,8 @@
  * ## Example configuration
  *
  *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire.conf.d/my-protocol-simple.conf
+ *
  * context.modules = [
  * {   name = libpipewire-module-protocol-simple
  *     args = {

src/modules/module-pulse-tunnel.c

@@ -83,6 +83,8 @@
  * ## Example configuration of a virtual sink
  *
  *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire.conf.d/my-pulse-tunnel.conf
+ *
  * context.modules = [
  * {   name = libpipewire-module-pulse-tunnel
  *     args = {

src/modules/module-raop-discover.c

@@ -55,6 +55,8 @@
  * ## Example configuration
  *
  *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire.conf.d/my-raop-discover.conf
+ *
  * context.modules = [
  * {   name = libpipewire-module-raop-discover
  *     args = {

src/modules/module-raop-sink.c

@@ -94,6 +94,8 @@
  * ## Example configuration
  *
  *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire.conf.d/my-raop-sink.conf
+ *
  * context.modules = [
  * {   name = libpipewire-module-raop-sink
  *     args = {

src/modules/module-roc-sink.c

@@ -56,6 +56,8 @@
  *
  * ## Example configuration
  *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire.conf.d/my-roc-sink.conf
+ *
  * context.modules = [
  *  {   name = libpipewire-module-roc-sink
  *      args = {

src/modules/module-roc-source.c

@@ -59,6 +59,8 @@
  *
  * ## Example configuration
  *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire.conf.d/my-roc-source.conf
+ *
  * context.modules = [
  *  {   name = libpipewire-module-roc-source
  *      args = {

src/modules/module-rtp-sap.c

@@ -73,6 +73,8 @@
  *
  * ## Example configuration
  *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire.conf.d/my-rtp-sap.conf
+ *
  * context.modules = [
  * {   name = libpipewire-module-rtp-sap
  *     args = {

src/modules/module-rtp-session.c

@@ -97,6 +97,8 @@
  *
  * ## Example configuration
  *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire.conf.d/my-rtp-session.conf
+ *
  * context.modules = [
  * {   name = libpipewire-module-rtp-session
  *     args = {

src/modules/module-rtp-sink.c

@@ -87,6 +87,8 @@
  *
  * ## Example configuration
  *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire.conf.d/my-rtp-sink.conf
+ *
  * context.modules = [
  * {   name = libpipewire-module-rtp-sink
  *     args = {

src/modules/module-rtp-source.c

@@ -81,6 +81,8 @@
  *
  * ## Example configuration
  *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire.conf.d/my-rtp-source.conf
+ *
  * context.modules = [
  * {   name = libpipewire-module-rtp-source
  *     args = {

src/modules/module-snapcast-discover.c

@@ -88,6 +88,8 @@
  * ## Example configuration
  *
  *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire.conf.d/my-snapcast-discover.conf
+ *
  * context.modules = [
  * {   name = libpipewire-module-snapcast-discover
  *     args = {

src/modules/module-vban-recv.c

@@ -77,6 +77,8 @@
  *
  * ## Example configuration
  *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire.conf.d/my-vban-recv.conf
+ *
  * context.modules = [
  * {   name = libpipewire-module-vban-recv
  *     args = {

src/modules/module-vban-send.c

@@ -78,6 +78,8 @@
  *
  * ## Example configuration
  *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire.conf.d/my-vban-send.conf
+ *
  * context.modules = [
  * {   name = libpipewire-module-vban-send
  *     args = {

src/modules/module-zeroconf-discover.c

@@ -48,6 +48,8 @@
  * ## Example configuration
  *
  *\code{.unparsed}
+ * # ~/.config/pipewire/pipewire.conf.d/my-zeroconf-discover.conf
+ *
  * context.modules = [
  * {   name = libpipewire-module-zeroconf-discover
  *     args = { }