[pulseaudio-discuss] Man page clarifications

[David Henningsson]

I'm relaying a bug comment to this list, the reporter has ideas about 
the PulseAudio documentation. He originally filed a bug about that when 
adding a pair of lines to ~/.pulse/default.pa and PulseAudio stopped 
working, as he was unaware that it caused /etc/pulse/default.pa not 
being used. I think it's healthy to get bug reports like these, could to 
know what confuses users and what makes PA harder to use.

Bug report link: https://bugs.launchpad.net/bugs/663019

===== Comment from B Bobo begins here ===

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.


-- 
David Henningsson, Canonical Ltd.
http://launchpad.net/~diwic