[pulseaudio-discuss] [PATCH] Documentation of known misuse of PulseAudio API

[Tanu Kaskinen]

On Tue, 2013-10-22 at 00:19 +0100, Alexander E. Patrakov wrote:
> Hello.
> 
> Over time, I became aware of several instances of tempting but
> semantically incorrect usage of PulseAudio API (one from my own bad
> proposal of "improving" Wine, one from Parole media player and one
> from Webkit-GTK). I want to document these gotchas so that other
> developers don't fall for that. See the attached patch.
> 
> I have checked that the rendered HTML is correct, but need someone to
> confirm the factual accuracy of the proposed changes and, possibly, to
> improve the wording.

This is the only bit that I'd change in some way:

> + * is too high. With flat volumes disabled (the default in Ubuntu), it means
> + * the maximum hardware volume attenuated by the sink volume. In most cases,
> + * this is appropriate.

I think "the maximum hardware volume attenuated by the sink volume" is a
bit hard to understand wording. Perhaps this would be better: "With flat
volumes disabled (the default in Ubuntu), the sink input volume is
relative to the sink volume, so 100% sink input volume means that the
sink input is played at the current sink volume level."

I don't know what you meant with "In most cases, this is appropriate".
What does "this" refer to?

-- 
Tanu