[TUHS] Re: On Bloat and the Idea of Small Specialized Tools

[segaloco via TUHS <tuhs@tuhs.org>]

On Saturday, May 18th, 2024 at 12:19 PM, Luther Johnson <luther.johnson@makerlisp.com> wrote:

> Complexity is entropy. It occurs naturally in all human endeavor. It takes work to keep things small, orderly, and rational. But there is also a point where although a tool may be perfect in its conception and execution, from its own perspective, it is not as useful as a slightly more disorderly version that does what people want it to do. "Well they shouldn't want that !" is a common response. Then people write scripts to do for themselves what the tool doesn't do. Which might be right, but it might lead to a whole bunch of similar scripts to do the same thing, just a little differently And that's when we discover that it would have been better to have it in the one tool in the first place.
> 
> So it's a back and forth, trial and error process. Eventually new balances get struck, and people of like minds and tastes find a new center, like Plan 9, or other things.
> 
> Myself, I do tend to like tools that are smaller and more single-minded in their function (and that makes it possible to have documentation that is clearer and more concise), but as an example, sometimes I want the "-u" switch on diff, to make a patch, sometimes I don't, the default display is better for a quick review (but I think or expect that the essential diff engine is being shared). It's all a matter of judgment, but you can't apply good judgment until you have the experience gained from trying several alternatives. So things will get bloated up, and then they will need to be pruned and re-engineered, but hopefully we don't throw out the most helpful exceptions to the rule just because they don't fit with some sort of consistency aesthetic.
> 
> On 05/18/2024 11:52 AM, Clem Cole wrote:
> 
> > 
> > 
> > On Sat, May 18, 2024 at 2:18 PM Larry McVoy <lm@mcvoy.com> wrote:
> > 
> > > But I'm ok with a terse man page with a SEE ALSO that points to a user guide.
> > 
> > Only if the SEE ALSO has more complete and relevant information - otherwise, it degrades to VMS's famous "see figure 1" SPR.
> > 
> > > 
> > > Docs should be helpful.
> > 
> > And easy to extract information.
> > 
> > 
> > The issue to be comes back to the type of information each document is designed to give. I believe there at least three types of docs:
> > 
> > 1.  Full manuals explain how something is built and it it used. It helps to have theory/principles of operations behind it and enough detail when done, you can understand why and how to use it.
> > 2.  Tutorials are excellent for someone trying to learn a new tool. Less theory - and more -- examples, showing off the features and how to do something.
> > 3.  References pages - need to be quick look-ups to remind someone how to use something - particularly for tools you don't use every day/generally don't memorize.
> > 
> > 
> > 
> > There are at least two more: an academic paper which might be looked at as a start of #1 and full books which take #1 to even more details. Some academic papers indeed are fine manuals, and I can also argue the "manual" for some tools like awk/sed or, for that matter, yacc(1) are full books. But the idea is the >>complete<< review here.
> > 
> > 
> > Tutorials and reference pages are supposed to easy helpful things -- but often miss the mark for the audience. To me, the problem is the wrong type of information is put in each one and, more importantly, people's expectations from the document. I love properly built manual pages - I detest things like the VMS/TOPS help command or gnu info pages. What I really hate is when there is no manual, but they tell you see the HELP command -- but which command or "subtopic" -- Yikes. The traditional man system is simple quick reminders, basic reference and I can move on. For instance, I needed to remember which C library has the definition these days for some set of functions and what are its error return codes -- man 3 functions, I'm done.
> > 
> > 
> > Tutorials are funny. For some people, what they want to learn the ideas behind a tool. Typically, I don't need that as much as how this toll does some function. For instance, Apple is forcing me the learn lldb because the traditional debuggers derived from UCB's DBX are not there. It's similar to different. The man page is useful only for the command lines switches. It turns out the commands are all really long, but they have abbreviations and can be aliases. I found references to this in an lldb tutorial - but the tutorial is written to teach people more how to use a debugger to debug there code, and less how this debugger maps into the traditional functions. Hey I would like to find an cheat sheet or a set of aliases that map DBX/GDB into it -- but so far I've found nothing.
> > 
> > 
> > So Larry -- I agree with you ... "Docs should be helpful," but I fear saying like that is a bit like the Faber College Motto/Founder's Quote: "Knowledge is good."
> > 
> > 
> > 
> > 
> > ᐧ

Facing ever-growing complexity, I often find myself turning strictly to the POSIX/SUS manpages for anything that has one, not only due to an interest in keeping things as portable as possible, but also admittedly out of some trepidation that the cool shiny specific feature of the week for a specific implementation doesn't have quite the same stabilizing standard behind it, and as such has the unlikely but real potential to change right out from under you in a new major version.  Issuing 'man 1p' or 'man 3p' before most studying has become habit, turning to a vendors' docs only when necessary.

Granted, no standardization of debuggers, assemblers, linkers, etc. makes this much trickier when working with embedded stuff or intensive diagnostics, so in that regard I've thus far been aligned with the GNU family of these components.  For the sake of embedded devs, it would be nice if the as/ld/db set of utilities had some sort of guiding light driving disparate implementations.  A particular example of divergent behavior wearing a familiar mask is the cc65 suite.  The assembler and linker smell of predictable UNIX fare, but differ in a number of little, quite annoying ways, among them "export" instead of "globl", cheap labels based strictly on counts forward and backward rather than recyclable numeric labels, just little things.  While a standard isn't the end all be all solution to everything, it certainly decreases at least some of the cognitive load, giving you a subset of behaviors to learn once, only turning to specifics when you've exhausted your options (or patience) with the intersections of various implementations.

I see a domino effect in this sort of thing too, one basal tool diverges a bit from other versions, then folks who only ever use that implementation head down a new fork in the road, those in their "camp" follow, before long whatever that difference is happens to be entrenched in a number of folks' vocabularies.  Like linguistic divergence, eventually the dialectical bits of how they work are no longer mutually intelligible.  The Tower of Babel grows ever higher, only time will tell whether the varied, sometimes contradictory styles of architecture are a strength or weakness.  Like evolution, oft times the most successful, sensible approaches prevail, but nature has a funny way of lapsing on our narrow understanding of "fitness" too.  After all, most of what many of us use on the regular guarantees no "fitness for a particular purpose".  Does this make stability an organic consequence or a happy accident?  I know I couldn't say.

- Matt G.