From mboxrd@z Thu Jan 1 00:00:00 1970 X-Spam-Checker-Version: SpamAssassin 3.4.4 (2020-01-24) on inbox.vuxu.org X-Spam-Level: X-Spam-Status: No, score=-0.8 required=5.0 tests=DKIM_ADSP_CUSTOM_MED, DKIM_INVALID,DKIM_SIGNED,FREEMAIL_FROM,HTML_MESSAGE,MAILING_LIST_MULTI autolearn=ham autolearn_force=no version=3.4.4 Received: (qmail 12911 invoked from network); 21 Sep 2023 03:06:56 -0000 Received: from minnie.tuhs.org (50.116.15.146) by inbox.vuxu.org with ESMTPUTF8; 21 Sep 2023 03:06:56 -0000 Received: from minnie.tuhs.org (localhost [IPv6:::1]) by minnie.tuhs.org (Postfix) with ESMTP id 5B6AB415A9; Thu, 21 Sep 2023 13:06:47 +1000 (AEST) Received: from mail-ed1-x52f.google.com (mail-ed1-x52f.google.com [IPv6:2a00:1450:4864:20::52f]) by minnie.tuhs.org (Postfix) with ESMTPS id 3C4F4415A5 for ; Thu, 21 Sep 2023 13:06:41 +1000 (AEST) Received: by mail-ed1-x52f.google.com with SMTP id 4fb4d7f45d1cf-530a6cbbb47so446806a12.0 for ; Wed, 20 Sep 2023 20:06:41 -0700 (PDT) DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20230601; t=1695265599; x=1695870399; darn=tuhs.org; h=to:subject:message-id:date:from:in-reply-to:references:mime-version :from:to:cc:subject:date:message-id:reply-to; bh=QGmKaN+67de8XFhyA9CR+bJm1SlSUb5EvxnujAohlp0=; b=aOOJP+qCaubkU2RsTRbEi2cSE2ZLH7L1RR4EjLEcjbkij716jggf0CbrAh1H7rWeq3 /0olMC7Am5+6trhtp0VJGvoWzhmAMFKxGr2Ql3Wql0lQoa/3pVnhqC4L41OwhM8oJ8QG roj34npT7nXf7g6DekLa76lqOoseeQbEVla791xwuEf08+5EuVhZ3QoGRGRf2BJj3l5B Aem0VccbotpWA9no2jifJfZmoWdPA7bP4cys+8K6O97DLYrPSU2JZ5lOkiaUzH/xvBHm 8BRJgbiQhRVLgC0UCBl/wsq2kuul3U5y6MjWX/oBukiMVKOv8XcLSaUihJOIu/NLA+Ar LvkQ== X-Google-DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=1e100.net; s=20230601; t=1695265599; x=1695870399; h=to:subject:message-id:date:from:in-reply-to:references:mime-version :x-gm-message-state:from:to:cc:subject:date:message-id:reply-to; bh=QGmKaN+67de8XFhyA9CR+bJm1SlSUb5EvxnujAohlp0=; b=dtXdZaR1GvCUWXO9a/69m5FhMiVNQpBpBWZJ+2sibT8eupWEwWHKcuLIZ4TH8k7zkg p74ZylT4wEVv+6h3I5Fv9j04zLAKEl3g9wmU0gHIv32xe+OSKEbpRAuYJlHceHctijdd Wuhj9udM78Moiulo9iiTfQYqm/cpB6AsA9SJbSw9m99iwmVfRyOwrkXahKb1zEHNzv2j Pj48ig00lR0ZulNA6l1EmCVijyhA/oIZ2Nn/BcS/olsOxhXFdndMsk/RtUBOKHext1Ur unke/8QCWaoo7CJ1hrXwcmAzfQ4fnW2IBnmnV3oHUwp1uu67cS3Y4CamU7Hwu/zehJA8 eJ3A== X-Gm-Message-State: AOJu0YyOVlwpEUScNAULtGlj89uN8W49J7oYOv4VrYzYBV1BuX7YE2i2 ODH2Wzz8PZlVrD5uSuqHBSAJOxFePrY6r4sB7jSvdgqB X-Google-Smtp-Source: AGHT+IH9ByF5/MQLKqQ50B2z4/AJN8hkxLvHJ+xg03w/awTexxVS4AGTlfZksHAaAyQbFGvAEJHeNK6A9tEKyBEJZAQ= X-Received: by 2002:a50:ef09:0:b0:530:a5d6:583d with SMTP id m9-20020a50ef09000000b00530a5d6583dmr4106487eds.11.1695265599013; Wed, 20 Sep 2023 20:06:39 -0700 (PDT) MIME-Version: 1.0 References: <4CmySC-mFud1dlrqfAq1itmNKoTWVi8cTuAqCvtUengKvv5CWEoYCFf6-I18dwf5BVSZWAxC-B6BP6Y1e0Gi_mlga344b5cxu5TlUCLXHeg=@protonmail.com> <20230919233925.GB28844@mcvoy.com> <20230920195635.GG28844@mcvoy.com> In-Reply-To: From: Adam Thornton Date: Wed, 20 Sep 2023 20:06:27 -0700 Message-ID: To: The Eunuchs Hysterical Society Content-Type: multipart/alternative; boundary="000000000000d449e00605d5c7b1" Message-ID-Hash: RLJFAODN4DSBKJVAJO6IZ7IBQCPSPDLK X-Message-ID-Hash: RLJFAODN4DSBKJVAJO6IZ7IBQCPSPDLK X-MailFrom: athornton@gmail.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: Project Idea: The UNIX Programmer's Manual: Heritage Edition List-Id: The Unix Heritage Society mailing list Archived-At: List-Archive: List-Help: List-Owner: List-Post: List-Subscribe: List-Unsubscribe: --000000000000d449e00605d5c7b1 Content-Type: text/plain; charset="UTF-8" That's it, isn't it? Man pages are great if you a) already know the name of the program you want (c'mon, apropos/man -k have never really worked that well), and b) have at least a vague idea of how to use it. If you want to look up what a flag does, or whether there's a flag that does what you need, they can't be beat. But they aren't great for either exploration or discoverability. Now, this is less of a problem when a command takes its input on stdin, writes its output to stdout, any errors to stderr, and it has, like, five or fewer different options. For the use case of programs-which-are-really-filter-stages designed to be connected via pipes, and when there aren't all that many of them, it works fine. Once something else is on the table, yeah, the man page is at best incomplete and at worst basically useless. Say what you will about VMS, its HELP functionality makes it much easier to go from "I want to do X" to "And here's a sequence of commands that will do X" when you don't already have a good mental model of what's on the system. Adam --000000000000d449e00605d5c7b1 Content-Type: text/html; charset="UTF-8" Content-Transfer-Encoding: quoted-printable
That's it, isn't it? Man pages are great if y= ou a) already know the name of the program you want (c'mon, apropos/man= -k have never really worked that well), and b) have at least a vague idea = of how to use it.=C2=A0 If you want to look up what a flag does, or whether= there's a flag that does what you need, they can't be beat.
<= div>
But they aren't great for either exploration or disc= overability.

Now, this is less of a problem when a= command takes its input on stdin, writes its output to stdout, any errors = to stderr, and it has, like, five or fewer different options.=C2=A0 For the= use case of programs-which-are-really-filter-stages designed to be connect= ed via pipes, and when there aren't all that many of them, it works fin= e.=C2=A0 Once something else is on the table, yeah, the man page is at best= incomplete and at worst basically useless.

Sa= y what you will about VMS, its HELP functionality makes it much easier to g= o from "I want to do X" to "And here's a sequence of com= mands that will do X" when you don't already have a good mental mo= del of what's on the system.

Adam
--000000000000d449e00605d5c7b1--