We need a wiki page about picking the arguments

Feature Request

The reason for this feature request is that I, as a not-totally-new bumblebee-status user, still have troubles with certain configuration aspects.

The closest thing I could find in the wiki some info in the index page and the Examples page. I dare to say this is not enough.

First of all, the Examples section in the index page looks like a shorter (or older, incomplete version) of the Examples section in the README. There’s nothing wrong with having a few cool looking screenshots in two places, but at least they should be synced, which, I far as I know, is not the case, right? Updates to README don’t automatically get synced to the wiki, this is manual work that has to be done. So I suggest removing the Examples section from the wiki index page (yes, a questionable and somewhat extreme measure) and simply linking to the README example section there instead.

Second, the examples in the Examples wiki page (pardon the pun) do not reflect the complexity of writing a long, custom bumblebee-status invocation. I will go into more details just below.

As I wrote above, sometimes I still have troubles with this. A quite painful problem is the “sliding widgets” symptom - when the text size in widgets varies during updates. I will try to present my perspective on this.

• bumblebee-status has quite sane defaults, I think it’s fair to call it “It just works” ™ software. This is great as long as the user is happy with the defaults. But it’s also a two-edged sword: if configuration is not hard enough (reasonably hard enough rather than too hard/cryptic) - it doesn’t motivate the user to go deeper and understand what certain things mean, how certain things work internally.

• I won’t speak for everyone (yet I won’t be surprised if this approach isn’t specific just for me), but this is what I did (I remember very well) when I tried to change things for the first time: The cpu module. It has a cpu.format parameter which defaults to “{:.01f}”. I tried to change the numbers and see how the data displayed by the widget is changing visually. IMPORTANT: this is a Python format string, but, despite having some Python knowledge (which, frankly, isn’t the case for any new bumblebee-status new user) - I’ve never used these format strings before. I was happy with “%s” % (foo) constructs. I think we should go over all modules, inspect each parameter in the header docstring, and explicitly state everywhere “Python format string” instead of just “format string”, at least to avoid confusion with other meanings of “format string”, like those in the date/time/datetime modules for example. It would be nice if the wiki index page mentions the Python format strings explicitly somewhere and even links to the relevant Python documentation about them, to help users who don’t know Python.

• guess what happens when running bumblebee-status -m traffic and watching it for a while? It slides! If traffic values change many times enough (easy to reproduce by putting some load on network) - the widgets change their size. A search through the code finds https://github.com/tobi-wan-kenobi/bumblebee-status/blob/a7d22edcdaba208f4bf4115cc012f53ffd90cbbc/bumblebee/output.py#L69 which makes me assume all modules have a generic “width” parameter (where are all generic module parameters that are common for all modules documented? I still don’t know) - as in “maxwidth”. I try bumblebee-status -m traffic -p traffic.width=50 and… visually nothing happens, I only get a warning message in console:

  unused parameter traffic.width - please check the documentation of the affected module to ensure the parameter exists
  

  so my assumption was wrong, I’m stuck and don’t know what to do next.

• I am diverging a bit from the bumblebee-status command line arguments and I shift to its output that complies to the i3bar protocol. There’s a “min_width” attribute there, There are a few “minwidth” matches inside the modules/ directory, but it is not clear how that connects to i3bar’s “min_width” and if the end user is getting access to it somehow.

• there is also the “align” attribute in the i3bar spec, but again, it’s not clear how it connects to bumblebee-status: modules don’t seem to have MODULENAME.align parameters, themes don’t seem to have anything related either, bumblebee-status -h | grep align returns no matches. There is some code related to this here https://github.com/tobi-wan-kenobi/bumblebee-status/blob/a7d22edcdaba208f4bf4115cc012f53ffd90cbbc/bumblebee/output.py#L76 but I can’t make the connection between it, the lacking assumed ways to set that as user and the i3bar spec either.

Summary: we really need a wiki section that will cover all these issues and will at least help the user to understand clearly how to achieve the following goals:

• get whole bumblebee-status bar of fixed size, consisting of widgets of fixed size
• control alignment of data in widgets, globally, per module/widget
• make it clear how to achieve fixed size for widgets that have text involving util.bytefmt(), because this line in that file https://github.com/tobi-wan-kenobi/bumblebee-status/blob/a7d22edcdaba208f4bf4115cc012f53ffd90cbbc/bumblebee/util.py#L64 scares me, those list items aren’t of the same size

[ghost]

was introduced to avoid “size jumping” issues for components such as the CPU module

That’s the whole point, I am still having troubles with variable size, notably related to traffic module, and I don’t know what to do. Either the master branch of bumblebee-status does not fully expose ways to fully fix this issue for now (and, since I’m not following the development branch as closely, if, by any chance, the problem is fully solved there, it might be worth to port that part into master branch, if that is technically possible). Or there’s actually a “silver bullet”, a gotcha, which I’m missing, so I’d like to learn about it.

For example, here’s a typical question that I asked myself when skimming through the wiki and the code. Considering the snippet that I linked above:

for unit in ["", "Ki", "Mi", "Gi"]: 

would it improve the widget size situation if it used a list of elements of the same size instead, like:

for unit in ["  ", "Ki", "Mi", "Gi"]: 

(first item is a two whitespace string)? As a side effect, that would cause a gap between the numeric value and units when the value is in bytes. Then is it possible to fix the side effect by customizing the format string? If not, I’d still prefer to have that gap in the bar if it would guarantee I get a widget of fixed size.

The whole overhaul of the wiki is indeed a long term project and is indeed fine to link it to the evolution of development branch, to avoid doing it twice. As for gaps in the documentation in its current state, I tried to “plug” some with information I provided in my “satellite” repos related to bumblebee-status. Aside from linking to them, you are always welcome to borrow anything you see being useful. But this is documentation that I wrote about things I know and made it public so I could get feedback if it has any mistakes.

The “sliding widgets” problem is something I’m willing to learn more about right now, if possible, and this is the whole point of the issue being opened. It’s not a second attempt to bump an older issue of mine, which I opened long ago, when I knew less, and which was stating the obvious “wiki needs improvements”. Many questions that I’ve raised there are already solved, eventually, as result of feature additions to bumblebee-status - custom colors for icons in themes, pango markup, graphs etc For now I’m just willing to learn if there’s anything I can do (which I’m not doing yet, because I don’t know how) to stabilize the sizes of widgets and control the data placement inside them alignment-wise. From the perspective of an end user and his demands, the master branch of bumblebee-status has reached the feature complete status and this is the only remaining problem that I need to solve, because it hurts me not only when I’m using bumblebee-status directly with i3, but also via bridges.

[tobi-wan-kenobi]

Yes, I think that’s a great suggestion. Similar to code, I think the documentation will improve over time, hopefully.

Also, thanks for your feedback, I hope I integrated everything you raised.