[pulseaudio-discuss] Man page clarifications
david.henningsson at canonical.com
Wed Oct 20 23:49:52 PDT 2010
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
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
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",
==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.
More information about the pulseaudio-discuss