[Toybox] [PATCH] netcat: clarify documentation.

[enh]

On Wed, May 22, 2024 at 2:30 AM Rob Landley <rob at landley.net> wrote:
>
> On 5/20/24 07:06, enh via Toybox wrote:
> > "Collate" means "sort", but -O is like -o other than buffering.
>
> It means "group". (The dictionary says "gather or arrange in the proper
> sequence".) I can see the confusion, but the collate button on the copier in
> high school stapled pages together (the pages came out the same order either
> way, the question was should the groups be attached). I also had a data entry
> work-study job in college where I had to "collate" reports (basically doing the
> same thing by hand, except using transparent file folders and this little
> plastic strip that slid along the edge to hold the pages in).

hey, you're the one who says toybox should aim at being intelligible
to non-native speakers. "collate" is (a) pretty obscure and (b)
definitely going to take people places that only talk about sorting.
https://en.wikipedia.org/wiki/Collation for example. or
https://www.man7.org/linux/man-pages/man3/strcoll.3.html or
https://www.unicode.org/reports/tr10/ or ...

> We just had a thread about "buffering", and I find that _less_ illuminating in
> context.

aye, but it's the word computer people use. i'd argue that sooner or
later anyone with computers is going to have to understand the concept
of buffering, and the name we use for that concept.

not least because it's already used in toybox help :-)

> Sigh, "grouped", "streamed", "together", "terse", "what I thought it was doing
> until I actually compared the output side by side", "showing the actual data
> instead of the transaction boundaries that survived the nagle algorithm",
> "assembled", "congregated", "collected", "packaged", "declutered", "thesaurus"...
>
> How does "packed" sound?

it sounds like i still don't understand why you're not just saying
"buffered". it makes me think there's something special going on here
that i don't understand. (for example, our existing "packed" hex dump
is the postscript style one from xxd where there are no spaces between
the bytes. different kind of hexdump, different word. but this is just
a "regular" hexdump.)

fwiw, i think flipping the sense and using the word "flush" would be
the other way to keep to the toybox "don't make help/errors require
advanced english skills" goal.

(now we're having a longer conversation, at a much higher level, i was
curious where these two options even came from... why not pipe through
one of toybox's many (!) existing hex dumps? and why use a switch
character that's already used for something else in "real" netcat? the
answer to former question might also usefully be in the help, unless
it was obvious to everyone _but_ me why this is needed :-) )

> Rob