Comment 8 for bug 663019

> Ok, but could you then explain where you would look, and what the text would look like to give you that information? It would be good for me to know where users are looking for information.

I have made a few suggestions below.

> People think of it as a configuration file, but it is rather a script. I think that could be the "gotcha".

Hmmm, the issue I had was rather that it was not clear that the mere existence of ~/.pulse/default.pa effectively blocks the entire contents of /etc/pulse/default.pa from being used, instead of being that any configuration variable assignments in ~/.pulse/default.pa just override the corresponding variable assignments in /etc/pulse/default.pa.

Personally, I think it would be make more sense from a user-perspective, and thus generate fewer support issues in the future, if pulseaudio were always to read both /etc/pulse/default.pa and ~/.pulse/default.pa, taking the values of configuration variables from both of them, with the values in ~/.pulse/default.pa overriding the values in /etc/pulse/default.pa. Actually, I think it would be clearer and more consistent for the users to have it work in the same way for all of the files in /etc/pulse/, following the pattern of system-wide defaults in /etc/, but override-able on a per-variable basis in the configuration in the user's .pulse directory. Some of the files in /etc/pulse/ are configuration scripts and the others are configuration files, but for both types it should be straightforward to make any variable assignments in the ~/.pulse/ version able to override those in the /etc/pulse version.

I think the reason so many people recently seem to be getting confused and fed up with pulseaudio is that the documentation as a whole does have some issues. One of the issues is that it is often too terse in its explanations. If it were a bit less terse, I think there would be fewer users with support issues. Another issue with it is there is some inconsistency in how it refers to the same configuration-related entities in different places. I am going to mention a few here now; I wish I had the time to study it completely and identify all of the issues one by one.

==man page for default.pa==
This man page has a title line referring to default.pa as a "startup script", while the first paragraph refers to it as just "the file". This change in terminology is potentially confusing for users. A script is a type of file, but many other things are also files, so "file" is ambiguous. It really would help the users if the terminology were 100% consistent. Calling it a "file" is too general; ditto for "script"; "configuration script" is more specific if a bit long. Whatever term is used, it needs to be used consistently.
There is the same issue of less than 100% consistency for other terms used elsewhere in the pulseaudio documentation. If I had time, I would like to list them all here. It does need a careful review and some rewriting.

There is also a question about the name "default.pa". It is too general. It is potentially confusing for users. There surely has to be a better name for it, something more specific that would show immediately that it is actually a pulseaudio CLI script, rather than a configuration file containing variables as could easily be expected. Something like "setup-script.cli" perhaps ? We are used to seeing many other sorts of scripts with an appropriate suffix, e.g. "startup.sh", "edit-config.pl", "search.py"...

==man page for pulse-daemon.conf==
This man page is quite confusing from the beginning because it talks about two similar terms "configuration file" and "configuration script" without explaining the difference clearly to users. It goes on to say that daemon.conf and default.pa both contain "configuration directives" implying they are both the same type of file, but they are not. That is unclear and extremely confusing for users. "Configuration directives" is too general a term to use in this context. To a user, it could mean statements from the pulseaudio CLI language, such as are used in default.pa, but in this case it doesn't mean that; it means variable assignments as used in configuration files. A bit of rewriting is required. This issue applies throughout the man pages; every page should state whether it is documenting a "configuration script" or a "configuration file", and should remind users of what the difference is.

==man page for system.pa==
Out of the four files in /etc/pulse/, there are man pages for only three of them. A man page for "system.pa" needs to be added.

==man page for pulse-client.conf==
This page says the configuration file is "a simple collection of variable declarations". Why the "simple"? Is the idea to make an implied comparison with "complicated" collections whatever they might be? Also, I think it is not strictly accurate to say the configuration file contains variable "declarations"; it contains variable assignments, not variable declarations; a configuration file (unless it is a script) normally cannot declare variables.

==man-pages naming consistency==
The names of the man pages for /etc/pulse/* are default.pa, pulse-daemon.conf, and pulse-client.conf. Those names are a bit inconsistent. If the "pulse" prefix and ".conf" suffix are going to be used at all, they should be used consistently for all of them. Having said that, I'm not sure ".conf" is the best suffix. Anyway, the names need to make a clearer distinction between what are configuration scripts and what are configuration files. For example, per the paragraph above entitled "man page for pulse-daemon.conf", "default.pa" should be renamed to something more specific like "setup-script.cli" for clarity.
Also, referring to "clients" and "servers" is very widely understood; using "clients" and "daemons" is, well, a bit eccentric. There is potential to confuse users. Globally substituting "server" throughout the documentation would help improve consistency, e.g. man page "pulse-daemon.conf" -> "pulse-server.conf".

==grammar: "when" vs "if"==
There are issues with grammar and logic in the first sentence of each of the man pages for default.pa, pulse-daemon.conf and pulse-client.conf. Paraphrasing it, it says, "pulseaudio reads things from a file X and when that file does not exist from Y". The grammatical error is that "when" is being used as if it were a synonym for "if", which it isn't. "when" is used for introducing time-dependent clauses in a sentence. "if" is used for introducing conditional clauses in a sentence. The second issue is a logical ambiguity. "pulseaudio reads things from a file X and when that file does not exist from Y" is logically ambiguous; it does not imply that "pulseaudio does not read things from file X when both file X and file Y exist." so the user is left wondering what does happen in such a case. So, fixing the grammar, the ambiguity, and re-phrasing it less tersely: "pulseaudio reads things from a file X. If file X exists, pulseaudio will not read anything from file Y. If and only if file X does not exist, pulseaudio reads things from file Y." Substitute X="~/.pulse/default.pa", Y="/etc/pulse/default.pa", things="configuration directives", and repeat with appropriate substitutions for each of the man pages.

==
I am sorry I don't have time to go through all of the issues with the pulseaudio documentation. I hope what I have written above is useful and will lead to improvements in future versions of the documentation. If I get time, I will come back with more notes and suggestions.

Thanks for your tip about how to fix my broken packages using apt-get. I'll try it.