[Toybox] [PATCH] toys.h: remove unused declaration.

[enh]

On Sat, Oct 31, 2020 at 8:12 AM Rob Landley <rob at landley.net> wrote:
>
> On 10/28/20 4:35 PM, enh wrote:
> > On Wed, Oct 28, 2020 at 2:26 PM Rob Landley <rob at landley.net> wrote:
> >>
> >> On 10/28/20 10:47 AM, enh wrote:
> >>> yeah, i don't have any particular use for it myself, but i accept the
> >>> "behave more like the thing you're replacing" argument and i don't see
> >>> any problem that patch would cause, so "lgtm".
> >>
> >> It's an optimization problem that I'm not the target audience for. Tricksy.
> >
> > yeah, same here. i didn't even know (before the bug reports/feature
> > requests came in), for example, that not everyone knows what "-" and
> > "--" usually mean.
>
> I know they don't, which is why I documented it, but I'm not sure what the best
> way to introduce/organize the material is off the top of my head.
>
> >>> mostly off topic, but personally i'd like to surface the "generally
> >>> applicable but not widely known and kind of annoying if we repeat it
> >>> everywhere it's relevant" stuff from --help:
> ...
> >>> but that shouldn't get in the way of this patch.
> >>
> >> Yup. It's in the toybox --help because I wanted to document it somewhere, but am
> >> not sure how to point people at it...
> >
> > like i said, although i personally think this is a more interesting
> > problem, i don't think it should get in the way of submitting your
> > current patch which solves _a_ problem others are having :-)
>
> I added making youtube video tutorials as a patreon goal when I first set that
> up, but it's never got close to it and I don't think the page even shows goals
> anymore? (Patreon keeps "improving" the interface so it shows less information
> in a more confusing manner.)
>
> But right now, I don't even have cycles to answer mail here promptly. Said I was
> busy with at $DAYJOB through the end of the year. (I hit the paus button so
> nobody gets billed for the patreon in November, because I'm not doing the work
> right now.)
>
> >>   Toybox 0.8.4 multicall binary: https://landley.net/toybox (toybox --help)
> >
> > i think part of the problem is that people don't know there's more
> > about argument parsing that they don't know,
>
> Yes, but that's not an isolated case. There's an awful lot of "I didn't know
> that was good to know", and when you pile it up in large amounts it gets
> overwhelming again...
>
> Years ago when I first sat down at a unix command prompt, I couldn't figure out
> what my OPTIONS were. I found out about man pages pretty quickly, but "where do
> I find a list of available commands" was something I couldn't get a straight
> answer to for YEARS.
>
> Of course now I know where to find the index of the posix spec, and where to
> find the linux standard base command list, and that man7.org has web pages with
> command lists for each man page section (and that there's an "intro" page within
> each section that describes the purpose of the section, if not listing the
> actual commands in it), and I can type "help" at the bash prompt to get a list
> of bash builtins, and "alias" to find the list of defined aliases that have been
> set up by my init scripts, and we're back into "overwhelming" territory before
> we've even started talking about anything android-specific yet...
>
> Add in the difference between a tutorial and a reference, and I'm going "youtube
> videos". I need to teach a course on unixing, broken into little searchable bits.
>
> (Speaking of argument parsing, there should be some way to generate a
> documentation skeleton from the NEWTOY() option string, and/or compare the
> option string against the docs. Basically the lib/args.c comments at the top
> applied to the optstr that can say "This takes an integer argument with range
> from x to y and default value z", "this string argument can occur multiple
> times", "this command stops parsing arguments after the first non-option
> argument"...)
>
> My todo list runneth over so much I seldom even MENTION that sort of thing
> because it's so far down...
>
> > and much of `toybox
> > --help` is about installation and the like anyway. i also have strong
> > anecdata that people read man7.org more than they read any of toybox's
> > --help output anyway :-/
>
> Sure, because it's got an index. :)

i think more likely a combination of "because it's indexed by Google"
and "because it's easier to search in a web page" and "because i don't
trust my distro to have the latest version of the man page".

fwiw, i've found that most people are ignorant of all the introductory
material that's in the man pages too. i genuinely think that only the
heavy hammer of appending something like "For general information see
`toybox --help`" is likely to work, and even there we struggle to
convey "this is stuff that's actually useful for you to read, not just
copyright blurbs and the like!" :-)

i don't think the FSF have helped here with very verbose (but not
usually very helpful) --help output, and a lackadaisical approach to
man pages in favor of info pages (which almost no one actually reads,
and which have basically been another pressure towards "just use
Google").

fwiw, i think things like your `sed --help` strike a good balance ---
a decent quick reference for folks who more or less know what they're
doing. unlike GNU sed which is just the command line options, or any
realistic sed manual which is going to need a lot of examples.

> I once did a basic "toybox help -s" with one line summaries of all the commands.
> The thing is, to make it not suck I need to take the first line of the SOURCE
> (I.E. the comment at the very top of the source file for each command), which
> doesn't match one to one with the commands, and... It went back on the todo list
> because it needed more work than I could give it just then.
>
> But yeah, automatic usage: line generation from the option string and the
> one-per-line option descriptions (where a command that takes an argument could
> look for the first ALLCAPS word in the command description so sed -e would see
> "-e Add SCRIPT to list" and be able to [-e SCRIPT] from that...)
>
> There's a bunch of stuff I _could_ be doing. But right now, I'm helping make
> investor fundraising decks for a startup and learning how USB 2.0 works under
> the covers.
>
> > as i may have already said, i'm not sure _this_ problem even has a solution!
>
> I have plans for many things I haven't had time to work on.
>
> >> And then I can change the top level toybox page from news.html to about.html
> >> except... looking at the about page again it's all FAQ entries, isn't it? I
> >> should just put an "about" section at the start of the FAQ, but although I can
> >> symlink index.html to any of the other pages I can't easily make it jump to an
> >> #anchor tag so it's not quite equivalent...
>
> I started on that. Haven't had time to finish it, but now my local copy of the
> FAQ is a terrible mess I should find time to clean up again.
>
> >> While I'm at it I also need to collate the "general questions" to the end of the
> >> FAQ. Things like "why time based releases" and "will you backport old versions"
> >> are generic open source project questions, not really toybox specific. (In fact
> >> the second one I originally wrote for busybox, but after I left they made it
> >> busybox-specific and thus a less useful general answer to the question. In
> >> https://busybox.net/FAQ.html#backporting everything from "if you don't want to
> >> take the risk" to right before "the volunteers are happy" was not part of what I
> >> originally wrote. One of my motivations for doing a new FAQ...)
>
> I should write that down on one of the todo lists, I suppose...
>
> >> Rob
>
> Rob