No this time it’s not a proposal to add support for writing documentation like last time, it’s more a proposal for the users I want to make.
Doug wrote about adding documentation for HAL USE flags (and I’m glad for that because most of them were unknown to me too), and I’ve added documentation for the USE flags I found less understandable in three packages I maintain directly (pulseaudio, amarok, rbot).
What I want to ask our users is to propose which USE flag should be better explained: a maintainer might find them obvious, and then leave them undocumented as obvious. But the feature is focused on the users, which need to know what an USE flag do.
So, if you find an USE flag that is non-obvious, not documented in metadata.xml, and the package falls in PAM, Sound or Proaudio herds, feel free to open a bug to ask for the USE flag to be documented. I’ll try to do my best to keep up with the requests.
I really like the idea that use-flags finally get some decent documentation. As I consider the fact that quite often it is impossible to figure out what a use-flag is supposed to do the major weakness of Gentoo. So thumbs up for this initiative.However isn’t it a bit early to call for bugs on use-flags that are not understandable?Browsing through the list of http://gentoo-portage.com/USE shows enough use-flags that for me as a user leave more questions then they answer and I’m quite sure it would not be appreciated if I start filing bug-reports on each of these.The explanation for use-flags as Doug used in his example is a great example of how it should be done. Compare that to the description on gentoo-portage for most use-flags.Note that the thing that I most often find missing is whether or not it makes sense to enable it for an ordinary system. (something like the advise giving for the kernel-option)
The description that gentoo-portage provide is the same present in use.desc and use.local.desc. Up to now the only description found for USE flags. And yes, that’s exactly what I wanted to address.What I was asking is for bugs to be filled for those present in packages for the herds I listed, as those I can take care of updating myself.I hope that other devs will start writing more documentation, but for now I am offering my service trying to help users out.
I totally agree on what you wrote, this is an issue expecially for those users who not really familiar with all the packages present nowadays on portage. do you think posting bugs even on different use flags you’re not on, will encourage devels to increase the documentation on them?
I’m afraid that other devs will hate me if I suggest so… maybe Doug’s packages are fine to be bugged, too, as he’s the acting guy in this deal, but other devs might not like it.So I can’t suggest you to do so, but…
this means that there should be an internal Gentoo policy on that. At least this can give a reason to developers not to ignore or get angry on such bug submissions. imho.