Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

When I call any applet with the --help option, please show this general information first #50

Closed
unforgettableid opened this issue Sep 26, 2016 · 20 comments

Comments

@unforgettableid
Copy link

unforgettableid commented Sep 26, 2016

Hi! When I call any applet with the --help option, it would be good if you could please start the output with the following lines, then a newline.

Toybox multi-call binary $(git describe)
Web page: http://landley.net/toybox/
Bug reports: https://github.com/landley/toybox/issues
Feedback: http://lists.landley.net/listinfo.cgi/toybox-landley.net
Contributors, see: https://landley.net/toybox/cleanup.html#intro

Some users have Toybox because it came preinstalled on their device. The above information will make it easier for such users to figure out where and how to submit bug reports and patches.

git describe looks at tag names and commits, and hopefully outputs a version number like "0.7.1-106-g409a8e0" or "0.7.2".

@d4rken
Copy link

d4rken commented Sep 26, 2016

Toybox multi-call binary $(git describe)

Why not reorder and make it

Toybox $(git describe) multi-call binary.

which would be analog to

BusyBox ...... multi-call binary.

and allow nice parsing of binary type and version.

@unforgettableid
Copy link
Author

unforgettableid commented Sep 26, 2016

The GNU standards point out that putting the version number at the very end of the line (with no trailing period) is easier to parse. BusyBox also prefixes their version numbers with an unnecessary letter 'v' (as in "BusyBox v1.21.0.git (2012-10-17 00:34:21 PDT) multi-call binary.") which makes their version numbers even harder to parse.

The GNU coreutils follow this standard, and so does GNU Emacs, though GNU Bash doesn't.

Someone should contact the BusyBox folks, either in their Bugzilla or on their mailing list. @d4rken, you could do it if you like. :)

landley added a commit that referenced this issue Aug 7, 2020
…being

the first google hit for "android toybox"), and want toybox --help to
mention it. I was referred to #50

So add a URL to toybox --help. While I was there, make unrecognized commands
(like toybox -?) suggest "toybox --help", move the install instructions
to the FAQ page (with a second link from toybox --help), and generally
tighten up the help text. Also, "toybox -*" is no longer a synonym for --long.

Oh, and I fixed some build dependencies when Config.in changes.
@landley
Copy link
Owner

landley commented Aug 7, 2020

Does efb8060 cover it?

@enh-google
Copy link
Collaborator

enh-google commented Aug 11, 2020

anyone wanting more specifics on Android in particular should see the commentary on #230 to learn why this is probably as good as it gets. (TL;DR: Android prohibits that kind of thing across the tree to minimize incremental OTA package sizes.)

@unforgettableid
Copy link
Author

unforgettableid commented Aug 17, 2020

Dear @landley:

efb8060 covers this issue partially but not fully.

Dear @enh-google:

Once the 250 bytes or so of enhanced help roll out to a device once, they need never roll out again, thanks to binary diffs. It's true that every rewritten page of flash is wear and tear, but I don't think that eMMC failure is very common.

The majority of individuals connect to Wi-Fi regularly. I'm not sure that such individuals need to receive OTA updates over mobile data. They can generally use Wi-Fi instead.

If your closing affects Android only, I wonder if you could please reopen this so that it might perhaps be implemented on other Toybox builds?

@enh-google
Copy link
Collaborator

enh-google commented Aug 17, 2020

Dear @enh-google:

Once the 250 bytes or so of enhanced help roll out to a device once, they need never roll out again, thanks to binary diffs.

it was specifically the idea of including a date or SHA or whatever -- something that does change because its purpose is to uniquely identify which version you're running -- on the other bug that was merged into this that i was talking about. just adding a website link or whatever is fine.

If your closing affects Android only, I wonder if you could please reopen this so that it might perhaps be implemented on other Toybox builds?

the default toybox build already does include details of the git revision and how many changes past the last release you are. it's only Android that turns that off.

@unforgettableid
Copy link
Author

unforgettableid commented Aug 17, 2020

I've created pull request #236, which fixes this issue partially but not fully.

For a more-complete fix, we'd also need to prepend all four web links to the help for each individual applet.

@enh-google
Copy link
Collaborator

enh-google commented Aug 18, 2020

For a more-complete fix, we'd also need to prepend all four web links to the help for each individual applet.

that seems like a bad idea... even the FSF only have two lines of spam in --help! busybox seems to manage with zero.

@unforgettableid
Copy link
Author

unforgettableid commented Aug 18, 2020

Fair point. OK; let's prepend just one line to every applet's --help text:

This is part of Toybox <http://landley.net/toybox/>.

This will help Android users to realize that they're using Toybox. This knowledge, in turn, will help them figure out where bug reports and patches should go.

Makes sense?

@landley
Copy link
Owner

landley commented Aug 18, 2020

Hmmm, that is a thing busybox does, true. I was thinking "ls -l $(which ls)" shows it's toybox, but that may be a bit "inside baseball" for a wider audience?

In fact that's where busybox sticks their --version info, ala "BusyBox v1.31.0 (2019-08-13 06:54:37 CDT) multi-call binary." which seems like it would conflict with the above android policy except on my "android 10, August 5, 2020 security update" phone typing "bzip2 --help" says "bzip2, a block-sorting file compressor. Version 1.0.6, 6-sept-2010" so I don't understand what this policy prohibits?

Anyway, I could move the "Toybox multicall binary URL" line currently in toybox --help to above the "usage" line and just have the help plumbing emit that (plus a blank line so usage: still stands out) for everybody.

Elliott: what's your opinion here? Leave it alone, make the existing line common as-is, or add the line and have the plumbing stick --version into it as seems to be the common case elsewhere? Either would be a fairly small source change...

@landley
Copy link
Owner

landley commented Aug 19, 2020

And now that I try to reproduce this the next day, I'm not seeing most commands having something before the usage: line. (Huh?) more --help, kmod --help, ss --help, pwd --help... less --help grabs the terminal and waits (of course it does),,,

@enh-google
Copy link
Collaborator

enh-google commented Aug 19, 2020

@landley
Copy link
Owner

landley commented Aug 19, 2020

Oh busybox is consistently saying it for all commands, which does raise the question of if "toybox sed --help" and "make sed; ./sed --help" standalone should behave differently which I WANT to say know but the word "multiplexer" in the standalone version... blah.

No, when I first did this I was running lots of random commands out of debian's $PATH and seeing them stick ID lines before usage: in their --help output, and the random sample I ran the NEXT day was all commands that didn't. (Random samples: fun for the whole family.)

Unfortunately, a loop trying to run all the commands in the $PATH with --help to get actual statistics hits "blueman-adapters --help" ignoring the --help and popping up a GUI window, or "less --help" displaying its output through less and waiting for you to press a key. (The blueman one seems to be a failure of regression testing, blueman-browse --help merely spits a screenful of gtk init messages to stderr and THEN outputs help text. Of course the Defective Annoying SHell doesn't understand that "--help" is even an option, and that's got to be a design decision from those guys. Who cares WHAT everyone everywhere else does, this one standards document does not require it there for we can't do it!)

@unforgettableid
Copy link
Author

unforgettableid commented Aug 19, 2020

@landley: Dunno.

For me, all the BusyBox commands I've tried always show an information line before the usage statement.

For example:

$ busybox less --help
BusyBox v1.27.2 (Ubuntu 1:1.27.2-2ubuntu3.2) multi-call binary.

Usage: less [-EIMmNSh~] [FILE]...

View FILE (or stdin) one screenful at a time

        -E      Quit once the end of a file is reached
        -I      Ignore case in all searches
        -M,-m   Display status line with line numbers
                and percentage through the file
        -N      Prefix line number to each line
        -S      Truncate long lines
        -~      Suppress ~s displayed past EOF

@unforgettableid
Copy link
Author

unforgettableid commented Aug 19, 2020

@landley: I'm using an old version of BusyBox, though.

@landley
Copy link
Owner

landley commented Aug 19, 2020

You know that line in the busybox faq about "work is underway on new options such as make standalone to build separate binaries for each applet"? (In https://busybox.net/FAQ.html#design ?) Yeah, I added that in 2006: https://git.busybox.net/busybox/commit/?id=aaffef4d33 and it was referring to http://lists.busybox.net/pipermail/busybox/2005-March/013939.html which kinda went away when I left.

"Should standalone busybox commands do this" is not a question the busybox developers I handed the project off to ever really asked because they didn't bother to finish/maintain the capability. Toybox can, so I have new questions to ask.

@unforgettableid
Copy link
Author

unforgettableid commented Aug 19, 2020

@landley:

Should standalone Toybox commands announce that they're part of Toybox?

Definitely. People want to know where to send feedback to.

The --help text could start with:

This is a Toybox standalone applet. Website: <http://landley.net/toybox/>.

Makes sense?

@landley
Copy link
Owner

landley commented Aug 19, 2020

  1. Toybox commands have never been java applets, they're "commands".

  2. If you type "insmod --help" you just get usage and options, no contact info. Same for mount, fdisk, route, git... Not obscure commands?

The "identify yourself" thing seems to have at least started as FSF self-promotion, which would argue against it being useful.

@unforgettableid
Copy link
Author

unforgettableid commented Aug 19, 2020

1.

You could instead say:

This is a standalone Toybox tool. Website: <http://landley.net/toybox/>.

Or:

This is a standalone Toybox utility. Website: <http://landley.net/toybox/>.

2.

You mentioned insmod, mount, fdisk, route, and git. In their man pages, all five tools mention a website URL and/or developer contact information. On Android, there's no man command, so that won't work.

Most of these tools do identify what package they came from, though, at least in their ‑‑version output.

I think that it would be wise for you, too, to mention Toybox by name, in each command's ‑‑version output.

You've now raised doubts in my mind. If you also mention Toybox by name in your ‑‑help output too, is that useful, or is it spam? I'm no longer sure.

Maybe @enh-google, @d4rken, and/or someone else will weigh in. If they don't, maybe it'd indeed be best to leave it out of the ‑‑help output.

It's probably true that more people know about ‑‑help than ‑‑version. But I'm not convinced that this is a good-enough reason to spam all ‑‑help users with mention of Toybox.

@enh-google
Copy link
Collaborator

enh-google commented Aug 20, 2020

i don't have a strong opinion on this. i'm not super convinced there's a problem here, but i also admit that by definition we don't know about those people who don't find us.

a link in --version seems completely fine, if only because it helps put something like "0.8.1" into context. is that new or old? a couple of years old or a decade old?

the top-level --help seems fine too, though by the time you're typing toybox --help you're 99% of the way there on your own anyway.

as long as it's at the top of the individual toy --help, i think that's fine too. i'm less keen on the GNU style of putting it at the bottom --- on a terminal, the last lines are the most precious. and busybox is precedent for putting it at the top of every command's --help. i assume rob would know if that had caused any upset over the years (and can't imagine that it would have).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging a pull request may close this issue.

4 participants