From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on inbox.vuxu.org X-Spam-Level: *** X-Spam-Status: No, score=3.0 required=5.0 tests=DKIM_INVALID,DKIM_SIGNED, HEADER_FROM_DIFFERENT_DOMAINS,HTML_FONT_LOW_CONTRAST,HTML_MESSAGE, MAILING_LIST_MULTI,RCVD_IN_SBL_CSS autolearn=no autolearn_force=no version=3.4.4 Received: from minnie.tuhs.org (minnie.tuhs.org [IPv6:2600:3c01:e000:146::1]) by inbox.vuxu.org (Postfix) with ESMTP id C03612173A for ; Sat, 18 May 2024 21:19:48 +0200 (CEST) Received: from minnie.tuhs.org (localhost [IPv6:::1]) by minnie.tuhs.org (Postfix) with ESMTP id BCBCA43667; Sun, 19 May 2024 05:19:42 +1000 (AEST) Received: from mout.perfora.net (mout.perfora.net [74.208.4.197]) by minnie.tuhs.org (Postfix) with ESMTPS id 8820A43664 for ; Sun, 19 May 2024 05:19:36 +1000 (AEST) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=makerlisp.com; s=s1-ionos; t=1716059975; x=1716664775; i=luther.johnson@makerlisp.com; bh=QbVetMwBf2E17rn+HwY/tSdtbvcXEjLCnXkqXl+5V84=; h=X-UI-Sender-Class:Subject:To:References:From:Message-ID:Date: MIME-Version:In-Reply-To:Content-Type:cc: content-transfer-encoding:content-type:date:from:message-id: mime-version:reply-to:subject:to; b=tMEYZKW8pCgkKUpqc6YCmCXFqEbf/K+AFp7jD22IChVSmrIdbcnt7LGFKOQ5WitD ve5qmnXkIXI7NoeDod61A05xyqNEldtXRYZ+hzAUH18+twcP9B8DIQZVs3FtsqQiB dMPilSvA168ZBVO0AEme/6rjN9x2nbXAml0L8jK03TJNh/0rExeQWyKEIV82hUTXj Q62A1y8iwiFx0qsshCkyQvjsIKjUOfGOwc7h74LPocBQn7O8O7FjMT+f/XKLxUYFA aj8yr7FOQgecW/GU1ykZ7ibNsh+zNxKF6fcOIk3l1kVg5TkGFekbkL5zyhU40uPCe E7bYyBmV1BFm1HH//w== X-UI-Sender-Class: 55c96926-9e95-11ee-ae09-1f7a4046a0f6 Received: from makerlispvps ([74.208.29.250]) by mrelay.perfora.net (mreueus003 [74.208.5.2]) with ESMTPSA (Nemesis) id 0MRF0r-1rzDZo28MB-00UdMC for ; Sat, 18 May 2024 21:19:35 +0200 Received: from [192.168.234.135] (unknown [172.56.208.41]) by makerlispvps (Postfix) with ESMTPSA id E187C8BF04 for ; Sat, 18 May 2024 19:19:34 +0000 (UTC) To: tuhs@tuhs.org References: <20240518181825.GT9216@mcvoy.com> From: Luther Johnson Message-ID: <0309bfd8-3f85-e687-1500-c1e447599e83@makerlisp.com> Date: Sat, 18 May 2024 12:19:32 -0700 User-Agent: Mozilla/5.0 (X11; Linux x86_64; rv:45.0) Gecko/20100101 Thunderbird/45.8.0 MIME-Version: 1.0 In-Reply-To: Content-Type: multipart/alternative; boundary="------------3EA15F9244A1EE977FF8BE62" X-Provags-ID: V03:K1:O+xIXa6qEJB/W75OJ4N/rFnF9i/UyaysMHW175pQLnV6TlfJprZ 952l7kqf0BFOd9AhaImk9a6sO9cgkhgqJkbhZSrhLfbtS5zR0QwZijhfn1uDLWj2EFX5iOQ GBZO8YfNqlQWW7bn9SX3Si9H6WGeOANCfrqghCtOpEwt4oZw1fNacIPNEKb+9lq3tLbUPqS tgxcTUrH+yhC8DNRPJ6Og== UI-OutboundReport: notjunk:1;M01:P0:uqSRHyVDCy0=;aeZaqZDB1XPz0Bf8D0Ddt/XsQj6 yp8dAdZSJqedVNCs4psg9MsmSCIdEDTm8eAs2cSLL9hM6TVWTi4ybvpSheKy1Tudq1P4YtpF/ 00zQgi/BdLKHbLNO3WveKvolbELfKEqVd0lUtkSDSCpM72qMzxvxWsYQ3k7sChMiIcaDHEDdU EGeybV24/7OPliA4FmV74VNsLZvR/gP1dnY1q3Ah9AZVX/okQXtMH5u9d99CBEbaswZIeMJpW cU/t1PenDuWoKUhkk3oL+yPrPJO3rmhjnOyuSYIbce2PfbxPg9ARkqadGQjdMU1bgMq9MUQqg XOQX8jX/Xw2BBmpQ0pQnAYK4oV/i4EqdXcebSItOnjeTe8pRdfrSEJjYRODsWywsYlwvgXrkZ vH6THrCOSud9gGWUB67WDQCnoBnKeI5MgHcVW5TZ4vD4g++PMgRbaN1mHgfa1Gqyh5/PENOZA kqaSgLpOondzh2oQRMIle2Bxok8nGf9ka92bb+JkLYBYcJfCScN6VPQDBuoIBqxPheYP1Oeu5 Yv/+ncQnpfU01B4ErO7pfUYGff8zCGKHEEE4lUtvV5WdJTw0dBI80YCZSUp767NzfZsgBgRkV WVuo1KkdbNL3aNv1Uw9QiyJkhgMbEa2urgeb0tr08Inra4aUX0FbOirUt4OvmDEBwaCLM9R9G q7whtLwb91et74Knj9BB5hlfttsTypTy9U4dHkAxRKAXuQLaF9JLqFyRtFfIKTBWsUfm/E5Ct R+8VaHT9566Hb+5B3lIve9wFSJD/SyKnfn92SOpUM4VqegLAA54iS8= Message-ID-Hash: QHMC24XDDSEVXGYE3NWO2QC5UTVWCYZI X-Message-ID-Hash: QHMC24XDDSEVXGYE3NWO2QC5UTVWCYZI X-MailFrom: luther.johnson@makerlisp.com X-Mailman-Rule-Misses: dmarc-mitigation; no-senders; approved; emergency; loop; banned-address; member-moderation; nonmember-moderation; administrivia; implicit-dest; max-recipients; max-size; news-moderation; no-subject; digests; suspicious-header X-Mailman-Version: 3.3.6b1 Precedence: list Subject: [TUHS] Re: On Bloat and the Idea of Small Specialized Tools List-Id: The Unix Heritage Society mailing list Archived-At: List-Archive: List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: This is a multi-part message in MIME format. --------------3EA15F9244A1EE977FF8BE62 Content-Type: text/plain; charset=utf-8; format=flowed Content-Transfer-Encoding: quoted-printable 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=E2=80=AFPM Larry McVoy > wrote: > > But I'm ok with a terse man page with a SEE ALSO thatpoints 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 howto 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 builtmanual > 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, > basicreferenceand 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/." > > > > =E1=90=A7 --------------3EA15F9244A1EE977FF8BE62 Content-Type: text/html; charset=utf-8 Content-Transfer-Encoding: quoted-printable

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=E2=80=AFPM Larry McVoy <lm@mcvoy.com> wrote:
But I'm ok with a terse man page with a SEE ALSO that=C2=A0points 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.=C2=A0

Docs should be helpful.
And easy to extract information.=C2=A0

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:<= /div>
  1. Full manuals=C2=A0explain how something=C2=A0is built and it = it=C2=A0used.=C2= =A0 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.=C2= =A0 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=C2=A0how to use somethi= ng - particularly=C2=A0for tools you don't use every day/generally=C2=A0don't memorize.

There are at least two more: an academic=C2=A0paper which might be looked at as a start of= #1 and full books which take #1 to even more details.=C2=A0 S= ome 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.=C2=A0But 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.=C2=A0=C2=A0To me, the problem is the wrong type of information is put in each one and, more importantly, people's expectations from the document.=C2=A0 I love properly built=C2=A0manual 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=C2=A0the=C2=A0HELP command -- but which command or "su= btopic" -- Yikes.=C2=A0 The=C2=A0traditional man=C2=A0system is si= mple quick reminders, basic reference and I can move on.=C2=A0 For instance, I need= ed 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.=C2=A0=C2=A0

Tutorials are funny.=C2=A0 For some people, wh= at they want to learn the ideas behind a tool.=C2=A0 Typicall= y, I don't need that as much as how this toll does some function.=C2=A0 =C2=A0For instance, Apple is forcing me th= e learn lldb because the traditional debuggers derived from UCB's DBX are not there.=C2=A0 =C2=A0It's similar to diffe= rent.=C2=A0 The man page is useful only for the command lines switches.=C2=A0 =C2=A0It turns out the commands are all re= ally long, but they have abbreviations=C2=A0and can be aliases.= =C2=A0 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.=C2=A0 Hey I would lik= e to find an cheat sheet or a set of aliases that map DBX/GDB into it -- but so far I've found nothing.

So Larr= y -- I agree with you ... "Docs should be helpful," but I fear saying like that=C2=A0is a bit like the Faber College Motto/Founder's=C2=A0Quote: "Kno= wledge is good."



3D""<= font color=3D"#ffffff" size=3D"1">=E1=90=A7

--------------3EA15F9244A1EE977FF8BE62--